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

recvmsg.3p (8048B)


  1. '\" et
  2. .TH RECVMSG "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. recvmsg
  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 recvmsg(int \fIsocket\fP, struct msghdr *\fImessage\fP, int \fIflags\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIrecvmsg\fR()
  23. function shall receive a message from a connection-mode or
  24. connectionless-mode socket. It is normally used with
  25. connectionless-mode sockets because it permits the application to
  26. retrieve the source address of received data.
  27. .P
  28. The
  29. \fIrecvmsg\fR()
  30. function takes the following arguments:
  31. .IP "\fIsocket\fR" 12
  32. Specifies the socket file descriptor.
  33. .IP "\fImessage\fR" 12
  34. Points to a
  35. .BR msghdr
  36. structure, containing both the buffer to store the source address and
  37. the buffers for the incoming message. The length and format of the
  38. address depend on the address family of the socket. The
  39. .IR msg_flags
  40. member is ignored on input, but may contain meaningful values on
  41. output.
  42. .IP "\fIflags\fR" 12
  43. Specifies the type of message reception. Values of this argument are
  44. formed by logically OR'ing zero or more of the following values:
  45. .RS 12
  46. .IP MSG_OOB 12
  47. Requests out-of-band data. The significance and semantics of
  48. out-of-band data are protocol-specific.
  49. .IP MSG_PEEK 12
  50. Peeks at the incoming message.
  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. \fIrecvmsg\fR()
  61. function shall receive messages from unconnected or connected
  62. sockets and shall return the length of the message.
  63. .P
  64. The
  65. \fIrecvmsg\fR()
  66. function shall return the total length of the message. For
  67. message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, the
  68. entire message shall be read in a single operation. If a message is too
  69. long to fit in the supplied buffers, and MSG_PEEK is not set in the
  70. .IR flags
  71. argument, the excess bytes shall be discarded, and MSG_TRUNC shall be
  72. set in the
  73. .IR msg_flags
  74. member of the
  75. .BR msghdr
  76. structure. For stream-based sockets, such as SOCK_STREAM, message
  77. boundaries shall be ignored. In this case, data shall be returned to
  78. the user as soon as it becomes available, and no data shall be
  79. discarded.
  80. .P
  81. If the MSG_WAITALL flag is not set, data shall be returned only up to
  82. the end of the first message.
  83. .P
  84. If no messages are available at the socket and O_NONBLOCK is not set on
  85. the socket's file descriptor,
  86. \fIrecvmsg\fR()
  87. shall block until a message arrives. If no messages are available at
  88. the socket and O_NONBLOCK is set on the socket's file descriptor, the
  89. \fIrecvmsg\fR()
  90. function shall fail and set
  91. .IR errno
  92. to
  93. .BR [EAGAIN]
  94. or
  95. .BR [EWOULDBLOCK] .
  96. .P
  97. In the
  98. .BR msghdr
  99. structure, the
  100. .IR msg_name
  101. member may be a null pointer if the source address is not required.
  102. Otherwise, if the socket is unconnected, the
  103. .IR msg_name
  104. member points to a
  105. .BR sockaddr
  106. structure in which the source address is to be stored, and the
  107. .IR msg_namelen
  108. member on input specifies the length of the supplied
  109. .BR sockaddr
  110. structure and on output specifies the length of the stored address.
  111. If the actual length of the address is greater than the length of the
  112. supplied
  113. .BR sockaddr
  114. structure, the stored address shall be truncated. If the socket is
  115. connected, the
  116. .IR msg_name
  117. and
  118. .IR msg_namelen
  119. members shall be ignored. The
  120. .IR msg_iov
  121. and
  122. .IR msg_iovlen
  123. fields are used to specify where the received data shall be stored.
  124. The
  125. .IR msg_iov
  126. member points to an array of
  127. .BR iovec
  128. structures; the
  129. .IR msg_iovlen
  130. member shall be set to the dimension of this array. In each
  131. .BR iovec
  132. structure, the
  133. .IR iov_base
  134. field specifies a storage area and the
  135. .IR iov_len
  136. field gives its size in bytes. Each storage area indicated by
  137. .IR msg_iov
  138. is filled with received data in turn until all of the received data is
  139. stored or all of the areas have been filled.
  140. .P
  141. Upon successful completion, the
  142. .IR msg_flags
  143. member of the message header shall be the bitwise-inclusive OR of all
  144. of the following flags that indicate conditions detected for the
  145. received message:
  146. .IP MSG_EOR 12
  147. End-of-record was received (if supported by the protocol).
  148. .IP MSG_OOB 12
  149. Out-of-band data was received.
  150. .IP MSG_TRUNC 12
  151. Normal data was truncated.
  152. .IP MSG_CTRUNC 12
  153. Control data was truncated.
  154. .SH "RETURN VALUE"
  155. Upon successful completion,
  156. \fIrecvmsg\fR()
  157. shall return the length of the message in bytes. If no messages are
  158. available to be received and the peer has performed an orderly
  159. shutdown,
  160. \fIrecvmsg\fR()
  161. shall return 0. Otherwise, \-1 shall be returned and
  162. .IR errno
  163. set to indicate the error.
  164. .SH ERRORS
  165. The
  166. \fIrecvmsg\fR()
  167. function shall fail if:
  168. .TP
  169. .BR EAGAIN " or " EWOULDBLOCK
  170. .br
  171. The socket's file descriptor is marked O_NONBLOCK and no data is
  172. waiting to be received; or MSG_OOB is set and no out-of-band data is
  173. available and either the socket's file descriptor is marked O_NONBLOCK
  174. or the socket does not support blocking to await out-of-band data.
  175. .TP
  176. .BR EBADF
  177. The
  178. .IR socket
  179. argument is not a valid open file descriptor.
  180. .TP
  181. .BR ECONNRESET
  182. A connection was forcibly closed by a peer.
  183. .TP
  184. .BR EINTR
  185. This function was interrupted by a signal before any data was
  186. available.
  187. .TP
  188. .BR EINVAL
  189. The sum of the
  190. .IR iov_len
  191. values overflows a
  192. .BR ssize_t ,
  193. or the MSG_OOB flag is set and no out-of-band data is available.
  194. .TP
  195. .BR EMSGSIZE
  196. The
  197. .IR msg_iovlen
  198. member of the
  199. .BR msghdr
  200. structure pointed to by
  201. .IR message
  202. is less than or equal to 0, or is greater than
  203. {IOV_MAX}.
  204. .TP
  205. .BR ENOTCONN
  206. A receive is attempted on a connection-mode socket that is not
  207. connected.
  208. .TP
  209. .BR ENOTSOCK
  210. The
  211. .IR socket
  212. argument does not refer to a socket.
  213. .TP
  214. .BR EOPNOTSUPP
  215. The specified flags are not supported for this socket type.
  216. .TP
  217. .BR ETIMEDOUT
  218. The connection timed out during connection establishment, or due to a
  219. transmission timeout on active connection.
  220. .P
  221. The
  222. \fIrecvmsg\fR()
  223. function may fail if:
  224. .TP
  225. .BR EIO
  226. An I/O error occurred while reading from or writing to the file
  227. system.
  228. .TP
  229. .BR ENOBUFS
  230. Insufficient resources were available in the system to perform the
  231. operation.
  232. .TP
  233. .BR ENOMEM
  234. Insufficient memory was available to fulfill the request.
  235. .LP
  236. .IR "The following sections are informative."
  237. .SH "EXAMPLES"
  238. None.
  239. .SH "APPLICATION USAGE"
  240. The
  241. \fIselect\fR()
  242. and
  243. \fIpoll\fR()
  244. functions can be used to determine when data is available to be
  245. received.
  246. .SH "RATIONALE"
  247. None.
  248. .SH "FUTURE DIRECTIONS"
  249. None.
  250. .SH "SEE ALSO"
  251. .IR "\fIpoll\fR\^(\|)",
  252. .IR "\fIpselect\fR\^(\|)",
  253. .IR "\fIrecv\fR\^(\|)",
  254. .IR "\fIrecvfrom\fR\^(\|)",
  255. .IR "\fIsend\fR\^(\|)",
  256. .IR "\fIsendmsg\fR\^(\|)",
  257. .IR "\fIsendto\fR\^(\|)",
  258. .IR "\fIshutdown\fR\^(\|)",
  259. .IR "\fIsocket\fR\^(\|)"
  260. .P
  261. The Base Definitions volume of POSIX.1\(hy2017,
  262. .IR "\fB<sys_socket.h>\fP"
  263. .\"
  264. .SH COPYRIGHT
  265. Portions of this text are reprinted and reproduced in electronic form
  266. from IEEE Std 1003.1-2017, Standard for Information Technology
  267. -- Portable Operating System Interface (POSIX), The Open Group Base
  268. Specifications Issue 7, 2018 Edition,
  269. Copyright (C) 2018 by the Institute of
  270. Electrical and Electronics Engineers, Inc and The Open Group.
  271. In the event of any discrepancy between this version and the original IEEE and
  272. The Open Group Standard, the original IEEE and The Open Group Standard
  273. is the referee document. The original Standard can be obtained online at
  274. http://www.opengroup.org/unix/online.html .
  275. .PP
  276. Any typographical or formatting errors that appear
  277. in this page are most likely
  278. to have been introduced during the conversion of the source files to
  279. man page format. To report such errors, see
  280. https://www.kernel.org/doc/man-pages/reporting_bugs.html .