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

sendto.3p (8502B)


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