1RECVFROM(3P)               POSIX Programmer's Manual              RECVFROM(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       recvfrom - receive a message from a socket
13

SYNOPSIS

15       #include <sys/socket.h>
16
17       ssize_t recvfrom(int socket, void *restrict buffer, size_t length,
18              int flags, struct sockaddr *restrict address,
19              socklen_t *restrict address_len);
20
21

DESCRIPTION

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

RETURN VALUE

103       Upon successful completion, recvfrom() shall return the length  of  the
104       message  in  bytes. If no messages are available to be received and the
105       peer has performed an orderly shutdown, recvfrom() shall return 0. Oth‐
106       erwise,  the  function  shall  return  -1 and set errno to indicate the
107       error.
108

ERRORS

110       The recvfrom() function shall fail if:
111
112       EAGAIN or EWOULDBLOCK
113
114              The socket's file descriptor is marked O_NONBLOCK and no data is
115              waiting  to  be  received;  or MSG_OOB is set and no out-of-band
116              data is available and either the  socket's  file  descriptor  is
117              marked  O_NONBLOCK  or  the  socket does not support blocking to
118              await out-of-band data.
119
120       EBADF  The socket argument is not a valid file descriptor.
121
122       ECONNRESET
123              A connection was forcibly closed by a peer.
124
125       EINTR  A signal interrupted recvfrom() before any data was available.
126
127       EINVAL The MSG_OOB flag is set and no out-of-band data is available.
128
129       ENOTCONN
130              A receive is attempted on a connection-mode socket that  is  not
131              connected.
132
133       ENOTSOCK
134              The socket argument does not refer to a socket.
135
136       EOPNOTSUPP
137              The specified flags are not supported for this socket type.
138
139       ETIMEDOUT
140              The connection timed out during connection establishment, or due
141              to a transmission timeout on active connection.
142
143
144       The recvfrom() function may fail if:
145
146       EIO    An I/O error occurred while reading from or writing to the  file
147              system.
148
149       ENOBUFS
150              Insufficient  resources  were available in the system to perform
151              the operation.
152
153       ENOMEM Insufficient memory was available to fulfill the request.
154
155
156       The following sections are informative.
157

EXAMPLES

159       None.
160

APPLICATION USAGE

162       The select() and poll() functions can be used to determine when data is
163       available to be received.
164

RATIONALE

166       None.
167

FUTURE DIRECTIONS

169       None.
170

SEE ALSO

172       poll(),   read(),   recv(),  recvmsg(),  select(),  send(),  sendmsg(),
173       sendto(), shutdown() , socket(), write(), the Base  Definitions  volume
174       of IEEE Std 1003.1-2001, <sys/socket.h>
175
177       Portions  of  this text are reprinted and reproduced in electronic form
178       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
179       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
180       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
181       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
182       event of any discrepancy between this version and the original IEEE and
183       The  Open Group Standard, the original IEEE and The Open Group Standard
184       is the referee document. The original Standard can be  obtained  online
185       at http://www.opengroup.org/unix/online.html .
186
187
188
189IEEE/The Open Group                  2003                         RECVFROM(3P)
Impressum