man2/accept.2

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