| .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
| .\" Portions extracted from /usr/include/sys/socket.h, which does not have |
| .\" any authorship information in it. It is probably available under the GPL. |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" |
| .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: |
| .\" |
| .\" Copyright (c) 1983 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 1998 by Andi Kleen |
| .\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ |
| .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .TH BIND 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| bind \- bind a name to a socket |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <sys/types.h>" " /* See NOTES */" |
| .B #include <sys/socket.h> |
| .sp |
| .BI "int bind(int " sockfd ", const struct sockaddr *" addr , |
| .BI " socklen_t " addrlen ); |
| .fi |
| .SH DESCRIPTION |
| When a socket is created with |
| .BR socket (2), |
| it exists in a name space (address family) but has no address assigned to it. |
| .BR bind () |
| assigns the address specified by |
| .I addr |
| to the socket referred to by the file descriptor |
| .IR sockfd . |
| .I addrlen |
| specifies the size, in bytes, of the address structure pointed to by |
| .IR addr . |
| Traditionally, this operation is called \(lqassigning a name to a socket\(rq. |
| .PP |
| It is normally necessary to assign a local address using |
| .BR bind () |
| before a |
| .B SOCK_STREAM |
| socket may receive connections (see |
| .BR accept (2)). |
| |
| The rules used in name binding vary between address families. |
| Consult the manual entries in Section 7 for detailed information. |
| For |
| .B AF_INET |
| see |
| .BR ip (7), |
| for |
| .B AF_INET6 |
| see |
| .BR ipv6 (7), |
| for |
| .B AF_UNIX |
| see |
| .BR unix (7), |
| for |
| .B AF_APPLETALK |
| see |
| .BR ddp (7), |
| for |
| .B AF_PACKET |
| see |
| .BR packet (7), |
| for |
| .B AF_X25 |
| see |
| .BR x25 (7) |
| and for |
| .B AF_NETLINK |
| see |
| .BR netlink (7). |
| |
| The actual structure passed for the |
| .I addr |
| argument will depend on the address family. |
| The |
| .I sockaddr |
| structure is defined as something like: |
| .in +4n |
| .nf |
| |
| struct sockaddr { |
| sa_family_t sa_family; |
| char sa_data[14]; |
| } |
| |
| .fi |
| .in |
| The only purpose of this structure is to cast the structure |
| pointer passed in |
| .I addr |
| in order to avoid compiler warnings. |
| See EXAMPLE below. |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| .\" e.g., privileged port in AF_INET domain |
| The address is protected, and the user is not the superuser. |
| .TP |
| .B EADDRINUSE |
| The given address is already in use. |
| .TP |
| .B EADDRINUSE |
| (Internet domain sockets) |
| The port number was specified as zero in the socket address structure, |
| but, upon attempting to bind to an ephemeral port, |
| it was determined that all port numbers in the ephemeral port range |
| are currently in use. |
| See the discussion of |
| .I /proc/sys/net/ipv4/ip_local_port_range |
| .BR ip (7). |
| .TP |
| .B EBADF |
| .I sockfd |
| is not a valid file descriptor. |
| .TP |
| .B EINVAL |
| The socket is already bound to an address. |
| .\" This may change in the future: see |
| .\" .I linux/unix/sock.c for details. |
| .TP |
| .B EINVAL |
| .I addrlen |
| is wrong, or |
| .I addr |
| is not a valid address for this socket's domain. |
| .TP |
| .B ENOTSOCK |
| The file descriptor |
| .I sockfd |
| does not refer to a socket. |
| .PP |
| The following errors are specific to UNIX domain |
| .RB ( AF_UNIX ) |
| sockets: |
| .TP |
| .B EACCES |
| Search permission is denied on a component of the path prefix. |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .B EADDRNOTAVAIL |
| A nonexistent interface was requested or the requested |
| address was not local. |
| .TP |
| .B EFAULT |
| .I addr |
| points outside the user's accessible address space. |
| .TP |
| .B ELOOP |
| Too many symbolic links were encountered in resolving |
| .IR addr . |
| .TP |
| .B ENAMETOOLONG |
| .I addr |
| is too long. |
| .TP |
| .B ENOENT |
| A component in the directory prefix of the socket pathname does not exist. |
| .TP |
| .B ENOMEM |
| Insufficient kernel memory was available. |
| .TP |
| .B ENOTDIR |
| A component of the path prefix is not a directory. |
| .TP |
| .B EROFS |
| The socket inode would reside on a read-only filesystem. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD |
| .RB ( bind () |
| first appeared in 4.2BSD). |
| .\" SVr4 documents an additional |
| .\" .B ENOSR |
| .\" general error condition, and |
| .\" additional |
| .\" .B EIO |
| .\" and |
| .\" .B EISDIR |
| .\" UNIX-domain error conditions. |
| .SH NOTES |
| POSIX.1 does not require the inclusion of |
| .IR <sys/types.h> , |
| and this header file is not required on Linux. |
| However, some historical (BSD) implementations required this header |
| file, and portable applications are probably wise to include it. |
| |
| The third argument of |
| .BR bind () |
| is in reality an |
| .I int |
| (and this is what 4.x BSD and libc4 and libc5 have). |
| Some POSIX confusion resulted in the present |
| .IR socklen_t , |
| also used by glibc. |
| See also |
| .BR accept (2). |
| .SH BUGS |
| The transparent proxy options are not described. |
| .\" FIXME Document transparent proxy options |
| .SH EXAMPLE |
| An example of the use of |
| .BR bind () |
| with Internet domain sockets can be found in |
| .BR getaddrinfo (3). |
| |
| The following example shows how to bind a stream socket in the UNIX |
| .RB ( AF_UNIX ) |
| domain, and accept connections: |
| .\" listen.7 refers to this example. |
| .\" accept.7 refers to this example. |
| .\" unix.7 refers to this example. |
| |
| .nf |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| #include <string.h> |
| |
| #define MY_SOCK_PATH "/somepath" |
| #define LISTEN_BACKLOG 50 |
| |
| #define handle_error(msg) \\ |
| do { perror(msg); exit(EXIT_FAILURE); } while (0) |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int sfd, cfd; |
| struct sockaddr_un my_addr, peer_addr; |
| socklen_t peer_addr_size; |
| |
| sfd = socket(AF_UNIX, SOCK_STREAM, 0); |
| if (sfd == \-1) |
| handle_error("socket"); |
| |
| memset(&my_addr, 0, sizeof(struct sockaddr_un)); |
| /* Clear structure */ |
| my_addr.sun_family = AF_UNIX; |
| strncpy(my_addr.sun_path, MY_SOCK_PATH, |
| sizeof(my_addr.sun_path) \- 1); |
| |
| if (bind(sfd, (struct sockaddr *) &my_addr, |
| sizeof(struct sockaddr_un)) == \-1) |
| handle_error("bind"); |
| |
| if (listen(sfd, LISTEN_BACKLOG) == \-1) |
| handle_error("listen"); |
| |
| /* Now we can accept incoming connections one |
| at a time using accept(2) */ |
| |
| peer_addr_size = sizeof(struct sockaddr_un); |
| cfd = accept(sfd, (struct sockaddr *) &peer_addr, |
| &peer_addr_size); |
| if (cfd == \-1) |
| handle_error("accept"); |
| |
| /* Code to deal with incoming connection(s)... */ |
| |
| /* When no longer required, the socket pathname, MY_SOCK_PATH |
| should be deleted using unlink(2) or remove(3) */ |
| } |
| .fi |
| .SH SEE ALSO |
| .BR accept (2), |
| .BR connect (2), |
| .BR getsockname (2), |
| .BR listen (2), |
| .BR socket (2), |
| .BR getaddrinfo (3), |
| .BR getifaddrs (3), |
| .BR ip (7), |
| .BR ipv6 (7), |
| .BR path_resolution (7), |
| .BR socket (7), |
| .BR unix (7) |