recvmsg Subroutine

Purpose

Receives a message from any socket.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
int recvmsg ( Socket,  Message,  Flags)
int Socket;
struct msghdr Message [ ];
int Flags;
int recvmmsg ( Socket, MessageVec, Num_msg,  Flags, Timeout)
int Socket;
struct mmsghdr MessageVec [ ];
unsigned int Num_msg ;
int Flags;
struct timespec *Timeout

Description

The recvmsg subroutine receives messages from unconnected or connected sockets. The recvmsg subroutine returns the length of the message. If a message is too long to fit in the supplied buffer, excess bytes may be truncated depending on the type of socket that issued the message.

If no messages are available at the socket, the recvmsg subroutine waits for a message to arrive. If the socket is nonblocking and no messages are available, the recvmsg subroutine is unsuccessful.

Use the select subroutine to determine when more data arrives.

The recvmsg subroutine uses a msghdr structure to decrease the number of directly supplied parameters. The msghdr structure is defined in thesys/socket.h file. In BSD 4.3 Reno, the size and members of the msghdr structure have been modified. Applications wanting to start the old structure need to compile with COMPAT_43 defined. The default behavior is that of BSD 4.4.

All applications containing the recvmsg subroutine must be compiled with the _BSD macro set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

The recvmmsg subroutine is an extension of the recvmsg subroutine that receives multiple messages from a socket to the caller socket. This subroutine has performance benefits for some applications. The recvmmsg subroutine supports timeout for wait during the receive operation.

The sockfd argument is the file descriptor of the socket from which data is received. The msgvec argument is a pointer to an array of mmsghdr structures. These arguments are defined in the sys/socket.h file.

On return from the recvmmsg subroutine, successive elements of the msgvec structure are updated to contain information about each received message. The msg_len field contains the size of the received message. The sub fields of the msg_hdr field are updated as described in the recvmsg subroutine. The return value of the recvmsg call indicates the number of elements of the msgvec field that are updated.

Parameters

Item Description
Socket Specifies the unique name of the socket.
Message Points to the address of the msghdr structure, which contains both the address for the incoming message and the space for the sender address.
Flags Permits the subroutine to exercise control over the reception of messages. The Flags parameter that is used to receive a call is formed by logically ORing one or more of the values which are shown in the following list:
MSG_OOB
Processes out-of-band data. The significance of out-of-band data is protocol-dependent.
MSG_PEEK
Peeks at incoming data. The data continues to be treated as unread and will be read by the next call to recv() or a similar function.
MSG_WAITALL
Requests that the function not return until the requested number of bytes have been read. The function can return fewer than the requested number of bytes only if a signal is caught, the connection is terminated, or an error is pending for the socket.
MSG_WAITFORONE
Turns on the MSG_DONTWAIT flag after the first message is received.

The /sys/socket.h file contains the possible values for the Flags parameter.
MessageVec Points to an array of mmsghdr structures, which contain msghdr structures for incoming messages, space for the sender address and a  value that represents the total number of elements in the array.
Num_msg Defines the number of messages to receive before the control is returned to the calling socket.
Timeout

The timeout argument points to a timespec structure that defines a timeout value(specified in seconds plus nanoseconds) for the receive operation. If the timeout value is NULL a call to the recvmmsg subroutine is blocked until the vlen messages are received or until the timeout value expires. A nonblocking call to the recvmmsg subroutine reads all messages that are available (the limit is specified by the vlen parameter) at the sender socket and returns from the subroutine to the calling function immediately.

Return Values

Upon successful completion of recvmsg subroutine, the length of the message in bytes is returned and for the recvmmsg subroutine, the number of received messages is returned.

If the recvmsg or the recvmmsg subroutine is unsuccessful, the subroutine handler performs the following functions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

The recvmsg subroutine is unsuccessful if any of the following error codes occurs:

Error Description
EBADF The Socket parameter is not valid.
ECONNRESET The remote peer forces the connection to be closed.
EFAULT The Address parameter is not in a writable part of the user address space.
EINTR The recvmsg subroutine was interrupted by delivery of a signal before any data was available for the receive.
EINVAL The length of the msghdr structure is invalid, or the MSG_OOB flag is set and no out-of-band data is available.
EMSGSIZE The msg_iovlen member of the msghdr structure pointed to by Message is less than or equal to 0, or is greater than IOV_MAX.
ENOBUF Insufficient resources are available in the system to perform the operation.
ENOPROTOOPT The protocol is not 64-bit supported.
ENOTCONN A receive is attempted on a SOCK_STREAM socket that is not connected.
ENOTSOCK The Socket parameter refers to a file, not a socket.
EOPNOTSUPP MSG_OOB flag is set for a SOCK_DGRAM socket, or MSG_OOB flag is set for any AF_UNIX socket.
ETIMEDOUT The connection timed out during connection establishment, or there was a transmission timeout on an active connection.
EWOULDBLOCK The socket is marked nonblocking, and no connections are present to be accepted.