| 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) |