recv(3sock)

recv -- receive a message from a socket

Synopsis

cc [options] file -lsocket -lnsl

#include <sys/types.h>
#include <sys/socket.h>

ssize_t recv(int socket, void *buf, size_t len, int flags);

ssize_t recvfrom(int socket, void *buf, size_t len, int flags,
	struct sockaddr *from, size_t *fromlen);

ssize_t recvmsg(int socket, struct msghdr *msg, int flags);

Description

socket is a socket file descriptor that has been created using socket. recv, recvfrom, and recvmsg are used to receive messages from another socket. recv may be used only on a connected socket (see connect(3sock)), while recvfrom and recvmsg may be used to receive data on a socket whether it is in a connected state or not. recvfrom is commonly used with connectionless sockets because it allows the source address to be extracted from received data.

If from is not a NULL pointer, the source address of the message is filled in. fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket(3sock)).

For message-based sockets such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, and MSG_PEEK is not set in flags, excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, message boundaries are ignored. As soon as it becomes available, data is returned to the user. No data is discarded in this case.

If no messages are available at the socket and O_NONBLOCK is not set on its file descriptor, the receive call waits for a message to arrive, unless the socket is nonblocking (see fcntl(2)) in which case -1 is returned with the external variable errno set to EWOULDBLOCK.

The select call may be used to determine when more data arrives.

The flags parameter is formed by ORing one or more of the following:

MSG_OOB: Read any out-of-band data present on the socket rather than the regular in-band data.
MSG_PEEK: ``Peek'' at the data present on the socket; the data is returned, but not consumed, so that a subsequent receive operation will see the same data.
MSG_WAITALL: Block until the full amount of requested data can be returned. May return a smaller amount of data if a signal is caught, the connection is terminated or an error is pending for the socket.

The recvmsg call uses a msghdr structure to minimize the number of directly supplied parameters. This structure is defined in sys/socket.h and includes the following members:

   void * msg_name;        /* optional address */
   size_t msg_namelen;     /* size of address */
   struct iovec * msg_iov; /* scatter/gather array */
   int    msg_iovlen;      /* number of elements in msg_iov */
   void * msg_accrights;   /* access rights sent/received */
   int    msg_accrightslen;
   void * msg_control;
   size_t msgcontrollen;
   int    msg_flags;

msg_name and msg_namelen specify the source address if the socket is unconnected; msg_name may be given as a NULL pointer if no names are desired or required. The msg_iov and msg_iovlen describe the scatter-gather locations, as described in read. A buffer to receive any access rights sent along with the message is specified in msg_accrights, which has length msg_accrightslen.

Files

/usr/lib/locale/locale/LC_MESSAGES/uxnsl

Return values

These calls return the number of bytes received, or -1 if an error occurred. recv returns 0 if the peer has performed an orderly shutdown and no messages are available to be received.

Errors

The calls fail if:

EBADF: socket is an invalid descriptor.
ECONNREFUSED: No socket was open to the peer for a previous send.
ECONNRESET: A connection was forcibly closed by a peer.
EHOSTDOWN: The peer was down for a previous send.
ENOTSOCK: socket is a descriptor for a file, not a socket.
EINTR: The operation was interrupted by delivery of a signal before any data was available to be received.
EINVAL: MSG_OOB is set and there is no available out-of-band data.
ENOTCONN: A receive is attempted on a connection-oriented socket that is not connected.
EWOULDBLOCK: The socket is marked non-blocking and the requested operation would block.
EOPNOTSUPP: The specified flags are not supported for this socket type or protocol.
ETIMEDOUT: The connection timed out during connection or because of a transmission timeout on active connection.
EIO: An I/O error occurred while reading to or writing from the file system.
ENOBUFS: System resources were insufficient to perform the operation.
ENOMEM: There was insufficient user memory available for the operation to complete.
ENOSR: There were insufficient STREAMS resources available for the operation to complete.

References

connect(3sock), fcntl(2), getsockopt(3sock), ioctl(2), read(2) send(3sock), socket(3sock)

RFC 2133

Notices

The type of address structure passed to recvfrom and recvmsg depends on the address family. UNIX^® domain sockets (address family AF_UNIX) require a sockaddr_un structure as defined in sys/un.h; Internet domain IPv4 sockets (address family AF_INET) require a struct sockaddr_in structure as defined in netinet/in.h; Internet domain IPv6 sockets (address family AF_INET6) require a struct sockaddr_in6 structure as defined in netinet/in.h. Other address families may require other structures. Use the structure appropriate to the address family; cast the structure address to a struct sockaddr* in the call to recvfrom and pass the size of the structure in the fromlen argument. If you are using recvmsg, set msghdr.msg_name to point to the appropriate structure and msghdr.msg_namelen to the length of the structure.

In UnixWare 7 the sockaddr structure has been modified to support variable length sockets. The net result of this modification is that the family member has been shortened to 8 bits and a new 8-bit member inserted before it called len. For more information on the new sockaddr structures, see: unix(7sock) and inet(7tcp).