recvmsg()

receive message from socket and store in structure 

Function

SYNOPSIS

#include <sys/socket.h>

int recvmsg(int s, struct msghdr *message, int flags);

DESCRIPTION

The recvmsg() system call receives a message from a socket and capture the address from which the data was sent. Unlike the recv() call, which can only be used on a connected stream socket or bound datagram socket, recvmsg() can be used to receive data on a socket whether or not it is connected. If no messages are available at the socket, the recvmsg() call waits for a message to arrive unless the socket is nonblocking. If a socket is nonblocking, -1 is returned and the external variable errno is set to EWOULDBLOCK. select() can be used to wait for incoming messages.

For a SOCK_STREAM socket, as much information is returned as is currently available, up to the size of the specified buffer. If the socket has been configured for inline reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data is returned. The application may use the ioctl() SIOCATMARK to determine whether any more out-of-band data remain to be read.

For SOCK_DGRAM sockets, data is extracted from the first queued message, up to the size of the specified buffer. If the datagram or message is larger than the specified buffer, as much data are stored in the buffer as possible and recvmsg() generates an error message (EMSGSIZE). The remainder (or excess) of the message is lost if passed via an unreliable protocol.

If from is nonzero and the socket is not connection-oriented, the network address of the peer that sent the data is copied to the corresponding structure sockaddr. The value returned by fromlen is initialized to the size of this structure and is modified on return to indicate the actual size of the address stored there.

If the socket is connection-oriented and the remote side has shut down the connection gracefully, a recvmsg() call completes immediately with 0 bytes received. If the connection has been reset, recvmsg() fails and returns the error message ECONNRESET.

flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

MSG_PEEK 

Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.

MSG_OOB 

Process out-of-band data.

PARAMETERS

s 

Specifies a socket descriptor from which data should be received.

message 

Points to a msghdr structure which contains both the buffer which is to contain the source address, plus the address of buffers into which the incoming message is stored. The msg_flags field is ignored.

flags 

Allows the caller to control the reception by peeking at incoming data (MSG_PEEK)or by sending or receiving out-of-band data (MSG_OOB).

RETURN VALUES

If successful, recvmsg() returns the number of bytes received. On failure, it returns a value of -1 and sets errno to one of the following values:

EBADF 

s is an invalid descriptor

ECONNABORTED 

The virtual circuit was aborted because of a timeout or other failure.

ECONNRESET 

The virtual circuit was reset by the remote host executing a hard or abortive close.

EFAULT 

buf is an invalid pointer.

EINTR 

A signal interrupted the recvmsg() call

EINVAL 

Socket has not been bound using bind(), or an invalid flag was specified, or len was 0 or negative.

EMSGSIZE 

The message was too large to be stored in the specified buffer and was truncated.

ENETDOWN 

The network subsystem has failed.

ENETRESET 

The connection is broken; the remote host reset.

ENOTCONN 

The socket was not connected.

ENOTSOCK 

s is not a socket descriptor

EOPNOTSUPP 

MSG_OOB was specified on socket that does not support out of band data.

ESHUTDOWN 

The socket has been shut down.

ETIMEDOUT 

The connection has been dropped because of a network failure.

EWOULDBLOCK 

s is nonblocking and recvmsg() would block

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

The recvmsg() function is only supported for sockets created with the AF_UNIX address family.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
bind(), connect(), ioctl(), read(), recv(), recvfrom(), send(), sendmsg(), sendto(), socket()

PTC MKS Toolkit 10.4 Documentation Build 39.