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:

• 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. You can't use this flag with protocols that place expedited data at the head of the normal data queue.
• MSG_PEEK -- peek at the 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 MSG_WAITALL flag isn't supported by the tiny TCP/IP stack. For more information, see npm-ttcpip.so in the Utilities Reference.

  ---

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

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

See also:

recv(), recvfrom(), sendmsg()