]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
7 | .\" Modified 1996-10-21 by Eric S. Raymond <esr@thyrsus.com> | |
8 | .\" Modified 1998-2000 by Andi Kleen to match Linux 2.2 reality | |
9 | .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch> | |
c11b1abf | 10 | .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
6f74cfbb | 11 | .\" 2008-12-04, mtk, Add documentation of accept4() |
fea681da | 12 | .\" |
45186a5d | 13 | .TH ACCEPT 2 2021-08-27 "Linux man-pages (unreleased)" |
fea681da | 14 | .SH NAME |
191a77d4 | 15 | accept, accept4 \- accept a connection on a socket |
974a5c3d AC |
16 | .SH LIBRARY |
17 | Standard C library | |
8fc3b2cf | 18 | .RI ( libc ", " \-lc ) |
fea681da | 19 | .SH SYNOPSIS |
6f74cfbb | 20 | .nf |
fea681da | 21 | .B #include <sys/socket.h> |
c63f06b5 | 22 | .PP |
e234eef0 AC |
23 | .BI "int accept(int " sockfd ", struct sockaddr *restrict " addr , |
24 | .BI " socklen_t *restrict " addrlen ); | |
eaa18d3c | 25 | .PP |
86b91fdf | 26 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
6f74cfbb | 27 | .B #include <sys/socket.h> |
c63f06b5 | 28 | .PP |
e234eef0 AC |
29 | .BI "int accept4(int " sockfd ", struct sockaddr *restrict " addr , |
30 | .BI " socklen_t *restrict " addrlen ", int " flags ); | |
6f74cfbb | 31 | .fi |
fea681da | 32 | .SH DESCRIPTION |
fea681da | 33 | The |
ae1a9ff4 MK |
34 | .BR accept () |
35 | system call is used with connection-based socket types | |
fea681da | 36 | .RB ( SOCK_STREAM , |
c51fc3c1 | 37 | .BR SOCK_SEQPACKET ). |
fea681da | 38 | It extracts the first connection request on the queue of pending |
00b7d497 MK |
39 | connections for the listening socket, |
40 | .IR sockfd , | |
41 | creates a new connected socket, and returns a new file | |
ae1a9ff4 MK |
42 | descriptor referring to that socket. |
43 | The newly created socket is not in the listening state. | |
fea681da | 44 | The original socket |
ae1a9ff4 MK |
45 | .I sockfd |
46 | is unaffected by this call. | |
fea681da MK |
47 | .PP |
48 | The argument | |
ae1a9ff4 | 49 | .I sockfd |
fea681da MK |
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). | |
c63f06b5 | 56 | .PP |
fea681da MK |
57 | The argument |
58 | .I addr | |
c13182ef | 59 | is a pointer to a |
ae1a9ff4 MK |
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 | |
fea681da | 65 | .I addr |
ae1a9ff4 | 66 | is determined by the socket's address family (see |
c13182ef | 67 | .BR socket (2) |
fea681da | 68 | and the respective protocol man pages). |
b98353f0 MK |
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. | |
c63f06b5 | 74 | .PP |
fea681da MK |
75 | The |
76 | .I addrlen | |
b98353f0 MK |
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 | |
fea681da | 80 | .IR addr ; |
b98353f0 | 81 | on return it will contain the actual size of the peer address. |
c63f06b5 | 82 | .PP |
b98353f0 MK |
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. | |
fea681da MK |
87 | .PP |
88 | If no pending | |
89 | connections are present on the queue, and the socket is not marked as | |
ff40dbb3 | 90 | nonblocking, |
ae1a9ff4 | 91 | .BR accept () |
c13182ef MK |
92 | blocks the caller until a connection is present. |
93 | If the socket is marked | |
ff40dbb3 | 94 | nonblocking and no pending connections are present on the queue, |
ae1a9ff4 | 95 | .BR accept () |
682edefb | 96 | fails with the error |
1ae6b2c7 | 97 | .B EAGAIN |
86426e0b MK |
98 | or |
99 | .BR EWOULDBLOCK . | |
fea681da MK |
100 | .PP |
101 | In order to be notified of incoming connections on a socket, you can use | |
cb1bcdf2 MK |
102 | .BR select (2), |
103 | .BR poll (2), | |
fea681da | 104 | or |
cb1bcdf2 | 105 | .BR epoll (7). |
fea681da MK |
106 | A readable event will be delivered when a new connection is attempted and you |
107 | may then call | |
ae1a9ff4 | 108 | .BR accept () |
c13182ef MK |
109 | to get a socket for that connection. |
110 | Alternatively, you can set the socket to deliver | |
fea681da MK |
111 | .B SIGIO |
112 | when activity occurs on a socket; see | |
113 | .BR socket (7) | |
114 | for details. | |
c63f06b5 | 115 | .PP |
6f74cfbb | 116 | If |
1ae6b2c7 | 117 | .I flags |
6f74cfbb MK |
118 | is 0, then |
119 | .BR accept4 () | |
120 | is the same as | |
121 | .BR accept (). | |
122 | The following values can be bitwise ORed in | |
1ae6b2c7 | 123 | .I flags |
6f74cfbb MK |
124 | to obtain different behavior: |
125 | .TP 16 | |
126 | .B SOCK_NONBLOCK | |
127 | Set the | |
1ae6b2c7 | 128 | .B O_NONBLOCK |
7f11e32c MK |
129 | file status flag on the open file description (see |
130 | .BR open (2)) | |
131 | referred to by the new file descriptor. | |
6f74cfbb MK |
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. | |
47297adb | 145 | .SH RETURN VALUE |
cca657e2 | 146 | On success, |
ed09120a MK |
147 | these system calls return a file descriptor |
148 | for the accepted socket (a nonnegative integer). | |
03349e33 | 149 | On error, \-1 is returned, |
cca657e2 | 150 | .I errno |
c112329f | 151 | is set to indicate the error, and |
03349e33 MK |
152 | .I addrlen |
153 | is left unchanged. | |
73d8cece | 154 | .SS Error handling |
c13182ef | 155 | Linux |
ae1a9ff4 | 156 | .BR accept () |
6f74cfbb MK |
157 | (and |
158 | .BR accept4 ()) | |
c13182ef MK |
159 | passes already-pending network errors on the new socket |
160 | as an error code from | |
161 | .BR accept (). | |
d9bfdb9c | 162 | This behavior differs from other BSD socket |
c13182ef MK |
163 | implementations. |
164 | For reliable operation the application should detect | |
165 | the network errors defined for the protocol after | |
ae1a9ff4 | 166 | .BR accept () |
fea681da | 167 | and treat |
c13182ef | 168 | them like |
0daa9e92 | 169 | .B EAGAIN |
c13182ef | 170 | by retrying. |
2dd7f4cb | 171 | In the case of TCP/IP, these are |
fea681da MK |
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 | |
fea681da MK |
182 | .TP |
183 | .BR EAGAIN " or " EWOULDBLOCK | |
86426e0b | 184 | .\" Actually EAGAIN on Linux |
ff40dbb3 | 185 | The socket is marked nonblocking and no connections are |
fea681da | 186 | present to be accepted. |
fe472573 MK |
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, | |
86426e0b | 190 | so a portable application should check for both possibilities. |
fea681da MK |
191 | .TP |
192 | .B EBADF | |
3ad77694 MK |
193 | .I sockfd |
194 | is not an open file descriptor. | |
fea681da MK |
195 | .TP |
196 | .B ECONNABORTED | |
197 | A connection has been aborted. | |
198 | .TP | |
fecaa19a MK |
199 | .B EFAULT |
200 | The | |
201 | .I addr | |
202 | argument is not in a writable part of the user address space. | |
203 | .TP | |
fea681da MK |
204 | .B EINTR |
205 | The system call was interrupted by a signal that was caught | |
01538d0d MK |
206 | before a valid connection arrived; see |
207 | .BR signal (7). | |
fea681da MK |
208 | .TP |
209 | .B EINVAL | |
16c892d3 MK |
210 | Socket is not listening for connections, or |
211 | .I addrlen | |
212 | is invalid (e.g., is negative). | |
fea681da | 213 | .TP |
6f74cfbb MK |
214 | .B EINVAL |
215 | .RB ( accept4 ()) | |
216 | invalid value in | |
217 | .IR flags . | |
218 | .TP | |
fea681da | 219 | .B EMFILE |
26c32fab | 220 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
221 | .TP |
222 | .B ENFILE | |
e258766b | 223 | The system-wide limit on the total number of open files has been reached. |
fea681da | 224 | .TP |
fecaa19a MK |
225 | .BR ENOBUFS ", " ENOMEM |
226 | Not enough free memory. | |
227 | This often means that the memory allocation is limited by the socket buffer | |
228 | limits, not by the system memory. | |
229 | .TP | |
fea681da | 230 | .B ENOTSOCK |
deedfd97 MK |
231 | The file descriptor |
232 | .I sockfd | |
233 | does not refer to a socket. | |
fea681da MK |
234 | .TP |
235 | .B EOPNOTSUPP | |
236 | The referenced socket is not of type | |
c13182ef | 237 | .BR SOCK_STREAM . |
fea681da | 238 | .TP |
fea681da MK |
239 | .B EPERM |
240 | Firewall rules forbid connection. | |
18ce9c4a MK |
241 | .TP |
242 | .B EPROTO | |
243 | Protocol error. | |
fea681da MK |
244 | .PP |
245 | In addition, network errors for the new socket and as defined | |
c13182ef MK |
246 | for the protocol may be returned. |
247 | Various Linux kernels can | |
fea681da MK |
248 | return other errors such as |
249 | .BR ENOSR , | |
250 | .BR ESOCKTNOSUPPORT , | |
251 | .BR EPROTONOSUPPORT , | |
252 | .BR ETIMEDOUT . | |
253 | The value | |
254 | .B ERESTARTSYS | |
255 | may be seen during a trace. | |
6f74cfbb | 256 | .SH VERSIONS |
6f74cfbb MK |
257 | The |
258 | .BR accept4 () | |
259 | system call is available starting with Linux 2.6.28; | |
260 | support in glibc is available starting with version 2.10. | |
3113c7f3 | 261 | .SH STANDARDS |
6f74cfbb | 262 | .BR accept (): |
9db8624b | 263 | POSIX.1-2001, POSIX.1-2008, |
2d7dbb05 | 264 | SVr4, 4.4BSD |
ae1a9ff4 | 265 | .RB ( accept () |
6f74cfbb | 266 | first appeared in 4.2BSD). |
9d9dc1e8 MK |
267 | .\" The BSD man page documents five possible error returns |
268 | .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). | |
c13182ef | 269 | .\" POSIX.1-2001 documents errors |
9d9dc1e8 | 270 | .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, |
c13182ef | 271 | .\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. |
9d9dc1e8 | 272 | .\" In addition, SUSv2 documents EFAULT and ENOSR. |
c63f06b5 | 273 | .PP |
6f74cfbb | 274 | .BR accept4 () |
c8f2dd47 | 275 | is a nonstandard Linux extension. |
c63f06b5 | 276 | .PP |
ae1a9ff4 | 277 | On Linux, the new socket returned by |
c13182ef | 278 | .BR accept () |
ae1a9ff4 | 279 | does \fInot\fP inherit file status flags such as |
0daa9e92 | 280 | .B O_NONBLOCK |
ae1a9ff4 | 281 | and |
0daa9e92 | 282 | .B O_ASYNC |
ae1a9ff4 | 283 | from the listening socket. |
d9bfdb9c | 284 | This behavior differs from the canonical BSD sockets implementation. |
ae1a9ff4 MK |
285 | .\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also |
286 | .\" do not inherit file status flags -- MTK Jun 05 | |
24b74457 | 287 | Portable programs should not rely on inheritance or noninheritance |
c13182ef MK |
288 | of file status flags and always explicitly set all required flags on |
289 | the socket returned from | |
ae1a9ff4 | 290 | .BR accept (). |
19c98696 | 291 | .SH NOTES |
a1d5f77c MK |
292 | There may not always be a connection waiting after a |
293 | .B SIGIO | |
294 | is delivered or | |
cb1bcdf2 MK |
295 | .BR select (2), |
296 | .BR poll (2), | |
a1d5f77c | 297 | or |
cb1bcdf2 | 298 | .BR epoll (7) |
a1d5f77c MK |
299 | return a readability event because the connection might have been |
300 | removed by an asynchronous network error or another thread before | |
301 | .BR accept () | |
302 | is called. | |
f14ae16e | 303 | If this happens, then the call will block waiting for the next |
a1d5f77c MK |
304 | connection to arrive. |
305 | To ensure that | |
306 | .BR accept () | |
307 | never blocks, the passed socket | |
308 | .I sockfd | |
309 | needs to have the | |
310 | .B O_NONBLOCK | |
311 | flag set (see | |
312 | .BR socket (7)). | |
c63f06b5 | 313 | .PP |
ccdf8bc0 | 314 | For certain protocols which require an explicit confirmation, |
4529738e | 315 | such as DECnet, |
ccdf8bc0 MK |
316 | .BR accept () |
317 | can be thought of as merely dequeuing the next connection request and not | |
318 | implying confirmation. | |
319 | Confirmation can be implied by | |
320 | a normal read or write on the new file descriptor, and rejection can be | |
321 | implied by closing the new socket. | |
4529738e | 322 | Currently, only DECnet has these semantics on Linux. |
ccdf8bc0 | 323 | .\" |
a1d5f77c | 324 | .SS The socklen_t type |
a05774c4 MK |
325 | In the original BSD sockets implementation (and on other older systems) |
326 | .\" such as Linux libc4 and libc5, SunOS 4, SGI | |
327 | the third argument of | |
ae1a9ff4 | 328 | .BR accept () |
a05774c4 MK |
329 | was declared as an \fIint\ *\fP. |
330 | A POSIX.1g draft | |
331 | standard wanted to change it into a \fIsize_t\ *\fPC; | |
332 | .\" SunOS 5 has 'size_t *' | |
333 | later POSIX standards and glibc 2.x have | |
9d66d927 | 334 | .IR "socklen_t\ * ". |
a14af333 | 335 | .SH EXAMPLES |
f11e5e44 MK |
336 | See |
337 | .BR bind (2). | |
47297adb | 338 | .SH SEE ALSO |
fea681da MK |
339 | .BR bind (2), |
340 | .BR connect (2), | |
341 | .BR listen (2), | |
342 | .BR select (2), | |
5dfedcae MK |
343 | .BR socket (2), |
344 | .BR socket (7) |