| blob | 2fec135d9182b5aa59a18490637a4016b9f353ce |
1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
2 .\" and Copyright 2005-2007, Michael Kerrisk <mtk.manpages@gmail.com>
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 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
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 .\"
14 .\" SPDX-License-Identifier: BSD-4-Clause-UC
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 $
19 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
20 .\"
21 .TH bind 2 (date) "Linux man-pages (unreleased)"
22 .SH NAME
23 bind \- bind a name to a socket
24 .SH LIBRARY
25 Standard C library
26 .RI ( libc ", " \-lc )
27 .SH SYNOPSIS
28 .nf
29 .B #include <sys/socket.h>
30 .P
31 .BI "int bind(int " sockfd ", const struct sockaddr *" addr ,
32 .BI " socklen_t " addrlen );
33 .fi
34 .SH DESCRIPTION
35 When a socket is created with
36 .BR socket (2),
37 it exists in a name space (address family) but has no address assigned to it.
38 .BR bind ()
39 assigns the address specified by
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 \[lq]assigning a name to a socket\[rq].
47 .P
48 It is normally necessary to assign a local address using
49 .BR bind ()
50 before a
51 .B SOCK_STREAM
52 socket may receive connections (see
53 .BR accept (2)).
54 .P
55 The rules used in name binding vary between address families.
56 Consult the manual entries in Section 7 for detailed information.
57 For
58 .BR AF_INET ,
59 see
60 .BR ip (7);
61 for
62 .BR AF_INET6 ,
63 see
64 .BR ipv6 (7);
65 for
66 .BR AF_UNIX ,
67 see
68 .BR unix (7);
69 for
70 .BR AF_APPLETALK ,
71 see
72 .BR ddp (7);
73 for
74 .BR AF_PACKET ,
75 see
76 .BR packet (7);
77 for
78 .BR AF_X25 ,
79 see
80 .BR x25 (7);
81 and for
82 .BR AF_NETLINK ,
83 see
84 .BR netlink (7).
85 .P
86 The actual structure passed for the
87 .I addr
88 argument will depend on the address family.
89 The
90 .I sockaddr
91 structure is defined as something like:
92 .P
93 .in +4n
94 .EX
95 struct sockaddr {
96 sa_family_t sa_family;
97 char sa_data[14];
98 }
99 .EE
100 .in
101 .P
102 The only purpose of this structure is to cast the structure
103 pointer passed in
104 .I addr
105 in order to avoid compiler warnings.
106 See EXAMPLES below.
107 .SH RETURN VALUE
108 On success, zero is returned.
109 On error, \-1 is returned, and
110 .I errno
111 is set to indicate the error.
112 .SH ERRORS
113 .TP
114 .B EACCES
115 .\" e.g., privileged port in AF_INET domain
116 The address is protected, and the user is not the superuser.
117 .TP
118 .B EADDRINUSE
119 The given address is already in use.
120 .TP
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
131 .B EBADF
132 .I sockfd
133 is not a valid file descriptor.
134 .TP
135 .B EINVAL
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.
139 .TP
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
146 .B ENOTSOCK
147 The file descriptor
148 .I sockfd
149 does not refer to a socket.
150 .P
151 The following errors are specific to UNIX domain
152 .RB ( AF_UNIX )
153 sockets:
154 .TP
155 .B EACCES
156 Search permission is denied on a component of the path prefix.
157 (See also
158 .BR path_resolution (7).)
159 .TP
160 .B EADDRNOTAVAIL
161 A nonexistent interface was requested or the requested
162 address was not local.
163 .TP
164 .B EFAULT
165 .I addr
166 points outside the user's accessible address space.
167 .TP
168 .B ELOOP
169 Too many symbolic links were encountered in resolving
170 .IR addr .
171 .TP
172 .B ENAMETOOLONG
173 .I addr
174 is too long.
175 .TP
176 .B ENOENT
177 A component in the directory prefix of the socket pathname does not exist.
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
186 The socket inode would reside on a read-only filesystem.
187 .SH STANDARDS
188 POSIX.1-2008.
189 .SH HISTORY
190 POSIX.1-2001, SVr4, 4.4BSD
191 .RB ( bind ()
192 first appeared in 4.2BSD).
193 .\" SVr4 documents an additional
194 .\" .B ENOSR
195 .\" general error condition, and
196 .\" additional
197 .\" .B EIO
198 .\" and
199 .\" .B EISDIR
200 .\" UNIX-domain error conditions.
201 .SH BUGS
202 The transparent proxy options are not described.
203 .\" FIXME Document transparent proxy options
204 .SH EXAMPLES
205 An example of the use of
206 .BR bind ()
207 with Internet domain sockets can be found in
208 .BR getaddrinfo (3).
209 .P
210 The following example shows how to bind a stream socket in the UNIX
211 .RB ( AF_UNIX )
212 domain, and accept connections:
213 .\" listen.7 refers to this example.
214 .\" accept.7 refers to this example.
215 .\" unix.7 refers to this example.
216 .P
217 .\" SRC BEGIN (bind.c)
218 .EX
219 #include <stdio.h>
220 #include <stdlib.h>
221 #include <string.h>
222 #include <sys/socket.h>
223 #include <sys/un.h>
224 #include <unistd.h>
225 \&
226 #define MY_SOCK_PATH "/somepath"
227 #define LISTEN_BACKLOG 50
228 \&
229 #define handle_error(msg) \e
230 do { perror(msg); exit(EXIT_FAILURE); } while (0)
231 \&
232 int
233 main(void)
234 {
235 int sfd, cfd;
236 socklen_t peer_addr_size;
237 struct sockaddr_un my_addr, peer_addr;
238 \&
239 sfd = socket(AF_UNIX, SOCK_STREAM, 0);
240 if (sfd == \-1)
241 handle_error("socket");
242 \&
243 memset(&my_addr, 0, sizeof(my_addr));
244 my_addr.sun_family = AF_UNIX;
245 strncpy(my_addr.sun_path, MY_SOCK_PATH,
246 sizeof(my_addr.sun_path) \- 1);
247 \&
248 if (bind(sfd, (struct sockaddr *) &my_addr,
249 sizeof(my_addr)) == \-1)
250 handle_error("bind");
251 \&
252 if (listen(sfd, LISTEN_BACKLOG) == \-1)
253 handle_error("listen");
254 \&
255 /* Now we can accept incoming connections one
256 at a time using accept(2). */
257 \&
258 peer_addr_size = sizeof(peer_addr);
259 cfd = accept(sfd, (struct sockaddr *) &peer_addr,
260 &peer_addr_size);
261 if (cfd == \-1)
262 handle_error("accept");
263 \&
264 /* Code to deal with incoming connection(s)... */
265 \&
266 if (close(sfd) == \-1)
267 handle_error("close");
268 \&
269 if (unlink(MY_SOCK_PATH) == \-1)
270 handle_error("unlink");
271 }
272 .EE
273 .\" SRC END
274 .SH SEE ALSO
275 .BR accept (2),
276 .BR connect (2),
277 .BR getsockname (2),
278 .BR listen (2),
279 .BR socket (2),
280 .BR getaddrinfo (3),
281 .BR getifaddrs (3),
282 .BR ip (7),
283 .BR ipv6 (7),
284 .BR path_resolution (7),
285 .BR socket (7),
286 .BR unix (7)