man2/socket.2

   1 '\" t
   2 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\" %%%LICENSE_END
  34 .\"
  35 .\"     $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $
  36 .\"
  37 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  38 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  39 .\" Modified 1998, 1999 by Andi Kleen <ak@muc.de>
  40 .\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  41 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  42 .\"
  43 .TH SOCKET 2 2015-12-28 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 socket \- create an endpoint for communication
  46 .SH SYNOPSIS
  47 .BR "#include <sys/types.h>" "          /* See NOTES */"
  48 .br
  49 .B #include <sys/socket.h>
  50 .sp
  51 .BI "int socket(int " domain ", int " type ", int " protocol );
  52 .SH DESCRIPTION
  53 .BR socket ()
  54 creates an endpoint for communication and returns a file descriptor
  55 that refers to that endpoint.
  56 .PP
  57 The
  58 .I domain
  59 argument specifies a communication domain; this selects the protocol
  60 family which will be used for communication.
  61 These families are defined in
  62 .IR <sys/socket.h> .
  63 The currently understood formats include:
  64 .TS
  65 tab(:);
  66 l l l.
  67 Name:Purpose:Man page
  68 T{
  69 .BR AF_UNIX ", " AF_LOCAL
  70 T}:T{
  71 Local communication
  72 T}:T{
  73 .BR unix (7)
  74 T}
  75 T{
  76 .B AF_INET
  77 T}:IPv4 Internet protocols:T{
  78 .BR ip (7)
  79 T}
  80 T{
  81 .B AF_INET6
  82 T}:IPv6 Internet protocols:T{
  83 .BR ipv6 (7)
  84 T}
  85 T{
  86 .B AF_IPX
  87 T}:IPX \- Novell protocols:
  88 T{
  89 .B AF_NETLINK
  90 T}:T{
  91 Kernel user interface device
  92 T}:T{
  93 .BR netlink (7)
  94 T}
  95 T{
  96 .B AF_X25
  97 T}:ITU-T X.25 / ISO-8208 protocol:T{
  98 .BR x25 (7)
  99 T}
 100 T{
 101 .B AF_AX25
 102 T}:T{
 103 Amateur radio AX.25 protocol
 104 T}:
 105 T{
 106 .B AF_ATMPVC
 107 T}:Access to raw ATM PVCs:
 108 T{
 109 .B AF_APPLETALK
 110 T}:AppleTalk:T{
 111 .BR ddp (7)
 112 T}
 113 T{
 114 .B AF_PACKET
 115 T}:T{
 116 Low level packet interface
 117 T}:T{
 118 .BR packet (7)
 119 T}
 120 T{
 121 .B AF_ALG
 122 T}:T{
 123 Interface to kernel crypto API
 124 T}
 125 .TE
 126 .PP
 127 The socket has the indicated
 128 .IR type ,
 129 which specifies the communication semantics.
 130 Currently defined types
 131 are:
 132 .TP 16
 133 .B SOCK_STREAM
 134 Provides sequenced, reliable, two-way, connection-based byte streams.
 135 An out-of-band data transmission mechanism may be supported.
 136 .TP
 137 .B SOCK_DGRAM
 138 Supports datagrams (connectionless, unreliable messages of a fixed
 139 maximum length).
 140 .TP
 141 .B SOCK_SEQPACKET
 142 Provides a sequenced, reliable, two-way connection-based data
 143 transmission path for datagrams of fixed maximum length; a consumer is
 144 required to read an entire packet with each input system call.
 145 .TP
 146 .B SOCK_RAW
 147 Provides raw network protocol access.
 148 .TP
 149 .B SOCK_RDM
 150 Provides a reliable datagram layer that does not guarantee ordering.
 151 .TP
 152 .B SOCK_PACKET
 153 Obsolete and should not be used in new programs;
 154 see
 155 .BR packet (7).
 156 .PP
 157 Some socket types may not be implemented by all protocol families.
 158 .PP
 159 Since Linux 2.6.27, the
 160 .I type
 161 argument serves a second purpose:
 162 in addition to specifying a socket type,
 163 it may include the bitwise OR of any of the following values,
 164 to modify the behavior of
 165 .BR socket ():
 166 .TP 16
 167 .B SOCK_NONBLOCK
 168 Set the
 169 .BR O_NONBLOCK
 170 file status flag on the new open file description.
 171 Using this flag saves extra calls to
 172 .BR fcntl (2)
 173 to achieve the same result.
 174 .TP
 175 .B SOCK_CLOEXEC
 176 Set the close-on-exec
 177 .RB ( FD_CLOEXEC )
 178 flag on the new file descriptor.
 179 See the description of the
 180 .B O_CLOEXEC
 181 flag in
 182 .BR open (2)
 183 for reasons why this may be useful.
 184 .PP
 185 The
 186 .I protocol
 187 specifies a particular protocol to be used with the socket.
 188 Normally only a single protocol exists to support a particular
 189 socket type within a given protocol family, in which case
 190 .I protocol
 191 can be specified as 0.
 192 However, it is possible that many protocols may exist, in
 193 which case a particular protocol must be specified in this manner.
 194 The protocol number to use is specific to the \*(lqcommunication domain\*(rq
 195 in which communication is to take place; see
 196 .BR protocols (5).
 197 See
 198 .BR getprotoent (3)
 199 on how to map protocol name strings to protocol numbers.
 200 .PP
 201 Sockets of type
 202 .B SOCK_STREAM
 203 are full-duplex byte streams.
 204 They do not preserve
 205 record boundaries.
 206 A stream socket must be in
 207 a
 208 .I connected
 209 state before any data may be sent or received on it.
 210 A connection to
 211 another socket is created with a
 212 .BR connect (2)
 213 call.
 214 Once connected, data may be transferred using
 215 .BR read (2)
 216 and
 217 .BR write (2)
 218 calls or some variant of the
 219 .BR send (2)
 220 and
 221 .BR recv (2)
 222 calls.
 223 When a session has been completed a
 224 .BR close (2)
 225 may be performed.
 226 Out-of-band data may also be transmitted as described in
 227 .BR send (2)
 228 and received as described in
 229 .BR recv (2).
 230 .PP
 231 The communications protocols which implement a
 232 .B SOCK_STREAM
 233 ensure that data is not lost or duplicated.
 234 If a piece of data for which
 235 the peer protocol has buffer space cannot be successfully transmitted
 236 within a reasonable length of time, then the connection is considered
 237 to be dead.
 238 When
 239 .B SO_KEEPALIVE
 240 is enabled on the socket the protocol checks in a protocol-specific
 241 manner if the other end is still alive.
 242 A
 243 .B SIGPIPE
 244 signal is raised if a process sends or receives
 245 on a broken stream; this causes naive processes,
 246 which do not handle the signal, to exit.
 247 .B SOCK_SEQPACKET
 248 sockets employ the same system calls as
 249 .B SOCK_STREAM
 250 sockets.
 251 The only difference is that
 252 .BR read (2)
 253 calls will return only the amount of data requested,
 254 and any data remaining in the arriving packet will be discarded.
 255 Also all message boundaries in incoming datagrams are preserved.
 256 .PP
 257 .B SOCK_DGRAM
 258 and
 259 .B SOCK_RAW
 260 sockets allow sending of datagrams to correspondents named in
 261 .BR sendto (2)
 262 calls.
 263 Datagrams are generally received with
 264 .BR recvfrom (2),
 265 which returns the next datagram along with the address of its sender.
 266 .PP
 267 .B SOCK_PACKET
 268 is an obsolete socket type to receive raw packets directly from the
 269 device driver.
 270 Use
 271 .BR packet (7)
 272 instead.
 273 .PP
 274 An
 275 .BR fcntl (2)
 276 .B F_SETOWN
 277 operation can be used to specify a process or process group to receive a
 278 .B SIGURG
 279 signal when the out-of-band data arrives or
 280 .B SIGPIPE
 281 signal when a
 282 .B SOCK_STREAM
 283 connection breaks unexpectedly.
 284 This operation may also be used to set the process or process group
 285 that receives the I/O and asynchronous notification of I/O events via
 286 .BR SIGIO .
 287 Using
 288 .B F_SETOWN
 289 is equivalent to an
 290 .BR ioctl (2)
 291 call with the
 292 .B FIOSETOWN
 293 or
 294 .B SIOCSPGRP
 295 argument.
 296 .PP
 297 When the network signals an error condition to the protocol module (e.g.,
 298 using a ICMP message for IP) the pending error flag is set for the socket.
 299 The next operation on this socket will return the error code of the pending
 300 error.
 301 For some protocols it is possible to enable a per-socket error queue
 302 to retrieve detailed information about the error; see
 303 .B IP_RECVERR
 304 in
 305 .BR ip (7).
 306 .PP
 307 The operation of sockets is controlled by socket level
 308 .IR options .
 309 These options are defined in
 310 .IR <sys/socket.h> .
 311 The functions
 312 .BR setsockopt (2)
 313 and
 314 .BR getsockopt (2)
 315 are used to set and get options, respectively.
 316 .SH RETURN VALUE
 317 On success, a file descriptor for the new socket is returned.
 318 On error, \-1 is returned, and
 319 .I errno
 320 is set appropriately.
 321 .SH ERRORS
 322 .TP
 323 .B EACCES
 324 Permission to create a socket of the specified type and/or protocol
 325 is denied.
 326 .TP
 327 .B EAFNOSUPPORT
 328 The implementation does not support the specified address family.
 329 .TP
 330 .B EINVAL
 331 Unknown protocol, or protocol family not available.
 332 .TP
 333 .B EINVAL
 334 .\" Since Linux 2.6.27
 335 Invalid flags in
 336 .IR type .
 337 .TP
 338 .B EMFILE
 339 The per-process limit on the number of open file descriptors has been reached.
 340 .TP
 341 .B ENFILE
 342 The system-wide limit on the total number of open files has been reached.
 343 .TP
 344 .BR ENOBUFS " or " ENOMEM
 345 Insufficient memory is available.
 346 The socket cannot be
 347 created until sufficient resources are freed.
 348 .TP
 349 .B EPROTONOSUPPORT
 350 The protocol type or the specified protocol is not
 351 supported within this domain.
 352 .PP
 353 Other errors may be generated by the underlying protocol modules.
 354 .SH CONFORMING TO
 355 POSIX.1-2001, POSIX.1-2008, 4.4BSD.
 356
 357 The
 358 .B SOCK_NONBLOCK
 359 and
 360 .B SOCK_CLOEXEC
 361 flags are Linux-specific.
 362
 363 .BR socket ()
 364 appeared in 4.2BSD.
 365 It is generally portable to/from
 366 non-BSD systems supporting clones of the BSD socket layer (including
 367 System\ V variants).
 368 .SH NOTES
 369 POSIX.1 does not require the inclusion of
 370 .IR <sys/types.h> ,
 371 and this header file is not required on Linux.
 372 However, some historical (BSD) implementations required this header
 373 file, and portable applications are probably wise to include it.
 374
 375 The manifest constants used under 4.x BSD for protocol families
 376 are
 377 .BR PF_UNIX ,
 378 .BR PF_INET ,
 379 and so on, while
 380 .BR AF_UNIX ,
 381 .BR AF_INET ,
 382 and so on are used for address
 383 families.
 384 However, already the BSD man page promises: "The protocol
 385 family generally is the same as the address family", and subsequent
 386 standards use AF_* everywhere.
 387
 388 The
 389 .B AF_ALG
 390 protocol type was added in Linux 2.6.38.
 391 More information on this interface is provided with the kernel HTML
 392 documentation at
 393 .IR https://www.kernel.org/doc/htmldocs/crypto-API/User.html .
 394 .SH EXAMPLE
 395 An example of the use of
 396 .BR socket ()
 397 is shown in
 398 .BR getaddrinfo (3).
 399 .SH SEE ALSO
 400 .BR accept (2),
 401 .BR bind (2),
 402 .BR close (2),
 403 .BR connect (2),
 404 .BR fcntl (2),
 405 .BR getpeername (2),
 406 .BR getsockname (2),
 407 .BR getsockopt (2),
 408 .BR ioctl (2),
 409 .BR listen (2),
 410 .BR read (2),
 411 .BR recv (2),
 412 .BR select (2),
 413 .BR send (2),
 414 .BR shutdown (2),
 415 .BR socketpair (2),
 416 .BR write (2),
 417 .BR getprotoent (3),
 418 .BR ip (7),
 419 .BR socket (7),
 420 .BR tcp (7),
 421 .BR udp (7),
 422 .BR unix (7)
 423
 424 \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq
 425 and
 426 \(lqBSD Interprocess Communication Tutorial\(rq,
 427 reprinted in
 428 .I UNIX Programmer's Supplementary Documents Volume 1.