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