jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: socket.2,v 1.46 2025/08/04 04:59:31 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 $Mdocdate: August 4 2025 $
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
45creates an endpoint for communication and returns a descriptor.
46.Pp
47The
48.Fa domain
49parameter specifies a communications domain within which
50communication will take place; this selects the protocol family
51which should be used.
52These families are defined in the include file
53.In sys/socket.h .
54The currently understood formats are:
55.Pp
56.Bl -tag -width "AF_INET6XXX" -offset indent -compact
57.It Dv AF_UNIX
58UNIX internal protocols
59.It Dv AF_INET
60Internet Protocol version 4 (IPv4) protocol family
61.It Dv AF_INET6
62Internet Protocol version 6 (IPv6) protocol family
63.El
64.Pp
65The socket has the indicated
66.Fa type ,
67which specifies the semantics of communication.
68Currently defined types are:
69.Pp
70.Bl -tag -width "SOCK_SEQPACKETXXX" -offset indent -compact
71.It Dv SOCK_STREAM
72.It Dv SOCK_DGRAM
73.It Dv SOCK_RAW
74.It Dv SOCK_SEQPACKET
75.El
76.Pp
77A
78.Dv SOCK_STREAM
79type provides sequenced, reliable,
80two-way connection based byte streams.
81An out-of-band data transmission mechanism may be supported.
82A
83.Dv SOCK_DGRAM
84socket supports
85datagrams (connectionless, unreliable messages of
86a fixed (typically small) maximum length).
87A
88.Dv SOCK_SEQPACKET
89socket may provide a sequenced, reliable,
90two-way connection-based data transmission path for datagrams
91of fixed maximum length; a consumer may be required to read
92an entire packet with each read system call.
93This facility is protocol specific, and presently implemented only for
94.Dv AF_UNIX .
95.Dv SOCK_RAW
96sockets provide access to internal network protocols and interfaces,
97and are available only to the superuser.
98.Pp
99Any combination of the following flags may additionally be used in the
100.Fa type
101argument:
102.Pp
103.Bl -tag -width "SOCK_NONBLOCKX" -offset indent -compact
104.It Dv SOCK_CLOEXEC
105Set close-on-exec flag on the new descriptor.
106.It Dv SOCK_CLOFORK
107Set close-on-fork flag on the new descriptor.
108.It Dv SOCK_NONBLOCK
109Set non-blocking I/O mode on the new socket.
110.It Dv SOCK_DNS
111For domains
112.Dv AF_INET
113or
114.Dv AF_INET6 ,
115only allow
116.Xr connect 2 ,
117.Xr sendto 2 ,
118or
119.Xr sendmsg 2
120to the DNS port (typically 53).
121.El
122.Pp
123The
124.Fa protocol
125specifies a particular protocol to be used with the socket.
126Normally only a single protocol exists to support a particular
127socket type within a given protocol family.
128However, it is possible that many protocols may exist,
129in which case a particular protocol must be specified in this manner.
130The protocol number to use is particular to the
131.Dq communication domain
132in which communication is to take place; see
133.Xr protocols 5 .
134A value of 0 for
135.Fa protocol
136will let the system select an appropriate protocol for the requested
137socket type.
138.Pp
139Sockets of type
140.Dv SOCK_STREAM
141are full-duplex byte streams.
142A stream socket must be in a
143.Em connected
144state before any data may be sent or received on it.
145A connection to another socket is created with a
146.Xr connect 2
147call.
148Once connected, data may be transferred using
149.Xr read 2
150and
151.Xr write 2
152calls or some variant of the
153.Xr send 2
154and
155.Xr recv 2
156calls.
157When a session has been completed, a
158.Xr close 2
159may be performed.
160Out-of-band data may also be transmitted as described in
161.Xr send 2
162and received as described in
163.Xr recv 2 .
164.Pp
165The communications protocols used to implement a
166.Dv SOCK_STREAM
167ensure that data is not lost or duplicated.
168If a piece of data for which the peer protocol has buffer space cannot
169be successfully transmitted within a reasonable length of time, then the
170connection is considered broken and calls will indicate an error with \-1
171returns and with
172.Er ETIMEDOUT
173as the specific code in the global variable
174.Va errno .
175The protocols optionally keep sockets
176.Dq warm
177by forcing transmissions roughly every minute in the absence of other activity.
178An error is then indicated if no response can be elicited on an otherwise
179idle connection for an extended period (e.g., 5 minutes).
180A
181.Dv SIGPIPE
182signal is raised if a process sends on a broken stream; this causes
183naive processes, which do not handle the signal, to exit.
184.Pp
185.Dv SOCK_SEQPACKET
186sockets employ the same system calls
187as
188.Dv SOCK_STREAM
189sockets.
190The only difference is that
191.Xr read 2
192calls will return only the amount of data requested,
193and any remaining in the arriving packet will be discarded.
194.Pp
195.Dv SOCK_DGRAM
196and
197.Dv SOCK_RAW
198sockets allow sending of datagrams to correspondents named in
199.Xr send 2
200calls.
201Datagrams are generally received with
202.Xr recvfrom 2 ,
203which returns the next datagram with its return address.
204.Pp
205An
206.Xr fcntl 2
207call can be used to specify a process group to receive
208a
209.Dv SIGURG
210signal when the out-of-band data arrives.
211It may also enable non-blocking I/O and asynchronous notification
212of I/O events via
213.Dv SIGIO .
214.Pp
215The operation of sockets is controlled by socket level
216.Em options .
217These options are defined in the file
218.In sys/socket.h .
219.Xr setsockopt 2
220and
221.Xr getsockopt 2
222are used to set and get options, respectively.
223.Sh RETURN VALUES
224If successful,
225.Fn socket
226returns a non-negative integer, the socket file descriptor.
227Otherwise, a value of \-1 is returned and
228.Va errno
229is set to indicate the error.
230.Sh ERRORS
231The
232.Fn socket
233call fails if:
234.Bl -tag -width Er
235.It Bq Er EAFNOSUPPORT
236The specified address family is not supported on this machine.
237.It Bq Er EPROTONOSUPPORT
238The protocol type or the specified protocol is not supported
239within this domain.
240.It Bq Er EPROTOTYPE
241The combination of the specified protocol and type is not supported.
242.It Bq Er EMFILE
243The per-process descriptor table is full.
244.It Bq Er ENFILE
245The system file table is full.
246.It Bq Er ENOBUFS
247Insufficient resources were available in the system
248to perform the operation.
249.It Bq Er EACCES
250Permission to create a socket of the specified type and/or protocol
251is denied.
252.El
253.Sh SEE ALSO
254.Xr accept 2 ,
255.Xr bind 2 ,
256.Xr connect 2 ,
257.Xr getsockname 2 ,
258.Xr getsockopt 2 ,
259.Xr ioctl 2 ,
260.Xr listen 2 ,
261.Xr poll 2 ,
262.Xr read 2 ,
263.Xr recv 2 ,
264.Xr select 2 ,
265.Xr send 2 ,
266.Xr setsockopt 2 ,
267.Xr shutdown 2 ,
268.Xr socketpair 2 ,
269.Xr write 2 ,
270.Xr getprotoent 3 ,
271.Xr inet 4 ,
272.Xr inet6 4 ,
273.Xr netintro 4 ,
274.Xr unix 4
275.Rs
276.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
277.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
278.Re
279.Rs
280.%T "BSD Interprocess Communication Tutorial"
281.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
282.Re
283.Sh STANDARDS
284The
285.Fn socket
286function conforms to
287.St -p1003.1-2024 .
288.Pp
289The
290.Dv SOCK_DNS
291flag is an
292.Ox
293extension.
294.Sh HISTORY
295The
296.Fn socket
297system call first appeared in
298.Bx 4.1c .
299Support for the
300.Dv SOCK_CLOEXEC
301and
302.Dv SOCK_NONBLOCK
303flags appeared in
304.Ox 5.7 .
305Support for the
306.Dv SOCK_DNS
307flag appeared in
308.Ox 5.9 .