Debian Codegraph @

upstream/debian-trixie/man2/accept.2

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