1SOCKET(2) Linux Programmer's Manual SOCKET(2)
2
6 socket - create an endpoint for communication
7
9 #include <sys/types.h> /* See NOTES */
10 #include <sys/socket.h>
11 int socket(int domain, int type, int protocol);
13
15 socket() creates an endpoint for communication and returns a descrip‐
16 tor.
17 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 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 The socket has the indicated type, which specifies the communication
36 semantics. Currently defined types are:
37 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 SOCK_DGRAM Supports datagrams (connectionless, unreliable messages
43 of a fixed maximum length).
44 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 SOCK_RAW Provides raw network protocol access.
51 SOCK_RDM Provides a reliable datagram layer that does not guar‐
53 antee ordering.
54 SOCK_PACKET Obsolete and should not be used in new programs; see
56 packet(7).
57 Some socket types may not be implemented by all protocol families; for
59 example, SOCK_SEQPACKET is not implemented for AF_INET.
60 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 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 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 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 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 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 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 SOCK_PACKET is an obsolete socket type to receive raw packets directly
112 from the device driver. Use packet(7) instead.
113 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 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 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
134 On success, a file descriptor for the new socket is returned. On
135 error, -1 is returned, and errno is set appropriately.
136
138 EACCES Permission to create a socket of the specified type and/or pro‐
139 tocol is denied.
140 EAFNOSUPPORT
142 The implementation does not support the specified address fam‐
143 ily.
144 EINVAL Unknown protocol, or protocol family not available.
146 EINVAL Invalid flags in type.
148 EMFILE Process file table overflow.
150 ENFILE The system limit on the total number of open files has been
152 reached.
153 ENOBUFS or ENOMEM
155 Insufficient memory is available. The socket cannot be created
156 until sufficient resources are freed.
157 EPROTONOSUPPORT
159 The protocol type or the specified protocol is not supported
160 within this domain.
161 Other errors may be generated by the underlying protocol modules.
163
165 4.4BSD, POSIX.1-2001.
166 The SOCK_NONBLOCK and SOCK_CLOEXEC flags are Linux-specific.
168 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
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 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
186 An example of the use of socket() is shown in getaddrinfo(3).
187
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 “An Introductory 4.3BSD Interprocess Communication Tutorial” is
195 reprinted in UNIX Programmer's Supplementary Documents Volume 1.
196 “BSD Interprocess Communication Tutorial” is reprinted in UNIX Program‐
198 mer's Supplementary Documents Volume 1.
199
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/.
204Linux 2009-01-19 SOCKET(2)