1SOCKET(2)                  Linux Programmer's Manual                 SOCKET(2)
2
3
4

NAME

6       socket - create an endpoint for communication
7

SYNOPSIS

9       #include <sys/types.h>          /* See NOTES */
10       #include <sys/socket.h>
11
12       int socket(int domain, int type, int protocol);
13

DESCRIPTION

15       socket()  creates  an endpoint for communication and returns a descrip‐
16       tor.
17
18       The domain argument specifies a communication domain; this selects  the
19       protocol  family  which will be used for communication.  These families
20       are  defined  in  <sys/socket.h>.   The  currently  understood  formats
21       include:
22
23       Name                Purpose                          Man page
24       AF_UNIX, AF_LOCAL   Local communication              unix(7)
25       AF_INET             IPv4 Internet protocols          ip(7)
26       AF_INET6            IPv6 Internet protocols          ipv6(7)
27       AF_IPX              IPX - Novell protocols
28       AF_NETLINK          Kernel user interface device     netlink(7)
29       AF_X25              ITU-T X.25 / ISO-8208 protocol   x25(7)
30       AF_AX25             Amateur radio AX.25 protocol
31       AF_ATMPVC           Access to raw ATM PVCs
32       AF_APPLETALK        Appletalk                        ddp(7)
33       AF_PACKET           Low level packet interface       packet(7)
34
35       The  socket  has  the indicated type, which specifies the communication
36       semantics.  Currently defined types are:
37
38       SOCK_STREAM     Provides sequenced, reliable, two-way, connection-based
39                       byte  streams.  An out-of-band data transmission mecha‐
40                       nism may be supported.
41
42       SOCK_DGRAM      Supports datagrams (connectionless, unreliable messages
43                       of a fixed maximum length).
44
45       SOCK_SEQPACKET  Provides  a  sequenced,  reliable,  two-way connection-
46                       based data transmission path  for  datagrams  of  fixed
47                       maximum  length;  a  consumer  is  required  to read an
48                       entire packet with each input system call.
49
50       SOCK_RAW        Provides raw network protocol access.
51
52       SOCK_RDM        Provides a reliable datagram layer that does not  guar‐
53                       antee ordering.
54
55       SOCK_PACKET     Obsolete  and  should  not be used in new programs; see
56                       packet(7).
57
58       Some socket types may not be implemented by all protocol families;  for
59       example, SOCK_SEQPACKET is not implemented for AF_INET.
60
61       Since Linux 2.6.27, the type argument serves a second purpose: in addi‐
62       tion to specifying a socket type, it may include the bitwise OR of  any
63       of the following values, to modify the behavior of socket():
64
65       SOCK_NONBLOCK   Set  the  O_NONBLOCK  file  status flag on the new open
66                       file description.  Using this flag saves extra calls to
67                       fcntl(2) to achieve the same result.
68
69       SOCK_CLOEXEC    Set the close-on-exec (FD_CLOEXEC) flag on the new file
70                       descriptor.  See the description of the O_CLOEXEC  flag
71                       in open(2) for reasons why this may be useful.
72
73       The  protocol  specifies  a  particular  protocol  to  be used with the
74       socket.  Normally only a single protocol exists to support a particular
75       socket  type within a given protocol family, in which case protocol can
76       be specified as 0.  However, it is possible  that  many  protocols  may
77       exist,  in  which  case a particular protocol must be specified in this
78       manner.  The protocol number to use is specific to  the  “communication
79       domain” in which communication is to take place; see protocols(5).  See
80       getprotoent(3) on how to map protocol name strings to protocol numbers.
81
82       Sockets of type SOCK_STREAM are full-duplex byte  streams,  similar  to
83       pipes.   They  do not preserve record boundaries.  A stream socket must
84       be in a connected state before any data may be sent or received on  it.
85       A connection to another socket is created with a connect(2) call.  Once
86       connected, data may be transferred using read(2) and write(2) calls  or
87       some variant of the send(2) and recv(2) calls.  When a session has been
88       completed a close(2) may be performed.  Out-of-band data  may  also  be
89       transmitted  as  described  in  send(2)  and  received  as described in
90       recv(2).
91
92       The communications protocols which implement a SOCK_STREAM ensure  that
93       data  is not lost or duplicated.  If a piece of data for which the peer
94       protocol has buffer space cannot be successfully transmitted  within  a
95       reasonable  length  of  time,  then  the connection is considered to be
96       dead.  When SO_KEEPALIVE is enabled on the socket the  protocol  checks
97       in  a protocol-specific manner if the other end is still alive.  A SIG‐
98       PIPE signal is raised if a  process  sends  or  receives  on  a  broken
99       stream; this causes naive processes, which do not handle the signal, to
100       exit.   SOCK_SEQPACKET  sockets  employ  the  same  system   calls   as
101       SOCK_STREAM  sockets.   The  only difference is that read(2) calls will
102       return only the amount of data requested, and any data remaining in the
103       arriving  packet  will  be  discarded.   Also all message boundaries in
104       incoming datagrams are preserved.
105
106       SOCK_DGRAM and SOCK_RAW sockets allow sending of  datagrams  to  corre‐
107       spondents  named  in sendto(2) calls.  Datagrams are generally received
108       with recvfrom(2), which  returns  the  next  datagram  along  with  the
109       address of its sender.
110
111       SOCK_PACKET  is an obsolete socket type to receive raw packets directly
112       from the device driver.  Use packet(7) instead.
113
114       An fcntl(2) F_SETOWN operation can be used  to  specify  a  process  or
115       process  group  to  receive  a  SIGURG signal when the out-of-band data
116       arrives or SIGPIPE signal when a SOCK_STREAM  connection  breaks  unex‐
117       pectedly.   This  operation  may  also  be  used  to set the process or
118       process group that receives the I/O and  asynchronous  notification  of
119       I/O events via SIGIO.  Using F_SETOWN is equivalent to an ioctl(2) call
120       with the FIOSETOWN or SIOCSPGRP argument.
121
122       When the network signals an error  condition  to  the  protocol  module
123       (e.g.,  using  a ICMP message for IP) the pending error flag is set for
124       the socket.  The next operation on this socket will  return  the  error
125       code of the pending error.  For some protocols it is possible to enable
126       a per-socket error queue to retrieve  detailed  information  about  the
127       error; see IP_RECVERR in ip(7).
128
129       The  operation of sockets is controlled by socket level options.  These
130       options are defined in <sys/socket.h>.  The functions setsockopt(2) and
131       getsockopt(2) are used to set and get options, respectively.
132

RETURN VALUE

134       On  success,  a  file  descriptor  for  the new socket is returned.  On
135       error, -1 is returned, and errno is set appropriately.
136

ERRORS

138       EACCES Permission to create a socket of the specified type and/or  pro‐
139              tocol is denied.
140
141       EAFNOSUPPORT
142              The  implementation  does not support the specified address fam‐
143              ily.
144
145       EINVAL Unknown protocol, or protocol family not available.
146
147       EINVAL Invalid flags in type.
148
149       EMFILE Process file table overflow.
150
151       ENFILE The system limit on the total number  of  open  files  has  been
152              reached.
153
154       ENOBUFS or ENOMEM
155              Insufficient  memory is available.  The socket cannot be created
156              until sufficient resources are freed.
157
158       EPROTONOSUPPORT
159              The protocol type or the specified  protocol  is  not  supported
160              within this domain.
161
162       Other errors may be generated by the underlying protocol modules.
163

CONFORMING TO

165       4.4BSD, POSIX.1-2001.
166
167       The SOCK_NONBLOCK and SOCK_CLOEXEC flags are Linux-specific.
168
169       socket()  appeared in 4.2BSD.  It is generally portable to/from non-BSD
170       systems supporting clones of the BSD socket layer (including  System  V
171       variants).
172

NOTES

174       POSIX.1-2001  does not require the inclusion of <sys/types.h>, and this
175       header file is not required on Linux.  However, some  historical  (BSD)
176       implementations  required  this  header file, and portable applications
177       are probably wise to include it.
178
179       The manifest constants used under 4.x BSD  for  protocol  families  are
180       PF_UNIX,  PF_INET,  etc., while AF_UNIX etc. are used for address fami‐
181       lies.  However, already the BSD man page promises: "The protocol family
182       generally  is the same as the address family", and subsequent standards
183       use AF_* everywhere.
184

EXAMPLE

186       An example of the use of socket() is shown in getaddrinfo(3).
187

SEE ALSO

189       accept(2),  bind(2),  connect(2),  fcntl(2),  getpeername(2),  getsock‐
190       name(2),   getsockopt(2),   ioctl(2),   listen(2),   read(2),  recv(2),
191       select(2),  send(2),  shutdown(2),  socketpair(2),  write(2),   getpro‐
192       toent(3), ip(7), socket(7), tcp(7), udp(7), unix(7)
193
194       “An   Introductory   4.3BSD  Interprocess  Communication  Tutorial”  is
195       reprinted in UNIX Programmer's Supplementary Documents Volume 1.
196
197       “BSD Interprocess Communication Tutorial” is reprinted in UNIX Program‐
198       mer's Supplementary Documents Volume 1.
199

COLOPHON

201       This  page  is  part of release 3.22 of the Linux man-pages project.  A
202       description of the project, and information about reporting  bugs,  can
203       be found at http://www.kernel.org/doc/man-pages/.
204
205
206
207Linux                             2009-01-19                         SOCKET(2)
Impressum