OSF

NAME

recvmsg −  Receives a message from a socket

SYNOPSIS

#include <sys/types.h> #include <sys/socket.h> int recvmsg(
int socket,
int flags ) ;

PARAMETERS

socketSpecifies a unique name of the socket. 

messagePoints to a msghdr structure, containing both the address for the incoming message and the buffers for the source address.  The format of the address is determined by the behavior requested for the socket.  If the compile-time option _SOCKADDR_LEN is defined before the sys/socket.h header file is included, the msghdr structure takes 4.4BSD behavior.  Otherwise, the default 4.3BSD msghdr structure is used. 

In 4.4BSD, the msghdr structure has a separate msg_flags field for holding flags from the received message.  In addition, the msg_accrights field is generalized into a msg_control field.  See DESCRIPTION for more information.  If _SOCKADDR_LEN is defined, the 4.3BSD msghdr structure is defined with the name omsghdr. 

flagsPermits the caller of this function to exercise control over the reception of messages.  The value for this parameter is formed by a logical OR of one or both of the following values:

MSG_PEEKPeeks at the incoming message. 

MSG_OOBProcesses out-of-band data. 

DESCRIPTION

The recvmsg() function receives messages from unconnected or connected sockets and returns the length of the message.  When a message is too long for the buffer, the message may be truncated depending on the type of socket from which the the message is written. 

When no messages are available at the socket specified by the socket parameter, the recvmsg() function waits for a message to arrive. When the socket is nonblocking and no message is available, the recvmsg() function fails and sets errno to [EWOULDBLOCK]. 

Use the select() function to determine when more data arrives. 

In the msghdr structure, the msg_name and msg_namelen fields specify the destination address if the socket is unconnected.  The msg_name field may be given as a null pointer if no names are desired or required.  The msg_iov and msg_iovlen fields describe the scatter gather locations. 

In 4.3BSD, the msg_accrights field is a buffer for passing access rights.  In 4.4BSD, the msg_accrights field has been expanded into a msg_control field, to include other protocol control messages or other miscellaneous ancillary data. 

In the 4.4BSD msghdr structure, the msg_flags field holds flags from the received message.  In addition to MSG_PEEK and MSG_OOB, the incoming flags reported in the msg_flags field can be any of the following values:

MSG_EORData includes the end-of-record marker. 

MSG_TRUNC
Data was truncated before delivery.

MSG_CTRUNC
Control data was truncated before delivery.

RETURN VALUES

Upon successful completion, the recvmsg() function returns the length of the message in bytes, and fills in the fields of the msghdr structure pointed to by the message parameter as appropriate.  Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the recvmsg() function fails, errno may be set to one of the following values:

[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 data is ready to be received.

[EINTR]This function was interrupted by a signal before any data was available. 

[EFAULT]The message parameter is not in a readable or writable part of user address-space. 

RELATED INFORMATION

Functions: recv(2), recvfrom(2), send(2), sendmsg(2), sendto(2), select(2), shutdown(2), socket(2)