original/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 2010-09-10 "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 or
 129 .BR poll (2).
 130 A readable event will be delivered when a new connection is attempted and you
 131 may then call
 132 .BR accept ()
 133 to get a socket for that connection.
 134 Alternatively, you can set the socket to deliver
 135 .B SIGIO
 136 when activity occurs on a socket; see
 137 .BR socket (7)
 138 for details.
 139 .PP
 140 For certain protocols which require an explicit confirmation,
 141 such as
 142 DECNet,
 143 .BR accept ()
 144 can be thought of as merely dequeuing the next connection request and not
 145 implying confirmation.
 146 Confirmation can be implied by
 147 a normal read or write on the new file descriptor, and rejection can be
 148 implied by closing the new socket.
 149 Currently only
 150 DECNet
 151 has these semantics on Linux.
 152
 153 If
 154 .IR flags
 155 is 0, then
 156 .BR accept4 ()
 157 is the same as
 158 .BR accept ().
 159 The following values can be bitwise ORed in
 160 .IR flags
 161 to obtain different behavior:
 162 .TP 16
 163 .B SOCK_NONBLOCK
 164 Set the
 165 .BR O_NONBLOCK
 166 file status flag on the new open file description.
 167 Using this flag saves extra calls to
 168 .BR fcntl (2)
 169 to achieve the same result.
 170 .TP
 171 .B SOCK_CLOEXEC
 172 Set the close-on-exec
 173 .RB ( FD_CLOEXEC )
 174 flag on the new file descriptor.
 175 See the description of the
 176 .B O_CLOEXEC
 177 flag in
 178 .BR open (2)
 179 for reasons why this may be useful.
 180 .SH RETURN VALUE
 181 On success,
 182 these system calls return a nonnegative integer that is a descriptor
 183 for the accepted socket.
 184 On error, \-1 is returned, and
 185 .I errno
 186 is set appropriately.
 187 .SS Error handling
 188 Linux
 189 .BR accept ()
 190 (and
 191 .BR accept4 ())
 192 passes already-pending network errors on the new socket
 193 as an error code from
 194 .BR accept ().
 195 This behavior differs from other BSD socket
 196 implementations.
 197 For reliable operation the application should detect
 198 the network errors defined for the protocol after
 199 .BR accept ()
 200 and treat
 201 them like
 202 .B EAGAIN
 203 by retrying.
 204 In the case of TCP/IP, these are
 205 .BR ENETDOWN ,
 206 .BR EPROTO ,
 207 .BR ENOPROTOOPT ,
 208 .BR EHOSTDOWN ,
 209 .BR ENONET ,
 210 .BR EHOSTUNREACH ,
 211 .BR EOPNOTSUPP ,
 212 and
 213 .BR ENETUNREACH .
 214 .SH ERRORS
 215 .TP
 216 .BR EAGAIN " or " EWOULDBLOCK
 217 .\" Actually EAGAIN on Linux
 218 The socket is marked nonblocking and no connections are
 219 present to be accepted.
 220 POSIX.1-2001 allows either error to be returned for this case,
 221 and does not require these constants to have the same value,
 222 so a portable application should check for both possibilities.
 223 .TP
 224 .B EBADF
 225 The descriptor is invalid.
 226 .TP
 227 .B ECONNABORTED
 228 A connection has been aborted.
 229 .TP
 230 .B EFAULT
 231 The
 232 .I addr
 233 argument is not in a writable part of the user address space.
 234 .TP
 235 .B EINTR
 236 The system call was interrupted by a signal that was caught
 237 before a valid connection arrived; see
 238 .BR signal (7).
 239 .TP
 240 .B EINVAL
 241 Socket is not listening for connections, or
 242 .I addrlen
 243 is invalid (e.g., is negative).
 244 .TP
 245 .B EINVAL
 246 .RB ( accept4 ())
 247 invalid value in
 248 .IR flags .
 249 .TP
 250 .B EMFILE
 251 The per-process limit of open file descriptors has been reached.
 252 .TP
 253 .B ENFILE
 254 The system limit on the total number of open files has been reached.
 255 .TP
 256 .BR ENOBUFS ", " ENOMEM
 257 Not enough free memory.
 258 This often means that the memory allocation is limited by the socket buffer
 259 limits, not by the system memory.
 260 .TP
 261 .B ENOTSOCK
 262 The descriptor references a file, not a socket.
 263 .TP
 264 .B EOPNOTSUPP
 265 The referenced socket is not of type
 266 .BR SOCK_STREAM .
 267 .TP
 268 .B EPROTO
 269 Protocol error.
 270 .PP
 271 In addition, Linux
 272 .BR accept ()
 273 may fail if:
 274 .TP
 275 .B EPERM
 276 Firewall rules forbid connection.
 277 .PP
 278 In addition, network errors for the new socket and as defined
 279 for the protocol may be returned.
 280 Various Linux kernels can
 281 return other errors such as
 282 .BR ENOSR ,
 283 .BR ESOCKTNOSUPPORT ,
 284 .BR EPROTONOSUPPORT ,
 285 .BR ETIMEDOUT .
 286 The value
 287 .B ERESTARTSYS
 288 may be seen during a trace.
 289 .SH VERSIONS
 290 The
 291 .BR accept4 ()
 292 system call is available starting with Linux 2.6.28;
 293 support in glibc is available starting with version 2.10.
 294 .SH CONFORMING TO
 295 .BR accept ():
 296 POSIX.1-2001,
 297 SVr4, 4.4BSD,
 298 .RB ( accept ()
 299 first appeared in 4.2BSD).
 300 .\" The BSD man page documents five possible error returns
 301 .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT).
 302 .\" POSIX.1-2001 documents errors
 303 .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE,
 304 .\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK.
 305 .\" In addition, SUSv2 documents EFAULT and ENOSR.
 306
 307 .BR accept4 ()
 308 is a nonstandard Linux extension.
 309 .LP
 310 On Linux, the new socket returned by
 311 .BR accept ()
 312 does \fInot\fP inherit file status flags such as
 313 .B O_NONBLOCK
 314 and
 315 .B O_ASYNC
 316 from the listening socket.
 317 This behavior differs from the canonical BSD sockets implementation.
 318 .\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also
 319 .\" do not inherit file status flags -- MTK Jun 05
 320 Portable programs should not rely on inheritance or noninheritance
 321 of file status flags and always explicitly set all required flags on
 322 the socket returned from
 323 .BR accept ().
 324 .SH NOTES
 325 POSIX.1-2001 does not require the inclusion of
 326 .IR <sys/types.h> ,
 327 and this header file is not required on Linux.
 328 However, some historical (BSD) implementations required this header
 329 file, and portable applications are probably wise to include it.
 330
 331 There may not always be a connection waiting after a
 332 .B SIGIO
 333 is delivered or
 334 .BR select (2)
 335 or
 336 .BR poll (2)
 337 return a readability event because the connection might have been
 338 removed by an asynchronous network error or another thread before
 339 .BR accept ()
 340 is called.
 341 If this happens, then the call will block waiting for the next
 342 connection to arrive.
 343 To ensure that
 344 .BR accept ()
 345 never blocks, the passed socket
 346 .I sockfd
 347 needs to have the
 348 .B O_NONBLOCK
 349 flag set (see
 350 .BR socket (7)).
 351 .SS The socklen_t type
 352 The third argument of
 353 .BR accept ()
 354 was originally declared as an \fIint *\fP (and is that under libc4 and libc5
 355 and on many other systems like 4.x BSD, SunOS 4, SGI); a POSIX.1g draft
 356 standard wanted to change it into a \fIsize_t *\fP, and that is what it is
 357 for SunOS 5.
 358 Later POSIX drafts have \fIsocklen_t *\fP,
 359 and so do the Single UNIX Specification and glibc2.
 360 Quoting Linus Torvalds:
 361
 362 .\" .I fails: only italicizes a single line
 363 "_Any_ sane library _must_ have "socklen_t" be the same size
 364 as int.
 365 Anything else breaks any BSD socket layer stuff.
 366 POSIX initially \fIdid\fP make it a size_t, and I (and hopefully others, but
 367 obviously not too many) complained to them very loudly indeed.
 368 Making it a size_t is completely broken, exactly because size_t very
 369 seldom is the same size as "int" on 64-bit architectures, for example.
 370 And it
 371 \fIhas\fP to be the same size as "int" because that's what the BSD socket
 372 interface is.
 373 Anyway, the POSIX people eventually got a clue, and created "socklen_t".
 374 They shouldn't have touched it in the first place, but once they did
 375 they felt it had to have a named type for some unfathomable reason
 376 (probably somebody didn't like losing face over having done the original
 377 stupid thing, so they silently just renamed their blunder)."
 378 .SH EXAMPLE
 379 See
 380 .BR bind (2).
 381 .SH SEE ALSO
 382 .BR bind (2),
 383 .BR connect (2),
 384 .BR listen (2),
 385 .BR select (2),
 386 .BR socket (2),
 387 .BR socket (7)
 388 .SH COLOPHON
 389 This page is part of release 3.79 of the Linux
 390 .I man-pages
 391 project.
 392 A description of the project,
 393 information about reporting bugs,
 394 and the latest version of this page,
 395 can be found at
 396 \%http://www.kernel.org/doc/man\-pages/.