Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

recvmsg()

Receive a message and its header from a socket

Synopsis:

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

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

Arguments:

s
The descriptor for the socket; see socket().
msg
A pointer to a msghdr structure where the function can store the message header; see below.
len
The size of the buffer.
flags
A combination formed by ORing one or more of the values:

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

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

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[]; */
};

Note: Currently, the tiny TCP/IP stack doesn't support ancillary data. The msg_controllen member of struct msghdr must be 0.

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:

POSIX 1003.1

Safety:
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread Yes

See also:

recv(), recvfrom(), sendmsg()