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 .Ao Pa sys/socket.h Ac .
  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_APPLETALK    AppleTalk protocols,
  80 PF_ROUTE        Internal Routing protocol,
  81 PF_LINK         Link layer interface,
  82 PF_XTP          eXpress Transfer Protocol,
  83 PF_COIP         Connection-Oriented IP, aka ST II,
  84 PF_CNT          Computer Network Technology,
  85 PF_SIP          Simple Internet Protocol,
  86 PF_IPX          Novell Internet Packet eXchange protocol,
  87 PF_RTIP         Help Identify RTIP packets,
  88 PF_PIP          Help Identify PIP packets,
  89 PF_ISDN         Integrated Services Digital Network,
  90 PF_KEY          Internal key-management function,
  91 PF_INET6        Internet version 6 protocols,
  92 PF_NATM         Native ATM access,
  93 PF_ATM          ATM,
  94 PF_NETGRAPH     Netgraph sockets
  95 .Ed
  96 .Pp
  97 The socket has the indicated
  98 .Fa type ,
  99 which specifies the semantics of communication.  Currently
 100 defined types are:
 101 .Pp
 102 .Bd -literal -offset indent -compact
 103 SOCK_STREAM     Stream socket,
 104 SOCK_DGRAM      Datagram socket,
 105 SOCK_RAW        Raw-protocol interface,
 106 SOCK_RDM        Reliably-delivered packet,
 107 SOCK_SEQPACKET  Sequenced packet stream
 108 .Ed
 109 .Pp
 110 A
 111 .Dv SOCK_STREAM
 112 type provides sequenced, reliable,
 113 two-way connection based byte streams.
 114 An out-of-band data transmission mechanism may be supported.
 115 A
 116 .Dv SOCK_DGRAM
 117 socket supports
 118 datagrams (connectionless, unreliable messages of
 119 a fixed (typically small) maximum length).
 120 A
 121 .Dv SOCK_SEQPACKET
 122 socket may provide a sequenced, reliable,
 123 two-way connection-based data transmission path for datagrams
 124 of fixed maximum length; a consumer may be required to read
 125 an entire packet with each read system call.
 126 This facility is protocol specific, and presently implemented
 127 only for
 128 .Dv PF_NS .
 129 .Dv SOCK_RAW
 130 sockets provide access to internal network protocols and interfaces.
 131 The types
 132 .Dv SOCK_RAW ,
 133 which is available only to the super-user, and
 134 .Dv SOCK_RDM ,
 135 which is planned,
 136 but not yet implemented, are not described here.
 137 .Pp
 138 The
 139 .Fa protocol
 140 specifies a particular protocol to be used with the socket.
 141 Normally only a single protocol exists to support a particular
 142 socket type within a given protocol family.  However, it is possible
 143 that many protocols may exist, in which case a particular protocol
 144 must be specified in this manner.  The protocol number to use is
 145 particular to the
 146 .Dq "communication domain"
 147 in which communication
 148 is to take place; see
 149 .Xr protocols 5 .
 150 .Pp
 151 Sockets of type
 152 .Dv SOCK_STREAM
 153 are full-duplex byte streams, similar
 154 to pipes.  A stream socket must be in a
 155 .Em connected
 156 state before any data may be sent or received
 157 on it.  A connection to another socket is created with a
 158 .Xr connect 2
 159 call.
 160 Once connected, data may be transferred using
 161 .Xr read 2
 162 and
 163 .Xr write 2
 164 calls or some variant of the
 165 .Xr send 2
 166 and
 167 .Xr recv 2
 168 calls.
 169 (Some protocol families, such as the Internet family,
 170 support the notion of an
 171 .Dq implied connect ,
 172 which permits data to be sent piggybacked onto a connect operation by
 173 using the
 174 .Xr sendto 2
 175 call.)
 176 When a session has been completed a
 177 .Xr close 2
 178 may be performed.
 179 Out-of-band data may also be transmitted as described in
 180 .Xr send 2
 181 and received as described in
 182 .Xr recv 2 .
 183 .Pp
 184 The communications protocols used to implement a
 185 .Dv SOCK_STREAM
 186 insure that data
 187 is not lost or duplicated.  If a piece of data for which the
 188 peer protocol has buffer space cannot be successfully transmitted
 189 within a reasonable length of time, then
 190 the connection is considered broken and calls
 191 will indicate an error with
 192 -1 returns and with
 193 .Er ETIMEDOUT
 194 as the specific code
 195 in the global variable
 196 .Va errno .
 197 The protocols optionally keep sockets
 198 .Dq warm
 199 by forcing transmissions
 200 roughly every minute in the absence of other activity.
 201 An error is then indicated if no response can be
 202 elicited on an otherwise
 203 idle connection for a extended period (e.g. 5 minutes).
 204 A
 205 .Dv SIGPIPE
 206 signal is raised if a process sends
 207 on a broken stream; this causes naive processes,
 208 which do not handle the signal, to exit.
 209 .Pp
 210 .Dv SOCK_SEQPACKET
 211 sockets employ the same system calls
 212 as
 213 .Dv SOCK_STREAM
 214 sockets.  The only difference
 215 is that
 216 .Xr read 2
 217 calls will return only the amount of data requested,
 218 and any remaining in the arriving packet will be discarded.
 219 .Pp
 220 .Dv SOCK_DGRAM
 221 and
 222 .Dv SOCK_RAW
 223 sockets allow sending of datagrams to correspondents
 224 named in
 225 .Xr send 2
 226 calls.  Datagrams are generally received with
 227 .Xr recvfrom 2 ,
 228 which returns the next datagram with its return address.
 229 .Pp
 230 An
 231 .Xr fcntl 2
 232 call can be used to specify a process group to receive
 233 a
 234 .Dv SIGURG
 235 signal when the out-of-band data arrives.
 236 It may also enable non-blocking I/O
 237 and asynchronous notification of I/O events
 238 via
 239 .Dv SIGIO .
 240 .Pp
 241 The operation of sockets is controlled by socket level
 242 .Em options .
 243 These options are defined in the file
 244 .Ao Pa sys/socket.h Ac .
 245 .Xr Setsockopt 2
 246 and
 247 .Xr getsockopt 2
 248 are used to set and get options, respectively.
 249 .Sh RETURN VALUES
 250 A -1 is returned if an error occurs, otherwise the return
 251 value is a descriptor referencing the socket.
 252 .Sh ERRORS
 253 The
 254 .Fn socket
 255 call fails if:
 256 .Bl -tag -width Er
 257 .It Bq Er EPROTONOSUPPORT
 258 The protocol type or the specified protocol is not supported
 259 within this domain.
 260 .It Bq Er EMFILE
 261 The per-process descriptor table is full.
 262 .It Bq Er ENFILE
 263 The system file table is full.
 264 .It Bq Er EACCES
 265 Permission to create a socket of the specified type and/or protocol
 266 is denied.
 267 .It Bq Er ENOBUFS
 268 Insufficient buffer space is available.
 269 The socket cannot be created until sufficient resources are freed.
 270 .El
 271 .Sh SEE ALSO
 272 .Xr accept 2 ,
 273 .Xr bind 2 ,
 274 .Xr connect 2 ,
 275 .Xr getpeername 2 ,
 276 .Xr getsockname 2 ,
 277 .Xr getsockopt 2 ,
 278 .Xr ioctl 2 ,
 279 .Xr listen 2 ,
 280 .Xr read 2 ,
 281 .Xr recv 2 ,
 282 .Xr select 2 ,
 283 .Xr send 2 ,
 284 .Xr shutdown 2 ,
 285 .Xr socketpair 2 ,
 286 .Xr write 2 ,
 287 .Xr getprotoent 3 ,
 288 .Xr netgraph 4 ,
 289 .Xr protocols 5
 290 .Rs
 291 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 292 .%B PS1
 293 .%N 7
 294 .Re
 295 .Rs
 296 .%T "BSD Interprocess Communication Tutorial"
 297 .%B PS1
 298 .%N 8
 299 .Re
 300 .Sh HISTORY
 301 The
 302 .Fn socket
 303 function call appeared in
 304 .Bx 4.2 .