summaryrefslogtreecommitdiffstats
path: root/man2/bind.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/bind.2')
-rw-r--r--man2/bind.2286
1 files changed, 286 insertions, 0 deletions
diff --git a/man2/bind.2 b/man2/bind.2
new file mode 100644
index 0000000..6288c41
--- /dev/null
+++ b/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 2023-05-03 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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].
+.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)).
+.PP
+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).
+.PP
+The actual structure passed for the
+.I addr
+argument will depend on the address family.
+The
+.I sockaddr
+structure is defined as something like:
+.PP
+.in +4n
+.EX
+struct sockaddr {
+ sa_family_t sa_family;
+ char sa_data[14];
+}
+.EE
+.in
+.PP
+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.
+.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 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).
+.PP
+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.
+.PP
+.\" 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)