| 1 |
27 |
unneback |
<html>
|
| 2 |
|
|
<body>
|
| 3 |
|
|
<pre>
|
| 4 |
|
|
NAME
|
| 5 |
|
|
recvfrom - receive a message from a socket
|
| 6 |
|
|
|
| 7 |
|
|
SYNOPSIS
|
| 8 |
|
|
#include <network.h>
|
| 9 |
|
|
|
| 10 |
|
|
int recvfrom(int s, void *buf, int len, unsigned int flags
|
| 11 |
|
|
struct sockaddr *from, int *fromlen);
|
| 12 |
|
|
|
| 13 |
|
|
DESCRIPTION
|
| 14 |
|
|
The recvfrom call is used to receive messages from a socket,
|
| 15 |
|
|
and may be used to receive data on a socket whether or not it
|
| 16 |
|
|
is connection-oriented.
|
| 17 |
|
|
|
| 18 |
|
|
|
| 19 |
|
|
If from is not NULL, and the socket is not connection-ori
|
| 20 |
|
|
ented, the source address of the message is filled in.
|
| 21 |
|
|
Fromlen is a value-result parameter, initialized to the
|
| 22 |
|
|
size of the buffer associated with from, and modified on
|
| 23 |
|
|
return to indicate the actual size of the address stored
|
| 24 |
|
|
there.
|
| 25 |
|
|
|
| 26 |
|
|
The routine returns the length of the message on
|
| 27 |
|
|
successful completion. If a message is too long to fit in
|
| 28 |
|
|
the supplied buffer, excess bytes may be discarded depend
|
| 29 |
|
|
ing on the type of socket the message is received from
|
| 30 |
|
|
(see socket(2)).
|
| 31 |
|
|
|
| 32 |
|
|
If no messages are available at the socket, the receive
|
| 33 |
|
|
calls wait for a message to arrive, unless the socket is
|
| 34 |
|
|
nonblocking (see fcntl(2)) in which case the value -1 is
|
| 35 |
|
|
returned and the external variable errno set to EAGAIN.
|
| 36 |
|
|
The receive calls normally return any data available, up
|
| 37 |
|
|
to the requested amount, rather than waiting for receipt
|
| 38 |
|
|
of the full amount requested.
|
| 39 |
|
|
|
| 40 |
|
|
The select(2) call may be used to determine
|
| 41 |
|
|
when more data arrives.
|
| 42 |
|
|
|
| 43 |
|
|
The flags argument to a recvfrom call is formed by OR'ing one
|
| 44 |
|
|
or more of the following values:
|
| 45 |
|
|
|
| 46 |
|
|
MSG_OOB
|
| 47 |
|
|
This flag requests receipt of out-of-band data that
|
| 48 |
|
|
would not be received in the normal data stream.
|
| 49 |
|
|
Some protocols place expedited data at the head of
|
| 50 |
|
|
the normal data queue, and thus this flag cannot be
|
| 51 |
|
|
used with such protocols.
|
| 52 |
|
|
|
| 53 |
|
|
MSG_PEEK
|
| 54 |
|
|
This flag causes the receive operation to return
|
| 55 |
|
|
data from the beginning of the receive queue with
|
| 56 |
|
|
out removing that data from the queue. Thus, a
|
| 57 |
|
|
subsequent receive call will return the same data.
|
| 58 |
|
|
|
| 59 |
|
|
MSG_WAITALL
|
| 60 |
|
|
This flag requests that the operation block until
|
| 61 |
|
|
the full request is satisfied. However, the call
|
| 62 |
|
|
may still return less data than requested if a sig
|
| 63 |
|
|
nal is caught, an error or disconnect occurs, or
|
| 64 |
|
|
the next data to be received is of a different type
|
| 65 |
|
|
than that returned.
|
| 66 |
|
|
|
| 67 |
|
|
MSG_ERRQUEUE
|
| 68 |
|
|
Receive packet from the error queue
|
| 69 |
|
|
|
| 70 |
|
|
MSG_NOSIGNAL
|
| 71 |
|
|
This flag turns off raising of SIGPIPE on stream
|
| 72 |
|
|
sockets when the other end disappears.
|
| 73 |
|
|
|
| 74 |
|
|
MSG_ERRQUEUE
|
| 75 |
|
|
This flag specifies that queued errors should be
|
| 76 |
|
|
received from the socket error queue. The error is
|
| 77 |
|
|
passed in a ancilliary message with a type depen
|
| 78 |
|
|
dent on the protocol (for IP IP_RECVERR). The
|
| 79 |
|
|
error is supplied in a sock_extended_error struc
|
| 80 |
|
|
ture:
|
| 81 |
|
|
|
| 82 |
|
|
#define SO_EE_ORIGIN_NONE 0
|
| 83 |
|
|
#define SO_EE_ORIGIN_LOCAL 1
|
| 84 |
|
|
#define SO_EE_ORIGIN_ICMP 2
|
| 85 |
|
|
#define SO_EE_ORIGIN_ICMP6 3
|
| 86 |
|
|
|
| 87 |
|
|
struct sock_extended_err
|
| 88 |
|
|
{
|
| 89 |
|
|
__u32 ee_errno; /* error number */
|
| 90 |
|
|
__u8 ee_origin; /* where the error originated */
|
| 91 |
|
|
__u8 ee_type; /* type */
|
| 92 |
|
|
__u8 ee_code; /* code */
|
| 93 |
|
|
__u8 ee_pad;
|
| 94 |
|
|
__u32 ee_info; /* additional information */
|
| 95 |
|
|
__u32 ee_data; /* other data */
|
| 96 |
|
|
};
|
| 97 |
|
|
|
| 98 |
|
|
struct sockaddr *SOCK_EE_OFFENDER(struct sock_extended_err *);
|
| 99 |
|
|
|
| 100 |
|
|
ee_errno contains the errno number of the queued
|
| 101 |
|
|
error. ee_origin is the origin code of where the
|
| 102 |
|
|
error originated. The other fields are protocol
|
| 103 |
|
|
specific. SOCK_EE_OFFENDER returns a pointer to
|
| 104 |
|
|
the address of the network object where the error
|
| 105 |
|
|
originated from. If this address is not known, the
|
| 106 |
|
|
sa_family member of the sockaddr contains AF_UNSPEC
|
| 107 |
|
|
and the other fields of the sockaddr are undefined.
|
| 108 |
|
|
The payload of the packet that caused the error is
|
| 109 |
|
|
passed as normal data.
|
| 110 |
|
|
|
| 111 |
|
|
For local errors, no address is passed (this can be
|
| 112 |
|
|
checked with the cmsg_len member of the cmsghdr).
|
| 113 |
|
|
For error receives, the MSG_ERRQUEUE is set in the
|
| 114 |
|
|
msghdr. After a error has been passed, the pending
|
| 115 |
|
|
socket error is regenerated based on the next
|
| 116 |
|
|
queued error and will be passed on the next socket
|
| 117 |
|
|
operation.
|
| 118 |
|
|
|
| 119 |
|
|
|
| 120 |
|
|
The msg_flags field is set on return according to the mes
|
| 121 |
|
|
sage received. MSG_EOR indicates end-of-record; the data
|
| 122 |
|
|
returned completed a record (generally used with sockets
|
| 123 |
|
|
of type SOCK_SEQPACKET). MSG_TRUNC indicates that the
|
| 124 |
|
|
trailing portion of a datagram was discarded because the
|
| 125 |
|
|
datagram was larger than the buffer supplied. MSG_CTRUNC
|
| 126 |
|
|
indicates that some control data were discarded due to
|
| 127 |
|
|
lack of space in the buffer for ancillary data. MSG_OOB
|
| 128 |
|
|
is returned to indicate that expedited or out-of-band data
|
| 129 |
|
|
were received. MSG_ERRQUEUE indicates that no data was
|
| 130 |
|
|
received but an extended error from the socket error
|
| 131 |
|
|
queue.
|
| 132 |
|
|
|
| 133 |
|
|
RETURN VALUES
|
| 134 |
|
|
These calls return the number of bytes received, or -1 if
|
| 135 |
|
|
an error occurred.
|
| 136 |
|
|
|
| 137 |
|
|
ERRORS
|
| 138 |
|
|
These are some standard errors generated by the socket
|
| 139 |
|
|
layer. Additional errors may be generated and returned
|
| 140 |
|
|
from the underlying protocol modules; see their manual
|
| 141 |
|
|
pages.
|
| 142 |
|
|
|
| 143 |
|
|
EBADF The argument s is an invalid descriptor.
|
| 144 |
|
|
|
| 145 |
|
|
ENOTSOCK
|
| 146 |
|
|
The argument s does not refer to a socket.
|
| 147 |
|
|
|
| 148 |
|
|
EAGAIN The socket is marked non-blocking and the receive
|
| 149 |
|
|
operation would block, or a receive timeout had
|
| 150 |
|
|
been set and the timeout expired before data was
|
| 151 |
|
|
received.
|
| 152 |
|
|
|
| 153 |
|
|
EINTR The receive was interrupted by delivery of a sig
|
| 154 |
|
|
nal before any data were available.
|
| 155 |
|
|
|
| 156 |
|
|
EINVAL Invalid argument passed.
|
| 157 |
|
|
</pre>
|
| 158 |
|
|
</body>
|
| 159 |
|
|
</html>
|
