Technical Reference: Communications, Volume 2

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;

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 _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Parameters

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 used to receive a call is formed by logically ORing one or more of the values 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.

The /sys/socket.h file contains the possible values for the Flags parameter.

Return Values

Upon successful completion, the length of the message in bytes is returned.

If the recvmsg 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.
ENOTSOCK	The Socket parameter refers to a file, not a socket.
EWOULDBLOCK	The socket is marked nonblocking, and no connections are present to be accepted.
EINTR	The recvmsg subroutine was interrupted by delivery of a signal before any data was available for the receive.
EFAULT	The Address parameter is not in a writable part of the user address space.

Related Information

The no command.

The recv subroutine, recvfrom subroutine, select subroutine, send subroutine, sendmsg subroutine, sendto subroutine, shutdown subroutine, socket subroutine.

Sockets Overview and Understanding Socket Data Transfer in AIX 5L Version 5.2 Communications Programming Concepts.