recvmsg(2)recvmsg(2)NAMErecvmsg - Receive 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 stan‐
dards as follows:
recvmsg(): XNS4.0, 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_options field
for holding options 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 func‐
tion 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 con‐
nection 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_options 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 pass‐
ing 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 incoming
flags reported in the msg_flags field can be any of the following val‐
ues: Data includes the end-of-record marker. Out-of-band data was
received. Data was truncated before delivery. Control data was trun‐
cated 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 fur‐
ther 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. If no messages
are available and the peer has closed the connection, the recv() func‐
tion returns a value of 0. 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 follow‐
ing 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 parame‐
ter; 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 avail‐
able. 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 con‐
nection-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 time‐
out 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
support blocking to wait for out-of-band data.
SEE ALSO
Functions: poll(2), recv(2), recvfrom(2), select(2), send(2),
sendmsg(2), sendto(2), shutdown(2), socket(2)
Standards: standards(5)
Network Programmer's Guide
recvmsg(2)
