recv(3sock)
recv --
receive a message from a socket
Synopsis
cc [options] file -lsocket -lnsl
#include <sys/types.h>
#include <sys/socket.h>
ssize_t recv(int socket, void *buf, size_t len, int flags);
ssize_t recvfrom(int socket, void *buf, size_t len, int flags,
struct sockaddr *from, size_t *fromlen);
ssize_t recvmsg(int socket, struct msghdr *msg, int flags);
Description
socket is a socket file descriptor that has been
created using socket.
recv, recvfrom, and recvmsg
are used to receive messages from another socket.
recv may be used only on a
connected
socket (see
connect(3sock)),
while recvfrom and
recvmsg may be used to receive data on a socket whether
it is in a connected state or not.
recvfrom is commonly used with connectionless sockets because it
allows the source address to be extracted from received data.
If
from
is not a
NULL
pointer, the source address of the message is filled in.
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 length of the message is returned.
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(3sock)).
For message-based sockets such as
SOCK_DGRAM and SOCK_SEQPACKET,
the entire message must be read in a single operation.
If a message is too long to fit in the supplied buffer,
and MSG_PEEK is not
set in flags, excess bytes are discarded.
For stream-based sockets such as SOCK_STREAM,
message boundaries are ignored.
As soon as it becomes available, data is returned to the user.
No data is discarded in this case.
If no messages are available at the socket and
O_NONBLOCK is not set on its file descriptor,
the receive call waits for a message to arrive,
unless the socket is nonblocking (see
fcntl(2))
in which case -1 is returned with the external variable
errno set to
EWOULDBLOCK.
The select
call may be used to determine when more data arrives.
The
flags
parameter is formed by
ORing
one or more of the following:
MSG_OOB-
Read any out-of-band data present on the
socket rather than the regular in-band data.
MSG_PEEK-
``Peek'' at the data present on the socket;
the data is returned, but not consumed,
so that a subsequent receive operation will see
the same data.
MSG_WAITALL-
Block until the full amount of requested data can be returned.
May return a smaller amount of data if a signal is caught,
the connection is
terminated or an error is pending for the socket.
The recvmsg call uses a msghdr
structure to minimize the number of directly supplied parameters.
This structure is defined in sys/socket.h
and includes the following members:
void * msg_name; /* optional address */
size_t msg_namelen; /* size of address */
struct iovec * msg_iov; /* scatter/gather array */
int msg_iovlen; /* number of elements in msg_iov */
void * msg_accrights; /* access rights sent/received */
int msg_accrightslen;
void * msg_control;
size_t msgcontrollen;
int msg_flags;
msg_name
and msg_namelen
specify the source address if the socket is unconnected;
msg_name
may be given as a NULL
pointer if no names are desired or required.
The msg_iov
and msg_iovlen
describe the scatter-gather locations, as described in read.
A buffer to receive any access rights sent along with the message is specified
in msg_accrights
, which has length msg_accrightslen
.
Files
/usr/lib/locale/locale/LC_MESSAGES/uxnsl
Return values
These calls return the number of bytes received,
or -1 if an error occurred.
recv returns 0 if the peer has performed
an orderly shutdown and no messages
are available to be received.
Errors
The calls fail if:
EBADF-
socket
is an invalid descriptor.
ECONNREFUSED-
No socket was open to the peer for a previous send.
ECONNRESET-
A connection was forcibly closed by a peer.
EHOSTDOWN-
The peer was down for a previous send.
ENOTSOCK-
socket is a descriptor for a file, not a socket.
EINTR-
The operation was interrupted by delivery of a signal before
any data was available to be received.
EINVAL-
MSG_OOB is set and there is no available out-of-band data.
ENOTCONN-
A receive is attempted on a connection-oriented socket that is not connected.
EWOULDBLOCK-
The socket is marked non-blocking and the requested operation
would block.
EOPNOTSUPP-
The specified flags are not supported for this socket type or protocol.
ETIMEDOUT-
The connection timed out during connection or because of a transmission timeout on
active connection.
EIO-
An I/O error occurred while reading to or writing from the file system.
ENOBUFS-
System resources were insufficient to perform the operation.
ENOMEM-
There was insufficient user memory available for the operation to
complete.
ENOSR-
There were insufficient
STREAMS
resources available for the operation
to complete.
References
connect(3sock),
fcntl(2),
getsockopt(3sock),
ioctl(2),
read(2)
send(3sock),
socket(3sock)
RFC 2133
Notices
The type of address structure passed to recvfrom and
recvmsg depends on the address family.
UNIX® domain sockets (address family AF_UNIX) require a
sockaddr_un structure as defined in sys/un.h;
Internet domain IPv4 sockets (address family AF_INET)
require a struct sockaddr_in structure as defined in
netinet/in.h;
Internet domain IPv6 sockets (address family AF_INET6)
require a struct sockaddr_in6 structure as defined in
netinet/in.h.
Other address families may require other structures.
Use the structure appropriate to the address family; cast the
structure address to a struct sockaddr* in the call to
recvfrom
and pass the size of the structure in the fromlen argument. If
you are using recvmsg, set msghdr.msg_name
to point
to the appropriate structure and msghdr.msg_namelen
to the
length of the structure.
In UnixWare 7 the sockaddr structure has been modified
to support variable length sockets. The net result of this modification
is that the family
member has been shortened to 8 bits and a
new 8-bit member inserted before it called len
. For more
information on the new sockaddr structures, see:
unix(7sock)
and
inet(7tcp).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004