View Source: recvfrom(2) - Waikato Linux Users Group

You are viewing an old revision of this page. View the current version.
RECV
!!!RECV
NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
CONFORMING TO
NOTE
SEE ALSO
----
!!NAME


recv, recvfrom, recvmsg - receive a message from a socket
!!SYNOPSIS


__#include __
#include __


__int recv(int__ ''s''__, void *__''buf''__,
size_t__ ''len''__, int__
''flags''__);__


__int recvfrom(int__ ''s''__, void
*__''buf''__, size_t__ ''len''__, int__
''flags''__, struct sockaddr *__''from''__,
socklen_t *__''fromlen''__);__


__int recvmsg(int__ ''s''__, struct msghdr
*__''msg''__, int__
''flags''__);__
!!DESCRIPTION


The __recvfrom__ and __recvmsg__ calls are used to
receive messages from a socket, and may be used to receive
data on a socket whether or not it is
connection-oriented.


If ''from'' is not NULL, and the socket is not
connection-oriented, the source address of the message is
filled in. The argument ''fromlen'' is a value-result
parameter, initialized to the size of the buffer associated
with ''from'', and modified on return to indicate the
actual size of the address stored there.


The __recv__ call is normally used only on a
''connected'' socket (see connect(2)) and is
identical to __recvfrom__ with a NULL ''from''
parameter.


All three routines return the length of the message on
successful completion. If a message is too long to fit in
the supplied buffer, excess bytes may be discarded depending
on the type of socket the message is received from (see
socket(2)).


If no messages are available at the socket, the receive
calls wait for a message to arrive, unless the socket is
nonblocking (see fcntl(2)) in which case the value -1
is returned and the external variable ''errno'' set to
__EAGAIN__. The receive calls normally return any data
available, up to the requested amount, rather than waiting
for receipt of the full amount requested.


The select(2) or poll(2) call may be used to
determine when more data arrives.


The ''flags'' argument to a recv call is formed by
''OR'''ing one or more of the following
values:


__MSG_OOB__


This flag requests receipt of out-of-band data that would
not be received in the normal data stream. Some protocols
place expedited data at the head of the normal data queue,
and thus this flag cannot be used with such
protocols.


__MSG_PEEK__


This flag causes the receive operation to return data from
the beginning of the receive queue without removing that
data from the queue. Thus, a subsequent receive call will
return the same data.


__MSG_WAITALL__


This flag requests that the operation block until the full
request is satisfied. However, the call may still return
less data than requested if a signal is caught, an error or
disconnect occurs, or the next data to be received is of a
different type than that returned.


__MSG_NOSIGNAL__


This flag turns off raising of __SIGPIPE__ on stream
sockets when the other end disappears.


__MSG_TRUNC__


Return the real length of the packet, even when it was
longer than the passed buffer. Only valid for packet
sockets.


__MSG_ERRQUEUE__


This flag specifies that queued errors should be received
from the socket error queue. The error is passed in an
ancillary message with a type dependent on the protocol (for
IPv4 __IP_RECVERR__). The user should supply a buffer of
sufficient size. See cmsg(3) and ip(7) for
more information. The payload of the original packet that
caused the error is passed as normal data via
__msg_iovec__. The original destination address of the
datagram that caused the error is supplied via
__msg_name__.


For local errors, no address is passed (this can be checked
with the ''cmsg_len'' member of the __cmsghdr__). For
error receives, the __MSG_ERRQUEUE__ is set in the
__msghdr__. After an error has been passed, the pending
socket error is regenerated based on the next queued error
and will be passed on the next socket
operation.


The error is supplied in a __sock_extended_err__
structure:


#define SO_EE_ORIGIN_NONE       0
#define SO_EE_ORIGIN_LOCAL      1
#define SO_EE_ORIGIN_ICMP       2
#define SO_EE_ORIGIN_ICMP6      3
struct sock_extended_err
{
u_int32_t       ee_errno;   /* error number */
u_int8_t        ee_origin;  /* where the error originated */
u_int8_t        ee_type;    /* type */
u_int8_t        ee_code;    /* code */
u_int8_t        ee_pad;
u_int32_t       ee_info;    /* additional information */
u_int32_t       ee_data;    /* other data */
/* More data may follow */
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);


__ee_errno__ contains the errno number of the queued
error. __ee_origin__ is the origin code of where the
error originated. The other fields are protocol specific.
The macro __SOCK_EE_OFFENDER__ returns a pointer to the
address of the network object where the error originated
from given a pointer to the ancillary message. If this
address is not known, the ''sa_family'' member of the
__sockaddr__ contains __AF_UNSPEC__ and the other
fields of the __sockaddr__ are undefined. The payload of
the packet that caused the error is passed as normal
data.


For local errors, no address is passed (this can be checked
with the ''cmsg_len'' member of the __cmsghdr__). For
error receives, the __MSG_ERRQUEUE__ is set in the
__msghdr__. After an error has been passed, the pending
socket error is regenerated based on the next queued error
and will be passed on the next socket
operation.


The __recvmsg__ call uses a ''msghdr'' structure to
minimize the number of directly supplied parameters. This
structure has the following form, as defined in
'''':


struct msghdr {
void         * msg_name;     /* optional address */
socklen_t    msg_namelen;    /* size of address */
struct iovec * msg_iov;      /* scatter/gather array */
size_t       msg_iovlen;     /* # elements in msg_iov */
void         * msg_control;  /* ancillary data, see below */
socklen_t    msg_controllen; /* ancillary data buffer len */
int          msg_flags;      /* flags on received message */
};


Here ''msg_name'' and ''msg_namelen'' specify the
destination address if the socket is unconnected;
''msg_name'' may be given as a null pointer if no names
are desired or required. The fields ''msg_iov'' and
''msg_iovlen'' describe scatter-gather locations, as
discussed in readv(2). The field ''msg_control'',
which has length ''msg_controllen'', points to a buffer
for other protocol control related messages or miscellaneous
ancillary data. When __recvmsg__ is called,
''msg_controllen'' should contain the length of the
available buffer in ''msg_control''; upon return from a
successful call it will contain the length of the control
message sequence.


The messages are of the form:


struct cmsghdr {
socklen_t   cmsg_len;   /* data byte count, including hdr */
int         cmsg_level; /* originating protocol */
int         cmsg_type;  /* protocol-specific type */
/* followed by
u_char      cmsg_data[[]; */
};


Ancillary data should only be accessed by the macros defined
in cmsg(3).


As an example, Linux uses this auxiliary data mechanism to
pass extended errors, IP options or file descriptors over
Unix sockets.


The ''msg_flags'' field in the msghdr is set on return of
__recvmsg__(). It can contain several flags:


__MSG_EOR__


indicates end-of-record; the data returned completed a
record (generally used with sockets of type
__SOCK_SEQPACKET__).


__MSG_TRUNC__


indicates that the trailing portion of a datagram was
discarded because the datagram was larger than the buffer
supplied.


__MSG_CTRUNC__


indicates that some control data were discarded due to lack
of space in the buffer for ancillary data.


__MSG_OOB__


is returned to indicate that expedited or out-of-band data
were received.


__MSG_ERRQUEUE__


indicates that no data was received but an extended error
from the socket error queue.


__MSG_DONTWAIT__


Enables non-blocking operation; if the operation would
block, __EAGAIN__ is returned (this can also be enabled
using the __O_NONBLOCK__ with the __F_SETFL
fcntl__(2)).
!!RETURN VALUE


These calls return the number of bytes received, or -1 if an
error occurred.
!!ERRORS


These are some standard errors generated by the socket
layer. Additional errors may be generated and returned from
the underlying protocol modules; see their manual
pages.


__EBADF__


The argument ''s'' is an invalid descriptor.


__ECONNREFUSED__


A remote host refused to allow the network connection
(typically because it is not running the requested
service).


__ENOTCONN__


The socket is associated with a connection-oriented protocol
and has not been connected (see connect(2) and
accept(2)).


__ENOTSOCK__


The argument ''s'' does not refer to a
socket.


__EAGAIN__


The socket is marked non-blocking and the receive operation
would block, or a receive timeout had been set and the
timeout expired before data was received.


__EINTR__


The receive was interrupted by delivery of a signal before
any data were available.


__EFAULT__


The receive buffer pointer(s) point outside the process's
address space.


__EINVAL__


Invalid argument passed.
!!CONFORMING TO


4.4BSD (these function calls first appeared in
4.2BSD).
!!NOTE


The prototypes given above follow glibc2. The Single Unix
Specification agrees, except that it has return values of
type `ssize_t' (while BSD 4.* and libc4 and libc5 all have
`int'). The ''flags'' argument is `int' in BSD 4.*, but
`unsigned int' in libc4 and libc5. The ''len'' argument
is `int' in BSD 4.*, but `size_t' in libc4 and libc5. The
''fromlen'' argument is `int *' in BSD 4.*, libc4 and
libc5. The present `socklen_t *' was invented by POSIX. See
also accept(2).
!!SEE ALSO


fcntl(2), read(2), select(2),
getsockopt(2), socket(2),
cmsg(3)
----
8 pages link to recvfrom(2):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Version 1, saved on Tuesday, June 4, 2002 12:23:45 am by "perry"
Edit PageHistory Diff Info LikePages
Upcoming meetings

Past meetings
