.sp
.BI "ssize_t recv(int " s ", void *" buf ", size_t " len ", int " flags );
.sp
-.BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " len ", int " flags ,
+.BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " len ", int " flags ,
.BI " struct sockaddr *" from ", socklen_t *" fromlen );
.sp
.BI "ssize_t recvmsg(int " s ", struct msghdr *" msg ", int " flags );
and modified on return to indicate the actual size of the address stored
there.
.PP
-The
+The
.BR recv ()
-call is normally used only on a
+call is normally used only on a
.I connected
socket (see
.BR connect (2))
.BR recvfrom ()
with a NULL
.I from
-parameter.
+parameter.
.PP
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
+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.
.PP
amount, rather than waiting for receipt of the full amount requested.
.PP
The
-.BR select (2)
+.BR select (2)
or
.BR poll (2)
call may be used to determine when more data arrives.
.PP
The
.I flags
-argument to a
+argument to a
.BR recv ()
-call is formed by
+call is formed by
.IR OR 'ing
one or more of the following values:
.TP
The error is passed in
an ancillary message with a type dependent on the protocol (for IPv4
.BR IP_RECVERR ).
-The user should supply a buffer of sufficient size. See
+The user should supply a buffer of sufficient size.
+See
.BR cmsg (3)
and
.BR ip (7)
is regenerated based on the next queued error and will be passed
on the next socket operation.
-The error is supplied in a
+The error is supplied in a
.I sock_extended_err
structure:
.in +0.25i
struct sock_extended_err
{
u_int32_t ee_errno; /* error number */
- u_int8_t ee_origin; /* where the error originated */
+ 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 */
+ u_int32_t ee_data; /* other data */
+ /* More data may follow */
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
.fi
.in -0.25i
.IP
-.B ee_errno
-contains the errno number of the queued error.
+.B ee_errno
+contains the errno number of the queued error.
.B ee_origin
-is the origin code of where the error originated.
-The other fields are protocol specific. The macro
-.B SOCK_EE_OFFENDER
+is the origin code of where the error originated.
+The other fields are protocol specific.
+The macro
+.B 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
-.I sa_family
-member of the
-.B sockaddr
-contains
+.I sa_family
+member of the
+.B sockaddr
+contains
.B AF_UNSPEC
-and the other fields of the
-.B sockaddr
-are undefined. The payload of the packet
-that caused the error is passed as normal data.
+and the other fields of the
+.B sockaddr
+are undefined.
+The payload of the packet that caused the error is passed as normal data.
.IP
For local errors, no address is passed (this
-can be checked with the
-.I cmsg_len
-member of the
-.IR cmsghdr ).
+can be checked with the
+.I cmsg_len
+member of the
+.IR cmsghdr ).
For error receives,
-the
-.B MSG_ERRQUEUE
-is set in the
-.IR msghdr .
+the
+.B MSG_ERRQUEUE
+is set in the
+.IR 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.
.TP
.B 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
+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.
.TP
.B 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
+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.
.TP
.B MSG_TRUNC
Return the real length of the packet, even when it was longer than
-the passed buffer. Only valid for packet sockets.
+the passed buffer.
+Only valid for packet sockets.
.TP
.B 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
+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.
.PP
The
.BR recvmsg ()
-call uses a
+call uses a
.I msghdr
-structure to minimize the number of directly supplied parameters. This
-structure has the following form, as defined in
+structure to minimize the number of directly supplied parameters.
+This structure has the following form, as defined in
.IR <sys/socket.h> :
.in +0.25i
.nf
.IR msg_control ,
which has length
.IR msg_controllen ,
-points to a buffer for other protocol control related messages or
-miscellaneous ancillary data. When
+points to a buffer for other protocol control related messages or
+miscellaneous ancillary data.
+When
.BR recvmsg ()
-is called,
+is called,
.I msg_controllen
-should contain the length of the available buffer in
-.IR msg_control ;
+should contain the length of the available buffer in
+.IR msg_control ;
upon return from a successful call it will contain the length
of the control message sequence.
.PP
.fi
.in -0.25i
.PP
-Ancillary data should only be accessed by the macros defined in
+Ancillary data should only be accessed by the macros defined in
.BR cmsg (3).
.PP
As an example, Linux uses this auxiliary data mechanism to pass extended
-errors, IP options or file descriptors over Unix sockets.
+errors, IP options or file descriptors over Unix sockets.
.PP
The
.I msg_flags
error queue.
.SH "RETURN VALUE"
These calls return the number of bytes received, or \-1
-if an error occurred. The return value will be 0 when the
+if an error occurred.
+The return value will be 0 when the
peer has performed an orderly shutdown.
.SH 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.
+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.
.TP
.B EAGAIN
The socket is marked non-blocking and the receive operation
any data were available.
.TP
.B EINVAL
-Invalid argument passed.
+Invalid argument passed.
.\" e.g., msg_namelen < 0 for recvmsg() or fromlen < 0 for recvfrom()
.TP
.B ENOMEM
-Could not allocate memory for
-.BR recvmsg ().
+Could not allocate memory for
+.BR recvmsg ().
.TP
.B ENOTCONN
The socket is associated with a connection-oriented protocol
.I msghdr
structure should be typed as
.IR socklen_t ,
-but glibc currently (2.4) types it as
+but glibc currently (2.4) types it as
.IR size_t .
.\" glibc bug raised 12 Mar 2006
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
projects / thirdparty / man-pages.git / blobdiff