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

bind.3p (7394B)


  1. '\" et
  2. .TH BIND "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. bind
  12. \(em bind a name to a socket
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/socket.h>
  17. .P
  18. int bind(int \fIsocket\fP, const struct sockaddr *\fIaddress\fP,
  19. socklen_t \fIaddress_len\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIbind\fR()
  24. function shall assign a local socket address
  25. .IR address
  26. to a socket identified by descriptor
  27. .IR socket
  28. that has no local socket address assigned. Sockets created with the
  29. \fIsocket\fR()
  30. function are initially unnamed; they are identified only by their
  31. address family.
  32. .P
  33. The
  34. \fIbind\fR()
  35. function takes the following arguments:
  36. .IP "\fIsocket\fR" 12
  37. Specifies the file descriptor of the socket to be bound.
  38. .IP "\fIaddress\fR" 12
  39. Points to a
  40. .BR sockaddr
  41. structure containing the address to be bound to the socket. The length
  42. and format of the address depend on the address family of the socket.
  43. .IP "\fIaddress_len\fR" 12
  44. Specifies the length of the
  45. .BR sockaddr
  46. structure pointed to by the
  47. .IR address
  48. argument.
  49. .P
  50. The socket specified by
  51. .IR socket
  52. may require the process to have appropriate privileges to use the
  53. \fIbind\fR()
  54. function.
  55. .P
  56. If the address family of the socket is AF_UNIX and the pathname in
  57. .IR address
  58. names a symbolic link,
  59. \fIbind\fR()
  60. shall fail and set
  61. .IR errno
  62. to
  63. .BR [EADDRINUSE] .
  64. .P
  65. If the socket address cannot be assigned immediately and O_NONBLOCK is
  66. set for the file descriptor for the socket,
  67. \fIbind\fR()
  68. shall fail and set
  69. .IR errno
  70. to
  71. .BR [EINPROGRESS] ,
  72. but the assignment request shall not be aborted, and the assignment
  73. shall be completed asynchronously. Subsequent calls to
  74. \fIbind\fR()
  75. for the same socket, before the assignment is completed, shall fail
  76. and set
  77. .IR errno
  78. to
  79. .BR [EALREADY] .
  80. .P
  81. When the assignment has been performed asynchronously,
  82. \fIpselect\fR(),
  83. \fIselect\fR(),
  84. and
  85. \fIpoll\fR()
  86. shall indicate that the file descriptor for the socket is ready for
  87. reading and writing.
  88. .SH "RETURN VALUE"
  89. Upon successful completion,
  90. \fIbind\fR()
  91. shall return 0; otherwise, \-1 shall be returned and
  92. .IR errno
  93. set to indicate the error.
  94. .SH ERRORS
  95. The
  96. \fIbind\fR()
  97. function shall fail if:
  98. .TP
  99. .BR EADDRINUSE
  100. The specified address is already in use.
  101. .TP
  102. .BR EADDRNOTAVAIL
  103. .br
  104. The specified address is not available from the local machine.
  105. .TP
  106. .BR EAFNOSUPPORT
  107. .br
  108. The specified address is not a valid address for the address family of
  109. the specified socket.
  110. .TP
  111. .BR EALREADY
  112. An assignment request is already in progress for the specified socket.
  113. .TP
  114. .BR EBADF
  115. The
  116. .IR socket
  117. argument is not a valid file descriptor.
  118. .TP
  119. .BR EINPROGRESS
  120. O_NONBLOCK is set for the file descriptor for the socket and the
  121. assignment cannot be immediately performed; the assignment shall be
  122. performed asynchronously.
  123. .TP
  124. .BR EINVAL
  125. The socket is already bound to an address, and the protocol does not
  126. support binding to a new address; or the socket has been shut down.
  127. .TP
  128. .BR ENOBUFS
  129. Insufficient resources were available to complete the call.
  130. .TP
  131. .BR ENOTSOCK
  132. The
  133. .IR socket
  134. argument does not refer to a socket.
  135. .TP
  136. .BR EOPNOTSUPP
  137. The socket type of the specified socket does not support binding to an
  138. address.
  139. .P
  140. If the address family of the socket is AF_UNIX, then
  141. \fIbind\fR()
  142. shall fail if:
  143. .TP
  144. .BR EACCES
  145. A component of the path prefix denies search permission, or the
  146. requested name requires writing in a directory with a mode that denies
  147. write permission.
  148. .TP
  149. .BR EDESTADDRREQ " or " EISDIR
  150. .br
  151. The
  152. .IR address
  153. argument is a null pointer.
  154. .TP
  155. .BR EIO
  156. An I/O error occurred.
  157. .TP
  158. .BR ELOOP
  159. A loop exists in symbolic links encountered during resolution of the
  160. pathname in
  161. .IR address .
  162. .TP
  163. .BR ENAMETOOLONG
  164. .br
  165. The length of a component of a pathname is longer than
  166. {NAME_MAX}.
  167. .TP
  168. .BR ENOENT
  169. A component of the path prefix of the pathname in
  170. .IR address
  171. does not name an existing file or the pathname is an empty string.
  172. .TP
  173. .BR ENOENT " or " ENOTDIR
  174. .br
  175. The pathname in
  176. .IR address
  177. contains at least one non-\c
  178. <slash>
  179. character and ends with one or more trailing
  180. <slash>
  181. characters. If the pathname without the trailing
  182. <slash>
  183. characters would name an existing file, an
  184. .BR [ENOENT]
  185. error shall not occur.
  186. .TP
  187. .BR ENOTDIR
  188. A component of the path prefix of the pathname in
  189. .IR address
  190. names an existing file that is neither a directory nor a symbolic link
  191. to a directory, or the pathname in
  192. .IR address
  193. contains at least one non-\c
  194. <slash>
  195. character and ends with one or more trailing
  196. <slash>
  197. characters and the last pathname component names an existing file
  198. that is neither a directory nor a symbolic link to a directory.
  199. .TP
  200. .BR EROFS
  201. The name would reside on a read-only file system.
  202. .P
  203. The
  204. \fIbind\fR()
  205. function may fail if:
  206. .TP
  207. .BR EACCES
  208. The specified address is protected and the current user does not have
  209. permission to bind to it.
  210. .TP
  211. .BR EINVAL
  212. The
  213. .IR address_len
  214. argument is not a valid length for the address family.
  215. .TP
  216. .BR EISCONN
  217. The socket is already connected.
  218. .TP
  219. .BR ELOOP
  220. More than
  221. {SYMLOOP_MAX}
  222. symbolic links were encountered during resolution of the pathname in
  223. .IR address .
  224. .TP
  225. .BR ENAMETOOLONG
  226. .br
  227. The length of a pathname exceeds
  228. {PATH_MAX},
  229. or pathname resolution of a symbolic link produced an intermediate
  230. result with a length that exceeds
  231. {PATH_MAX}.
  232. .LP
  233. .IR "The following sections are informative."
  234. .SH EXAMPLES
  235. The following code segment shows how to create a socket and
  236. bind it to a name in the AF_UNIX domain.
  237. .sp
  238. .RS 4
  239. .nf
  240. #define MY_SOCK_PATH "/somepath"
  241. .P
  242. int sfd;
  243. struct sockaddr_un my_addr;
  244. .P
  245. sfd = socket(AF_UNIX, SOCK_STREAM, 0);
  246. if (sfd == -1)
  247. /* Handle error */;
  248. .P
  249. memset(&my_addr, \(aq\e0\(aq, sizeof(struct sockaddr_un));
  250. /* Clear structure */
  251. my_addr.sun_family = AF_UNIX;
  252. strncpy(my_addr.sun_path, MY_SOCK_PATH, sizeof(my_addr.sun_path) -1);
  253. .P
  254. if (bind(sfd, (struct sockaddr *) &my_addr,
  255. sizeof(struct sockaddr_un)) == -1)
  256. /* Handle error */;
  257. .fi
  258. .P
  259. .RE
  260. .SH "APPLICATION USAGE"
  261. An application program can retrieve the assigned socket name with the
  262. \fIgetsockname\fR()
  263. function.
  264. .SH RATIONALE
  265. None.
  266. .SH "FUTURE DIRECTIONS"
  267. None.
  268. .SH "SEE ALSO"
  269. .IR "\fIconnect\fR\^(\|)",
  270. .IR "\fIgetsockname\fR\^(\|)",
  271. .IR "\fIlisten\fR\^(\|)",
  272. .IR "\fIsocket\fR\^(\|)"
  273. .P
  274. The Base Definitions volume of POSIX.1\(hy2017,
  275. .IR "\fB<sys_socket.h>\fP"
  276. .\"
  277. .SH COPYRIGHT
  278. Portions of this text are reprinted and reproduced in electronic form
  279. from IEEE Std 1003.1-2017, Standard for Information Technology
  280. -- Portable Operating System Interface (POSIX), The Open Group Base
  281. Specifications Issue 7, 2018 Edition,
  282. Copyright (C) 2018 by the Institute of
  283. Electrical and Electronics Engineers, Inc and The Open Group.
  284. In the event of any discrepancy between this version and the original IEEE and
  285. The Open Group Standard, the original IEEE and The Open Group Standard
  286. is the referee document. The original Standard can be obtained online at
  287. http://www.opengroup.org/unix/online.html .
  288. .PP
  289. Any typographical or formatting errors that appear
  290. in this page are most likely
  291. to have been introduced during the conversion of the source files to
  292. man page format. To report such errors, see
  293. https://www.kernel.org/doc/man-pages/reporting_bugs.html .