recvmsg()

The recvmsg() call receives messages on the socket with descriptor s and stores the messages in an array of message headers.

For datagram protocols, recvmsg() returns the source address associated with each incoming datagram. For connection-oriented protocols like TCP, getpeername() returns the address associated with the remote end of the connection.

#include <manifest.h>
#include <bsdtypes.h>
#include <socket.h>
 
int recvmsg(int s, struct msghdr *msg, int flags)

Parameter

Description

s

Socket descriptor.

msg

Points to an msghdr structure.

flags

Set the flags parameter by specifying one or more of the following flags. If more than one flag is specified, the logical OR operator ( | ) must be used to separate them. Setting this parameter is supported only for sockets in the AF_INET domain. Setting these flags is not supported for sockets in the AF_IUCV domain.

MSG_OOB: Reads any out-of-band data on the socket. This is valid for stream (TCP) sockets only.
MSG_PEEK: Peeks 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.

A message header is defined by structure msghdr. The definition of this structure can be found in the SOCKET.H header file and contains the following elements:

Variable

Description

msg_name

An optional pointer to a buffer where the sender address is stored for datagram sockets.

msg_namelen

The size of the address buffer.

msg_iov

An array of iovec buffers into which the message is placed. An iovec buffer contains the following variables:

iov_base: Points to the buffer.
iov_len: The length of the buffer.

msg_iovlen

The number of elements in the msg_iov array.

msg_accrights

The access rights received. This field is ignored.

msg_accrightslen

The length of access rights received. This field is ignored.

The recvmsg() call applies to sockets, regardless of whether they are in the connected state, except for TCP sockets, which must be connected.

This call returns the length of the data received. If data is not available for socket s, and s is in blocking mode, the recvmsg() call blocks the caller until data arrives. If data is not available, and s is in nonblocking mode, recvmsg() returns a -1 and sets errno to EWOULDBLOCK. See fcntl() or ioctl() to see how to set nonblocking mode.

If a datagram packet is too long to fit in the supplied buffer, datagram sockets discard extra bytes. Stream sockets act like 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. Therefore, applications using stream sockets should place this call in a loop, and call this function until all data has been received.

Return values

If successful, the length of the message in bytes is returned. The value 0 indicates that the connection is closed. The value -1 indicates an error. Errno identifies the specific error.

Errno: Description
EBADF: Indicates that s is not a valid socket descriptor.
EFAULT: Using msg would result in an attempt to access storage outside the caller address space. Also returned when msg_namelen is not valid.
EWOULDBLOCK: Indicates that s is in nonblocking mode and data is not available to read.
ENOTCONN: Returned for an unconnected TCP socket.
EMSGSIZE: For non-TCP sockets, this indicates that length exceeds the maximum data size determined by getsockopt() using SO_SNDBUF for the socket type (TCP, UDP, or RAW).

Related calls

connect(), fcntl(), getsockopt(), ioctl(), read(), readv(), recv(), recvfrom(), select(), selectex(), send(), sendmsg(), sendto(), setsockopt(), socket(), write(), writev()