recvmsg(3N-xs) (X/OPEN SOCKETS) recvmsg(3N-xs)
NAME
recvmsg - receive a message from a socket
SYNOPSIS
cc [flag ...] file ... -lxnet [library ...]
#include <sys/socket.h>
ssizet recvmsg(int socket, struct msghdr *message, int flags);
DESCRIPTION
The recvmsg function receives a message from a connection-oriented or
connectionless socket. It is normally used with connectionless sockets
because it permits the application to retrieve the source address of
received data.
The function takes the following arguments:
socket Specifies the socket file descriptor.
message Points to a msghdr structure, containing both the buffer
to store the source address and the buffers for the
incoming message. The length and format of the address
depend on the address family of the socket. The msgflags
member is ignored on input, but may contain meaningful
values on output.
flags Specifies the type of message reception. Values of this
argument are formed by logically ORing zero or more of
the following values:
MSGOOB
Requests out-of-band data. The significance and
semantics of out-of-band data are protocol-specific.
MSGPEEK
Peeks at the incoming message.
MSGWAITALL
Requests that the function block until the full
amount of data requested can be returned. The func-
tion 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 function receives messages from unconnected or connected
sockets and returns the length of the message.
Page 1 Reliant UNIX 5.44 Printed 11/98
recvmsg(3N-xs) (X/OPEN SOCKETS) recvmsg(3N-xs)
The recvmsg function returns the total length of the message. For
message-based sockets such as SOCKDGRAM and SOCKSEQPACKET, the
entire message must be read in a single operation. If a message is too
long to fit in the supplied buffers, and MSGPEEK is not set in the
flags argument, the excess bytes are discarded, and MSGTRUNC is set
in the msgflags member of the msghdr structure. For stream-based
sockets such as SOCKSTREAM, message boundaries are ignored. In this
case, data is returned to the user as soon as it becomes available,
and no data is discarded.
If the MSGWAITALL flag is not set, data will be returned only up to
the end of the first message.
If no messages are available at the socket and ONONBLOCK is not set
on the socket's file descriptor, recvfrom blocks until a message
arrives. If no messages are available at the socket and ONONBLOCK is
set on the socket's file descriptor, recvfrom function fails and sets
errno to EWOULDBLOCK or EAGAIN.
In the msghdr structure, the msgname and msgnamelen members specify
the source address if the socket is unconnected. If the socket is con-
nected, the msgname and msgnamelen members are ignored. The msgname
member may be a null pointer if no names are desired or required. The
msgiov and msgiovlen members describe the scatter/gather locations.
On successful completion, the msgflags member of the message header
is the bitwise-inclusive OR of all of the following flags that indi-
cate conditions detected for the received message:
MSGEOR End of record was received (if supported by the proto-
col).
MSGOOB Out-of-band data was received.
MSGTRUNC Normal data was truncated.
MSGCTRUNC Control data was truncated.
RETURN VALUE
Upon successful completion, recvmsg returns the length of the message
in bytes. If no messages are available to be received and the peer has
performed an orderly shutdown, recvmsg returns 0. Otherwise, -1 is
returned and errno is set to indicate the error.
ERRORS
The recvmsg function will fail if:
EBADF The socket argument is not a valid open file descrip-
tor.
ENOTSOCK The socket argument does not refer to a socket.
Page 2 Reliant UNIX 5.44 Printed 11/98
recvmsg(3N-xs) (X/OPEN SOCKETS) recvmsg(3N-xs)
EINVAL The sum of the iovlen values overflows an ssizet.
EWOULDBLOCK or EAGAIN
The socket's file descriptor is marked ONONBLOCK and
no data is waiting to be received; or MSGOOB is set
and no out-of-band data is available and either the
socket's file descriptor is marked ONONBLOCK or the
socket does not support blocking to await out-of-band
data.
EINTR This function was interrupted by a signal before any
data was available.
EOPNOTSUPP The specified flags are not supported for this socket
type.
ENOTCONN A receive is attempted on a connection-oriented socket
that is not connected.
ETIMEDOUT The connection timed out during connection establish-
ment, or due to a transmission timeout on active con-
nection.
EINVAL The MSGOOB flag is set and no out-of-band data is
available.
ECONNRESET A connection was forcibly closed by a peer.
The recvmsg function may fail if:
EINVAL The msgiovlen member of the msghdr structure pointed
to by msg is less than or equal to 0, or is greater
than {IOVMAX}.
EIO An IO error occurred while reading from or writing to
the file system.
ENOBUFS The resources available in the system were not suffi-
cient to perform the operation
ENOMEM The memory available was not sufficient to fulfill the
request.
ENOSR The STREAMS resources available were not sufficient to
complete the operation.
APPLICATION USAGE
The select and poll functions can be used to determine when data is
available to be received.
Page 3 Reliant UNIX 5.44 Printed 11/98
recvmsg(3N-xs) (X/OPEN SOCKETS) recvmsg(3N-xs)
SEE ALSO
poll(2), select(3C), recv(3N-xs), recvfrom(3N-xs), send(3N-xs),
sendmsg(3N-xs), sendto(3N-xs), shutdown(3N-xs), socket(3N-xs).
Page 4 Reliant UNIX 5.44 Printed 11/98