mirror of https://github.com/mkerrisk/man-pages
330 lines
9.0 KiB
Groff
330 lines
9.0 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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 2007-12-28 "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 to 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 EBADF
|
|
.I sockfd
|
|
is not a valid 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 ENOTSOCK
|
|
.I sockfd
|
|
is a descriptor for a file, not 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 EINVAL
|
|
The
|
|
.I addrlen
|
|
is wrong, or the socket was not in the
|
|
.B AF_UNIX
|
|
family.
|
|
.TP
|
|
.B ELOOP
|
|
Too many symbolic links were encountered in resolving
|
|
.IR addr .
|
|
.TP
|
|
.B ENAMETOOLONG
|
|
.I addr
|
|
is too long.
|
|
.TP
|
|
.B ENOENT
|
|
The file 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 file system.
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.4BSD, POSIX.1-2001
|
|
.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-2001 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 What *are* 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)
|