The RECVFROM macro receives data for a socket and stores it in a buffer. RECVFROM returns the length of the incoming message or data stream.
If data is not available for the socket designated by descriptor S, and socket S is in blocking mode, the RECVFROM call blocks the caller until data arrives.
If data is not available and socket S is in nonblocking mode, RECVFROM returns a -1 and sets ERRNO to 35 (EWOULDBLOCK). Because RECVFROM returns the socket address in the NAME structure, it applies to any datagram socket, whether connected or unconnected. See FCNTL or IOCTL for a description of how to set nonblocking mode. If a datagram packet is too long to fit in the supplied buffer, datagram sockets discard extra bytes.
For stream sockets, the data is processed as streams of information with no boundaries separating data. For example, if applications A and B are connected with a stream socket and Application A sends 1000 bytes, each call to this function can return 1 byte, or 10 bytes, or the entire 1000 bytes. Applications using stream sockets should place RECVFROM in a loop that repeats until all of the data has been received.
Authorization: | Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: | Task. |
Cross memory mode: | PASN = HASN. |
Amode: | 31-bit or 24-bit. Note: See "Addressability
mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.
|
ASC mode: | Primary address space control (ASC) mode. |
Interrupt status: | Enabled for interrupts. |
Locks: | Unlocked. |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
>>-EZASMI--TYPE=RECVFROM--,S--=--+-number---+-------------------> +-address--+ +-*indaddr-+ '-(reg)----' >--,NBYTE--=--+-number---+--,BUF--=--+-address--+---------------> +-address--+ +-*indaddr-+ +-*indaddr-+ '-(reg)----' '-(reg)----' >--,NAME--=--+-address--+--+------------------------+-----------> +-*indaddr-+ '-,ALET--=--+-address--+-' '-(reg)----' +-*indaddr-+ '-(reg)----' >--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+-----------> +-*indaddr-+ +-*indaddr-+ '-(reg)----' '-(reg)----' >--+------------------------------+-----------------------------> '-,FLAGS--=--+-'MSG_OOB'-----+-' +-'MSG_PEEK'----+ +-'MSG_WAITALL'-+ +-address-------+ +-*indaddr------+ '-(reg)---------' >--+---------------------------+--+-------------------------+---> +-,ECB--=--+-address--+-----+ '-,ERROR--=--+-address--+-' | +-*indaddr-+ | +-*indaddr-+ | '-(reg)----' | '-(reg)----' '-,REQAREA--=--+-address--+-' +-*indaddr-+ '-(reg)----' >--+------------------------+---------------------------------->< '-,TASK--=--+-address--+-' +-*indaddr-+ '-(reg)----'
Initially, the IPv4 or IPv6 application provides a pointer to a structure that will contain the peer socket name on completion of the call. If the NAME parameter value is nonzero, the IPv4 or IPv6 source address of the message is specified with the address of who sent the datagram. Include the SYS1.MACLIB(BPXYSOCK) macro to get the assembler mappings for the socket address structure. The socket address structure mappings begin at the SOCKADDR label. The AF_INET socket address structure fields start at the SOCK_SIN label. The AF_INET6 socket address structure fields start at the SOCK_SIN6 label.
The IPv4 socket address structure contains the following fields:
If a nonzero ALET is specified, the ALET must represent a valid entry in the dispatchable unit access list (DU-AL) for the task issuing this call. Note that ALETs can only be specified for synchronous socket calls (for example, ECB/REQAREA cannot be specified). An exception to this is an ALET representing a SCOPE=COMMON data space.
Literal Value | Binary Value | Description |
---|---|---|
'MSG_OOB' | X'00000001' | Receive out-of-band data (stream sockets only). Out-of-band data can be read if the SO_OOBINLINE option is set for the socket regardless of whether the MSG_OOB flag is set. |
'MSG_PEEK' | X'00000002' | Peek at the data, but do not destroy the data. If the peek flag is set, the next receive operation reads the same data. |
'MSG_WAITALL' | X'00000040' | Requests that the function block until the full amount of requested data can be returned (stream sockets only). The function might return a smaller amount of data if the connection is terminated, if an error is pending, or if the SO_RCVTIMEO field is set and the timer expired for the socket. |