]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
35e6d17b | 2 | .\" and Copyright 2005-2007, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
3 | .\" Portions extracted from /usr/include/sys/socket.h, which does not have |
4 | .\" any authorship information in it. It is probably available under the GPL. | |
5 | .\" | |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
27 | .\" |
28 | .\" | |
29 | .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: | |
30 | .\" | |
31 | .\" Copyright (c) 1983 The Regents of the University of California. | |
32 | .\" All rights reserved. | |
33 | .\" | |
a9cd9cb7 | 34 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
35 | .\" Redistribution and use in source and binary forms, with or without |
36 | .\" modification, are permitted provided that the following conditions | |
37 | .\" are met: | |
38 | .\" 1. Redistributions of source code must retain the above copyright | |
39 | .\" notice, this list of conditions and the following disclaimer. | |
40 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
41 | .\" notice, this list of conditions and the following disclaimer in the | |
42 | .\" documentation and/or other materials provided with the distribution. | |
43 | .\" 3. All advertising materials mentioning features or use of this software | |
44 | .\" must display the following acknowledgement: | |
45 | .\" This product includes software developed by the University of | |
46 | .\" California, Berkeley and its contributors. | |
47 | .\" 4. Neither the name of the University nor the names of its contributors | |
48 | .\" may be used to endorse or promote products derived from this software | |
49 | .\" without specific prior written permission. | |
50 | .\" | |
51 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
52 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
53 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
54 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
55 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
56 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
57 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
58 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
59 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
60 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
61 | .\" SUCH DAMAGE. | |
8c9302dc | 62 | .\" %%%LICENSE_END |
fea681da MK |
63 | .\" |
64 | .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> | |
65 | .\" Modified 1998 by Andi Kleen | |
66 | .\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ | |
c11b1abf | 67 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 68 | .\" |
9ba01802 | 69 | .TH BIND 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da MK |
70 | .SH NAME |
71 | bind \- bind a name to a socket | |
72 | .SH SYNOPSIS | |
521bf584 | 73 | .nf |
53a6b01d | 74 | .BR "#include <sys/types.h>" " /* See NOTES */" |
fea681da | 75 | .B #include <sys/socket.h> |
15e88fe8 | 76 | .PP |
791ce3b9 | 77 | .BI "int bind(int " sockfd ", const struct sockaddr *" addr , |
e2de12c2 | 78 | .BI " socklen_t " addrlen ); |
521bf584 | 79 | .fi |
fea681da | 80 | .SH DESCRIPTION |
fea681da MK |
81 | When a socket is created with |
82 | .BR socket (2), | |
791ce3b9 MK |
83 | it exists in a name space (address family) but has no address assigned to it. |
84 | .BR bind () | |
b546a528 | 85 | assigns the address specified by |
791ce3b9 MK |
86 | .I addr |
87 | to the socket referred to by the file descriptor | |
88 | .IR sockfd . | |
89 | .I addrlen | |
90 | specifies the size, in bytes, of the address structure pointed to by | |
91 | .IR addr . | |
92 | Traditionally, this operation is called \(lqassigning a name to a socket\(rq. | |
fea681da MK |
93 | .PP |
94 | It is normally necessary to assign a local address using | |
a089ce72 | 95 | .BR bind () |
fea681da MK |
96 | before a |
97 | .B SOCK_STREAM | |
98 | socket may receive connections (see | |
99 | .BR accept (2)). | |
15e88fe8 | 100 | .PP |
c13182ef MK |
101 | The rules used in name binding vary between address families. |
102 | Consult the manual entries in Section 7 for detailed information. | |
103 | For | |
5db5b78c | 104 | .BR AF_INET , |
fea681da | 105 | see |
5db5b78c | 106 | .BR ip (7); |
fea681da | 107 | for |
5db5b78c | 108 | .BR AF_INET6 , |
ffa01655 | 109 | see |
5db5b78c | 110 | .BR ipv6 (7); |
ffa01655 | 111 | for |
5db5b78c | 112 | .BR AF_UNIX , |
fea681da | 113 | see |
5db5b78c | 114 | .BR unix (7); |
fea681da | 115 | for |
5db5b78c | 116 | .BR AF_APPLETALK , |
fea681da | 117 | see |
5db5b78c | 118 | .BR ddp (7); |
fea681da | 119 | for |
5db5b78c | 120 | .BR AF_PACKET , |
fea681da | 121 | see |
5db5b78c | 122 | .BR packet (7); |
fea681da | 123 | for |
5db5b78c | 124 | .BR AF_X25 , |
fea681da | 125 | see |
5db5b78c | 126 | .BR x25 (7); |
fea681da | 127 | and for |
5db5b78c | 128 | .BR AF_NETLINK , |
fea681da MK |
129 | see |
130 | .BR netlink (7). | |
15e88fe8 | 131 | .PP |
ffa01655 | 132 | The actual structure passed for the |
791ce3b9 | 133 | .I addr |
ffa01655 MK |
134 | argument will depend on the address family. |
135 | The | |
136 | .I sockaddr | |
137 | structure is defined as something like: | |
15e88fe8 | 138 | .PP |
a08ea57c | 139 | .in +4n |
15e88fe8 | 140 | .EX |
ffa01655 MK |
141 | struct sockaddr { |
142 | sa_family_t sa_family; | |
143 | char sa_data[14]; | |
144 | } | |
15e88fe8 | 145 | .EE |
a08ea57c | 146 | .in |
15e88fe8 | 147 | .PP |
c13182ef MK |
148 | The only purpose of this structure is to cast the structure |
149 | pointer passed in | |
791ce3b9 | 150 | .I addr |
c13182ef | 151 | in order to avoid compiler warnings. |
185f6872 | 152 | See EXAMPLE below. |
47297adb | 153 | .SH RETURN VALUE |
c13182ef MK |
154 | On success, zero is returned. |
155 | On error, \-1 is returned, and | |
fea681da MK |
156 | .I errno |
157 | is set appropriately. | |
158 | .SH ERRORS | |
159 | .TP | |
160 | .B EACCES | |
6eb334b2 | 161 | .\" e.g., privileged port in AF_INET domain |
2c8d1c7d | 162 | The address is protected, and the user is not the superuser. |
fea681da | 163 | .TP |
5059acc3 MK |
164 | .B EADDRINUSE |
165 | The given address is already in use. | |
166 | .TP | |
9b533686 MK |
167 | .B EADDRINUSE |
168 | (Internet domain sockets) | |
169 | The port number was specified as zero in the socket address structure, | |
170 | but, upon attempting to bind to an ephemeral port, | |
171 | it was determined that all port numbers in the ephemeral port range | |
172 | are currently in use. | |
173 | See the discussion of | |
174 | .I /proc/sys/net/ipv4/ip_local_port_range | |
175 | .BR ip (7). | |
176 | .TP | |
fea681da MK |
177 | .B EBADF |
178 | .I sockfd | |
d9cb0d7d | 179 | is not a valid file descriptor. |
fea681da MK |
180 | .TP |
181 | .B EINVAL | |
5059acc3 MK |
182 | The socket is already bound to an address. |
183 | .\" This may change in the future: see | |
184 | .\" .I linux/unix/sock.c for details. | |
fea681da | 185 | .TP |
b18ea633 MK |
186 | .B EINVAL |
187 | .I addrlen | |
188 | is wrong, or | |
189 | .I addr | |
190 | is not a valid address for this socket's domain. | |
191 | .TP | |
fea681da | 192 | .B ENOTSOCK |
deedfd97 | 193 | The file descriptor |
7741d967 | 194 | .I sockfd |
deedfd97 | 195 | does not refer to a socket. |
fea681da | 196 | .PP |
008f1ecc | 197 | The following errors are specific to UNIX domain |
c13182ef | 198 | .RB ( AF_UNIX ) |
fea681da MK |
199 | sockets: |
200 | .TP | |
201 | .B EACCES | |
202 | Search permission is denied on a component of the path prefix. | |
203 | (See also | |
ad7cc990 | 204 | .BR path_resolution (7).) |
fea681da | 205 | .TP |
1ba452d4 | 206 | .B EADDRNOTAVAIL |
c382a365 | 207 | A nonexistent interface was requested or the requested |
1ba452d4 MK |
208 | address was not local. |
209 | .TP | |
fea681da | 210 | .B EFAULT |
791ce3b9 | 211 | .I addr |
fea681da MK |
212 | points outside the user's accessible address space. |
213 | .TP | |
fea681da MK |
214 | .B ELOOP |
215 | Too many symbolic links were encountered in resolving | |
791ce3b9 | 216 | .IR addr . |
fea681da MK |
217 | .TP |
218 | .B ENAMETOOLONG | |
791ce3b9 | 219 | .I addr |
fea681da MK |
220 | is too long. |
221 | .TP | |
222 | .B ENOENT | |
a1dc786b | 223 | A component in the directory prefix of the socket pathname does not exist. |
fea681da MK |
224 | .TP |
225 | .B ENOMEM | |
226 | Insufficient kernel memory was available. | |
227 | .TP | |
228 | .B ENOTDIR | |
229 | A component of the path prefix is not a directory. | |
230 | .TP | |
231 | .B EROFS | |
9ee4a2b6 | 232 | The socket inode would reside on a read-only filesystem. |
47297adb | 233 | .SH CONFORMING TO |
04b63f48 | 234 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD |
791ce3b9 MK |
235 | .RB ( bind () |
236 | first appeared in 4.2BSD). | |
9d9dc1e8 | 237 | .\" SVr4 documents an additional |
c13182ef | 238 | .\" .B ENOSR |
9d9dc1e8 | 239 | .\" general error condition, and |
c13182ef | 240 | .\" additional |
9d9dc1e8 MK |
241 | .\" .B EIO |
242 | .\" and | |
243 | .\" .B EISDIR | |
008f1ecc | 244 | .\" UNIX-domain error conditions. |
19c98696 | 245 | .SH NOTES |
04b63f48 | 246 | POSIX.1 does not require the inclusion of |
53a6b01d MK |
247 | .IR <sys/types.h> , |
248 | and this header file is not required on Linux. | |
249 | However, some historical (BSD) implementations required this header | |
250 | file, and portable applications are probably wise to include it. | |
15e88fe8 | 251 | .PP |
ec5df7af MK |
252 | For background on the |
253 | .I socklen_t | |
254 | type, see | |
fea681da | 255 | .BR accept (2). |
f5b03186 MK |
256 | .SH BUGS |
257 | The transparent proxy options are not described. | |
bea08fec | 258 | .\" FIXME Document transparent proxy options |
185f6872 | 259 | .SH EXAMPLE |
1c27853f MK |
260 | An example of the use of |
261 | .BR bind () | |
262 | with Internet domain sockets can be found in | |
263 | .BR getaddrinfo (3). | |
15e88fe8 | 264 | .PP |
008f1ecc | 265 | The following example shows how to bind a stream socket in the UNIX |
185f6872 MK |
266 | .RB ( AF_UNIX ) |
267 | domain, and accept connections: | |
1c27853f MK |
268 | .\" listen.7 refers to this example. |
269 | .\" accept.7 refers to this example. | |
270 | .\" unix.7 refers to this example. | |
15e88fe8 MK |
271 | .PP |
272 | .EX | |
185f6872 MK |
273 | #include <sys/socket.h> |
274 | #include <sys/un.h> | |
275 | #include <stdlib.h> | |
276 | #include <stdio.h> | |
277 | #include <string.h> | |
278 | ||
279 | #define MY_SOCK_PATH "/somepath" | |
280 | #define LISTEN_BACKLOG 50 | |
281 | ||
d1a71985 | 282 | #define handle_error(msg) \e |
6a578b88 | 283 | do { perror(msg); exit(EXIT_FAILURE); } while (0) |
d3b5ab82 | 284 | |
185f6872 MK |
285 | int |
286 | main(int argc, char *argv[]) | |
287 | { | |
288 | int sfd, cfd; | |
289 | struct sockaddr_un my_addr, peer_addr; | |
290 | socklen_t peer_addr_size; | |
291 | ||
292 | sfd = socket(AF_UNIX, SOCK_STREAM, 0); | |
29059a65 | 293 | if (sfd == \-1) |
6a578b88 | 294 | handle_error("socket"); |
185f6872 MK |
295 | |
296 | memset(&my_addr, 0, sizeof(struct sockaddr_un)); | |
297 | /* Clear structure */ | |
298 | my_addr.sun_family = AF_UNIX; | |
299 | strncpy(my_addr.sun_path, MY_SOCK_PATH, | |
29059a65 | 300 | sizeof(my_addr.sun_path) \- 1); |
185f6872 MK |
301 | |
302 | if (bind(sfd, (struct sockaddr *) &my_addr, | |
29059a65 | 303 | sizeof(struct sockaddr_un)) == \-1) |
6a578b88 | 304 | handle_error("bind"); |
988db661 | 305 | |
29059a65 | 306 | if (listen(sfd, LISTEN_BACKLOG) == \-1) |
6a578b88 | 307 | handle_error("listen"); |
185f6872 | 308 | |
988db661 | 309 | /* Now we can accept incoming connections one |
185f6872 MK |
310 | at a time using accept(2) */ |
311 | ||
312 | peer_addr_size = sizeof(struct sockaddr_un); | |
313 | cfd = accept(sfd, (struct sockaddr *) &peer_addr, | |
028f847b | 314 | &peer_addr_size); |
29059a65 | 315 | if (cfd == \-1) |
6a578b88 | 316 | handle_error("accept"); |
1f821a55 MK |
317 | |
318 | /* Code to deal with incoming connection(s)... */ | |
319 | ||
320 | /* When no longer required, the socket pathname, MY_SOCK_PATH | |
321 | should be deleted using unlink(2) or remove(3) */ | |
185f6872 | 322 | } |
15e88fe8 | 323 | .EE |
47297adb | 324 | .SH SEE ALSO |
fea681da MK |
325 | .BR accept (2), |
326 | .BR connect (2), | |
327 | .BR getsockname (2), | |
328 | .BR listen (2), | |
fea681da | 329 | .BR socket (2), |
0e5b601a | 330 | .BR getaddrinfo (3), |
bbc0dbf0 | 331 | .BR getifaddrs (3), |
fea681da | 332 | .BR ip (7), |
ffa01655 | 333 | .BR ipv6 (7), |
ad7cc990 | 334 | .BR path_resolution (7), |
ffa01655 MK |
335 | .BR socket (7), |
336 | .BR unix (7) |