calmsacibis995
200 lines
4.7 KiB
Plaintext
200 lines
4.7 KiB
Plaintext
'\"macro stdmacro
|
|
.\" Copyright (c) 1983 Regents of the University of California.
|
|
.\" All rights reserved. The Berkeley software License Agreement
|
|
.\" specifies the terms and conditions for redistribution.
|
|
.\"
|
|
.\" @(#)recv.2 6.3 (Berkeley) 5/23/86
|
|
.\"
|
|
.if n .pH man2.recv @(#)recv 30.3 of 2/1/86
|
|
.TH RECV 2
|
|
.UC 5
|
|
.SH NAME
|
|
recv, recvfrom, recvmsg \- receive a message from a socket
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
.PP
|
|
.B "int recv\|(int s, void \(**buf, int len, int flags);"
|
|
.sp .5
|
|
.B "int recvfrom\|(int s, void \(**buf, int len, int flags,"
|
|
.br
|
|
.B " struct sockaddr \(**from, int \(**fromlen);"
|
|
.sp .5
|
|
.B "int recvmsg\|(int s, struct msghdr \(**msg, int flags);"
|
|
.ft 1
|
|
.SH DESCRIPTION
|
|
.IR Recv ,
|
|
.IR recvfrom ,
|
|
and
|
|
.IR recvmsg
|
|
are used to receive messages from a socket.
|
|
.PP
|
|
The
|
|
.I recv
|
|
call is normally used only on a
|
|
.I connected
|
|
socket (see
|
|
.IR connect (2)),
|
|
while
|
|
.I recvfrom
|
|
and
|
|
.I recvmsg
|
|
may be used to receive data on a socket whether
|
|
it is in a connected state or not.
|
|
.PP
|
|
If
|
|
.I from
|
|
is non-zero, the source address of the message is filled in.
|
|
.I Fromlen
|
|
is a value-result parameter, initialized to the size of
|
|
the buffer associated with
|
|
.IR from ,
|
|
and modified on return to indicate the actual size of the
|
|
address stored there.
|
|
A successful call returns the length of the message.
|
|
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
|
|
.IR socket (2)).
|
|
.PP
|
|
If no messages are available at the socket, the
|
|
receive call waits for a message to arrive, unless
|
|
the socket is nonblocking (see
|
|
.IR ioctl (2))
|
|
in which case the call
|
|
returns \-1 with the external variable errno
|
|
set to EWOULDBLOCK.
|
|
.PP
|
|
The
|
|
.IR select (2)
|
|
call may be used to determine when more data arrives.
|
|
.PP
|
|
The
|
|
.I flags
|
|
argument to a recv call is formed by
|
|
.IR or 'ing
|
|
one or more of the values,
|
|
.PP
|
|
.nf
|
|
.\".RS
|
|
.\".ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u
|
|
\0\0#define MSG_OOB 0x1 /* process out-of-band data */
|
|
.br
|
|
\0\0#define MSG_PEEK 0x2 /* peek at incoming message */
|
|
.br
|
|
\0\0#define MSG_WAITALL 0x40 /* wait for full request or error */
|
|
.br
|
|
\0\0#define MSG_DONTWAIT 0x80 /* this message should be nonblocking */
|
|
.\".RE
|
|
.fi
|
|
.PP
|
|
The
|
|
.I recvmsg
|
|
call uses a
|
|
.I msghdr
|
|
structure to minimize the number of directly supplied parameters.
|
|
This structure has the following form, as defined in
|
|
.IR <sys/socket.h> :
|
|
.PP
|
|
.nf
|
|
.RS
|
|
.DT
|
|
struct msghdr {
|
|
caddr_t msg_name; /* optional address */
|
|
int msg_namelen; /* size of address */
|
|
struct iovec *msg_iov; /* scatter/gather array */
|
|
int msg_iovlen; /* # elements in msg_iov */
|
|
caddr_t msg_accrights; /* access rights sent/received */
|
|
int msg_accrightslen;
|
|
};
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Here
|
|
.I msg_name
|
|
and
|
|
.I msg_namelen
|
|
specify the destination address if the socket is unconnected;
|
|
.I msg_name
|
|
may be given as a null pointer if no names are desired or required.
|
|
The
|
|
.I msg_iov
|
|
and
|
|
.I msg_iovlen
|
|
describe the scatter/gather locations.
|
|
The
|
|
.I iovec
|
|
structure is defined as
|
|
.PP
|
|
.nf
|
|
.RS
|
|
.DT
|
|
struct iovec {
|
|
caddr_t iov_base;
|
|
int iov_len;
|
|
};
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Each
|
|
.I iovec
|
|
entry specifies the base address and length of an area
|
|
in memory where data should be placed.
|
|
.I recvmsg
|
|
will always fill an area completely before proceeding
|
|
to the next.
|
|
.PP
|
|
A buffer to receive any access rights sent along with the message is specified
|
|
in
|
|
.IR msg_accrights ,
|
|
which has length
|
|
.IR msg_accrightslen .
|
|
Access rights are opaque data that
|
|
are interpreted within the context of the communication
|
|
domain and are currently limited to file descriptors,
|
|
which each occupy the size of an
|
|
.BR int
|
|
(see
|
|
.IR unix (7F)
|
|
for details).
|
|
.SH "RETURN VALUE
|
|
These calls return the number of bytes received, or \-1
|
|
if an error occurred.
|
|
.SH ERRORS
|
|
The calls fail if:
|
|
.TP 20
|
|
[EBADF]
|
|
The argument \f2s\fP is an invalid descriptor.
|
|
.TP 20
|
|
[ENOTSOCK]
|
|
The argument \f2s\fP is not a socket.
|
|
.TP 20
|
|
[EWOULDBLOCK]
|
|
The socket is marked non-blocking and the receive operation
|
|
would block.
|
|
.TP 20
|
|
[EINTR]
|
|
The receive was interrupted by delivery of a signal before
|
|
any data was available for the receive.
|
|
.TP 20
|
|
[EFAULT]
|
|
The data was specified to be received into a non-existent
|
|
or protected part of the process address space.
|
|
.SH SEE ALSO
|
|
fcntl(2), getsockopt(2), read(2), select(2), send(2), socket(2)
|
|
.SH NOTES
|
|
ABI-compliant versions of the above calls can be obtained from
|
|
.IR libsocket.so .
|
|
.PP
|
|
When using
|
|
.I recvmsg
|
|
to receive access rights, it may be necessary for the application to
|
|
request a single byte of normal data as well, so that the
|
|
call does not return immediately if the access rights are not yet present.
|
|
Doing so will cause the
|
|
.I recvmsg
|
|
call to block until the access rights are available.
|
|
'\".so /pubs/tools/origin.bsd
|