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

recv.3p (6311B)

    

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