man2/accept.2

   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 <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>
  10 .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  11 .\" 2008-12-04, mtk, Add documentation of accept4()
  12 .\"
  13 .TH ACCEPT 2 2022-09-09 "Linux man-pages (unreleased)"
  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 .PP
  23 .BI "int accept(int " sockfd ", struct sockaddr *restrict " addr ,
  24 .BI "           socklen_t *restrict " addrlen );
  25 .PP
  26 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  27 .B #include <sys/socket.h>
  28 .PP
  29 .BI "int accept4(int " sockfd ", struct sockaddr *restrict " addr ,
  30 .BI "           socklen_t *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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
 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 .PP
 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 .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
 230 .B ENOTSOCK
 231 The file descriptor
 232 .I sockfd
 233 does not refer to a socket.
 234 .TP
 235 .B EOPNOTSUPP
 236 The referenced socket is not of type
 237 .BR SOCK_STREAM .
 238 .TP
 239 .B EPERM
 240 Firewall rules forbid connection.
 241 .TP
 242 .B EPROTO
 243 Protocol error.
 244 .PP
 245 In addition, network errors for the new socket and as defined
 246 for the protocol may be returned.
 247 Various Linux kernels can
 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.
 256 .SH VERSIONS
 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.
 261 .SH STANDARDS
 262 .BR accept ():
 263 POSIX.1-2001, POSIX.1-2008,
 264 SVr4, 4.4BSD
 265 .RB ( accept ()
 266 first appeared in 4.2BSD).
 267 .\" The BSD man page documents five possible error returns
 268 .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT).
 269 .\" POSIX.1-2001 documents errors
 270 .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE,
 271 .\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK.
 272 .\" In addition, SUSv2 documents EFAULT and ENOSR.
 273 .PP
 274 .BR accept4 ()
 275 is a nonstandard Linux extension.
 276 .PP
 277 On Linux, the new socket returned by
 278 .BR accept ()
 279 does \fInot\fP inherit file status flags such as
 280 .B O_NONBLOCK
 281 and
 282 .B O_ASYNC
 283 from the listening socket.
 284 This behavior differs from the canonical BSD sockets implementation.
 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
 287 Portable programs should not rely on inheritance or noninheritance
 288 of file status flags and always explicitly set all required flags on
 289 the socket returned from
 290 .BR accept ().
 291 .SH NOTES
 292 There may not always be a connection waiting after a
 293 .B SIGIO
 294 is delivered or
 295 .BR select (2),
 296 .BR poll (2),
 297 or
 298 .BR epoll (7)
 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.
 303 If this happens, then the call will block waiting for the next
 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)).
 313 .PP
 314 For certain protocols which require an explicit confirmation,
 315 such as DECnet,
 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.
 322 Currently, only DECnet has these semantics on Linux.
 323 .\"
 324 .SS The socklen_t type
 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
 328 .BR accept ()
 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
 334 .IR "socklen_t\ * ".
 335 .SH EXAMPLES
 336 See
 337 .BR bind (2).
 338 .SH SEE ALSO
 339 .BR bind (2),
 340 .BR connect (2),
 341 .BR listen (2),
 342 .BR select (2),
 343 .BR socket (2),
 344 .BR socket (7)