recvmsg() — Receive messages on a socket and store in an array of message headers

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	both

Format

X/Open

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

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

Berkeley sockets

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

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

General description

The recvmsg() function receives messages on a socket with descriptor socket and stores them in an array of message headers.

Parameter

Description

socket

The socket descriptor.

msg

An array of message headers into which messages are received.

flags

The flags parameter is set 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. 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, and the output MSG_OOB msg_flag in the message header will be set on. 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 will see 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.

A message header is defined by a msghdr structure. A definition of this structure can be found in the sys/socket.h include file and contains the following elements:

Element: Description
msg_iov: An array of iovec buffers into which the message is placed.
msg_iovlen: The number of elements in the msg_iov array. If the MSG_CONNTERM flag is set, the number of elements must be zero.
msg_name: An optional pointer to a buffer where the sender's address is stored.
msg_namelen: The size of the address buffer.
caddr_t msg_accrights: Access rights sent/received (ignored if specified by the user).
int msg_accrightslen: Length of access rights data (ignored if specified by the user).
msg_control: Ancillary data, see below.
msg_controllen: Ancillary data buffer length.
msg_flags: Flags on received message.

Ancillary data consists of a sequence of pairs, each consisting of a cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the cmsghdr structure contains descriptive information that allows an application to correctly parse the data.

The sys/socket.h header file defines the cmsghdr structure that includes at least the following members:

Element: Description
cmsg_len: Data byte count, including header.
cmsg_level: Originating protocol.
cmsg_type: Protocol-specific type.

The following ancillary data are available at the IPv4 level:

Ancillary data: Description
IP_PKTINFO: (RAW and UDP) Returns the source IP address for an outgoing packet and the outgoing interface. The data is passed in an in_pktinfo structure as defined in netinet/in.h.

The following ancillary data are available at the IPv6 level:

Ancillary data: Description
IPV6_HOPLIMIT: (RAW, TCP, and UDP) Returns the maximum hop limit for an incoming packet. The data is passed in a structure as defined in netinet/in.h.
IPV6_PATHMTU: (RAW and UDP) Returns the path MTU value for the source of a connected socket. The data is passed in a structure as defined in netinet/in.h.
IPV6_PKTINFO: (RAW and UDP) Returns the source IP address for an outgoing packet and the outgoing interface. The data is passed in an in6_pktinfo structure as defined in netinet/in.h.

The following ancillary data are available at the socket level:

Ancillary data: Description
SCM_RIGHTS: Returns the data array that contains the access rights to be sent or received. This ancillary data is valid only for the AF_UNIX domain. The structure is defined in sys/socket.h.

The sys/socket.h header file defines the following macros to gain access to the data arrays in the ancillary data associated with a message header:

CMSG_DATA(cmsg): If the argument is a pointer to a cmsghdr structure, this macro returns an unsigned character pointer to the data array associated with the cmsghdr structure.
CMSG_NXTHDR(mhdr,cmsg): If the first argument is a pointer to a msghdr structure and the second argument is a pointer to a cmsghdr structure in the ancillary data, pointed to by the msg_control field of that msghdr structure, this macro returns a pointer to the next cmsghdr structure, or a NULL pointer if this structure is the last cmsghdr in the ancillary data.
CMSG_FIRSTHDR(mhdr): If the argument is a pointer to a msghdr structure, this macro returns a pointer to the first cmsghdr structure in the ancillary data associated with this msghdr structure, or a NULL pointer if there is no ancillary data associated with the msghdr structure.

The recvmsg() function applies to sockets, regardless of whether they are in the connected state.

This call returns the length of the data received. If data is not available for the socket socket, and socket is in blocking mode, the recvmsg() call blocks the caller until data arrives. If data is not available and socket is in nonblocking mode, recvmsg() returns a -1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for a description of how to set nonblocking mode.

For datagram sockets, this call returns the entire datagram that was sent, provided that the datagram fits into the specified buffer. 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, calling this function until all data has been received.

On successful completion, the msg_flags member for the message header is the bitwise inclusive-OR of all of the following flags that indicate conditions detected for the received message:

MSG_OOB: Out-of-band data was received.
MSG_TRUNC: Normal data was truncated.
MSG_CTRUNC: Control data was truncated.

Socket address structure for IPv6: For an AF_INET6 socket, the address is returned in a sockaddr_in6 address structure. The sockaddr_in6 structure is defined in the header file netinet/in.h.

Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.

Note: The recvmsg() function has a dependency on the level of the Enhanced ASCII Extensions. See Enhanced ASCII support for details.

Returned value

If successful, recvmsg() returns the length of the message in bytes. The value 0 indicates the connection is closed.

If unsuccessful, recvmsg() returns -1 and sets errno to one of the following values:

Error Code: Description
EBADF: socket is not a valid socket descriptor.
ECONNRESET: The connection was forcibly closed by a peer.
EFAULT: Using msg would result in an attempt to access storage outside the caller's address space.
EINTR: The function was interrupted by a signal before any data was available.
EINVAL: The request is invalid or not supported. The sum of the iov_len values overflows a ssize_t.
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.