jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: accept.2,v 1.31 2025/08/04 04:59:31 guenther Exp $
2.\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $
3.\"
4.\" Copyright (c) 1983, 1990, 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.\" @(#)accept.2 8.2 (Berkeley) 12/11/93
32.\"
33.Dd $Mdocdate: August 4 2025 $
34.Dt ACCEPT 2
35.Os
36.Sh NAME
37.Nm accept ,
38.Nm accept4
39.Nd accept a connection on a socket
40.Sh SYNOPSIS
41.In sys/socket.h
42.Ft int
43.Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
44.Ft int
45.Fn accept4 "int s" "struct sockaddr *addr" "socklen_t *addrlen" "int flags"
46.Sh DESCRIPTION
47The argument
48.Fa s
49is a socket that has been created with
50.Xr socket 2 ,
51bound to an address with
52.Xr bind 2 ,
53and is listening for connections after a
54.Xr listen 2 .
55The
56.Fn accept
57call extracts the first connection request on the queue of pending
58connections, creates a new socket with the same non-blocking I/O mode as
59.Fa s ,
60and allocates a new file descriptor for the socket with the
61close-on-exec and close-on-fork flags clear.
62.Pp
63The
64.Fn accept4
65system call is similar, however the non-blocking I/O mode,
66close-on-exec flag,
67and close-on-fork flag on the new file descriptor are
68determined by the
69.Dv SOCK_NONBLOCK , SOCK_CLOEXEC ,
70and
71.Dv SOCK_CLOFORK
72flags, respectively, in the
73.Fa flags
74argument.
75.Pp
76If no pending connections are present on the queue,
77and the socket is not marked as non-blocking,
78.Fn accept
79blocks the caller until a connection is present.
80If the socket is marked non-blocking and no pending
81connections are present on the queue,
82.Fn accept
83returns an error as described below.
84The accepted socket may not be used to accept more connections.
85The original socket
86.Fa s
87remains open.
88.Pp
89The argument
90.Fa addr
91is a result parameter that is filled in with the address of the connecting
92entity as known to the communications layer.
93The exact format of the
94.Fa addr
95parameter is determined by the domain in which the communication
96is occurring.
97The structure
98.Vt sockaddr_storage
99exists for greater portability.
100It is large enough to hold any of the types that may be returned in the
101.Fa addr
102parameter.
103.Pp
104The
105.Fa addrlen
106is a value-result parameter; it should initially contain the
107amount of space pointed to by
108.Fa addr ;
109on return it will contain the actual length (in bytes) of the
110address returned.
111If
112.Fa addrlen
113does not point to enough space to hold the entire socket address, the
114result will be truncated to the initial value of
115.Fa addrlen
116(in bytes).
117This call is used with connection-based socket types, currently with
118.Dv SOCK_STREAM .
119.Pp
120It is possible to
121.Xr select 2
122or
123.Xr poll 2
124a socket for the purposes of doing an
125.Fn accept
126by selecting it for read.
127.Sh RETURN VALUES
128If successful,
129.Fn accept
130and
131.Fn accept4
132return a non-negative integer, the accepted socket file descriptor.
133Otherwise, a value of \-1 is returned and
134.Va errno
135is set to indicate the error.
136.Sh EXAMPLES
137The following code uses struct
138.Vt sockaddr_storage
139to allocate enough space for the returned address:
140.Bd -literal -offset indent
141#include <sys/types.h>
142#include <sys/socket.h>
143
144struct sockaddr_storage addr;
145socklen_t len = sizeof(addr);
146int retcode;
147
148retcode = accept(s, (struct sockaddr *)&addr, &len);
149if (retcode == -1)
150 err(1, "accept");
151.Ed
152.Sh ERRORS
153.Fn accept
154and
155.Fn accept4
156will fail if:
157.Bl -tag -width Er
158.It Bq Er EBADF
159The descriptor is invalid.
160.It Bq Er ENOTSOCK
161The descriptor doesn't reference a socket.
162.It Bq Er EOPNOTSUPP
163The referenced socket is not of type
164.Dv SOCK_STREAM .
165.It Bq Er EINTR
166A signal was caught before a connection arrived.
167.It Bq Er EINVAL
168The referenced socket is not listening for connections (that is,
169.Xr listen 2
170has not yet been called).
171.It Bq Er EFAULT
172The
173.Fa addr
174or
175.Fa addrlen
176parameter is not in a valid part of the process address space.
177.It Bq Er EWOULDBLOCK
178The socket is marked non-blocking and no connections
179are present to be accepted.
180.It Bq Er EMFILE
181The per-process descriptor table is full.
182.It Bq Er ENFILE
183The system file table is full.
184.It Bq Er ECONNABORTED
185A connection has been aborted.
186.El
187.Pp
188In addition,
189.Fn accept4
190will fail if
191.Bl -tag -width Er
192.It Bq Er EINVAL
193.Fa flags
194is invalid.
195.El
196.Sh SEE ALSO
197.Xr bind 2 ,
198.Xr connect 2 ,
199.Xr listen 2 ,
200.Xr poll 2 ,
201.Xr select 2 ,
202.Xr socket 2
203.Sh STANDARDS
204The
205.Fn accept
206and
207.Fn accept4
208functions conform to
209.St -p1003.1-2024 .
210.Sh HISTORY
211The
212.Fn accept
213system call first appeared in
214.Bx 4.1c
215and
216.Fn accept4
217in
218.Ox 5.7 .
219.Sh CAVEATS
220When
221.Er EMFILE
222or
223.Er ENFILE
224is returned,
225new connections are neither dequeued nor discarded.
226Thus considerable care is required in
227.Xr select 2
228and
229.Xr poll 2
230loops.