lib/libc/bind.2

   1 .\"     $OpenBSD: bind.2,v 1.21 2015/10/11 07:25:11 guenther Exp $
   2 .\"     $NetBSD: bind.2,v 1.8 1995/10/12 15:40:46 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)bind.2      8.1 (Berkeley) 6/4/93
  32 .\"
  33 .Dd October 24, 2016
  34 .Dt BIND 2
  35 .Os
  36 .Sh NAME
  37 .Nm bind
  38 .Nd bind a name to a socket
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .Ft int
  42 .Fn bind "int s" "const struct sockaddr *name" "socklen_t namelen"
  43 .Sh DESCRIPTION
  44 .Fn bind
  45 assigns a name to an unnamed socket.
  46 When a socket is created with
  47 .Xr socket 2
  48 it exists in a name space (address family) but has no name assigned.
  49 .Fn bind
  50 requests that
  51 .Fa name
  52 be assigned to the socket.
  53 .Fa namelen
  54 indicates the amount of space pointed to by
  55 .Fa name ,
  56 in bytes; the
  57 .Fa sa_len
  58 member of
  59 .Fa name
  60 is ignored.
  61 .Sh NOTES
  62 Binding a name in the
  63 .Ux Ns -domain
  64 creates a socket in the file system that must be deleted by the caller
  65 when it is no longer needed (using
  66 .Xr unlink 2 ) .
  67 .Pp
  68 The rules used in name binding vary between communication domains.
  69 Consult the manual entries in section 7P for detailed information.
  70 .Sh RETURN VALUES
  71 .Rv -std
  72 .Sh ERRORS
  73 The
  74 .Fn bind
  75 function will fail if:
  76 .Bl -tag -width Er
  77 .It Bq Er EBADF
  78 .Fa s
  79 is not a valid descriptor.
  80 .It Bq Er ENOTSOCK
  81 .Fa s
  82 is not a socket.
  83 .It Bq Er EADDRNOTAVAIL
  84 The specified address is not available from the local machine.
  85 .It Bq Er EADDRINUSE
  86 The specified address is already in use.
  87 .It Bq Er EINVAL
  88 The socket is already bound to an address, or
  89 .Fa namelen
  90 is not a valid length for the supplied address.
  91 .It Bq Er EAFNOSUPPORT
  92 The family of the socket and that requested in
  93 .Va name->sa_family
  94 are not equivalent.
  95 .It Bq Er ENOBUFS
  96 Insufficient buffer space is available.
  97 .It Bq Er EACCES
  98 The requested address is protected, and the current user
  99 has inadequate permission to access it.
 100 .It Bq Er EFAULT
 101 The
 102 .Fa name
 103 parameter is not in a valid part of the user address space.
 104 .El
 105 .Pp
 106 The following errors are specific to binding names in the
 107 .Ux Ns -domain .
 108 .Bl -tag -width Er
 109 .It Bq Er ENOTDIR
 110 A component of the path prefix is not a directory.
 111 .It Bq Er ENAMETOOLONG
 112 A component of a pathname exceeded
 113 .Dv NAME_MAX
 114 characters, or an entire pathname (including the terminating NUL)
 115 exceeded
 116 .Dv PATH_MAX
 117 bytes.
 118 .It Bq Er ENOENT
 119 A prefix component of the path name does not exist.
 120 .It Bq Er ELOOP
 121 Too many symbolic links were encountered in translating the pathname.
 122 .It Bq Er EIO
 123 An I/O error occurred while making the directory entry or allocating the inode.
 124 .It Bq Er EROFS
 125 The name would reside on a read-only file system.
 126 .It Bq Er EISDIR
 127 An empty pathname was specified.
 128 .El
 129 .Sh SEE ALSO
 130 .Xr connect 2 ,
 131 .Xr getsockname 2 ,
 132 .Xr listen 2 ,
 133 .Xr socket 2
 134 .Sh STANDARDS
 135 The
 136 .Fn bind
 137 function conforms to
 138 .St -p1003.1-2008 .
 139 .Sh HISTORY
 140 The
 141 .Fn bind
 142 system call first appeared in
 143 .Bx 4.1c .