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