| blob | 29a8de8e53eb89133c7ac98550be9aa12e8df215 |
1 .\" $OpenBSD: socket.2,v 1.41 2016/03/19 22:10:49 guenther Exp $
2 .\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd Exp $
3 .\"
4 .\" Copyright (c) 1983, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)socket.2 8.1 (Berkeley) 6/4/93
32 .\"
33 .Dd October 26, 2016
34 .Dt SOCKET 2
35 .Os
36 .Sh NAME
37 .Nm socket
38 .Nd create an endpoint for communication
39 .Sh SYNOPSIS
40 .In sys/socket.h
41 .Ft int
42 .Fn socket "int domain" "int type" "int protocol"
43 .Sh DESCRIPTION
44 .Fn socket
45 creates an endpoint for communication and returns a descriptor.
46 .Pp
47 The
48 .Fa domain
49 parameter specifies a communications domain within which
50 communication will take place; this selects the protocol family
51 which should be used.
52 These families are defined in the include file
53 .In sys/socket.h .
54 The currently understood formats are:
55 .Pp
56 .Bl -tag -width "AF_INET6XXX" -offset indent -compact
57 .It AF_UNIX
58 UNIX internal protocols
59 .It AF_INET
60 ARPA Internet protocols
61 .It AF_INET6
62 IPv6 (Internet Protocol version 6) protocols
63 .El
64 .Pp
65 The socket has the indicated
66 .Fa type ,
67 which specifies the semantics of communication.
68 Currently defined types are:
69 .Pp
70 .Bl -tag -width "SOCK_SEQPACKETXXX" -offset indent -compact
71 .It SOCK_STREAM
72 .It SOCK_DGRAM
73 .It SOCK_RAW
74 .It SOCK_SEQPACKET
75 .El
76 .Pp
77 A
78 .Dv SOCK_STREAM
79 type provides sequenced, reliable,
80 two-way connection based byte streams.
81 An out-of-band data transmission mechanism may be supported.
82 A
83 .Dv SOCK_DGRAM
84 socket supports
85 datagrams (connectionless, unreliable messages of
86 a fixed (typically small) maximum length).
87 A
88 .Dv SOCK_SEQPACKET
89 socket may provide a sequenced, reliable,
90 two-way connection-based data transmission path for datagrams
91 of fixed maximum length; a consumer may be required to read
92 an entire packet with each read system call.
93 This facility is protocol specific, and currently implemented for
94 .Dv AF_UNIX
95 as well as
96 .Dv IPPROTO_SCTP
97 in the
98 .Dv AF_INET
99 and
100 .Dv AF_INET6
101 domains.
102 .Dv SOCK_RAW
103 sockets provide access to internal network protocols and interfaces,
104 and are available only with the
105 .Dv net_rawaccess
106 privilege.
107 .Pp
108 Any combination of the following flags may additionally be used in the
109 .Fa type
110 argument:
111 .Pp
112 .Bl -tag -width "SOCK_NONBLOCKX" -offset indent -compact
113 .It SOCK_CLOEXEC
114 Set close-on-exec flag on the new descriptor.
115 .It SOCK_NONBLOCK
116 Set non-blocking I/O mode on the new socket.
117 .El
118 .Pp
119 The
120 .Fa protocol
121 specifies a particular protocol to be used with the socket.
122 Normally only a single protocol exists to support a particular
123 socket type within a given protocol family.
124 However, it is possible that many protocols may exist,
125 in which case a particular protocol must be specified in this manner.
126 The protocol number to use is particular to the
127 .Dq communication domain
128 in which communication is to take place; see
129 .Xr protocols 4 .
130 A value of 0 for
131 .Fa protocol
132 will let the system select an appropriate protocol for the requested
133 socket type.
134 .Pp
135 Sockets of type
136 .Dv SOCK_STREAM
137 are full-duplex byte streams.
138 A stream socket must be in a
139 .Em connected
140 state before any data may be sent or received on it.
141 A connection to another socket is created with a
142 .Xr connect 2
143 call.
144 Once connected, data may be transferred using
145 .Xr read 2
146 and
147 .Xr write 2
148 calls or some variant of the
149 .Xr send 2
150 and
151 .Xr recv 2
152 calls.
153 When a session has been completed a
154 .Xr close 2
155 may be performed.
156 Out-of-band data may also be transmitted as described in
157 .Xr send 2
158 and received as described in
159 .Xr recv 2 .
160 .Pp
161 The communications protocols used to implement a
162 .Dv SOCK_STREAM
163 ensure that data is not lost or duplicated.
164 If a piece of data for which the peer protocol has buffer space cannot
165 be successfully transmitted within a reasonable length of time, then the
166 connection is considered broken and calls will indicate an error with \-1
167 returns and with
168 .Er ETIMEDOUT
169 as the specific code in the global variable
170 .Va errno .
171 The protocols optionally keep sockets
172 .Dq warm
173 by forcing transmissions roughly every minute in the absence of other activity.
174 An error is then indicated if no response can be elicited on an otherwise
175 idle connection for an extended period (e.g., 5 minutes).
176 A
177 .Dv SIGPIPE
178 signal is raised if a process sends on a broken stream; this causes
179 naive processes, which do not handle the signal, to exit.
180 .Pp
181 .Dv SOCK_SEQPACKET
182 sockets employ the same system calls
183 as
184 .Dv SOCK_STREAM
185 sockets.
186 The only difference is that
187 .Xr read 2
188 calls will return only the amount of data requested,
189 and any remaining in the arriving packet will be discarded.
190 .Pp
191 .Dv SOCK_DGRAM
192 and
193 .Dv SOCK_RAW
194 sockets allow sending of datagrams to correspondents named in
195 .Xr send 2
196 calls.
197 Datagrams are generally received with
198 .Xr recvfrom 2 ,
199 which returns the next datagram with its return address.
200 .Pp
201 An
202 .Xr fcntl 2
203 call can be used to specify a process group to receive
204 a
205 .Dv SIGURG
206 signal when the out-of-band data arrives.
207 It may also enable non-blocking I/O and asynchronous notification
208 of I/O events via
209 .Dv SIGIO .
210 .Pp
211 The operation of sockets is controlled by socket level
212 .Em options .
213 These options are defined in the file
214 .In sys/socket.h .
215 .Xr setsockopt 2
216 and
217 .Xr getsockopt 2
218 are used to set and get options, respectively.
219 .Sh RETURN VALUES
220 A \-1 is returned if an error occurs, otherwise the return
221 value is a descriptor referencing the socket.
222 .Sh ERRORS
223 The
224 .Fn socket
225 call fails if:
226 .Bl -tag -width Er
227 .It Bq Er EAFNOSUPPORT
228 The specified address family is not supported on this machine.
229 .It Bq Er EPROTONOSUPPORT
230 The protocol type or the specified protocol is not supported
231 within this domain.
232 .It Bq Er EPROTOTYPE
233 The combination of the specified protocol and type is not supported.
234 .It Bq Er EMFILE
235 The per-process descriptor table is full.
236 .It Bq Er ENFILE
237 The system file table is full.
238 .It Bq Er ENOBUFS
239 Insufficient resources were available in the system
240 to perform the operation.
241 .It Bq Er ENOMEM
242 Insufficient user memory was available to perform the operation.
243 .It Bq Er EACCES
244 Permission to create a socket of the specified type and/or protocol
245 is denied.
246 .El
247 .Sh SEE ALSO
248 .Xr accept 2 ,
249 .Xr bind 2 ,
250 .Xr connect 2 ,
251 .Xr getsockname 2 ,
252 .Xr getsockopt 2 ,
253 .Xr ioctl 2 ,
254 .Xr listen 2 ,
255 .Xr poll 2 ,
256 .Xr read 2 ,
257 .Xr recv 2 ,
258 .Xr select 2 ,
259 .Xr send 2 ,
260 .Xr setsockopt 2 ,
261 .Xr shutdown 2 ,
262 .Xr socketpair 2 ,
263 .Xr write 2 ,
264 .Xr getprotoent 3 ,
265 .Xr inet 7P ,
266 .Xr inet6 7P
267 .Rs
268 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
269 .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
270 .Re
271 .Rs
272 .%T "BSD Interprocess Communication Tutorial"
273 .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
274 .Re
275 .Sh STANDARDS
276 The
277 .Fn socket
278 function conforms to
279 .St -p1003.1-2008 .
280 The
281 .Dv SOCK_CLOEXEC
282 and
283 .Dv SOCK_NONBLOCK
284 flags are expected to conform to a future revision of that standard.
285 .Sh HISTORY
286 The
287 .Fn socket
288 system call first appeared in
289 .Bx 4.1c .