recvmsg

Reads a message from a socket and stores it in a message structure.

Library:LibC
Standard:BSD
Service:Networking

Syntax

  #include <sys/socket.h> 
  
  ssize_t recvmsg (
     int              s, 
     struct msghdr   *msg, 
     int              flags);

Parameters

s

(IN) Specifies the socket file handle from which data is to be read.

msg

(IN/OUT) Points to message and buffer address information.

flags

(IN) Specifies the type of message reception. See Message Types.

Return Values

If successful, returns the number of bytes received. If no message is available and the peer has performed an orderly shutdown, returns 0. Otherwise, returns -1 and sets errno to one of the following:

Decimal

Constant

Description

4

EBADF

The socket parameter is an invalid socket file handle.

9

EINVAL

MSG_OOB is invalid when used with SO_OOBINLINE, or the out-of-band data is not present.

35

EWOULDBLOCK

The socket is marked nonblocking, and the receive operation would block.

38

ENOTSOCK

The socket parameter does not reference a socket handle.

45

EOPNOTSUPP

flags are not supported.

57

ENOTCONN

The socket is not in a connected state.

Remarks

The recvmsg function is normally used with connectionless sockets because the application can retrieve the source address of the received data.

From a message-based socket, such as a SOCK_DGRAM socket, the entire message is read in a single operation. If a message is too long to fit in the supplied buffer, and MSG_PEEK is not set in the flags argument, the excess bytes are discarded.

From a stream-based socket, such as a SOCK_STREAM socket, data is returned to a user as soon as it is available and no data is discarded.

If data is not available at the socket, one of the following occurs:

  • If the O_NONBLOCK flag is not set on the socket handle, the recvmsg function blocks.

  • If the socket is nonblocking because the O_NONBLOCK flag is set on the socket handle, recvmsg returns -1 and sets errno to EWOULDBLOCK.

Call select to determine when more data arrives.

MSG_OOB is used only with TCP sockets. MSG_OOB actually refers to the byte of data following a TCP urgent boundary. After the socket client has discovered new out-of-band data (by calling select for exceptions) and has read normal data up to the out-of-band byte, it reads one byte of out-of-band data by setting the MSG_OOB flag.

MSG_PEEK permits the socket client to look at a message or STREAM data without removing it from the socket.

See Also