logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

recvfrom.3p (7403B)


  1. '\" et
  2. .TH RECVFROM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. recvfrom
  12. \(em receive a message from a socket
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/socket.h>
  17. .P
  18. ssize_t recvfrom(int \fIsocket\fP, void *restrict \fIbuffer\fP, size_t \fIlength\fP,
  19. int \fIflags\fP, struct sockaddr *restrict \fIaddress\fP,
  20. socklen_t *restrict \fIaddress_len\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIrecvfrom\fR()
  25. function shall receive a message from a connection-mode or
  26. connectionless-mode socket. It is normally used with
  27. connectionless-mode sockets because it permits the application to
  28. retrieve the source address of received data.
  29. .P
  30. The
  31. \fIrecvfrom\fR()
  32. function takes the following arguments:
  33. .IP "\fIsocket\fR" 12
  34. Specifies the socket file descriptor.
  35. .IP "\fIbuffer\fR" 12
  36. Points to the buffer where the message should be stored.
  37. .IP "\fIlength\fR" 12
  38. Specifies the length in bytes of the buffer pointed to by the
  39. .IR buffer
  40. argument.
  41. .IP "\fIflags\fR" 12
  42. Specifies the type of message reception. Values of this argument are
  43. formed by logically OR'ing zero or more of the following values:
  44. .RS 12
  45. .IP MSG_PEEK 12
  46. Peeks at an incoming message. The data is treated as unread and the
  47. next
  48. \fIrecvfrom\fR()
  49. or similar function shall still return this data.
  50. .IP MSG_OOB 12
  51. Requests out-of-band data. The significance and semantics of
  52. out-of-band data are protocol-specific.
  53. .IP MSG_WAITALL 12
  54. On SOCK_STREAM sockets this requests that the function block until the
  55. full amount of data can be returned. The function may return the
  56. smaller amount of data if the socket is a message-based socket, if a
  57. signal is caught, if the connection is terminated, if MSG_PEEK was
  58. specified, or if an error is pending for the socket.
  59. .RE
  60. .IP "\fIaddress\fR" 12
  61. A null pointer, or points to a
  62. .BR sockaddr
  63. structure in which the sending address is to be stored. The length and
  64. format of the address depend on the address family of the socket.
  65. .IP "\fIaddress_len\fR" 12
  66. Either a null pointer, if
  67. .IR address
  68. is a null pointer, or a pointer to a
  69. .BR socklen_t
  70. object which on input specifies the length of the supplied
  71. .BR sockaddr
  72. structure, and on output specifies the length of the stored address.
  73. .P
  74. The
  75. \fIrecvfrom\fR()
  76. function shall return the length of the message written to the buffer
  77. pointed to by the
  78. .IR buffer
  79. argument. For message-based sockets, such as
  80. SOCK_RAW,
  81. SOCK_DGRAM, and SOCK_SEQPACKET, the entire message shall be read in a
  82. single operation. If a message is too long to fit in the supplied
  83. buffer, and MSG_PEEK is not set in the
  84. .IR flags
  85. argument, the excess bytes shall be discarded. For stream-based
  86. sockets, such as SOCK_STREAM, message boundaries shall be ignored. In
  87. this case, data shall be returned to the user as soon as it becomes
  88. available, and no data shall be discarded.
  89. .P
  90. If the MSG_WAITALL flag is not set, data shall be returned only up to
  91. the end of the first message.
  92. .P
  93. Not all protocols provide the source address for messages. If the
  94. .IR address
  95. argument is not a null pointer and the protocol provides the source
  96. address of messages, the source address of the received message shall
  97. be stored in the
  98. .BR sockaddr
  99. structure pointed to by the
  100. .IR address
  101. argument, and the length of this address shall be stored in the object
  102. pointed to by the
  103. .IR address_len
  104. argument.
  105. .P
  106. If the actual length of the address is greater than the length of the
  107. supplied
  108. .BR sockaddr
  109. structure, the stored address shall be truncated.
  110. .P
  111. If the
  112. .IR address
  113. argument is not a null pointer and the protocol does not provide the
  114. source address of messages, the value stored in the object pointed to
  115. by
  116. .IR address
  117. is unspecified.
  118. .P
  119. If no messages are available at the socket and O_NONBLOCK is not set on
  120. the socket's file descriptor,
  121. \fIrecvfrom\fR()
  122. shall block until a message arrives. If no messages are available at
  123. the socket and O_NONBLOCK is set on the socket's file descriptor,
  124. \fIrecvfrom\fR()
  125. shall fail and set
  126. .IR errno
  127. to
  128. .BR [EAGAIN]
  129. or
  130. .BR [EWOULDBLOCK] .
  131. .SH "RETURN VALUE"
  132. Upon successful completion,
  133. \fIrecvfrom\fR()
  134. shall return the length of the message in bytes. If no messages are
  135. available to be received and the peer has performed an orderly
  136. shutdown,
  137. \fIrecvfrom\fR()
  138. shall return 0. Otherwise, the function shall return \-1 and set
  139. .IR errno
  140. to indicate the error.
  141. .SH ERRORS
  142. The
  143. \fIrecvfrom\fR()
  144. function shall fail if:
  145. .TP
  146. .BR EAGAIN " or " EWOULDBLOCK
  147. .br
  148. The socket's file descriptor is marked O_NONBLOCK and no data is
  149. waiting to be received; or MSG_OOB is set and no out-of-band data is
  150. available and either the socket's file descriptor is marked O_NONBLOCK
  151. or the socket does not support blocking to await out-of-band data.
  152. .TP
  153. .BR EBADF
  154. The
  155. .IR socket
  156. argument is not a valid file descriptor.
  157. .TP
  158. .BR ECONNRESET
  159. A connection was forcibly closed by a peer.
  160. .TP
  161. .BR EINTR
  162. A signal interrupted
  163. \fIrecvfrom\fR()
  164. before any data was available.
  165. .TP
  166. .BR EINVAL
  167. The MSG_OOB flag is set and no out-of-band data is available.
  168. .TP
  169. .BR ENOTCONN
  170. A receive is attempted on a connection-mode socket that is not connected.
  171. .TP
  172. .BR ENOTSOCK
  173. The
  174. .IR socket
  175. argument does not refer to a socket.
  176. .TP
  177. .BR EOPNOTSUPP
  178. The specified flags are not supported for this socket type.
  179. .TP
  180. .BR ETIMEDOUT
  181. The connection timed out during connection establishment, or due to a
  182. transmission timeout on active connection.
  183. .P
  184. The
  185. \fIrecvfrom\fR()
  186. function may fail if:
  187. .TP
  188. .BR EIO
  189. An I/O error occurred while reading from or writing to the file
  190. system.
  191. .TP
  192. .BR ENOBUFS
  193. Insufficient resources were available in the system to perform the
  194. operation.
  195. .TP
  196. .BR ENOMEM
  197. Insufficient memory was available to fulfill the request.
  198. .LP
  199. .IR "The following sections are informative."
  200. .SH "EXAMPLES"
  201. None.
  202. .SH "APPLICATION USAGE"
  203. The
  204. \fIselect\fR()
  205. and
  206. \fIpoll\fR()
  207. functions can be used to determine when data is available to be
  208. received.
  209. .SH "RATIONALE"
  210. None.
  211. .SH "FUTURE DIRECTIONS"
  212. None.
  213. .SH "SEE ALSO"
  214. .IR "\fIpoll\fR\^(\|)",
  215. .IR "\fIpselect\fR\^(\|)",
  216. .IR "\fIread\fR\^(\|)",
  217. .IR "\fIrecv\fR\^(\|)",
  218. .IR "\fIrecvmsg\fR\^(\|)",
  219. .IR "\fIsend\fR\^(\|)",
  220. .IR "\fIsendmsg\fR\^(\|)",
  221. .IR "\fIsendto\fR\^(\|)",
  222. .IR "\fIshutdown\fR\^(\|)",
  223. .IR "\fIsocket\fR\^(\|)",
  224. .IR "\fIwrite\fR\^(\|)"
  225. .P
  226. The Base Definitions volume of POSIX.1\(hy2017,
  227. .IR "\fB<sys_socket.h>\fP"
  228. .\"
  229. .SH COPYRIGHT
  230. Portions of this text are reprinted and reproduced in electronic form
  231. from IEEE Std 1003.1-2017, Standard for Information Technology
  232. -- Portable Operating System Interface (POSIX), The Open Group Base
  233. Specifications Issue 7, 2018 Edition,
  234. Copyright (C) 2018 by the Institute of
  235. Electrical and Electronics Engineers, Inc and The Open Group.
  236. In the event of any discrepancy between this version and the original IEEE and
  237. The Open Group Standard, the original IEEE and The Open Group Standard
  238. is the referee document. The original Standard can be obtained online at
  239. http://www.opengroup.org/unix/online.html .
  240. .PP
  241. Any typographical or formatting errors that appear
  242. in this page are most likely
  243. to have been introduced during the conversion of the source files to
  244. man page format. To report such errors, see
  245. https://www.kernel.org/doc/man-pages/reporting_bugs.html .