recvmsg()

Receive a message and its header from a socket

Synopsis:

#include <sys/types.h>
#include <sys/socket.h>

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

Library:

socket3r.lib, socket3s.lib

Description:

The recvmsg() routine receives a message from a socket, s, whether or not it's connection-oriented.

The flags argument is formed by "ORing" one or more of the values:

MSG_OOB

Process out-of-band data. This flag requests receipt of out-of-band data that wouldn't be received in the normal data stream. This flag can't be used with protocols that place expedited data at the head of the normal data queue.

MSG_PEEK

Peek at incoming message. This flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data.

MSG_WAITALL

Wait for full request or error. This flag requests that the operation block until the full request is satisfied. But the call may still return less data than requested if a signal is caught, if an error or disconnect occurs, or if the next data to be received is of a different type than that returned.

The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure, defined in <sys/socket.h>, has the following form:

struct msghdr {
     caddr_t msg_name;       /* optional address */
     u_int   msg_namelen;    /* size of address */
     struct  iovec *msg_iov; /* scatter/gather array */
     u_int   msg_iovlen;     /* # elements in msg_iov */
     caddr_t msg_control;    /* ancillary data, see below */
     u_int   msg_controllen; /* ancillary data buffer len */
     int     msg_flags;      /* flags on received message */
};

The msg_name and msg_namelen parameters specify the address (source address for recvmsg(); destination address for sendmsg()) if the socket is unconnected; the msg_name parameter may be given as a null pointer if no names are desired or required.

The msg_iov and msg_iovlen parameters describe scatter-gather locations, as discussed in read().

The msg_control parameter, whose length is determined by msg_controllen, points to a buffer for other protocol-control related messages or for other miscellaneous ancillary data. The messages are of the form:

struct cmsghdr {
     u_int cmsg_len;    /* data byte count, including hdr */
     int cmsg_level;    /* originating protocol */
     int cmsg_type;     /* protocol-specific type */
                        /* followed by u_char cmsg_data[]; */
};

The msg_flags field is set on return according to the message received:

MSG_CTRUNC

Indicates that some control data was discarded due to lack of space in the buffer for ancillary data.

MSG_EOR

Indicates end-of-record; the data returned completed a record.

MSG_OOB

Indicates that expedited or out-of-band data was received.

MSG_TRUNC

Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.

Returns:

The number of bytes received, or -1 if an error occurs (errno is set).

Errors:

ENOMEM

Not enough memory.

Classification:

Standard Unix, POSIX 1003.1g (draft)

See also:

recv(), recvfrom()