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 .\" $DragonFly: src/lib/libc/sys/socket.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd November 24, 1997
  37 .Dt SOCKET 2
  38 .Os
  39 .Sh NAME
  40 .Nm socket
  41 .Nd create an endpoint for communication
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In sys/socket.h
  47 .Ft int
  48 .Fn socket "int domain" "int type" "int protocol"
  49 .Sh DESCRIPTION
  50 .Fn Socket
  51 creates an endpoint for communication and returns a descriptor.
  52 .Pp
  53 The
  54 .Fa domain
  55 parameter specifies a communications domain within which
  56 communication will take place; this selects the protocol family
  57 which should be used.
  58 These families are defined in the include file
  59 .Ao Pa sys/socket.h Ac .
  60 The currently understood formats are:
  61 .Pp
  62 .Bd -literal -offset indent -compact
  63 PF_LOCAL        Host-internal protocols, formerly called PF_UNIX,
  64 PF_UNIX         Host-internal protocols, deprecated, use PF_LOCAL,
  65 PF_INET         Internet version 4 protocols,
  66 PF_IMPLINK      ARPAnet IMP addresses,
  67 PF_PUP          PUP protocols, like BSP,
  68 PF_CHAOS        MIT CHAOS protocols,
  69 PF_NS           Xerox Network Systems protocols,
  70 PF_ISO          ISO protocols,
  71 PF_OSI          Open Systems Interconnection protocols,
  72 PF_ECMA         European Computer Manufacturers,
  73 PF_DATAKIT      Datakit protocols,
  74 PF_CCITT        ITU-T protocols, like X.25,
  75 PF_SNA          IBM SNA,
  76 PF_DECnet       DECnet,
  77 PF_DLI          DEC Direct Data Link Interface protocol,
  78 PF_LAT          LAT protocol,
  79 PF_HYLINK       NSC Hyperchannel,
  80 PF_APPLETALK    AppleTalk protocols,
  81 PF_ROUTE        Internal Routing protocol,
  82 PF_LINK         Link layer interface,
  83 PF_XTP          eXpress Transfer Protocol,
  84 PF_COIP         Connection-Oriented IP, aka ST II,
  85 PF_CNT          Computer Network Technology,
  86 PF_SIP          Simple Internet Protocol,
  87 PF_IPX          Novell Internet Packet eXchange protocol,
  88 PF_RTIP         Help Identify RTIP packets,
  89 PF_PIP          Help Identify PIP packets,
  90 PF_ISDN         Integrated Services Digital Network,
  91 PF_KEY          Internal key-management function,
  92 PF_INET6        Internet version 6 protocols,
  93 PF_NATM         Native ATM access,
  94 PF_ATM          ATM,
  95 PF_NETGRAPH     Netgraph sockets
  96 .Ed
  97 .Pp
  98 The socket has the indicated
  99 .Fa type ,
 100 which specifies the semantics of communication.  Currently
 101 defined types are:
 102 .Pp
 103 .Bd -literal -offset indent -compact
 104 SOCK_STREAM     Stream socket,
 105 SOCK_DGRAM      Datagram socket,
 106 SOCK_RAW        Raw-protocol interface,
 107 SOCK_RDM        Reliably-delivered packet,
 108 SOCK_SEQPACKET  Sequenced packet stream
 109 .Ed
 110 .Pp
 111 A
 112 .Dv SOCK_STREAM
 113 type provides sequenced, reliable,
 114 two-way connection based byte streams.
 115 An out-of-band data transmission mechanism may be supported.
 116 A
 117 .Dv SOCK_DGRAM
 118 socket supports
 119 datagrams (connectionless, unreliable messages of
 120 a fixed (typically small) maximum length).
 121 A
 122 .Dv SOCK_SEQPACKET
 123 socket may provide a sequenced, reliable,
 124 two-way connection-based data transmission path for datagrams
 125 of fixed maximum length; a consumer may be required to read
 126 an entire packet with each read system call.
 127 This facility is protocol specific, and presently implemented
 128 only for
 129 .Dv PF_NS .
 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 a 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 .Ao Pa sys/socket.h Ac .
 246 .Xr Setsockopt 2
 247 and
 248 .Xr getsockopt 2
 249 are used to set and get options, respectively.
 250 .Sh RETURN VALUES
 251 A -1 is returned if an error occurs, otherwise the return
 252 value is a descriptor referencing the socket.
 253 .Sh ERRORS
 254 The
 255 .Fn socket
 256 call fails if:
 257 .Bl -tag -width Er
 258 .It Bq Er EPROTONOSUPPORT
 259 The protocol type or the specified protocol is not supported
 260 within this domain.
 261 .It Bq Er EMFILE
 262 The per-process descriptor table is full.
 263 .It Bq Er ENFILE
 264 The system file table is full.
 265 .It Bq Er EACCES
 266 Permission to create a socket of the specified type and/or protocol
 267 is denied.
 268 .It Bq Er ENOBUFS
 269 Insufficient buffer space is available.
 270 The socket cannot be created until sufficient resources are freed.
 271 .El
 272 .Sh SEE ALSO
 273 .Xr accept 2 ,
 274 .Xr bind 2 ,
 275 .Xr connect 2 ,
 276 .Xr getpeername 2 ,
 277 .Xr getsockname 2 ,
 278 .Xr getsockopt 2 ,
 279 .Xr ioctl 2 ,
 280 .Xr listen 2 ,
 281 .Xr read 2 ,
 282 .Xr recv 2 ,
 283 .Xr select 2 ,
 284 .Xr send 2 ,
 285 .Xr shutdown 2 ,
 286 .Xr socketpair 2 ,
 287 .Xr write 2 ,
 288 .Xr getprotoent 3 ,
 289 .Xr netgraph 4 ,
 290 .Xr protocols 5
 291 .Rs
 292 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 293 .%B PS1
 294 .%N 7
 295 .Re
 296 .Rs
 297 .%T "BSD Interprocess Communication Tutorial"
 298 .%B PS1
 299 .%N 8
 300 .Re
 301 .Sh HISTORY
 302 The
 303 .Fn socket
 304 function call appeared in
 305 .Bx 4.2 .