Chapter Contents

Previous

Next
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

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.