| blob | b5fc70767e90259273fa375bbf2f5d0633d16012 |
1 .\" $NetBSD: bind.2,v 1.27 2010/05/31 12:16:20 njoly Exp $
2 .\"
3 .\" Copyright (c) 1983, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)bind.2 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd August 30, 2005
33 .Dt BIND 2
34 .Os
35 .Sh NAME
36 .Nm bind
37 .Nd bind a name to a socket
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/socket.h
42 .Ft int
43 .Fn bind "int s" "const struct sockaddr *name" "socklen_t namelen"
44 .Sh DESCRIPTION
45 .Fn bind
46 assigns a name to an unnamed socket.
47 When a socket is created
48 with
49 .Xr socket 2
50 it exists in a name space (address family)
51 but has no name assigned.
52 .Fn bind
53 requests that
54 .Fa name
55 be assigned to the socket.
56 .Fa namelen
57 indicates the amount of space pointed to by
58 .Fa name ,
59 in bytes.
60 .Sh NOTES
61 Binding a name in the
62 .Ux
63 domain creates a socket in the file
64 system that must be deleted by the caller when it is no longer
65 needed (using
66 .Xr unlink 2 ) .
67 .Pp
68 The rules used in name binding vary between communication domains.
69 Consult the manual entries in section 4 for detailed information.
70 .Sh RETURN VALUES
71 If the bind is successful, a 0 value is returned.
72 A return value of \-1 indicates an error, which is
73 further specified in the global
74 .Va errno .
75 .Sh ERRORS
76 The
77 .Fn bind
78 call will fail if:
79 .Bl -tag -width Er
80 .It Bq Er EBADF
81 .Fa s
82 is not a valid descriptor.
83 .It Bq Er ENOTSOCK
84 .Fa s
85 is not a socket.
86 .It Bq Er EADDRNOTAVAIL
87 The specified address is not available from the local machine.
88 .It Bq Er EADDRINUSE
89 The specified address is already in use.
90 .It Bq Er EINVAL
91 The socket is already bound to an address.
92 .It Bq Er EINVAL
93 The family of the socket and that requested in
94 .Fa name-\*[Gt]sa_family
95 are not equivalent.
96 .It Bq Er EACCES
97 The requested address is protected, and the current user
98 has inadequate permission to access it.
99 .It Bq Er EFAULT
100 The
101 .Fa name
102 parameter is not in a valid part of the user
103 address space.
104 .El
105 .Pp
106 The following errors are specific to binding names in the
107 .Ux
108 domain.
109 .Bl -tag -width Er
110 .It Bq Er ENOTDIR
111 A component of the path prefix is not a directory.
112 .It Bq Er ENAMETOOLONG
113 A component of a pathname exceeded
114 .Brq Dv NAME_MAX
115 characters, or an entire path name exceeded
116 .Brq Dv PATH_MAX
117 characters.
118 .It Bq Er ENOENT
119 A prefix component of the path name does not exist.
120 .It Bq Er ELOOP
121 Too many symbolic links were encountered in translating the pathname.
122 .It Bq Er EIO
123 An I/O error occurred while making the directory entry or allocating the inode.
124 .It Bq Er EROFS
125 The name would reside on a read-only file system.
126 .It Bq Er EISDIR
127 An empty pathname was specified.
128 .El
129 .Sh SEE ALSO
130 .Xr connect 2 ,
131 .Xr getsockname 2 ,
132 .Xr listen 2 ,
133 .Xr socket 2
134 .Sh HISTORY
135 The
136 .Fn bind
137 function call appeared in
138 .Bx 4.2 .
139 .Sh SECURITY CONSIDERATIONS
140 .Fn bind
141 was changed in
142 .Nx 1.4
143 to prevent the binding of a socket to the same port as an existing
144 socket when all of the following is true:
145 .Bl -bullet -compact -offset indent
146 .It
147 either of the existing or new addresses is
148 .Li INADDR_ANY ,
149 .It
150 the uid of the new socket is not root, and
151 the uids of the creators of the sockets are different,
152 .It
153 the address is not a multicast address, and
154 .It
155 both sockets are not bound to
156 .Li INADDR_ANY
157 with
158 .Li SO_REUSEPORT
159 set.
160 .El
161 .Pp
162 This prevents an attack where a user could bind to a port with
163 the host's IP address (after setting
164 .Li SO_REUSEADDR )
165 and
166 .Sq steal
167 packets destined for a server that bound to the
168 same port with
169 .Li INADDR_ANY .
170 .Pp
171 .Fn bind
172 was changed in
173 .Nx 4.0
174 to honor the user's umask when binding sockets in the local domain.
175 This was done to match the behavior of other operating systems,
176 including
177 .Fx ,
178 .Ox ,
179 and
180 Linux, and to improve compatibility with some third-party software.
181 Please note that this behavior
182 .Em is not portable .
183 If you must bind a local socket in a portable and secure way, you need
184 to make a directory with tight permissions and then create the socket
185 inside it.