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.
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[]; */ };
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:
Safety: | |
---|---|
Cancellation point | Yes |
Interrupt handler | No |
Signal handler | No |
Thread | Yes |