diff options
Diffstat (limited to 'man/man2/bind.2')
| -rw-r--r-- | man/man2/bind.2 | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/man/man2/bind.2 b/man/man2/bind.2 new file mode 100644 index 000000000..2fec135d9 --- /dev/null +++ b/man/man2/bind.2 @@ -0,0 +1,286 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" and Copyright 2005-2007, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.\" 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. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +bind \- bind a name to a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.P +.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 \[lq]assigning a name to a socket\[rq]. +.P +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)). +.P +The rules used in name binding vary between address families. +Consult the manual entries in Section 7 for detailed information. +For +.BR AF_INET , +see +.BR ip (7); +for +.BR AF_INET6 , +see +.BR ipv6 (7); +for +.BR AF_UNIX , +see +.BR unix (7); +for +.BR AF_APPLETALK , +see +.BR ddp (7); +for +.BR AF_PACKET , +see +.BR packet (7); +for +.BR AF_X25 , +see +.BR x25 (7); +and for +.BR AF_NETLINK , +see +.BR netlink (7). +.P +The actual structure passed for the +.I addr +argument will depend on the address family. +The +.I sockaddr +structure is defined as something like: +.P +.in +4n +.EX +struct sockaddr { + sa_family_t sa_family; + char sa_data[14]; +} +.EE +.in +.P +The only purpose of this structure is to cast the structure +pointer passed in +.I addr +in order to avoid compiler warnings. +See EXAMPLES below. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.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. +.P +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 STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 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 BUGS +The transparent proxy options are not described. +.\" FIXME Document transparent proxy options +.SH EXAMPLES +An example of the use of +.BR bind () +with Internet domain sockets can be found in +.BR getaddrinfo (3). +.P +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. +.P +.\" SRC BEGIN (bind.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/socket.h> +#include <sys/un.h> +#include <unistd.h> +\& +#define MY_SOCK_PATH "/somepath" +#define LISTEN_BACKLOG 50 +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +int +main(void) +{ + int sfd, cfd; + socklen_t peer_addr_size; + struct sockaddr_un my_addr, peer_addr; +\& + sfd = socket(AF_UNIX, SOCK_STREAM, 0); + if (sfd == \-1) + handle_error("socket"); +\& + memset(&my_addr, 0, sizeof(my_addr)); + 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(my_addr)) == \-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(peer_addr); + cfd = accept(sfd, (struct sockaddr *) &peer_addr, + &peer_addr_size); + if (cfd == \-1) + handle_error("accept"); +\& + /* Code to deal with incoming connection(s)... */ +\& + if (close(sfd) == \-1) + handle_error("close"); +\& + if (unlink(MY_SOCK_PATH) == \-1) + handle_error("unlink"); +} +.EE +.\" SRC END +.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) |