recvfrom() — Receive messages on a socket

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>

int recvfrom(int socket, void *__restrict__ buffer, 
             size_t length, int flags,
             struct sockaddr *__restrict__ address, 
             socklen_t *__restrict__ address_length);

#define _OE_SOCKETS
#include <sys/socket.h>

int recvfrom(int socket, char *buffer, 
             int length, int flags,
             struct sockaddr *address, 
             int *address_length);

Parameter

Description

socket

The socket descriptor.

buffer

The pointer to the buffer that receives the data.

length

The length in bytes of the buffer pointed to by the buffer parameter. If the MSG_CONNTERM flag is set, the length of the buffer must be zero.

flags

A parameter that can be set to 0, MSG_CONNTERM, MSG_PEEK, MSG_OOB, or MSG_WAITALL. The MSG_CONNTERM flag is mutually exclusive with other flags.

MSG_CONNTERM

Requests that the function completes only when a TCP connection is terminated. It is valid for TCP sockets only. Other normal receive requests are also completed. The application must be able to deal with the fact that a normal receive and this special connection termination receive might be driven in parallel.

AT-TLS considerations: If AT-TLS is being used to provide transparent TLS/SSL support for a TCP socket and a receive request with MSG_CONNTERM is outstanding, AT-TLS will immediately honor any TLS/SSL close notify alerts sent by the peer and initiate TLS/SSL session shutdown. For more information about AT-TLS and determining whether a TCP connection is using AT-TLS, see z/OS Communications Server: IP Programmer's Guide and Reference.

MSG_OOB

Reads any out-of-band data on the socket. Out-of-band data is sent when the MSG_OOB flag is on for a send(), sendto(), or sendmsg().

The fcntl() command should be used with F_SETOWN to specify the recipient, either a pid or a gid, of a SIGURG signal that will be sent when out-of-band data is sent. If no recipient is set, no signal will be sent. For more information, see the fcntl() command. The recipient of the data determines whether to receive out-of-band data inline or not inline by the setting of the SO_OOBINLINE option of setsockopt(). If SO_OOBINLINE is set off and the MSG_OOB flag is set on, the out-of-band data byte will be read out-of-line. It is invalid for the MSG_OOB flag to be set on when SO_OOBINLINE is set on. If there is out-of-band data available, and the MSG_OOB flag is not set (SO_OOBINLINE can be on or off), then the data up to, but not including, the out-of-band data will be read. When the read cursor has reached the out-of-band data byte, then only the out-of-band data will be read on the next read. The SIOCATMARK option of ioctl() can be used to determine if the read cursor is currently at the out-of-band data byte. For more information, refer to the setsockopt() and ioctl() commands.

MSG_PEEK

Peeks at the data present on the socket; the data is returned but not consumed, so that a subsequent receive operation sees the same data.

MSG_WAITALL

Requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, an error is pending or SO_RCVTIMEO is set and the timer is expired for the socket. For AF_UNIX, the function may also return earlier if out-of-band (OOB) data is inline and there is OOB data to be read. In this case, the data up to the OOB data is returned on the first recvfrom(). The OOB data is returned on the subsequent read request.

address

A pointer to a socket address structure from which data is received. If address is nonzero, the source address is returned.

address_length

Must initially point to an integer that contains the size in bytes of the storage pointed to by address. On return, that integer contains the size required to represent the address of the connecting socket. If this value is larger than the size supplied on input, then the information contained in sockaddr is truncated to the length supplied on input. If address is NULL, address_length is ignored.

Error Code

Description

EBADF

socket is not a valid socket descriptor.

ECONNRESET

The connection was forcibly closed by a peer.

EFAULT

Using the buffer and length parameters would result in an attempt to access storage outside the caller's address space.

EINTR

A signal interrupted recvfrom() before any data was available.

EINVAL

The request is invalid or not supported. The MSG_OOB flag is set and no out-of-band data is available.

EIO

There has been a network or transport failure.

ENOBUFS

Insufficient system resources are available to complete the call.

ENOTCONN

A receive is attempted on a connection-oriented socket that is not connected.

ENOTSOCK

The descriptor is for a file, not for a socket.

EOPNOTSUPP

The specified flags are not supported for this socket type.

ETIMEDOUT

The connection timed out during connection establishment, or due to a transmission timeout on active connection.

EWOULDBLOCK

socket is in nonblocking mode and data is not available to read. or the SO_RCVTIMEO timeout value was been reached before data was available.