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