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

sendmsg.3p (8745B)


  1. '\" et
  2. .TH SENDMSG "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. sendmsg
  12. \(em send a message on a socket using a message structure
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/socket.h>
  17. .P
  18. ssize_t sendmsg(int \fIsocket\fP, const struct msghdr *\fImessage\fP, int \fIflags\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsendmsg\fR()
  23. function shall send a message through a connection-mode or
  24. connectionless-mode socket. If the socket is a connectionless-mode
  25. socket, the message shall be sent to the address specified by
  26. .BR msghdr
  27. if no pre-specified peer address has been set. If a peer address has
  28. been pre-specified, either the message shall be sent to the address
  29. specified in
  30. .BR msghdr
  31. (overriding the pre-specified peer address), or the function shall
  32. return \-1 and set
  33. .IR errno
  34. to
  35. .BR [EISCONN] .
  36. If the socket is connection-mode, the destination address in
  37. .BR msghdr
  38. shall be ignored.
  39. .P
  40. The
  41. \fIsendmsg\fR()
  42. function takes the following arguments:
  43. .IP "\fIsocket\fR" 12
  44. Specifies the socket file descriptor.
  45. .IP "\fImessage\fR" 12
  46. Points to a
  47. .BR msghdr
  48. structure, containing both the destination address and the buffers for
  49. the outgoing message. The length and format of the address depend on
  50. the address family of the socket. The
  51. .IR msg_flags
  52. member is ignored.
  53. .IP "\fIflags\fR" 12
  54. Specifies the type of message transmission. The application may
  55. specify 0 or the following flag:
  56. .RS 12
  57. .IP MSG_EOR 14
  58. Terminates a record (if supported by the protocol).
  59. .IP MSG_OOB 14
  60. Sends out-of-band data on sockets that support out-of-bound data. The
  61. significance and semantics of out-of-band data are protocol-specific.
  62. .IP MSG_NOSIGNAL 14
  63. Requests not to send the SIGPIPE signal if an attempt to send is made
  64. on a stream-oriented socket that is no longer connected. The
  65. .BR [EPIPE]
  66. error shall still be returned.
  67. .RE
  68. .P
  69. The
  70. .IR msg_iov
  71. and
  72. .IR msg_iovlen
  73. fields of
  74. .IR message
  75. specify zero or more buffers containing the data to be sent.
  76. .IR msg_iov
  77. points to an array of
  78. .BR iovec
  79. structures;
  80. .IR msg_iovlen
  81. shall be set to the dimension of this array. In each
  82. .BR iovec
  83. structure, the
  84. .IR iov_base
  85. field specifies a storage area and the
  86. .IR iov_len
  87. field gives its size in bytes. Some of these sizes can be zero. The
  88. data from each storage area indicated by
  89. .IR msg_iov
  90. is sent in turn.
  91. .P
  92. Successful completion of a call to
  93. \fIsendmsg\fR()
  94. does not guarantee delivery of the message. A return value of \-1
  95. indicates only locally-detected errors.
  96. .P
  97. If space is not available at the sending socket to hold the message to
  98. be transmitted and the socket file descriptor does not have O_NONBLOCK
  99. set, the
  100. \fIsendmsg\fR()
  101. function shall block until space is available. If space is not
  102. available at the sending socket to hold the message to be transmitted
  103. and the socket file descriptor does have O_NONBLOCK set, the
  104. \fIsendmsg\fR()
  105. function shall fail.
  106. .P
  107. If the socket protocol supports broadcast and the specified address is
  108. a broadcast address for the socket protocol,
  109. \fIsendmsg\fR()
  110. shall fail if the SO_BROADCAST option is not set for the socket.
  111. .P
  112. The socket in use may require the process to have appropriate
  113. privileges to use the
  114. \fIsendmsg\fR()
  115. function.
  116. .SH "RETURN VALUE"
  117. Upon successful completion,
  118. \fIsendmsg\fR()
  119. shall return the number of bytes sent. Otherwise, \-1 shall
  120. be returned and
  121. .IR errno
  122. set to indicate the error.
  123. .SH ERRORS
  124. The
  125. \fIsendmsg\fR()
  126. function shall fail if:
  127. .TP
  128. .BR EAGAIN " or " EWOULDBLOCK
  129. .br
  130. The socket's file descriptor is marked O_NONBLOCK and the requested
  131. operation would block.
  132. .TP
  133. .BR EAFNOSUPPORT
  134. .br
  135. Addresses in the specified address family cannot be used with this
  136. socket.
  137. .TP
  138. .BR EBADF
  139. The
  140. .IR socket
  141. argument is not a valid file descriptor.
  142. .TP
  143. .BR ECONNRESET
  144. A connection was forcibly closed by a peer.
  145. .TP
  146. .BR EINTR
  147. A signal interrupted
  148. \fIsendmsg\fR()
  149. before any data was transmitted.
  150. .TP
  151. .BR EINVAL
  152. The sum of the
  153. .IR iov_len
  154. values overflows an
  155. .BR ssize_t .
  156. .TP
  157. .BR EMSGSIZE
  158. The message is too large to be sent all at once (as the socket
  159. requires), or the
  160. .IR msg_iovlen
  161. member of the
  162. .BR msghdr
  163. structure pointed to by
  164. .IR message
  165. is less than or equal to 0 or is greater than
  166. {IOV_MAX}.
  167. .TP
  168. .BR ENOTCONN
  169. The socket is connection-mode but is not connected.
  170. .TP
  171. .BR ENOTSOCK
  172. The
  173. .IR socket
  174. argument does not refer to a socket.
  175. .TP
  176. .BR EOPNOTSUPP
  177. The
  178. .IR socket
  179. argument is associated with a socket that does not support one or more
  180. of the values set in
  181. .IR flags .
  182. .TP
  183. .BR EPIPE
  184. The socket is shut down for writing, or the socket is connection-mode
  185. and is no longer connected. In the latter case, and if the socket is of
  186. type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set,
  187. the SIGPIPE signal is generated to the calling thread.
  188. .P
  189. If the address family of the socket is AF_UNIX, then
  190. \fIsendmsg\fR()
  191. shall fail if:
  192. .TP
  193. .BR EIO
  194. An I/O error occurred while reading from or writing to the file
  195. system.
  196. .TP
  197. .BR ELOOP
  198. A loop exists in symbolic links encountered during resolution of the
  199. pathname in the socket address.
  200. .TP
  201. .BR ENAMETOOLONG
  202. .br
  203. The length of a component of a pathname is longer than
  204. {NAME_MAX}.
  205. .TP
  206. .BR ENOENT
  207. A component of the pathname does not name an existing file or the path
  208. name is an empty string.
  209. .TP
  210. .BR ENOTDIR
  211. A component of the path prefix of the pathname in the socket address
  212. names an existing file that is neither a directory nor a symbolic link
  213. to a directory, or the pathname in the socket address contains at least
  214. one non-\c
  215. <slash>
  216. character and ends with one or more trailing
  217. <slash>
  218. characters and the last pathname component names an existing file that
  219. is neither a directory nor a symbolic link to a directory.
  220. .br
  221. .P
  222. The
  223. \fIsendmsg\fR()
  224. function may fail if:
  225. .TP
  226. .BR EACCES
  227. Search permission is denied for a component of the path prefix; or
  228. write access to the named socket is denied.
  229. .TP
  230. .BR EDESTADDRREQ
  231. .br
  232. The socket is not connection-mode and does not have its peer address
  233. set, and no destination address was specified.
  234. .TP
  235. .BR EHOSTUNREACH
  236. .br
  237. The destination host cannot be reached (probably because the host is
  238. down or a remote router cannot reach it).
  239. .TP
  240. .BR EIO
  241. An I/O error occurred while reading from or writing to the file system.
  242. .TP
  243. .BR EISCONN
  244. A destination address was specified and the socket is already
  245. connected.
  246. .TP
  247. .BR ENETDOWN
  248. The local network interface used to reach the destination is down.
  249. .TP
  250. .BR ENETUNREACH
  251. .br
  252. No route to the network is present.
  253. .TP
  254. .BR ENOBUFS
  255. Insufficient resources were available in the system to perform the
  256. operation.
  257. .TP
  258. .BR ENOMEM
  259. Insufficient memory was available to fulfill the request.
  260. .P
  261. If the address family of the socket is AF_UNIX, then
  262. \fIsendmsg\fR()
  263. may fail if:
  264. .TP
  265. .BR ELOOP
  266. More than
  267. {SYMLOOP_MAX}
  268. symbolic links were encountered during resolution of the pathname in
  269. the socket address.
  270. .TP
  271. .BR ENAMETOOLONG
  272. .br
  273. The length of a pathname exceeds
  274. {PATH_MAX},
  275. or pathname resolution of a symbolic link produced an intermediate
  276. result with a length that exceeds
  277. {PATH_MAX}.
  278. .LP
  279. .IR "The following sections are informative."
  280. .SH "EXAMPLES"
  281. Done.
  282. .SH "APPLICATION USAGE"
  283. The
  284. \fIselect\fR()
  285. and
  286. \fIpoll\fR()
  287. functions can be used to determine when it is possible to send more
  288. data.
  289. .SH "RATIONALE"
  290. None.
  291. .SH "FUTURE DIRECTIONS"
  292. None.
  293. .SH "SEE ALSO"
  294. .IR "\fIgetsockopt\fR\^(\|)",
  295. .IR "\fIpoll\fR\^(\|)",
  296. .IR "\fIpselect\fR\^(\|)",
  297. .IR "\fIrecv\fR\^(\|)",
  298. .IR "\fIrecvfrom\fR\^(\|)",
  299. .IR "\fIrecvmsg\fR\^(\|)",
  300. .IR "\fIsend\fR\^(\|)",
  301. .IR "\fIsendto\fR\^(\|)",
  302. .IR "\fIsetsockopt\fR\^(\|)",
  303. .IR "\fIshutdown\fR\^(\|)",
  304. .IR "\fIsocket\fR\^(\|)"
  305. .P
  306. The Base Definitions volume of POSIX.1\(hy2017,
  307. .IR "\fB<sys_socket.h>\fP"
  308. .\"
  309. .SH COPYRIGHT
  310. Portions of this text are reprinted and reproduced in electronic form
  311. from IEEE Std 1003.1-2017, Standard for Information Technology
  312. -- Portable Operating System Interface (POSIX), The Open Group Base
  313. Specifications Issue 7, 2018 Edition,
  314. Copyright (C) 2018 by the Institute of
  315. Electrical and Electronics Engineers, Inc and The Open Group.
  316. In the event of any discrepancy between this version and the original IEEE and
  317. The Open Group Standard, the original IEEE and The Open Group Standard
  318. is the referee document. The original Standard can be obtained online at
  319. http://www.opengroup.org/unix/online.html .
  320. .PP
  321. Any typographical or formatting errors that appear
  322. in this page are most likely
  323. to have been introduced during the conversion of the source files to
  324. man page format. To report such errors, see
  325. https://www.kernel.org/doc/man-pages/reporting_bugs.html .