recvfrom(3xnet)

1recvfrom(3XNET)  X/Open Networking Services Library Functions  recvfrom(3XNET)
2
3
4

NAME

6       recvfrom - receive a message from a socket
7

SYNOPSIS

9       cc [ flag ... ] file ... -lxnet [ library ... ]
10       #include <sys/socket.h>
11
12       ssize_t recvfrom(int socket, void *restrict buffer, size_t length,
13            int flags, struct sockaddr *restrict address,
14            socklen_t *restrict address_len);
15
16

DESCRIPTION

18       The  recvfrom()  function  receives a message from a connection-mode or
19       connectionless-mode socket.  It is normally used  with  connectionless-
20       mode  sockets because it permits the application to retrieve the source
21       address of received data.
22
23
24       The function takes the following arguments:
25
26       socket         Specifies the socket file descriptor.
27
28
29       buffer         Points to the buffer where the message should be stored.
30
31
32       length         Specifies the length in bytes of the buffer  pointed  to
33                      by the buffer argument.
34
35
36       flags          Specifies the type of message reception.  Values of this
37                      argument are formed by logically OR'ing zero or more  of
38                      the following values:
39
40                      MSG_PEEK       Peeks  at  an incoming message.  The data
41                                     is  treated  as  unread  and   the   next
42                                     recvfrom() or similar function will still
43                                     return this data.
44
45
46                      MSG_OOB        Requests out-of-band data.  The  signifi‐
47                                     cance  and  semantics of out-of-band data
48                                     are protocol-specific.
49
50
51                      MSG_WAITALL    Requests that the  function  block  until
52                                     the  full amount of data requested can be
53                                     returned.   The  function  may  return  a
54                                     smaller  amount  of  data  if a signal is
55                                     caught,  if the connection is terminated,
56                                     if MSG_PEEK was specified, or if an error
57                                     is pending for the socket.
58
59
60
61       address        A null pointer, or points to  a  sockaddr  structure  in
62                      which  the  sending address is to be stored.  The length
63                      and format of the address depend on the  address  family
64                      of the socket.
65
66
67       address_len    Specifies  the  length of the sockaddr structure pointed
68                      to by the address argument.
69
70
71
72       The recvfrom() function returns the length of the  message  written  to
73       the  buffer pointed to by the buffer argument.  For message-based sock‐
74       ets such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message  must  be
75       read  in  a  single  operation.  If a message is too long to fit in the
76       supplied buffer, and MSG_PEEK is not set in  the  flags  argument,  the
77       excess   bytes   are  discarded.   For  stream-based  sockets  such  as
78       SOCK_STREAM, message boundaries are ignored.  In  this  case,  data  is
79       returned  to  the  user as soon as it becomes available, and no data is
80       discarded.
81
82
83       If the MSG_WAITALL flag is not set, data will be returned  only  up  to
84       the end of the first message.
85
86
87       Not  all  protocols  provide  the  source address for messages.  If the
88       address argument is not a null pointer and the  protocol  provides  the
89       source  address of messages, the source address of the received message
90       is stored in the sockaddr structure pointed to by the address argument,
91       and  the  length  of this address is stored in the object pointed to by
92       the address_len argument.
93
94
95       If the actual length of the address is greater than the length  of  the
96       supplied sockaddr structure, the stored address will be truncated.
97
98
99       If the address argument is not a null pointer and the protocol does not
100       provide the source address of messages, the the  value  stored  in  the
101       object pointed to by address is unspecified.
102
103
104       If no messages are available at the socket and O_NONBLOCK is not set on
105       the  socket's  file  descriptor,  recvfrom()  blocks  until  a  message
106       arrives.  If  no messages are available at the socket and O_NONBLOCK is
107       set on the socket's file descriptor, recvfrom() fails and sets errno to
108       EAGAIN or EWOULDBLOCK.
109

USAGE

111       The select(3C) and poll(2) functions can be used to determine when data
112       is available to be received.
113

RETURN VALUES

115       Upon successful completion, recvfrom() returns the length of  the  mes‐
116       sage  in  bytes.   If  no messages are available to be received and the
117       peer has performed an orderly shutdown, recvfrom() returns  0.   Other‐
118       wise the function returns −1 and sets errno to indicate the error.
119

ERRORS

121       The recvfrom() function will fail if:
122
123       EAGAIN         The socket's file descriptor is marked O_NONBLOCK and no
124       EWOULDBLOCK    data is waiting to be received, or MSG_OOB is set and no
125                      out-of-band  data  is  available and either the socket's
126                      file descriptor is marked O_NONBLOCK or the socket  does
127                      not support blocking to await out-of-band data.
128
129
130       EBADF          The socket argument is not a valid file descriptor.
131
132
133       ECONNRESET     A connection was forcibly closed by a peer.
134
135
136       EFAULT         The   buffer,  address or  address_len parameter can not
137                      be accessed or written.
138
139
140       EINTR          A signal interrupted  recvfrom()  before  any  data  was
141                      available.
142
143
144       EINVAL         The  MSG_OOB  flag  is  set  and  no out-of-band data is
145                      available.
146
147
148       ENOTCONN       A receive is attempted on a connection-mode socket  that
149                      is not connected.
150
151
152       ENOTSOCK       The socket argument does not refer to a socket.
153
154
155       EOPNOTSUPP     The  specified  flags  are not supported for this socket
156                      type.
157
158
159       ETIMEDOUT      The connection timed out  during  connection  establish‐
160                      ment, or due to a transmission timeout on active connec‐
161                      tion.
162
163
164
165       The recvfrom() function may fail if:
166
167       EIO        An I/O error occurred while reading from or writing  to  the
168                  file system.
169
170
171       ENOBUFS    Insufficient  resources were available in the system to per‐
172                  form the operation.
173
174
175       ENOMEM     Insufficient memory was available to fulfill the request.
176
177
178       ENOSR      There were insufficient STREAMS resources available for  the
179                  operation to complete.
180
181

ATTRIBUTES

183       See attributes(5) for descriptions of the following attributes:
184
185
186
187
188       ┌─────────────────────────────┬─────────────────────────────┐
189       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │Interface Stability          │Standard                     │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │MT-Level                     │MT-Safe                      │
194       └─────────────────────────────┴─────────────────────────────┘
195