usr/src/man/man3socket/bind.3socket

   1 '\" te
   2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH BIND 3SOCKET "May 11, 2009"
   8 .SH NAME
   9 bind \- bind a name to a socket
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  14 #include <sys/types.h>
  15 #include <sys/socket.h>
  16
  17
  18
  19 \fBint\fR \fBbind\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .LP
  24 The \fBbind()\fR function assigns a name to an unnamed socket. When a socket is
  25 created with \fBsocket\fR(3SOCKET), it exists in a name space (address family)
  26 but has no name assigned. The \fBbind()\fR function requests that the name
  27 pointed to by \fIname\fR be assigned to the socket.
  28 .SH RETURN VALUES
  29 .LP
  30 Upon successful completion \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
  31 returned and \fBerrno\fR is set to indicate the error.
  32 .SH ERRORS
  33 .LP
  34 The \fBbind()\fR function will fail if:
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fBEACCES\fR\fR
  39 .ad
  40 .RS 17n
  41 The requested address is protected, and \fB{PRIV_NET_PRIVADDR}\fR is not
  42 asserted in the effective set of the current process.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBEADDRINUSE\fR\fR
  49 .ad
  50 .RS 17n
  51 The specified address is already in use.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBEADDRNOTAVAIL\fR\fR
  58 .ad
  59 .RS 17n
  60 The specified address is not available on the local machine.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBEBADF\fR\fR
  67 .ad
  68 .RS 17n
  69 \fIs\fR is not a valid descriptor.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBEINVAL\fR\fR
  76 .ad
  77 .RS 17n
  78 \fInamelen\fR is not the size of a valid address for the specified address
  79 family.
  80 .sp
  81 The socket is already bound to an address.
  82 .sp
  83 Socket options are inconsistent with port attributes.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBENOSR\fR\fR
  90 .ad
  91 .RS 17n
  92 There were insufficient \fBSTREAMS\fR resources for the operation to complete.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBENOTSOCK\fR\fR
  99 .ad
 100 .RS 17n
 101 \fIs\fR is a descriptor for a file, not a socket.
 102 .RE
 103
 104 .sp
 105 .LP
 106 The following errors are specific to binding names in the UNIX domain:
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBEACCES\fR\fR
 111 .ad
 112 .RS 11n
 113 Search permission is denied for a component of the path prefix of the pathname
 114 in \fIname\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEIO\fR\fR
 121 .ad
 122 .RS 11n
 123 An I/O error occurred while making the directory entry or allocating the inode.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBEISDIR\fR\fR
 130 .ad
 131 .RS 11n
 132 A null pathname was specified.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBELOOP\fR\fR
 139 .ad
 140 .RS 11n
 141 Too many symbolic links were encountered in translating the pathname in
 142 \fIname\fR.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBENOENT\fR\fR
 149 .ad
 150 .RS 11n
 151 A component of the path prefix of the pathname in \fIname\fR does not exist.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBENOTDIR\fR\fR
 158 .ad
 159 .RS 11n
 160 A component of the path prefix of the pathname in \fIname\fR is not a
 161 directory.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBEROFS\fR\fR
 168 .ad
 169 .RS 11n
 170 The inode would reside on a read-only file system.
 171 .RE
 172
 173 .SH ATTRIBUTES
 174 .LP
 175 See \fBattributes\fR(5) for descriptions of the following attributes:
 176 .sp
 177
 178 .sp
 179 .TS
 180 box;
 181 c | c
 182 l | l .
 183 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 184 _
 185 MT-Level        Safe
 186 .TE
 187
 188 .SH SEE ALSO
 189 .LP
 190 \fBunlink\fR(2), \fBsocket\fR(3SOCKET), \fBsockaddr\fR(3SOCKET),
 191 \fBattributes\fR(5), \fBprivileges\fR(5), \fBsocket.h\fR(3HEAD)
 192 .SH NOTES
 193 .LP
 194 Binding a name in the UNIX domain creates a socket in the file system that must
 195 be deleted by the caller when it is no longer needed by using \fBunlink\fR(2).
 196 .sp
 197 .LP
 198 The rules used in name binding vary between communication domains.