mirror of https://github.com/mkerrisk/man-pages
279 lines
7.4 KiB
Groff
279 lines
7.4 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@gmx.net>
|
|
.\"
|
|
.TH BIND 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
bind \- bind a name to a socket
|
|
.SH SYNOPSIS
|
|
.B #include <sys/types.h>
|
|
.br
|
|
.B #include <sys/socket.h>
|
|
.sp
|
|
.BI "int bind(int " sockfd ", const struct sockaddr *" my_addr \
|
|
", socklen_t " addrlen );
|
|
.SH DESCRIPTION
|
|
.BR bind ()
|
|
gives the socket
|
|
.I sockfd
|
|
the local address
|
|
.IR my_addr .
|
|
.I my_addr
|
|
is
|
|
.I addrlen
|
|
bytes long.
|
|
Traditionally, this is called \(lqassigning a name to a socket.\(rq
|
|
When a socket is created with
|
|
.BR socket (2),
|
|
it exists in a name space (address family) but has no name assigned.
|
|
.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 my_addr
|
|
argument will depend on the address family.
|
|
The
|
|
.I sockaddr
|
|
structure is defined as something like:
|
|
.in +0.25in
|
|
.nf
|
|
|
|
struct sockaddr {
|
|
sa_family_t sa_family;
|
|
char sa_data[14];
|
|
}
|
|
|
|
.fi
|
|
.in -0.25in
|
|
The only purpose of this structure is to cast the structure
|
|
pointer passed in
|
|
.I my_addr
|
|
in order to avoid compiler warnings.
|
|
The following example shows how this is done when binding a socket
|
|
in the Unix
|
|
.RB ( AF_UNIX )
|
|
domain:
|
|
|
|
.in +0.25in
|
|
.nf
|
|
#include <sys/socket.h>
|
|
#include <sys/un.h>
|
|
|
|
int sfd;
|
|
struct sockaddr_un addr;
|
|
|
|
sfd = socket(AF_UNIX, SOCK_STREAM, 0);
|
|
if (sfd == -1) { perror("socket"); exit(EXIT_FAILURE); }
|
|
|
|
memset(&addr, 0, sizeof(struct sockaddr_un));
|
|
/* Clear structure */
|
|
addr.sun_family = AF_UNIX;
|
|
strncpy(addr.sun_path, MY_SOCK_PATH,
|
|
sizeof(addr.sun_path) - 1);
|
|
|
|
if (bind(sfd, (struct sockaddr *) &addr,
|
|
sizeof(struct sockaddr_un)) == -1) {
|
|
perror("bind");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
.fi
|
|
.in -0.25in
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned. On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
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
|
|
Argument 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 (2).)
|
|
.TP
|
|
.B EFAULT
|
|
.I my_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 my_addr .
|
|
.TP
|
|
.B ENAMETOOLONG
|
|
.I my_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 BUGS
|
|
The transparent proxy options are not described.
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.4BSD (the
|
|
.BR bind ()
|
|
function first appeared in 4.2BSD).
|
|
SVr4 documents additional
|
|
.BR EADDRNOTAVAIL
|
|
and
|
|
.B ENOSR
|
|
general error conditions, and
|
|
additional
|
|
.B EIO
|
|
and
|
|
.B EISDIR
|
|
Unix-domain error conditions.
|
|
.SH NOTE
|
|
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 "SEE ALSO"
|
|
.BR accept (2),
|
|
.BR connect (2),
|
|
.BR getsockname (2),
|
|
.BR listen (2),
|
|
.BR path_resolution (2),
|
|
.BR socket (2),
|
|
.BR getaddrinfo (3),
|
|
.BR ip (7),
|
|
.BR ipv6 (7),
|
|
.BR socket (7),
|
|
.BR unix (7)
|