Debian Codegraph @

upstream/debian-unstable/man2/bind.2

raw
1 .\" Copyright 1993, Rickard E. Faith <[email protected]>
2 .\" Copyright 2005-2007, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\"
8 .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page:
9 .\"
10 .\" Copyright 1983, The Regents of the University of California.
11 .\"
12 .\" SPDX-License-Identifier: BSD-4-Clause-UC
13 .\"
14 .TH bind 2 2026-02-08 "Linux man-pages 6.18"
15 .SH NAME
16 bind \- bind a name to a socket
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ,\~ \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <sys/socket.h>
23 .P
24 .BI "int bind(int " sockfd ", const struct sockaddr *" addr ,
25 .BI " socklen_t " addrlen );
26 .fi
27 .SH DESCRIPTION
28 When a socket is created with
29 .BR socket (2),
30 it exists in a name space (address family) but has no address assigned to it.
31 .BR bind ()
32 assigns the address specified by
33 .I addr
34 to the socket referred to by the file descriptor
35 .IR sockfd .
36 .I addrlen
37 specifies the size, in bytes, of the address structure pointed to by
38 .IR addr .
39 Traditionally, this operation is called \[lq]assigning a name to a socket\[rq].
40 .P
41 It is normally necessary to assign a local address using
42 .BR bind ()
43 before a
44 .B SOCK_STREAM
45 socket may receive connections (see
46 .BR accept (2)).
47 .P
48 The rules used in name binding vary between address families.
49 Consult the manual entries in Section 7 for detailed information.
50 For
51 .BR AF_INET ,
52 see
53 .BR ip (7);
54 for
55 .BR AF_INET6 ,
56 see
57 .BR ipv6 (7);
58 for
59 .BR AF_UNIX ,
60 see
61 .BR unix (7);
62 for
63 .BR AF_APPLETALK ,
64 see
65 .BR ddp (7);
66 for
67 .BR AF_PACKET ,
68 see
69 .BR packet (7);
70 for
71 .BR AF_X25 ,
72 see
73 .BR x25 (7);
74 and for
75 .BR AF_NETLINK ,
76 see
77 .BR netlink (7).
78 .P
79 The actual structure passed for the
80 .I addr
81 argument will depend on the address family.
82 The
83 .I sockaddr
84 structure is defined as something like:
85 .P
86 .in +4n
87 .EX
88 struct sockaddr {
89 sa_family_t sa_family;
90 char sa_data[14];
91 }
92 .EE
93 .in
94 .P
95 The only purpose of this structure is to cast the structure
96 pointer passed in
97 .I addr
98 in order to avoid compiler warnings.
99 See EXAMPLES below.
100 .SH RETURN VALUE
101 On success, zero is returned.
102 On error, \-1 is returned, and
103 .I errno
104 is set to indicate the error.
105 .SH ERRORS
106 .TP
107 .B EACCES
108 .\" e.g., privileged port in AF_INET domain
109 The address is protected, and the user is not the superuser.
110 .TP
111 .B EADDRINUSE
112 The given address is already in use.
113 .TP
114 .B EADDRINUSE
115 (Internet domain sockets)
116 The port number was specified as zero in the socket address structure,
117 but, upon attempting to bind to an ephemeral port,
118 it was determined that all port numbers in the ephemeral port range
119 are currently in use.
120 See the discussion of
121 .I /proc/sys/net/ipv4/ip_local_port_range
122 .BR ip (7).
123 .TP
124 .B EBADF
125 .I sockfd
126 is not a valid file descriptor.
127 .TP
128 .B EINVAL
129 The socket is already bound to an address.
130 .\" This may change in the future: see
131 .\" .I linux/unix/sock.c for details.
132 .TP
133 .B EINVAL
134 .I addrlen
135 is wrong, or
136 .I addr
137 is not a valid address for this socket's domain.
138 .TP
139 .B ENOTSOCK
140 The file descriptor
141 .I sockfd
142 does not refer to a socket.
143 .TP
144 .B EADDRNOTAVAIL
145 A nonexistent interface was requested or the requested
146 address was not local.
147 .P
148 The following errors are specific to UNIX domain
149 .RB ( AF_UNIX )
150 sockets:
151 .TP
152 .B EACCES
153 Search permission is denied on a component of the path prefix.
154 (See also
155 .BR path_resolution (7).)
156 .TP
157 .B EFAULT
158 .I addr
159 points outside the user's accessible address space.
160 .TP
161 .B ELOOP
162 Too many symbolic links were encountered in resolving
163 .IR addr .
164 .TP
165 .B ENAMETOOLONG
166 .I addr
167 is too long.
168 .TP
169 .B ENOENT
170 A component in the directory prefix of the socket pathname does not exist.
171 .TP
172 .B ENOMEM
173 Insufficient kernel memory was available.
174 .TP
175 .B ENOTDIR
176 A component of the path prefix is not a directory.
177 .TP
178 .B EROFS
179 The socket inode would reside on a read-only filesystem.
180 .P
181 Other errors may be generated by the underlying protocol modules.
182 .SH VERSIONS
183 Portable programs must ensure that
184 .I addr.sun_path
185 is a null-terminated string
186 for
187 .B AF_UNIX
188 sockets.
189 .SH STANDARDS
190 POSIX.1-2024.
191 .SH HISTORY
192 POSIX.1-2001, SVr4, 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 <err.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 int
230 main(void)
231 {
232 int sfd, cfd;
233 socklen_t peer_addr_size;
234 struct sockaddr_un my_addr, peer_addr;
235 \&
236 sfd = socket(AF_UNIX, SOCK_STREAM, 0);
237 if (sfd == \-1)
238 err(EXIT_FAILURE, "socket");
239 \&
240 memset(&my_addr, 0, sizeof(my_addr));
241 my_addr.sun_family = AF_UNIX;
242 strncpy(my_addr.sun_path, MY_SOCK_PATH,
243 sizeof(my_addr.sun_path) \- 1);
244 \&
245 if (bind(sfd, (struct sockaddr *) &my_addr,
246 sizeof(my_addr)) == \-1)
247 err(EXIT_FAILURE, "bind");
248 \&
249 if (listen(sfd, LISTEN_BACKLOG) == \-1)
250 err(EXIT_FAILURE, "listen");
251 \&
252 /* Now we can accept incoming connections one
253 at a time using accept(2). */
254 \&
255 peer_addr_size = sizeof(peer_addr);
256 cfd = accept(sfd, (struct sockaddr *) &peer_addr,
257 &peer_addr_size);
258 if (cfd == \-1)
259 err(EXIT_FAILURE, "accept");
260 \&
261 /* Code to deal with incoming connection(s)... */
262 \&
263 if (close(sfd) == \-1)
264 err(EXIT_FAILURE, "close");
265 \&
266 if (unlink(MY_SOCK_PATH) == \-1)
267 err(EXIT_FAILURE, "unlink");
268 }
269 .EE
270 .\" SRC END
271 .SH SEE ALSO
272 .BR accept (2),
273 .BR connect (2),
274 .BR getsockname (2),
275 .BR listen (2),
276 .BR socket (2),
277 .BR getaddrinfo (3),
278 .BR getifaddrs (3),
279 .BR ip (7),
280 .BR ipv6 (7),
281 .BR path_resolution (7),
282 .BR socket (7),
283 .BR unix (7)