lib/libc/sys/socket.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)socket.2      8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/sys/socket.2,v 1.12.2.11 2002/12/29 16:35:34 schweikh Exp $
  34 .\"
  35 .Dd November 24, 1997
  36 .Dt SOCKET 2
  37 .Os
  38 .Sh NAME
  39 .Nm socket
  40 .Nd create an endpoint for communication
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/socket.h
  46 .Ft int
  47 .Fn socket "int domain" "int type" "int protocol"
  48 .Sh DESCRIPTION
  49 .Fn Socket
  50 creates an endpoint for communication and returns a descriptor.
  51 .Pp
  52 The
  53 .Fa domain
  54 parameter specifies a communications domain within which
  55 communication will take place; this selects the protocol family
  56 which should be used.
  57 These families are defined in the include file
  58 .In sys/socket.h .
  59 The currently understood formats are:
  60 .Pp
  61 .Bd -literal -offset indent -compact
  62 PF_LOCAL        Host-internal protocols, formerly called PF_UNIX,
  63 PF_UNIX         Host-internal protocols, deprecated, use PF_LOCAL,
  64 PF_INET         Internet version 4 protocols,
  65 PF_IMPLINK      ARPAnet IMP addresses,
  66 PF_PUP          PUP protocols, like BSP,
  67 PF_CHAOS        MIT CHAOS protocols,
  68 PF_NS           Xerox Network Systems protocols,
  69 PF_ISO          ISO protocols,
  70 PF_OSI          Open Systems Interconnection protocols,
  71 PF_ECMA         European Computer Manufacturers,
  72 PF_DATAKIT      Datakit protocols,
  73 PF_CCITT        ITU-T protocols, like X.25,
  74 PF_SNA          IBM SNA,
  75 PF_DECnet       DECnet,
  76 PF_DLI          DEC Direct Data Link Interface protocol,
  77 PF_LAT          LAT protocol,
  78 PF_HYLINK       NSC Hyperchannel,
  79 PF_ROUTE        Internal Routing protocol,
  80 PF_LINK         Link layer interface,
  81 PF_XTP          eXpress Transfer Protocol,
  82 PF_COIP         Connection-Oriented IP, aka ST II,
  83 PF_CNT          Computer Network Technology,
  84 PF_SIP          Simple Internet Protocol,
  85 PF_IPX          Novell Internet Packet eXchange protocol,
  86 PF_RTIP         Help Identify RTIP packets,
  87 PF_PIP          Help Identify PIP packets,
  88 PF_ISDN         Integrated Services Digital Network,
  89 PF_KEY          Internal key-management function,
  90 PF_INET6        Internet version 6 protocols,
  91 PF_NATM         Native ATM access,
  92 PF_ATM          ATM,
  93 PF_NETGRAPH     Netgraph sockets
  94 .Ed
  95 .Pp
  96 The socket has the indicated
  97 .Fa type ,
  98 which specifies the semantics of communication.  Currently
  99 defined types are:
 100 .Pp
 101 .Bd -literal -offset indent -compact
 102 SOCK_STREAM     Stream socket,
 103 SOCK_DGRAM      Datagram socket,
 104 SOCK_RAW        Raw-protocol interface,
 105 SOCK_RDM        Reliably-delivered packet,
 106 SOCK_SEQPACKET  Sequenced packet stream
 107 .Ed
 108 .Pp
 109 A
 110 .Dv SOCK_STREAM
 111 type provides sequenced, reliable,
 112 two-way connection based byte streams.
 113 An out-of-band data transmission mechanism may be supported.
 114 A
 115 .Dv SOCK_DGRAM
 116 socket supports
 117 datagrams (connectionless, unreliable messages of
 118 a fixed (typically small) maximum length).
 119 A
 120 .Dv SOCK_SEQPACKET
 121 socket may provide a sequenced, reliable,
 122 two-way connection-based data transmission path for datagrams
 123 of fixed maximum length; a consumer may be required to read
 124 an entire packet with each read system call.
 125 This facility is protocol specific, and presently implemented
 126 only for
 127 .Dv PF_NS
 128 and
 129 .Dv PF_UNIX .
 130 .Dv SOCK_RAW
 131 sockets provide access to internal network protocols and interfaces.
 132 The types
 133 .Dv SOCK_RAW ,
 134 which is available only to the super-user, and
 135 .Dv SOCK_RDM ,
 136 which is planned,
 137 but not yet implemented, are not described here.
 138 .Pp
 139 The
 140 .Fa protocol
 141 specifies a particular protocol to be used with the socket.
 142 Normally only a single protocol exists to support a particular
 143 socket type within a given protocol family.  However, it is possible
 144 that many protocols may exist, in which case a particular protocol
 145 must be specified in this manner.  The protocol number to use is
 146 particular to the
 147 .Dq "communication domain"
 148 in which communication
 149 is to take place; see
 150 .Xr protocols 5 .
 151 .Pp
 152 Sockets of type
 153 .Dv SOCK_STREAM
 154 are full-duplex byte streams, similar
 155 to pipes.  A stream socket must be in a
 156 .Em connected
 157 state before any data may be sent or received
 158 on it.  A connection to another socket is created with a
 159 .Xr connect 2
 160 call.
 161 Once connected, data may be transferred using
 162 .Xr read 2
 163 and
 164 .Xr write 2
 165 calls or some variant of the
 166 .Xr send 2
 167 and
 168 .Xr recv 2
 169 calls.
 170 (Some protocol families, such as the Internet family,
 171 support the notion of an
 172 .Dq implied connect ,
 173 which permits data to be sent piggybacked onto a connect operation by
 174 using the
 175 .Xr sendto 2
 176 call.)
 177 When a session has been completed a
 178 .Xr close 2
 179 may be performed.
 180 Out-of-band data may also be transmitted as described in
 181 .Xr send 2
 182 and received as described in
 183 .Xr recv 2 .
 184 .Pp
 185 The communications protocols used to implement a
 186 .Dv SOCK_STREAM
 187 insure that data
 188 is not lost or duplicated.  If a piece of data for which the
 189 peer protocol has buffer space cannot be successfully transmitted
 190 within a reasonable length of time, then
 191 the connection is considered broken and calls
 192 will indicate an error with
 193 -1 returns and with
 194 .Er ETIMEDOUT
 195 as the specific code
 196 in the global variable
 197 .Va errno .
 198 The protocols optionally keep sockets
 199 .Dq warm
 200 by forcing transmissions
 201 roughly every minute in the absence of other activity.
 202 An error is then indicated if no response can be
 203 elicited on an otherwise
 204 idle connection for an extended period (e.g. 5 minutes).
 205 A
 206 .Dv SIGPIPE
 207 signal is raised if a process sends
 208 on a broken stream; this causes naive processes,
 209 which do not handle the signal, to exit.
 210 .Pp
 211 .Dv SOCK_SEQPACKET
 212 sockets employ the same system calls
 213 as
 214 .Dv SOCK_STREAM
 215 sockets.  The only difference
 216 is that
 217 .Xr read 2
 218 calls will return only the amount of data requested,
 219 and any remaining in the arriving packet will be discarded.
 220 .Pp
 221 .Dv SOCK_DGRAM
 222 and
 223 .Dv SOCK_RAW
 224 sockets allow sending of datagrams to correspondents
 225 named in
 226 .Xr send 2
 227 calls.  Datagrams are generally received with
 228 .Xr recvfrom 2 ,
 229 which returns the next datagram with its return address.
 230 .Pp
 231 An
 232 .Xr fcntl 2
 233 call can be used to specify a process group to receive
 234 a
 235 .Dv SIGURG
 236 signal when the out-of-band data arrives.
 237 It may also enable non-blocking I/O
 238 and asynchronous notification of I/O events
 239 via
 240 .Dv SIGIO .
 241 .Pp
 242 The operation of sockets is controlled by socket level
 243 .Em options .
 244 These options are defined in the file
 245 .In sys/socket.h .
 246 .Xr Setsockopt 2
 247 and
 248 .Xr getsockopt 2
 249 are used to set and get options, respectively.
 250 .Sh RETURN VALUES
 251 Upon successful completion
 252 .Fn socket
 253 returns a descriptor referencing the socket.
 254 Otherwise, -1 is returned and the global variable
 255 .Va errno
 256 is set to indicate the error.
 257 .Sh ERRORS
 258 The
 259 .Fn socket
 260 call fails if:
 261 .Bl -tag -width Er
 262 .It Bq Er EPROTONOSUPPORT
 263 The protocol type or the specified protocol is not supported
 264 within this domain.
 265 .It Bq Er EMFILE
 266 The per-process descriptor table is full.
 267 .It Bq Er ENFILE
 268 The system file table is full.
 269 .It Bq Er EACCES
 270 Permission to create a socket of the specified type and/or protocol
 271 is denied.
 272 .It Bq Er ENOBUFS
 273 Insufficient buffer space is available.
 274 The socket cannot be created until sufficient resources are freed.
 275 .El
 276 .Sh SEE ALSO
 277 .Xr accept 2 ,
 278 .Xr bind 2 ,
 279 .Xr connect 2 ,
 280 .Xr getpeername 2 ,
 281 .Xr getsockname 2 ,
 282 .Xr getsockopt 2 ,
 283 .Xr ioctl 2 ,
 284 .Xr listen 2 ,
 285 .Xr read 2 ,
 286 .Xr recv 2 ,
 287 .Xr select 2 ,
 288 .Xr send 2 ,
 289 .Xr shutdown 2 ,
 290 .Xr socketpair 2 ,
 291 .Xr write 2 ,
 292 .Xr getprotoent 3 ,
 293 .Xr netgraph 4 ,
 294 .Xr protocols 5
 295 .Rs
 296 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 297 .%B PS1
 298 .%N 7
 299 .Re
 300 .Rs
 301 .%T "BSD Interprocess Communication Tutorial"
 302 .%B PS1
 303 .%N 8
 304 .Re
 305 .Sh HISTORY
 306 The
 307 .Fn socket
 308 function call appeared in
 309 .Bx 4.2 .