recvmsg(2) System Calls Manual recvmsg(2)
NAME
recvmsg - Receives a message from a socket using a message structure
SYNOPSIS
#include <sys/socket.h>
ssize_t recvmsg ( int socket, struct msghdr *message, int flags) ;
[Tru64 UNIX] The following definition of the recvmsg() function does not conform to current standards and is supported only for backward
compatibility (see standards(5)):
int recvmsg ( int socket, struct msghdr *message, int flags) ;
STANDARDS
Interfaces documented on this reference page conform to industry standards as follows:
recvmsg(): XNS5.0
Refer to the standards(5) reference page for more information about industry standards and associated tags.
PARAMETERS
Specifies the socket file descriptor. Points to a msghdr structure, containing pointers to both the destination address for the incoming
message and to buffers containing ancillary data. The format of the address is determined by the behavior requested for the socket.
[Tru64 UNIX] If the compile-time option _SOCKADDR_LEN is defined before the <sys/socket.h> header file is included, the msghdr
structure takes 4.4BSD behavior. Otherwise, the default 4.3BSD msghdr structure is used. In 4.4BSD, the msghdr structure has a
separate msg_flags field for holding flags from the received message. In addition, the msg_accrights field is generalized into a
msg_control field. See DESCRIPTION for more information. If _SOCKADDR_LEN is defined, the 4.3BSD msghdr structure is defined with
the name omsghdr. Permits the caller of this function to exercise control over the reception of messages. The value for this
parameter is formed by a logical OR of one or more of the following values:
Peeks at the incoming message. Processes out-of-band data on sockets that support out-of-band data. Requests that the function
block wait 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, MSG_PEEK was specified, or an error is pending for the socket.
DESCRIPTION
The recvmsg() function receives messages from unconnected or connected sockets and returns the total length of the message.
For message-based sockets (for example, SOCK_DGRAM), you must read the entire message in a single operation. When a message is too long
for the buffer and MSG_PEEK is not specified, the message is truncated and MSG_TRUNC set in the msg_flags member or the msghdr structure.
For stream-based sockets (SOCK_STREAM), message boundaries are ignored, and data is returned as soon as it is available.
If the MSG_WAITALL flag is not set, the function returns data up to the end of the first message.
When no messages are available at the socket specified by the socket parameter, the recvmsg() function waits for a message to arrive. When
the socket is nonblocking and no message is available, the recvmsg() function fails and sets errno to [EWOULDBLOCK].
Use the select() and poll() functions to determine when more data arrives.
The recvmsg() function uses a msghdr structure to minimize the number of directly supplied parameters. In the msghdr structure, the
msg_name and msg_namelen fields specify the destination address if the socket is unconnected. The msg_name field may be given as a null
pointer if no names are desired or required. The msg_iov and msg_iovlen fields describe the scatter gather locations.
The msghdr structure uses a socklen_t data type for the msg_iovlen field instead of a size_t data type as specified in XNS4.0.
[Tru64 UNIX] In 4.3BSD, the msg_accrights field is a buffer for passing access rights. In 4.4BSD, the msg_accrights field has been
expanded into a msg_control field, to include other protocol control messages or other miscellaneous ancillary data.
In the 4.4BSD msghdr structure, the msg_flags field holds flags from the received message. In addition to MSG_PEEK and MSG_OOB, the incom-
ing flags reported in the msg_flags field can be any of the following values: Data includes the end-of-record marker. Out-of-band data was
received. Data was truncated before delivery. Control data was truncated before delivery.
NOTES
[Tru64 UNIX] When compiled in the X/Open UNIX environment, calls to the recvmsg() function are internally renamed by prepending _E to the
function name. When you are debugging a module that includes the recvmsg() function and for which _XOPEN_SOURCE_EXTENDED has been defined,
use _Erecvmsg to refer to the recvmsg() call. See standards(5) for further information.
[Tru64 UNIX] When compiled in the POSIX.1g socket environment, calls to the recvmsg() function are internally renamed by prepending _P to
the function name. When you are debugging a module that includes the recvmsg() function and for which _POSIX_PII_SOCKET has been defined,
use _Precvmsg to refer to the recvmsg() call. See standards(5) for further information.
RETURN VALUES
Upon successful completion, the recvmsg() function returns the length of the message in bytes, and fills in the fields of the msghdr struc-
ture pointed to by the message parameter as appropriate. Otherwise, a value of -1 is returned and errno is set to indicate the error.
ERRORS
If the recvmsg() function fails, errno may be set to one of the following values: The socket parameter is not valid. A connection was
forcibly closed by a peer. The message parameter; storage pointed to by the msg_name, msg_control, or msg_iov fields of the message param-
eter; or storage pointed to by the iovec structures pointed to by the msg_iov field are not in a readable or writable part of user address-
space. A signal interrupted this function before any data was available. The MSG_OOB flag is set and no out-of-band data is available.
The sum of the iov_len values overflows an ssize_t. An I/O error occurred while reading from or writing to the file system. The
value of the msg_iovlen member of the msghdr structure is less than or equal to zero (0) or is greater than IOV_MAX. Insufficient
resources were available in the system to complete the call. The system did not have sufficient memory to fulfill the request. The
available STREAMS resources were insufficient for the operation to complete. A receive is attempted on a connection-oriented socket
that is not connected. The socket parameter refers to a file, not a socket. The specified flags are not supported this socket
type. The connection timed out during connection establishment, or due to a transmission timeout on active connection. The socket
is marked nonblocking and no data is ready to be received.
The MSG-OOB flag is set, no out-of-band data is available, and either the socket is marked nonblocking or the socket does not sup-
port blocking to wait for out-of-band data.
RELATED INFORMATION
Functions: poll(2), recv(2), recvfrom(2), select(2), send(2), sendmsg(2), sendto(2), shutdown(2), socket(2)
Standards: standards(5) delim off
recvmsg(2)