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 2016-10-08 "Linux" "Linux Programmer's Manual"
  42 .SH NAME
  43 accept, accept4 \- accept a connection on a socket
  44 .SH SYNOPSIS
  45 .nf
  46 .BR "#include <sys/types.h>" "          /* See NOTES */"
  47 .B #include <sys/socket.h>
  48
  49 .BI "int accept(int " sockfd ", struct sockaddr *" addr ", socklen_t *" addrlen );
  50
  51 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  52 .B #include <sys/socket.h>
  53
  54 .BI "int accept4(int " sockfd ", struct sockaddr *" addr ,
  55 .BI "            socklen_t *" 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
  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
 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
 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
 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 new open file description.
 155 Using this flag saves extra calls to
 156 .BR fcntl (2)
 157 to achieve the same result.
 158 .TP
 159 .B SOCK_CLOEXEC
 160 Set the close-on-exec
 161 .RB ( FD_CLOEXEC )
 162 flag on the new file descriptor.
 163 See the description of the
 164 .B O_CLOEXEC
 165 flag in
 166 .BR open (2)
 167 for reasons why this may be useful.
 168 .SH RETURN VALUE
 169 On success,
 170 these system calls return a nonnegative integer that is a file descriptor
 171 for the accepted socket.
 172 On error, \-1 is returned, and
 173 .I errno
 174 is set appropriately.
 175 .SS Error handling
 176 Linux
 177 .BR accept ()
 178 (and
 179 .BR accept4 ())
 180 passes already-pending network errors on the new socket
 181 as an error code from
 182 .BR accept ().
 183 This behavior differs from other BSD socket
 184 implementations.
 185 For reliable operation the application should detect
 186 the network errors defined for the protocol after
 187 .BR accept ()
 188 and treat
 189 them like
 190 .B EAGAIN
 191 by retrying.
 192 In the case of TCP/IP, these are
 193 .BR ENETDOWN ,
 194 .BR EPROTO ,
 195 .BR ENOPROTOOPT ,
 196 .BR EHOSTDOWN ,
 197 .BR ENONET ,
 198 .BR EHOSTUNREACH ,
 199 .BR EOPNOTSUPP ,
 200 and
 201 .BR ENETUNREACH .
 202 .SH ERRORS
 203 .TP
 204 .BR EAGAIN " or " EWOULDBLOCK
 205 .\" Actually EAGAIN on Linux
 206 The socket is marked nonblocking and no connections are
 207 present to be accepted.
 208 POSIX.1-2001 and POSIX.1-2008
 209 allow either error to be returned for this case,
 210 and do not require these constants to have the same value,
 211 so a portable application should check for both possibilities.
 212 .TP
 213 .B EBADF
 214 .I sockfd
 215 is not an open file descriptor.
 216 .TP
 217 .B ECONNABORTED
 218 A connection has been aborted.
 219 .TP
 220 .B EFAULT
 221 The
 222 .I addr
 223 argument is not in a writable part of the user address space.
 224 .TP
 225 .B EINTR
 226 The system call was interrupted by a signal that was caught
 227 before a valid connection arrived; see
 228 .BR signal (7).
 229 .TP
 230 .B EINVAL
 231 Socket is not listening for connections, or
 232 .I addrlen
 233 is invalid (e.g., is negative).
 234 .TP
 235 .B EINVAL
 236 .RB ( accept4 ())
 237 invalid value in
 238 .IR flags .
 239 .TP
 240 .B EMFILE
 241 The per-process limit on the number of open file descriptors has been reached.
 242 .TP
 243 .B ENFILE
 244 The system-wide limit on the total number of open files has been reached.
 245 .TP
 246 .BR ENOBUFS ", " ENOMEM
 247 Not enough free memory.
 248 This often means that the memory allocation is limited by the socket buffer
 249 limits, not by the system memory.
 250 .TP
 251 .B ENOTSOCK
 252 The file descriptor
 253 .I sockfd
 254 does not refer to a socket.
 255 .TP
 256 .B EOPNOTSUPP
 257 The referenced socket is not of type
 258 .BR SOCK_STREAM .
 259 .TP
 260 .B EPROTO
 261 Protocol error.
 262 .PP
 263 In addition, Linux
 264 .BR accept ()
 265 may fail if:
 266 .TP
 267 .B EPERM
 268 Firewall rules forbid connection.
 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
 299 .BR accept4 ()
 300 is a nonstandard Linux extension.
 301 .LP
 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 POSIX.1-2001 does not require the inclusion of
 318 .IR <sys/types.h> ,
 319 and this header file is not required on Linux.
 320 However, some historical (BSD) implementations required this header
 321 file, and portable applications are probably wise to include it.
 322
 323 There may not always be a connection waiting after a
 324 .B SIGIO
 325 is delivered or
 326 .BR select (2),
 327 .BR poll (2),
 328 or
 329 .BR epoll (7)
 330 return a readability event because the connection might have been
 331 removed by an asynchronous network error or another thread before
 332 .BR accept ()
 333 is called.
 334 If this happens, then the call will block waiting for the next
 335 connection to arrive.
 336 To ensure that
 337 .BR accept ()
 338 never blocks, the passed socket
 339 .I sockfd
 340 needs to have the
 341 .B O_NONBLOCK
 342 flag set (see
 343 .BR socket (7)).
 344
 345 For certain protocols which require an explicit confirmation,
 346 such as DECnet,
 347 .BR accept ()
 348 can be thought of as merely dequeuing the next connection request and not
 349 implying confirmation.
 350 Confirmation can be implied by
 351 a normal read or write on the new file descriptor, and rejection can be
 352 implied by closing the new socket.
 353 Currently, only DECnet has these semantics on Linux.
 354 .\"
 355 .SS The socklen_t type
 356 In the original BSD sockets implementation (and on other older systems)
 357 .\" such as Linux libc4 and libc5, SunOS 4, SGI
 358 the third argument of
 359 .BR accept ()
 360 was declared as an \fIint\ *\fP.
 361 A POSIX.1g draft
 362 standard wanted to change it into a \fIsize_t\ *\fPC;
 363 .\" SunOS 5 has 'size_t *'
 364 later POSIX standards and glibc 2.x have
 365 .IR "socklen_t\ * ".
 366 .SH EXAMPLE
 367 See
 368 .BR bind (2).
 369 .SH SEE ALSO
 370 .BR bind (2),
 371 .BR connect (2),
 372 .BR listen (2),
 373 .BR select (2),
 374 .BR socket (2),
 375 .BR socket (7)