socket(2)

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>
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 parameter 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       PF_UNIX, PF_LOCAL   Local communication              unix(7)
25       PF_INET             IPv4 Internet protocols          ip(7)
26       PF_INET6            IPv6 Internet protocols          ipv6(7)
27       PF_IPX              IPX - Novell protocols
28       PF_NETLINK          Kernel user interface device     netlink(7)
29       PF_X25              ITU-T X.25 / ISO-8208 protocol   x25(7)
30       PF_AX25             Amateur radio AX.25 protocol
31       PF_ATMPVC           Access to raw ATM PVCs
32       PF_APPLETALK        Appletalk                        ddp(7)
33       PF_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
39              Provides sequenced,  reliable,  two-way,  connection-based  byte
40              streams.  An out-of-band data transmission mechanism may be sup‐
41              ported.
42
43       SOCK_DGRAM
44              Supports datagrams (connectionless,  unreliable  messages  of  a
45              fixed maximum length).
46
47       SOCK_SEQPACKET
48              Provides  a  sequenced,  reliable, two-way connection-based data
49              transmission path for datagrams of fixed maximum length; a  con‐
50              sumer is required to read an entire packet with each read system
51              call.
52
53       SOCK_RAW
54              Provides raw network protocol access.
55
56       SOCK_RDM
57              Provides a reliable  datagram  layer  that  does  not  guarantee
58              ordering.
59
60       SOCK_PACKET
61              Obsolete and should not be used in new programs; see packet(7).
62
63       Some  socket types may not be implemented by all protocol families; for
64       example, SOCK_SEQPACKET is not implemented for AF_INET.
65
66       The protocol specifies a  particular  protocol  to  be  used  with  the
67       socket.  Normally only a single protocol exists to support a particular
68       socket type within a given protocol family, in which case protocol  can
69       be  specified  as  0.   However, it is possible that many protocols may
70       exist, in which case a particular protocol must be  specified  in  this
71       manner.   The  protocol number to use is specific to the “communication
72       domain” in which communication is to take place; see protocols(5).  See
73       getprotoent(3) on how to map protocol name strings to protocol numbers.
74
75       Sockets  of  type  SOCK_STREAM are full-duplex byte streams, similar to
76       pipes.  They do not preserve record boundaries. A stream socket must be
77       in  a connected state before any data may be sent or received on it.  A
78       connection to another socket is created with a connect(2)  call.   Once
79       connected,  data may be transferred using read(2) and write(2) calls or
80       some variant of the send(2) and recv(2) calls.  When a session has been
81       completed  a  close(2)  may be performed.  Out-of-band data may also be
82       transmitted as described  in  send(2)  and  received  as  described  in
83       recv(2).
84
85       The  communications protocols which implement a SOCK_STREAM ensure that
86       data is not lost or duplicated.  If a piece of data for which the  peer
87       protocol  has  buffer space cannot be successfully transmitted within a
88       reasonable length of time, then the  connection  is  considered  to  be
89       dead.   When  SO_KEEPALIVE is enabled on the socket the protocol checks
90       in a protocol-specific manner if the other end is still alive.  A  SIG‐
91       PIPE  signal  is  raised  if  a  process  sends or receives on a broken
92       stream; this causes naive processes, which do not handle the signal, to
93       exit.    SOCK_SEQPACKET   sockets  employ  the  same  system  calls  as
94       SOCK_STREAM sockets.  The only difference is that  read(2)  calls  will
95       return only the amount of data requested, and any data remaining in the
96       arriving packet will be discarded.   Also  all  message  boundaries  in
97       incoming datagrams are preserved.
98
99       SOCK_DGRAM  and  SOCK_RAW  sockets allow sending of datagrams to corre‐
100       spondents named in sendto(2) calls.  Datagrams are  generally  received
101       with  recvfrom(2),  which  returns  the  next  datagram  along with the
102       address of its sender.
103
104       SOCK_PACKET is an obsolete socket type to receive raw packets  directly
105       from the device driver. Use packet(7) instead.
106
107       An  fcntl(2)  F_SETOWN  operation  can  be used to specify a process or
108       process group to receive a SIGURG  signal  when  the  out-of-band  data
109       arrives  or  SIGPIPE  signal when a SOCK_STREAM connection breaks unex‐
110       pectedly.  This operation may also  be  used  to  set  the  process  or
111       process  group  that  receives the I/O and asynchronous notification of
112       I/O events via SIGIO.  Using F_SETOWN is equivalent to an ioctl(2) call
113       with the FIOSETOWN or SIOCSPGRP argument.
114
115       When  the  network  signals  an  error condition to the protocol module
116       (e.g., using a ICMP message for IP) the pending error flag is  set  for
117       the  socket.   The  next operation on this socket will return the error
118       code of the pending error. For some protocols it is possible to  enable
119       a  per-socket  error  queue  to retrieve detailed information about the
120       error; see IP_RECVERR in ip(7).
121
122       The operation of sockets is controlled by socket level options.   These
123       options are defined in <sys/socket.h>.  The functions setsockopt(2) and
124       getsockopt(2) are used to set and get options, respectively.
125

RETURN VALUE

127       On success, a file descriptor for  the  new  socket  is  returned.   On
128       error, -1 is returned, and errno is set appropriately.
129

ERRORS

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

CONFORMING TO

156       4.4BSD, POSIX.1-2001.  socket() appeared in  4.2BSD.  It  is  generally
157       portable  to/from  non-BSD  systems supporting clones of the BSD socket
158       layer (including System V variants).
159

NOTE

161       The manifest constants used under 4.x BSD  for  protocol  families  are
162       PF_UNIX,  PF_INET,  etc., while AF_UNIX etc. are used for address fami‐
163       lies. However, already the BSD man page promises: "The protocol  family
164       generally  is the same as the address family", and subsequent standards
165       use AF_* everywhere.
166

BUGS

168       SOCK_UUCP is not implemented yet.
169