]>
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 | .\" | |
5fbde956 | 6 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
7 | .\" |
8 | .\" | |
9 | .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: | |
10 | .\" | |
11 | .\" Copyright (c) 1983 The Regents of the University of California. | |
12 | .\" All rights reserved. | |
13 | .\" | |
47009d5e | 14 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
15 | .\" |
16 | .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> | |
17 | .\" Modified 1998 by Andi Kleen | |
18 | .\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ | |
c11b1abf | 19 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 20 | .\" |
45186a5d | 21 | .TH BIND 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
22 | .SH NAME |
23 | bind \- bind a name to a socket | |
5f259cf0 AC |
24 | .SH LIBRARY |
25 | Standard C library | |
8fc3b2cf | 26 | .RI ( libc ", " \-lc ) |
fea681da | 27 | .SH SYNOPSIS |
521bf584 | 28 | .nf |
fea681da | 29 | .B #include <sys/socket.h> |
15e88fe8 | 30 | .PP |
791ce3b9 | 31 | .BI "int bind(int " sockfd ", const struct sockaddr *" addr , |
e2de12c2 | 32 | .BI " socklen_t " addrlen ); |
521bf584 | 33 | .fi |
fea681da | 34 | .SH DESCRIPTION |
fea681da MK |
35 | When a socket is created with |
36 | .BR socket (2), | |
791ce3b9 MK |
37 | it exists in a name space (address family) but has no address assigned to it. |
38 | .BR bind () | |
b546a528 | 39 | assigns the address specified by |
791ce3b9 MK |
40 | .I addr |
41 | to the socket referred to by the file descriptor | |
42 | .IR sockfd . | |
43 | .I addrlen | |
44 | specifies the size, in bytes, of the address structure pointed to by | |
45 | .IR addr . | |
46 | Traditionally, this operation is called \(lqassigning a name to a socket\(rq. | |
fea681da MK |
47 | .PP |
48 | It is normally necessary to assign a local address using | |
a089ce72 | 49 | .BR bind () |
fea681da MK |
50 | before a |
51 | .B SOCK_STREAM | |
52 | socket may receive connections (see | |
53 | .BR accept (2)). | |
15e88fe8 | 54 | .PP |
c13182ef MK |
55 | The rules used in name binding vary between address families. |
56 | Consult the manual entries in Section 7 for detailed information. | |
57 | For | |
5db5b78c | 58 | .BR AF_INET , |
fea681da | 59 | see |
5db5b78c | 60 | .BR ip (7); |
fea681da | 61 | for |
5db5b78c | 62 | .BR AF_INET6 , |
ffa01655 | 63 | see |
5db5b78c | 64 | .BR ipv6 (7); |
ffa01655 | 65 | for |
5db5b78c | 66 | .BR AF_UNIX , |
fea681da | 67 | see |
5db5b78c | 68 | .BR unix (7); |
fea681da | 69 | for |
5db5b78c | 70 | .BR AF_APPLETALK , |
fea681da | 71 | see |
5db5b78c | 72 | .BR ddp (7); |
fea681da | 73 | for |
5db5b78c | 74 | .BR AF_PACKET , |
fea681da | 75 | see |
5db5b78c | 76 | .BR packet (7); |
fea681da | 77 | for |
5db5b78c | 78 | .BR AF_X25 , |
fea681da | 79 | see |
5db5b78c | 80 | .BR x25 (7); |
fea681da | 81 | and for |
5db5b78c | 82 | .BR AF_NETLINK , |
fea681da MK |
83 | see |
84 | .BR netlink (7). | |
15e88fe8 | 85 | .PP |
ffa01655 | 86 | The actual structure passed for the |
791ce3b9 | 87 | .I addr |
ffa01655 MK |
88 | argument will depend on the address family. |
89 | The | |
90 | .I sockaddr | |
91 | structure is defined as something like: | |
15e88fe8 | 92 | .PP |
a08ea57c | 93 | .in +4n |
15e88fe8 | 94 | .EX |
ffa01655 MK |
95 | struct sockaddr { |
96 | sa_family_t sa_family; | |
97 | char sa_data[14]; | |
98 | } | |
15e88fe8 | 99 | .EE |
a08ea57c | 100 | .in |
15e88fe8 | 101 | .PP |
c13182ef MK |
102 | The only purpose of this structure is to cast the structure |
103 | pointer passed in | |
791ce3b9 | 104 | .I addr |
c13182ef | 105 | in order to avoid compiler warnings. |
78da9b6b | 106 | See EXAMPLES below. |
47297adb | 107 | .SH RETURN VALUE |
c13182ef MK |
108 | On success, zero is returned. |
109 | On error, \-1 is returned, and | |
fea681da | 110 | .I errno |
f6a4078b | 111 | is set to indicate the error. |
fea681da MK |
112 | .SH ERRORS |
113 | .TP | |
114 | .B EACCES | |
6eb334b2 | 115 | .\" e.g., privileged port in AF_INET domain |
2c8d1c7d | 116 | The address is protected, and the user is not the superuser. |
fea681da | 117 | .TP |
5059acc3 MK |
118 | .B EADDRINUSE |
119 | The given address is already in use. | |
120 | .TP | |
9b533686 MK |
121 | .B EADDRINUSE |
122 | (Internet domain sockets) | |
123 | The port number was specified as zero in the socket address structure, | |
124 | but, upon attempting to bind to an ephemeral port, | |
125 | it was determined that all port numbers in the ephemeral port range | |
126 | are currently in use. | |
127 | See the discussion of | |
128 | .I /proc/sys/net/ipv4/ip_local_port_range | |
129 | .BR ip (7). | |
130 | .TP | |
fea681da MK |
131 | .B EBADF |
132 | .I sockfd | |
d9cb0d7d | 133 | is not a valid file descriptor. |
fea681da MK |
134 | .TP |
135 | .B EINVAL | |
5059acc3 MK |
136 | The socket is already bound to an address. |
137 | .\" This may change in the future: see | |
138 | .\" .I linux/unix/sock.c for details. | |
fea681da | 139 | .TP |
b18ea633 MK |
140 | .B EINVAL |
141 | .I addrlen | |
142 | is wrong, or | |
143 | .I addr | |
144 | is not a valid address for this socket's domain. | |
145 | .TP | |
fea681da | 146 | .B ENOTSOCK |
deedfd97 | 147 | The file descriptor |
7741d967 | 148 | .I sockfd |
deedfd97 | 149 | does not refer to a socket. |
fea681da | 150 | .PP |
008f1ecc | 151 | The following errors are specific to UNIX domain |
c13182ef | 152 | .RB ( AF_UNIX ) |
fea681da MK |
153 | sockets: |
154 | .TP | |
155 | .B EACCES | |
156 | Search permission is denied on a component of the path prefix. | |
157 | (See also | |
ad7cc990 | 158 | .BR path_resolution (7).) |
fea681da | 159 | .TP |
1ba452d4 | 160 | .B EADDRNOTAVAIL |
c382a365 | 161 | A nonexistent interface was requested or the requested |
1ba452d4 MK |
162 | address was not local. |
163 | .TP | |
fea681da | 164 | .B EFAULT |
791ce3b9 | 165 | .I addr |
fea681da MK |
166 | points outside the user's accessible address space. |
167 | .TP | |
fea681da MK |
168 | .B ELOOP |
169 | Too many symbolic links were encountered in resolving | |
791ce3b9 | 170 | .IR addr . |
fea681da MK |
171 | .TP |
172 | .B ENAMETOOLONG | |
791ce3b9 | 173 | .I addr |
fea681da MK |
174 | is too long. |
175 | .TP | |
176 | .B ENOENT | |
a1dc786b | 177 | A component in the directory prefix of the socket pathname does not exist. |
fea681da MK |
178 | .TP |
179 | .B ENOMEM | |
180 | Insufficient kernel memory was available. | |
181 | .TP | |
182 | .B ENOTDIR | |
183 | A component of the path prefix is not a directory. | |
184 | .TP | |
185 | .B EROFS | |
9ee4a2b6 | 186 | The socket inode would reside on a read-only filesystem. |
3113c7f3 | 187 | .SH STANDARDS |
04b63f48 | 188 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD |
791ce3b9 MK |
189 | .RB ( bind () |
190 | first appeared in 4.2BSD). | |
9d9dc1e8 | 191 | .\" SVr4 documents an additional |
c13182ef | 192 | .\" .B ENOSR |
9d9dc1e8 | 193 | .\" general error condition, and |
c13182ef | 194 | .\" additional |
9d9dc1e8 MK |
195 | .\" .B EIO |
196 | .\" and | |
197 | .\" .B EISDIR | |
008f1ecc | 198 | .\" UNIX-domain error conditions. |
19c98696 | 199 | .SH NOTES |
ec5df7af MK |
200 | For background on the |
201 | .I socklen_t | |
202 | type, see | |
fea681da | 203 | .BR accept (2). |
f5b03186 MK |
204 | .SH BUGS |
205 | The transparent proxy options are not described. | |
bea08fec | 206 | .\" FIXME Document transparent proxy options |
a14af333 | 207 | .SH EXAMPLES |
1c27853f MK |
208 | An example of the use of |
209 | .BR bind () | |
210 | with Internet domain sockets can be found in | |
211 | .BR getaddrinfo (3). | |
15e88fe8 | 212 | .PP |
008f1ecc | 213 | The following example shows how to bind a stream socket in the UNIX |
185f6872 MK |
214 | .RB ( AF_UNIX ) |
215 | domain, and accept connections: | |
1c27853f MK |
216 | .\" listen.7 refers to this example. |
217 | .\" accept.7 refers to this example. | |
218 | .\" unix.7 refers to this example. | |
15e88fe8 | 219 | .PP |
33857069 | 220 | .\" SRC BEGIN (bind.c) |
15e88fe8 | 221 | .EX |
185f6872 | 222 | #include <stdio.h> |
4ae706b0 | 223 | #include <stdlib.h> |
185f6872 | 224 | #include <string.h> |
4ae706b0 AC |
225 | #include <sys/socket.h> |
226 | #include <sys/un.h> | |
2f5c165c | 227 | #include <unistd.h> |
185f6872 MK |
228 | |
229 | #define MY_SOCK_PATH "/somepath" | |
230 | #define LISTEN_BACKLOG 50 | |
231 | ||
d1a71985 | 232 | #define handle_error(msg) \e |
6a578b88 | 233 | do { perror(msg); exit(EXIT_FAILURE); } while (0) |
d3b5ab82 | 234 | |
185f6872 | 235 | int |
c6ae6d97 | 236 | main(void) |
185f6872 MK |
237 | { |
238 | int sfd, cfd; | |
239 | struct sockaddr_un my_addr, peer_addr; | |
240 | socklen_t peer_addr_size; | |
241 | ||
242 | sfd = socket(AF_UNIX, SOCK_STREAM, 0); | |
29059a65 | 243 | if (sfd == \-1) |
6a578b88 | 244 | handle_error("socket"); |
185f6872 | 245 | |
b40e812a | 246 | memset(&my_addr, 0, sizeof(my_addr)); |
185f6872 MK |
247 | my_addr.sun_family = AF_UNIX; |
248 | strncpy(my_addr.sun_path, MY_SOCK_PATH, | |
29059a65 | 249 | sizeof(my_addr.sun_path) \- 1); |
185f6872 MK |
250 | |
251 | if (bind(sfd, (struct sockaddr *) &my_addr, | |
4687ab0e | 252 | sizeof(my_addr)) == \-1) |
6a578b88 | 253 | handle_error("bind"); |
988db661 | 254 | |
29059a65 | 255 | if (listen(sfd, LISTEN_BACKLOG) == \-1) |
6a578b88 | 256 | handle_error("listen"); |
185f6872 | 257 | |
988db661 | 258 | /* Now we can accept incoming connections one |
c6beb8a1 | 259 | at a time using accept(2). */ |
185f6872 | 260 | |
b40e812a | 261 | peer_addr_size = sizeof(peer_addr); |
185f6872 | 262 | cfd = accept(sfd, (struct sockaddr *) &peer_addr, |
028f847b | 263 | &peer_addr_size); |
29059a65 | 264 | if (cfd == \-1) |
6a578b88 | 265 | handle_error("accept"); |
1f821a55 MK |
266 | |
267 | /* Code to deal with incoming connection(s)... */ | |
268 | ||
529027f0 | 269 | if (close(sfd) == \-1) |
54f3fc2c AC |
270 | handle_error("close"); |
271 | ||
529027f0 | 272 | if (unlink(MY_SOCK_PATH) == \-1) |
54f3fc2c | 273 | handle_error("unlink"); |
185f6872 | 274 | } |
15e88fe8 | 275 | .EE |
33857069 | 276 | .\" SRC END |
47297adb | 277 | .SH SEE ALSO |
fea681da MK |
278 | .BR accept (2), |
279 | .BR connect (2), | |
280 | .BR getsockname (2), | |
281 | .BR listen (2), | |
fea681da | 282 | .BR socket (2), |
0e5b601a | 283 | .BR getaddrinfo (3), |
bbc0dbf0 | 284 | .BR getifaddrs (3), |
fea681da | 285 | .BR ip (7), |
ffa01655 | 286 | .BR ipv6 (7), |
ad7cc990 | 287 | .BR path_resolution (7), |
ffa01655 MK |
288 | .BR socket (7), |
289 | .BR unix (7) |