Debian Codegraph @

upstream/fedora-44/man2/bind.2

raw
1 .\" Copyright 1993 Rickard E. Faith ([email protected])
2 .\" and Copyright 2005-2007, Michael Kerrisk <[email protected]>
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 <[email protected]>
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 <[email protected]>
20 .\"
21 .TH bind 2 2024-11-06 "Linux man-pages 6.13"
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 .TP
151 .B EADDRNOTAVAIL
152 A nonexistent interface was requested or the requested
153 address was not local.
154 .P
155 The following errors are specific to UNIX domain
156 .RB ( AF_UNIX )
157 sockets:
158 .TP
159 .B EACCES
160 Search permission is denied on a component of the path prefix.
161 (See also
162 .BR path_resolution (7).)
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 .P
188 Other errors may be generated by the underlying protocol modules.
189 .SH STANDARDS
190 POSIX.1-2008.
191 .SH HISTORY
192 POSIX.1-2001, SVr4, 4.4BSD
193 .RB ( bind ()
194 first appeared in 4.2BSD).
195 .\" SVr4 documents an additional
196 .\" .B ENOSR
197 .\" general error condition, and
198 .\" additional
199 .\" .B EIO
200 .\" and
201 .\" .B EISDIR
202 .\" UNIX-domain error conditions.
203 .SH BUGS
204 The transparent proxy options are not described.
205 .\" FIXME Document transparent proxy options
206 .SH EXAMPLES
207 An example of the use of
208 .BR bind ()
209 with Internet domain sockets can be found in
210 .BR getaddrinfo (3).
211 .P
212 The following example shows how to bind a stream socket in the UNIX
213 .RB ( AF_UNIX )
214 domain, and accept connections:
215 .\" listen.7 refers to this example.
216 .\" accept.7 refers to this example.
217 .\" unix.7 refers to this example.
218 .P
219 .\" SRC BEGIN (bind.c)
220 .EX
221 #include <stdio.h>
222 #include <stdlib.h>
223 #include <string.h>
224 #include <sys/socket.h>
225 #include <sys/un.h>
226 #include <unistd.h>
227 \&
228 #define MY_SOCK_PATH "/somepath"
229 #define LISTEN_BACKLOG 50
230 \&
231 #define handle_error(msg) \[rs]
232 do { perror(msg); exit(EXIT_FAILURE); } while (0)
233 \&
234 int
235 main(void)
236 {
237 int sfd, cfd;
238 socklen_t peer_addr_size;
239 struct sockaddr_un my_addr, peer_addr;
240 \&
241 sfd = socket(AF_UNIX, SOCK_STREAM, 0);
242 if (sfd == \-1)
243 handle_error("socket");
244 \&
245 memset(&my_addr, 0, sizeof(my_addr));
246 my_addr.sun_family = AF_UNIX;
247 strncpy(my_addr.sun_path, MY_SOCK_PATH,
248 sizeof(my_addr.sun_path) \- 1);
249 \&
250 if (bind(sfd, (struct sockaddr *) &my_addr,
251 sizeof(my_addr)) == \-1)
252 handle_error("bind");
253 \&
254 if (listen(sfd, LISTEN_BACKLOG) == \-1)
255 handle_error("listen");
256 \&
257 /* Now we can accept incoming connections one
258 at a time using accept(2). */
259 \&
260 peer_addr_size = sizeof(peer_addr);
261 cfd = accept(sfd, (struct sockaddr *) &peer_addr,
262 &peer_addr_size);
263 if (cfd == \-1)
264 handle_error("accept");
265 \&
266 /* Code to deal with incoming connection(s)... */
267 \&
268 if (close(sfd) == \-1)
269 handle_error("close");
270 \&
271 if (unlink(MY_SOCK_PATH) == \-1)
272 handle_error("unlink");
273 }
274 .EE
275 .\" SRC END
276 .SH SEE ALSO
277 .BR accept (2),
278 .BR connect (2),
279 .BR getsockname (2),
280 .BR listen (2),
281 .BR socket (2),
282 .BR getaddrinfo (3),
283 .BR getifaddrs (3),
284 .BR ip (7),
285 .BR ipv6 (7),
286 .BR path_resolution (7),
287 .BR socket (7),
288 .BR unix (7)