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