bind(2) - c6

1BIND(2)                    Linux Programmer's Manual                   BIND(2)
2
3
4

NAME

6       bind - bind a name to a socket
7

SYNOPSIS

9       #include <sys/types.h>          /* See NOTES */
10       #include <sys/socket.h>
11
12       int bind(int sockfd, const struct sockaddr *addr,
13                socklen_t addrlen);
14

DESCRIPTION

16       When  a  socket  is  created  with socket(2), it exists in a name space
17       (address family) but has no address assigned to it.  bind() assigns the
18       address  specified  to  by  addr  to the socket referred to by the file
19       descriptor sockfd.  addrlen  specifies  the  size,  in  bytes,  of  the
20       address structure pointed to by addr.  Traditionally, this operation is
21       called “assigning a name to a socket”.
22
23       It is normally necessary to assign a local address using bind()  before
24       a SOCK_STREAM socket may receive connections (see accept(2)).
25
26       The  rules used in name binding vary between address families.  Consult
27       the manual entries in Section 7 for detailed information.  For  AF_INET
28       see  ip(7),  for  AF_INET6  see  ipv6(7),  for AF_UNIX see unix(7), for
29       AF_APPLETALK see ddp(7), for AF_PACKET see packet(7),  for  AF_X25  see
30       x25(7) and for AF_NETLINK see netlink(7).
31
32       The  actual  structure  passed for the addr argument will depend on the
33       address family.  The sockaddr structure is defined as something like:
34
35           struct sockaddr {
36               sa_family_t sa_family;
37               char        sa_data[14];
38           }
39
40       The only purpose of this structure is to  cast  the  structure  pointer
41       passed in addr in order to avoid compiler warnings.  See EXAMPLE below.
42

RETURN VALUE

44       On  success,  zero is returned.  On error, -1 is returned, and errno is
45       set appropriately.
46

ERRORS

48       EACCES The address is protected, and the user is not the superuser.
49
50       EADDRINUSE
51              The given address is already in use.
52
53       EBADF  sockfd is not a valid descriptor.
54
55       EINVAL The socket is already bound to an address.
56
57       ENOTSOCK
58              sockfd is a descriptor for a file, not a socket.
59
60       The following errors are specific to Unix domain (AF_UNIX) sockets:
61
62       EACCES Search permission is denied on a component of the  path  prefix.
63              (See also path_resolution(7).)
64
65       EADDRNOTAVAIL
66              A  nonexistent  interface was requested or the requested address
67              was not local.
68
69       EFAULT addr points outside the user's accessible address space.
70
71       EINVAL The addrlen is wrong, or the socket was not in the AF_UNIX  fam‐
72              ily.
73
74       ELOOP  Too many symbolic links were encountered in resolving addr.
75
76       ENAMETOOLONG
77              addr is too long.
78
79       ENOENT The file does not exist.
80
81       ENOMEM Insufficient kernel memory was available.
82
83       ENOTDIR
84              A component of the path prefix is not a directory.
85
86       EROFS  The socket inode would reside on a read-only file system.
87

CONFORMING TO

89       SVr4, 4.4BSD, POSIX.1-2001 (bind() first appeared in 4.2BSD).
90

NOTES

92       POSIX.1-2001  does not require the inclusion of <sys/types.h>, and this
93       header file is not required on Linux.  However, some  historical  (BSD)
94       implementations  required  this  header file, and portable applications
95       are probably wise to include it.
96
97       The third argument of bind() is in reality an int (and this is what 4.x
98       BSD  and  libc4  and libc5 have).  Some POSIX confusion resulted in the
99       present socklen_t, also used by glibc.  See also accept(2).
100

BUGS

102       The transparent proxy options are not described.
103

EXAMPLE

105       An example of the use of bind() with Internet  domain  sockets  can  be
106       found in getaddrinfo(3).
107
108       The  following  example  shows  how to bind a stream socket in the Unix
109       (AF_UNIX) domain, and accept connections:
110
111       #include <sys/socket.h>
112       #include <sys/un.h>
113       #include <stdlib.h>
114       #include <stdio.h>
115       #include <string.h>
116
117       #define MY_SOCK_PATH "/somepath"
118       #define LISTEN_BACKLOG 50
119
120       #define handle_error(msg) \
121           do { perror(msg); exit(EXIT_FAILURE); } while (0)
122
123       int
124       main(int argc, char *argv[])
125       {
126           int sfd, cfd;
127           struct sockaddr_un my_addr, peer_addr;
128           socklen_t peer_addr_size;
129
130           sfd = socket(AF_UNIX, SOCK_STREAM, 0);
131           if (sfd == -1)
132               handle_error("socket");
133
134           memset(&my_addr, 0, sizeof(struct sockaddr_un));
135                               /* Clear structure */
136           my_addr.sun_family = AF_UNIX;
137           strncpy(my_addr.sun_path, MY_SOCK_PATH,
138                   sizeof(my_addr.sun_path) - 1);
139
140           if (bind(sfd, (struct sockaddr *) &my_addr,
141                   sizeof(struct sockaddr_un)) == -1)
142               handle_error("bind");
143
144           if (listen(sfd, LISTEN_BACKLOG) == -1)
145               handle_error("listen");
146
147           /* Now we can accept incoming connections one
148              at a time using accept(2) */
149
150           peer_addr_size = sizeof(struct sockaddr_un);
151           cfd = accept(sfd, (struct sockaddr *) &peer_addr,
152                        &peer_addr_size);
153           if (cfd == -1)
154               handle_error("accept");
155
156           /* Code to deal with incoming connection(s)... */
157
158           /* When no longer required, the socket pathname, MY_SOCK_PATH
159              should be deleted using unlink(2) or remove(3) */
160       }
161

COLOPHON

168       This page is part of release 3.22 of the Linux  man-pages  project.   A
169       description  of  the project, and information about reporting bugs, can
170       be found at http://www.kernel.org/doc/man-pages/.
171
172
173
174Linux                             2007-12-28                           BIND(2)