Debian Codegraph @

upstream/debian-unstable/man2/accept.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH accept 2 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 accept, accept4 \- accept a connection on a socket
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr ,
17 .BI " socklen_t *_Nullable restrict " addrlen );
18 .P
19 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
20 .B #include <sys/socket.h>
21 .P
22 .BI "int accept4(int " sockfd ", struct sockaddr *_Nullable restrict " addr ,
23 .BI " socklen_t *_Nullable restrict " addrlen ", int " flags );
24 .fi
25 .SH DESCRIPTION
26 The
27 .BR accept ()
28 system call is used with connection-based socket types
29 .RB ( SOCK_STREAM ,
30 .BR SOCK_SEQPACKET ).
31 It extracts the first connection request on the queue of pending
32 connections for the listening socket,
33 .IR sockfd ,
34 creates a new connected socket, and returns a new file
35 descriptor referring to that socket.
36 The newly created socket is not in the listening state.
37 The original socket
38 .I sockfd
39 is unaffected by this call.
40 .P
41 The argument
42 .I sockfd
43 is a socket that has been created with
44 .BR socket (2),
45 bound to a local address with
46 .BR bind (2),
47 and is listening for connections after a
48 .BR listen (2).
49 .P
50 The argument
51 .I addr
52 is a pointer to a
53 .I sockaddr
54 structure.
55 This structure is filled in with the address of the peer socket,
56 as known to the communications layer.
57 The exact format of the address returned
58 .I addr
59 is determined by the socket's address family (see
60 .BR socket (2)
61 and the respective protocol man pages).
62 When
63 .I addr
64 is NULL, nothing is filled in;
65 in this case,
66 .I addrlen
67 is not used, and should also be NULL.
68 .P
69 The
70 .I addrlen
71 argument is a value-result argument:
72 the caller must initialize it to contain the
73 size (in bytes) of the structure pointed to by
74 .IR addr ;
75 on return it will contain the actual size of the peer address.
76 .P
77 The returned address is truncated if the buffer provided is too small;
78 in this case,
79 .I addrlen
80 will return a value greater than was supplied to the call.
81 .P
82 If no pending
83 connections are present on the queue, and the socket is not marked as
84 nonblocking,
85 .BR accept ()
86 blocks the caller until a connection is present.
87 If the socket is marked
88 nonblocking and no pending connections are present on the queue,
89 .BR accept ()
90 fails with the error
91 .B EAGAIN
92 or
93 .BR EWOULDBLOCK .
94 .P
95 In order to be notified of incoming connections on a socket, you can use
96 .BR select (2),
97 .BR poll (2),
98 or
99 .BR epoll (7).
100 A readable event will be delivered when a new connection is attempted and you
101 may then call
102 .BR accept ()
103 to get a socket for that connection.
104 Alternatively, you can set the socket to deliver
105 .B SIGIO
106 when activity occurs on a socket;
107 see
108 .BR socket (7)
109 for details.
110 .P
111 If
112 .I flags
113 is 0, then
114 .BR accept4 ()
115 is the same as
116 .BR accept ().
117 The following values can be bitwise ORed in
118 .I flags
119 to obtain different behavior:
120 .TP 16
121 .B SOCK_NONBLOCK
122 Set the
123 .B O_NONBLOCK
124 file status flag on the open file description (see
125 .BR open (2))
126 referred to by the new file descriptor.
127 Using this flag saves extra calls to
128 .BR fcntl (2)
129 to achieve the same result.
130 .TP
131 .B SOCK_CLOEXEC
132 Set the close-on-exec
133 .RB ( FD_CLOEXEC )
134 flag on the new file descriptor.
135 See the description of the
136 .B O_CLOEXEC
137 flag in
138 .BR open (2)
139 for reasons why this may be useful.
140 .SH RETURN VALUE
141 On success,
142 these system calls return a file descriptor
143 for the accepted socket (a nonnegative integer).
144 On error, \-1 is returned,
145 .I errno
146 is set to indicate the error, and
147 .I addrlen
148 is left unchanged.
149 .SS Error handling
150 Linux
151 .BR accept ()
152 (and
153 .BR accept4 ())
154 passes already-pending network errors on the new socket
155 as an error code from
156 .BR accept ().
157 This behavior differs from other BSD socket
158 implementations.
159 For reliable operation the application should detect
160 the network errors defined for the protocol after
161 .BR accept ()
162 and treat
163 them like
164 .B EAGAIN
165 by retrying.
166 In the case of TCP/IP, these are
167 .BR ENETDOWN ,
168 .BR EPROTO ,
169 .BR ENOPROTOOPT ,
170 .BR EHOSTDOWN ,
171 .BR ENONET ,
172 .BR EHOSTUNREACH ,
173 .BR EOPNOTSUPP ,
174 and
175 .BR ENETUNREACH .
176 .SH ERRORS
177 .TP
178 .BR EAGAIN " or " EWOULDBLOCK
179 .\" Actually EAGAIN on Linux
180 The socket is marked nonblocking and no connections are
181 present to be accepted.
182 POSIX.1-2001 and POSIX.1-2008
183 allow either error to be returned for this case,
184 and do not require these constants to have the same value,
185 so a portable application should check for both possibilities.
186 .TP
187 .B EBADF
188 .I sockfd
189 is not an open file descriptor.
190 .TP
191 .B ECONNABORTED
192 A connection has been aborted.
193 .TP
194 .B EFAULT
195 The
196 .I addr
197 argument is not in a writable part of the user address space.
198 .TP
199 .B EINTR
200 The system call was interrupted by a signal that was caught
201 before a valid connection arrived;
202 see
203 .BR signal (7).
204 .TP
205 .B EINVAL
206 Socket is not listening for connections, or
207 .I addrlen
208 is invalid (e.g., is negative).
209 .TP
210 .B EINVAL
211 .RB ( accept4 ())
212 invalid value in
213 .IR flags .
214 .TP
215 .B EMFILE
216 The per-process limit on the number of open file descriptors has been reached.
217 .TP
218 .B ENFILE
219 The system-wide limit on the total number of open files has been reached.
220 .TP
221 .B ENOBUFS
222 .TQ
223 .B ENOMEM
224 Not enough free memory.
225 This often means that the memory allocation is limited by the socket buffer
226 limits, not by the system memory.
227 .TP
228 .B ENOTSOCK
229 The file descriptor
230 .I sockfd
231 does not refer to a socket.
232 .TP
233 .B EOPNOTSUPP
234 The referenced socket is not of type
235 .BR SOCK_STREAM .
236 .TP
237 .B EPERM
238 Firewall rules forbid connection.
239 .TP
240 .B EPROTO
241 Protocol error.
242 .P
243 In addition, network errors for the new socket and as defined
244 for the protocol may be returned.
245 Various Linux kernels can
246 return other errors such as
247 .BR ENOSR ,
248 .BR ESOCKTNOSUPPORT ,
249 .BR EPROTONOSUPPORT ,
250 .BR ETIMEDOUT .
251 The value
252 .B ERESTARTSYS
253 may be seen during a trace.
254 .SH VERSIONS
255 On Linux, the new socket returned by
256 .BR accept ()
257 does
258 .I not
259 inherit file status flags such as
260 .B O_NONBLOCK
261 and
262 .B O_ASYNC
263 from the listening socket.
264 This behavior differs from the canonical BSD sockets implementation.
265 .\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also
266 .\" do not inherit file status flags -- MTK Jun 05
267 Portable programs should not rely on inheritance or noninheritance
268 of file status flags and always explicitly set all required flags on
269 the socket returned from
270 .BR accept ().
271 .SH STANDARDS
272 POSIX.1-2024.
273 .SH HISTORY
274 .TP
275 .BR accept ()
276 POSIX.1-2001, SVr4, 4.4BSD
277 .RB ( accept ()
278 first appeared in 4.2BSD).
279 .\" The BSD man page documents five possible error returns
280 .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT).
281 .\" POSIX.1-2001 documents errors
282 .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE,
283 .\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK.
284 .\" In addition, SUSv2 documents EFAULT and ENOSR.
285 .TP
286 .BR accept4 ()
287 POSIX.1-2024.
288 Linux 2.6.28,
289 glibc 2.10.
290 .SH NOTES
291 There may not always be a connection waiting after a
292 .B SIGIO
293 is delivered or
294 .BR select (2),
295 .BR poll (2),
296 or
297 .BR epoll (7)
298 return a readability event because the connection might have been
299 removed by an asynchronous network error or another thread before
300 .BR accept ()
301 is called.
302 If this happens, then the call will block waiting for the next
303 connection to arrive.
304 To ensure that
305 .BR accept ()
306 never blocks, the passed socket
307 .I sockfd
308 needs to have the
309 .B O_NONBLOCK
310 flag set (see
311 .BR socket (7)).
312 .P
313 For certain protocols which require an explicit confirmation,
314 such as DECnet,
315 .BR accept ()
316 can be thought of as merely dequeuing the next connection request and not
317 implying confirmation.
318 Confirmation can be implied by
319 a normal read or write on the new file descriptor, and rejection can be
320 implied by closing the new socket.
321 Currently, only DECnet has these semantics on Linux.
322 .\"
323 .SS The socklen_t type
324 In the original BSD sockets implementation (and on other older systems)
325 .\" such as Linux libc4 and libc5, SunOS 4, SGI
326 the third argument of
327 .BR accept ()
328 was declared as an
329 .IR "int\ *" .
330 A POSIX.1g draft
331 standard wanted to change it into a
332 .IR "size_t\ *" ;
333 .\" SunOS 5 has 'size_t *'
334 later POSIX standards and glibc 2.x have
335 .IR "socklen_t\ * ".
336 .SH EXAMPLES
337 See
338 .BR bind (2).
339 .SH SEE ALSO
340 .BR bind (2),
341 .BR connect (2),
342 .BR listen (2),
343 .BR select (2),
344 .BR socket (2),
345 .BR socket (7)