recvmsg

recvmsg

Receives Data from a Connected or Unconnected Socket Descriptor

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
PORTABILITY
RELATED FUNCTIONS

SYNOPSIS

#include <sys/types.h>
#include <sys/uio.h>
#include <sys/socket.h>

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

DESCRIPTION

recvmsg receives data from an unconnected or connected socket descriptor s . mh points to a structure that contains further parameters. The definition of the msghdr structure is in the <sys/socket.h> header file. The elements of this structure are as follows:

msg_name: points to a structure in which recvmsg stores the source address of the message that is being received. This field can be NULL if the socket s is connected, or if the application doesn't require information on the source address.
msg_namelen: is the length of the buffer pointed to by msg_name .
msg_iov: points to an array of struct iovec similar to that used by readv .
msg_iovlen: is the number of elements in the array pointed to by msg_iov .
msg_accrights: is ignored for AF_INET .
msg_accrightslen: is ignored for AF_INET .

flags consists of the following:

MSG_OOB: processes a single byte of out-of-band data if data are present. If out-of-band data have been moved inline with the SO_OOBINLINE socket option, multiple bytes of data can be accessed, and the MSG_OOB option is not necessary.
MSG_PEEK: peeks at the incoming message. The data remain available for the next recvmsg call.

RETURN VALUE

If recvmsg succeeds, it returns the length of the message. If recv returns a 0 , it indicates that the connection is closed. Otherwise, it returns a -1 , and sets errno to indicate the type of error. It is possible for recvmsg to return fewer bytes than the total number specified by the iovec elements. This is not an error.

CAUTION

recvmsg is an atomic operation. With UDP, no more than one datagram can be read per call. If you are using datagram sockets, make sure that there is enough buffer space in the I/O vector to contain an incoming datagram.

PORTABILITY

mh is commonly documented as struct msghdr mh[] , implying that the call operates on an array of these structures. In reality, only one structure is modified by the call. For the purposes of clarity, this technical report documents mh in a different way, but the implementation is the same. recvmsg is portable to other environments, including most UNIX systems, that implement BSD sockets.

RELATED FUNCTIONS

connect , getsockopt , recv , recvfrom , send , sendmsg , sendto , setsockopt

Chapter Contents
Previous
Next
Top of Page