original/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-02-01 "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 descriptor.
  55 .PP
  56 The
  57 .I domain
  58 argument specifies a communication domain; this selects the protocol
  59 family which will be used for communication.
  60 These families are defined in
  61 .IR <sys/socket.h> .
  62 The currently understood formats include:
  63 .TS
  64 tab(:);
  65 l l l.
  66 Name:Purpose:Man page
  67 T{
  68 .BR AF_UNIX ", " AF_LOCAL
  69 T}:T{
  70 Local communication
  71 T}:T{
  72 .BR unix (7)
  73 T}
  74 T{
  75 .B AF_INET
  76 T}:IPv4 Internet protocols:T{
  77 .BR ip (7)
  78 T}
  79 T{
  80 .B AF_INET6
  81 T}:IPv6 Internet protocols:T{
  82 .BR ipv6 (7)
  83 T}
  84 T{
  85 .B AF_IPX
  86 T}:IPX \- Novell protocols:
  87 T{
  88 .B AF_NETLINK
  89 T}:T{
  90 Kernel user interface device
  91 T}:T{
  92 .BR netlink (7)
  93 T}
  94 T{
  95 .B AF_X25
  96 T}:ITU-T X.25 / ISO-8208 protocol:T{
  97 .BR x25 (7)
  98 T}
  99 T{
 100 .B AF_AX25
 101 T}:T{
 102 Amateur radio AX.25 protocol
 103 T}:
 104 T{
 105 .B AF_ATMPVC
 106 T}:Access to raw ATM PVCs:
 107 T{
 108 .B AF_APPLETALK
 109 T}:AppleTalk:T{
 110 .BR ddp (7)
 111 T}
 112 T{
 113 .B AF_PACKET
 114 T}:T{
 115 Low level packet interface
 116 T}:T{
 117 .BR packet (7)
 118 T}
 119 T{
 120 .B AF_ALG
 121 T}:T{
 122 Interface to kernel crypto API
 123 T}
 124 .TE
 125 .PP
 126 The socket has the indicated
 127 .IR type ,
 128 which specifies the communication semantics.
 129 Currently defined types
 130 are:
 131 .TP 16
 132 .B SOCK_STREAM
 133 Provides sequenced, reliable, two-way, connection-based byte streams.
 134 An out-of-band data transmission mechanism may be supported.
 135 .TP
 136 .B SOCK_DGRAM
 137 Supports datagrams (connectionless, unreliable messages of a fixed
 138 maximum length).
 139 .TP
 140 .B SOCK_SEQPACKET
 141 Provides a sequenced, reliable, two-way connection-based data
 142 transmission path for datagrams of fixed maximum length; a consumer is
 143 required to read an entire packet with each input system call.
 144 .TP
 145 .B SOCK_RAW
 146 Provides raw network protocol access.
 147 .TP
 148 .B SOCK_RDM
 149 Provides a reliable datagram layer that does not guarantee ordering.
 150 .TP
 151 .B SOCK_PACKET
 152 Obsolete and should not be used in new programs;
 153 see
 154 .BR packet (7).
 155 .PP
 156 Some socket types may not be implemented by all protocol families.
 157 .PP
 158 Since Linux 2.6.27, the
 159 .I type
 160 argument serves a second purpose:
 161 in addition to specifying a socket type,
 162 it may include the bitwise OR of any of the following values,
 163 to modify the behavior of
 164 .BR socket ():
 165 .TP 16
 166 .B SOCK_NONBLOCK
 167 Set the
 168 .BR O_NONBLOCK
 169 file status flag on the new open file description.
 170 Using this flag saves extra calls to
 171 .BR fcntl (2)
 172 to achieve the same result.
 173 .TP
 174 .B SOCK_CLOEXEC
 175 Set the close-on-exec
 176 .RB ( FD_CLOEXEC )
 177 flag on the new file descriptor.
 178 See the description of the
 179 .B O_CLOEXEC
 180 flag in
 181 .BR open (2)
 182 for reasons why this may be useful.
 183 .PP
 184 The
 185 .I protocol
 186 specifies a particular protocol to be used with the socket.
 187 Normally only a single protocol exists to support a particular
 188 socket type within a given protocol family, in which case
 189 .I protocol
 190 can be specified as 0.
 191 However, it is possible that many protocols may exist, in
 192 which case a particular protocol must be specified in this manner.
 193 The protocol number to use is specific to the \*(lqcommunication domain\*(rq
 194 in which communication is to take place; see
 195 .BR protocols (5).
 196 See
 197 .BR getprotoent (3)
 198 on how to map protocol name strings to protocol numbers.
 199 .PP
 200 Sockets of type
 201 .B SOCK_STREAM
 202 are full-duplex byte streams.
 203 They do not preserve
 204 record boundaries.
 205 A stream socket must be in
 206 a
 207 .I connected
 208 state before any data may be sent or received on it.
 209 A connection to
 210 another socket is created with a
 211 .BR connect (2)
 212 call.
 213 Once connected, data may be transferred using
 214 .BR read (2)
 215 and
 216 .BR write (2)
 217 calls or some variant of the
 218 .BR send (2)
 219 and
 220 .BR recv (2)
 221 calls.
 222 When a session has been completed a
 223 .BR close (2)
 224 may be performed.
 225 Out-of-band data may also be transmitted as described in
 226 .BR send (2)
 227 and received as described in
 228 .BR recv (2).
 229 .PP
 230 The communications protocols which implement a
 231 .B SOCK_STREAM
 232 ensure that data is not lost or duplicated.
 233 If a piece of data for which
 234 the peer protocol has buffer space cannot be successfully transmitted
 235 within a reasonable length of time, then the connection is considered
 236 to be dead.
 237 When
 238 .B SO_KEEPALIVE
 239 is enabled on the socket the protocol checks in a protocol-specific
 240 manner if the other end is still alive.
 241 A
 242 .B SIGPIPE
 243 signal is raised if a process sends or receives
 244 on a broken stream; this causes naive processes,
 245 which do not handle the signal, to exit.
 246 .B SOCK_SEQPACKET
 247 sockets employ the same system calls as
 248 .B SOCK_STREAM
 249 sockets.
 250 The only difference is that
 251 .BR read (2)
 252 calls will return only the amount of data requested,
 253 and any data remaining in the arriving packet will be discarded.
 254 Also all message boundaries in incoming datagrams are preserved.
 255 .PP
 256 .B SOCK_DGRAM
 257 and
 258 .B SOCK_RAW
 259 sockets allow sending of datagrams to correspondents named in
 260 .BR sendto (2)
 261 calls.
 262 Datagrams are generally received with
 263 .BR recvfrom (2),
 264 which returns the next datagram along with the address of its sender.
 265 .PP
 266 .B SOCK_PACKET
 267 is an obsolete socket type to receive raw packets directly from the
 268 device driver.
 269 Use
 270 .BR packet (7)
 271 instead.
 272 .PP
 273 An
 274 .BR fcntl (2)
 275 .B F_SETOWN
 276 operation can be used to specify a process or process group to receive a
 277 .B SIGURG
 278 signal when the out-of-band data arrives or
 279 .B SIGPIPE
 280 signal when a
 281 .B SOCK_STREAM
 282 connection breaks unexpectedly.
 283 This operation may also be used to set the process or process group
 284 that receives the I/O and asynchronous notification of I/O events via
 285 .BR SIGIO .
 286 Using
 287 .B F_SETOWN
 288 is equivalent to an
 289 .BR ioctl (2)
 290 call with the
 291 .B FIOSETOWN
 292 or
 293 .B SIOCSPGRP
 294 argument.
 295 .PP
 296 When the network signals an error condition to the protocol module (e.g.,
 297 using a ICMP message for IP) the pending error flag is set for the socket.
 298 The next operation on this socket will return the error code of the pending
 299 error.
 300 For some protocols it is possible to enable a per-socket error queue
 301 to retrieve detailed information about the error; see
 302 .B IP_RECVERR
 303 in
 304 .BR ip (7).
 305 .PP
 306 The operation of sockets is controlled by socket level
 307 .IR options .
 308 These options are defined in
 309 .IR <sys/socket.h> .
 310 The functions
 311 .BR setsockopt (2)
 312 and
 313 .BR getsockopt (2)
 314 are used to set and get options, respectively.
 315 .SH RETURN VALUE
 316 On success, a file descriptor for the new socket is returned.
 317 On error, \-1 is returned, and
 318 .I errno
 319 is set appropriately.
 320 .SH ERRORS
 321 .TP
 322 .B EACCES
 323 Permission to create a socket of the specified type and/or protocol
 324 is denied.
 325 .TP
 326 .B EAFNOSUPPORT
 327 The implementation does not support the specified address family.
 328 .TP
 329 .B EINVAL
 330 Unknown protocol, or protocol family not available.
 331 .TP
 332 .B EINVAL
 333 .\" Since Linux 2.6.27
 334 Invalid flags in
 335 .IR type .
 336 .TP
 337 .B EMFILE
 338 Process file table overflow.
 339 .TP
 340 .B ENFILE
 341 The system limit on the total number of open files has been reached.
 342 .TP
 343 .BR ENOBUFS " or " ENOMEM
 344 Insufficient memory is available.
 345 The socket cannot be
 346 created until sufficient resources are freed.
 347 .TP
 348 .B EPROTONOSUPPORT
 349 The protocol type or the specified protocol is not
 350 supported within this domain.
 351 .PP
 352 Other errors may be generated by the underlying protocol modules.
 353 .SH CONFORMING TO
 354 4.4BSD, POSIX.1-2001.
 355
 356 The
 357 .B SOCK_NONBLOCK
 358 and
 359 .B SOCK_CLOEXEC
 360 flags are Linux-specific.
 361
 362 .BR socket ()
 363 appeared in 4.2BSD.
 364 It is generally portable to/from
 365 non-BSD systems supporting clones of the BSD socket layer (including
 366 System\ V variants).
 367 .SH NOTES
 368 POSIX.1-2001 does not require the inclusion of
 369 .IR <sys/types.h> ,
 370 and this header file is not required on Linux.
 371 However, some historical (BSD) implementations required this header
 372 file, and portable applications are probably wise to include it.
 373
 374 The manifest constants used under 4.x BSD for protocol families
 375 are
 376 .BR PF_UNIX ,
 377 .BR PF_INET ,
 378 and so on, while
 379 .BR AF_UNIX ,
 380 .BR AF_INET ,
 381 and so on are used for address
 382 families.
 383 However, already the BSD man page promises: "The protocol
 384 family generally is the same as the address family", and subsequent
 385 standards use AF_* everywhere.
 386
 387 The
 388 .B AF_ALG
 389 protocol type was added in Linux 2.6.38.
 390 More information on this interface is provided in the kernel source file,
 391 .IR Documentation/crypto/crypto-API-userspace.txt .
 392 .SH EXAMPLE
 393 An example of the use of
 394 .BR socket ()
 395 is shown in
 396 .BR getaddrinfo (3).
 397 .SH SEE ALSO
 398 .BR accept (2),
 399 .BR bind (2),
 400 .BR connect (2),
 401 .BR fcntl (2),
 402 .BR getpeername (2),
 403 .BR getsockname (2),
 404 .BR getsockopt (2),
 405 .BR ioctl (2),
 406 .BR listen (2),
 407 .BR read (2),
 408 .BR recv (2),
 409 .BR select (2),
 410 .BR send (2),
 411 .BR shutdown (2),
 412 .BR socketpair (2),
 413 .BR write (2),
 414 .BR getprotoent (3),
 415 .BR ip (7),
 416 .BR socket (7),
 417 .BR tcp (7),
 418 .BR udp (7),
 419 .BR unix (7)
 420
 421 \(lqAn Introductory 4.3BSD Interprocess Communication Tutorial\(rq
 422 and
 423 \(lqBSD Interprocess Communication Tutorial\(rq,
 424 reprinted in
 425 .I UNIX Programmer's Supplementary Documents Volume 1.
 426 .SH COLOPHON
 427 This page is part of release 3.79 of the Linux
 428 .I man-pages
 429 project.
 430 A description of the project,
 431 information about reporting bugs,
 432 and the latest version of this page,
 433 can be found at
 434 \%http://www.kernel.org/doc/man\-pages/.