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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)socket.2      8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 15, 2023
  32 .Dt SOCKET 2
  33 .Os
  34 .Sh NAME
  35 .Nm socket
  36 .Nd create an endpoint for communication
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .Ft int
  42 .Fn socket "int domain" "int type" "int protocol"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn socket
  46 system call
  47 creates an endpoint for communication and returns a descriptor.
  48 .Pp
  49 The
  50 .Fa domain
  51 argument specifies a communications domain within which
  52 communication will take place; this selects the protocol family
  53 which should be used.
  54 These families are defined in the include file
  55 .In sys/socket.h .
  56 The currently understood formats are:
  57 .Pp
  58 .Bd -literal -offset indent -compact
  59 PF_LOCAL        Host-internal protocols (alias for PF_UNIX),
  60 PF_UNIX         Host-internal protocols,
  61 PF_INET         Internet version 4 protocols,
  62 PF_INET6        Internet version 6 protocols,
  63 PF_DIVERT       Firewall packet diversion/re-injection,
  64 PF_ROUTE        Internal routing protocol,
  65 PF_KEY          Internal key-management function,
  66 PF_NETGRAPH     Netgraph sockets,
  67 PF_NETLINK      Netlink protocols,
  68 PF_BLUETOOTH    Bluetooth protocols,
  69 PF_INET_SDP     OFED socket direct protocol (IPv4),
  70 AF_HYPERV       HyperV sockets
  71 .Ed
  72 .Pp
  73 Each protocol family is connected to an address family, which has the
  74 same name except that the prefix is
  75 .Dq Dv AF_
  76 in place of
  77 .Dq Dv PF_ .
  78 Other protocol families may be also defined, beginning with
  79 .Dq Dv PF_ ,
  80 with corresponding address families.
  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_SEQPACKET  Sequenced packet stream
  93 .Ed
  94 .Pp
  95 A
  96 .Dv SOCK_STREAM
  97 type provides sequenced, reliable,
  98 two-way connection based byte streams.
  99 An out-of-band data transmission mechanism may be supported.
 100 A
 101 .Dv SOCK_DGRAM
 102 socket supports
 103 datagrams (connectionless, unreliable messages of
 104 a fixed (typically small) maximum length).
 105 A
 106 .Dv SOCK_SEQPACKET
 107 socket may provide a sequenced, reliable,
 108 two-way connection-based data transmission path for datagrams
 109 of fixed maximum length; a consumer may be required to read
 110 an entire packet with each read system call.
 111 This facility may have protocol-specific properties.
 112 .Dv SOCK_RAW
 113 sockets provide access to internal network protocols and interfaces.
 114 The
 115 .Dv SOCK_RAW
 116 type is available only to the super-user and is described in
 117 .Xr ip 4
 118 and
 119 .Xr ip6 4 .
 120 .Pp
 121 Additionally, the following flags are allowed in the
 122 .Fa type
 123 argument:
 124 .Pp
 125 .Bd -literal -offset indent -compact
 126 SOCK_CLOEXEC    Set close-on-exec on the new descriptor,
 127 SOCK_NONBLOCK   Set non-blocking mode on the new socket
 128 .Ed
 129 .Pp
 130 The
 131 .Fa protocol
 132 argument
 133 specifies a particular protocol to be used with the socket.
 134 Normally only a single protocol exists to support a particular
 135 socket type within a given protocol family.
 136 However, it is possible
 137 that many protocols may exist, in which case a particular protocol
 138 must be specified in this manner.
 139 The protocol number to use is
 140 particular to the
 141 .Dq "communication domain"
 142 in which communication
 143 is to take place; see
 144 .Xr protocols 5 .
 145 .Pp
 146 The
 147 .Fa protocol
 148 argument may be set to zero (0) to request the default
 149 implementation of a socket type for the protocol, if any.
 150 .Pp
 151 Sockets of type
 152 .Dv SOCK_STREAM
 153 are full-duplex byte streams, similar
 154 to pipes.
 155 A stream socket must be in a
 156 .Em connected
 157 state before any data may be sent or received
 158 on it.
 159 A connection to another socket is created with a
 160 .Xr connect 2
 161 system call.
 162 Once connected, data may be transferred using
 163 .Xr read 2
 164 and
 165 .Xr write 2
 166 calls or some variant of the
 167 .Xr send 2
 168 and
 169 .Xr recv 2
 170 functions.
 171 (Some protocol families, such as the Internet family,
 172 support the notion of an
 173 .Dq implied connect ,
 174 which permits data to be sent piggybacked onto a connect operation by
 175 using the
 176 .Xr sendto 2
 177 system call.)
 178 When a session has been completed a
 179 .Xr close 2
 180 may be performed.
 181 Out-of-band data may also be transmitted as described in
 182 .Xr send 2
 183 and received as described in
 184 .Xr recv 2 .
 185 .Pp
 186 The communications protocols used to implement a
 187 .Dv SOCK_STREAM
 188 ensure that data
 189 is not lost or duplicated.
 190 If a piece of data for which the
 191 peer protocol has buffer space cannot be successfully transmitted
 192 within a reasonable length of time, then
 193 the connection is considered broken and calls
 194 will indicate an error with
 195 -1 returns and with
 196 .Er ETIMEDOUT
 197 as the specific code
 198 in the global variable
 199 .Va errno .
 200 The protocols optionally keep sockets
 201 .Dq warm
 202 by forcing transmissions
 203 roughly every minute in the absence of other activity.
 204 An error is then indicated if no response can be
 205 elicited on an otherwise
 206 idle connection for an extended period (e.g.\& 5 minutes).
 207 By default, a
 208 .Dv SIGPIPE
 209 signal is raised if a process sends
 210 on a broken stream, but this behavior may be inhibited via
 211 .Xr setsockopt 2 .
 212 .Pp
 213 .Dv SOCK_SEQPACKET
 214 sockets employ the same system calls
 215 as
 216 .Dv SOCK_STREAM
 217 sockets.
 218 The only difference
 219 is that
 220 .Xr read 2
 221 calls will return only the amount of data requested,
 222 and any remaining in the arriving packet will be discarded.
 223 .Pp
 224 .Dv SOCK_DGRAM
 225 and
 226 .Dv SOCK_RAW
 227 sockets allow sending of datagrams to correspondents
 228 named in
 229 .Xr send 2
 230 calls.
 231 Datagrams are generally received with
 232 .Xr recvfrom 2 ,
 233 which returns the next datagram with its return address.
 234 .Pp
 235 An
 236 .Xr fcntl 2
 237 system call can be used to specify a process group to receive
 238 a
 239 .Dv SIGURG
 240 signal when the out-of-band data arrives.
 241 It may also enable non-blocking I/O
 242 and asynchronous notification of I/O events
 243 via
 244 .Dv SIGIO .
 245 .Pp
 246 The operation of sockets is controlled by socket level
 247 .Em options .
 248 These options are defined in the file
 249 .In sys/socket.h .
 250 The
 251 .Xr setsockopt 2
 252 and
 253 .Xr getsockopt 2
 254 system calls are used to set and get options, respectively.
 255 .Sh RETURN VALUES
 256 A -1 is returned if an error occurs, otherwise the return
 257 value is a descriptor referencing the socket.
 258 .Sh ERRORS
 259 The
 260 .Fn socket
 261 system call fails if:
 262 .Bl -tag -width Er
 263 .It Bq Er EACCES
 264 Permission to create a socket of the specified type and/or protocol
 265 is denied.
 266 .It Bq Er EAFNOSUPPORT
 267 The address family (domain) is not supported or the
 268 specified domain is not supported by this protocol family.
 269 .It Bq Er EMFILE
 270 The per-process descriptor table is full.
 271 .It Bq Er ENFILE
 272 The system file table is full.
 273 .It Bq Er ENOBUFS
 274 Insufficient buffer space is available.
 275 The socket cannot be created until sufficient resources are freed.
 276 .It Bq Er EPERM
 277 User has insufficient privileges to carry out the requested operation.
 278 .It Bq Er EPROTONOSUPPORT
 279 The protocol type or the specified protocol is not supported
 280 within this domain.
 281 .It Bq Er EPROTOTYPE
 282 The socket type is not supported by the protocol.
 283 .El
 284 .Sh SEE ALSO
 285 .Xr accept 2 ,
 286 .Xr bind 2 ,
 287 .Xr connect 2 ,
 288 .Xr divert 4 ,
 289 .Xr getpeername 2 ,
 290 .Xr getsockname 2 ,
 291 .Xr getsockopt 2 ,
 292 .Xr ioctl 2 ,
 293 .Xr ip 4 ,
 294 .Xr ip6 4 ,
 295 .Xr listen 2 ,
 296 .Xr read 2 ,
 297 .Xr recv 2 ,
 298 .Xr select 2 ,
 299 .Xr send 2 ,
 300 .Xr shutdown 2 ,
 301 .Xr socketpair 2 ,
 302 .Xr write 2 ,
 303 .Xr CMSG_DATA 3 ,
 304 .Xr getprotoent 3 ,
 305 .Xr netgraph 4 ,
 306 .Xr protocols 5
 307 .Rs
 308 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 309 .%B PS1
 310 .%N 7
 311 .Re
 312 .Rs
 313 .%T "BSD Interprocess Communication Tutorial"
 314 .%B PS1
 315 .%N 8
 316 .Re
 317 .Sh STANDARDS
 318 The
 319 .Fn socket
 320 function conforms to
 321 .St -p1003.1-2008 .
 322 The
 323 .Tn POSIX
 324 standard specifies only the
 325 .Dv AF_INET ,
 326 .Dv AF_INET6 ,
 327 and
 328 .Dv AF_UNIX
 329 constants for address families, and requires the use of
 330 .Dv AF_*
 331 constants for the
 332 .Fa domain
 333 argument of
 334 .Fn socket .
 335 The
 336 .Dv SOCK_CLOEXEC
 337 flag is expected to conform to the next revision of the
 338 .Tn POSIX
 339 standard.
 340 The
 341 .Dv SOCK_RDM
 342 .Fa type ,
 343 the
 344 .Dv PF_*
 345 constants, and other address families are
 346 .Fx
 347 extensions.
 348 .Sh HISTORY
 349 The
 350 .Fn socket
 351 system call appeared in
 352 .Bx 4.2 .