1 .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
2 .\" All rights reserved.
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
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.
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
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()
41 .TH ACCEPT 2 2010-09-10 "Linux" "Linux Programmer's Manual"
43 accept, accept4 \- accept a connection on a socket
46 .BR "#include <sys/types.h>" " /* See NOTES */"
47 .B #include <sys/socket.h>
49 .BI "int accept(int " sockfd ", struct sockaddr *" addr ", socklen_t *" addrlen );
51 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
52 .B #include <sys/socket.h>
54 .BI "int accept4(int " sockfd ", struct sockaddr *" addr ,
55 .BI " socklen_t *" addrlen ", int " flags );
60 system call is used with connection-based socket types
63 It extracts the first connection request on the queue of pending
64 connections for the listening socket,
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.
71 is unaffected by this call.
75 is a socket that has been created with
77 bound to a local address with
79 and is listening for connections after a
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
91 is determined by the socket's address family (see
93 and the respective protocol man pages).
96 is NULL, nothing is filled in; in this case,
98 is not used, and should also be NULL.
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
106 on return it will contain the actual size of the peer address.
108 The returned address is truncated if the buffer provided is too small;
111 will return a value greater than was supplied to the call.
114 connections are present on the queue, and the socket is not marked as
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,
126 In order to be notified of incoming connections on a socket, you can use
130 A readable event will be delivered when a new connection is attempted and you
133 to get a socket for that connection.
134 Alternatively, you can set the socket to deliver
136 when activity occurs on a socket; see
140 For certain protocols which require an explicit confirmation,
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.
151 has these semantics on Linux.
159 The following values can be bitwise ORed in
161 to obtain different behavior:
166 file status flag on the new open file description.
167 Using this flag saves extra calls to
169 to achieve the same result.
172 Set the close-on-exec
174 flag on the new file descriptor.
175 See the description of the
179 for reasons why this may be useful.
182 these system calls return a nonnegative integer that is a descriptor
183 for the accepted socket.
184 On error, \-1 is returned, and
186 is set appropriately.
192 passes already-pending network errors on the new socket
193 as an error code from
195 This behavior differs from other BSD socket
197 For reliable operation the application should detect
198 the network errors defined for the protocol after
204 In the case of TCP/IP, these are
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.
225 The descriptor is invalid.
228 A connection has been aborted.
233 argument is not in a writable part of the user address space.
236 The system call was interrupted by a signal that was caught
237 before a valid connection arrived; see
241 Socket is not listening for connections, or
243 is invalid (e.g., is negative).
251 The per-process limit of open file descriptors has been reached.
254 The system limit on the total number of open files has been reached.
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.
262 The descriptor references a file, not a socket.
265 The referenced socket is not of type
276 Firewall rules forbid connection.
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
283 .BR ESOCKTNOSUPPORT ,
284 .BR EPROTONOSUPPORT ,
288 may be seen during a trace.
292 system call is available starting with Linux 2.6.28;
293 support in glibc is available starting with version 2.10.
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.
308 is a nonstandard Linux extension.
310 On Linux, the new socket returned by
312 does \fInot\fP inherit file status flags such as
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
325 POSIX.1-2001 does not require the inclusion of
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.
331 There may not always be a connection waiting after a
337 return a readability event because the connection might have been
338 removed by an asynchronous network error or another thread before
341 If this happens, then the call will block waiting for the next
342 connection to arrive.
345 never blocks, the passed socket
351 .SS The socklen_t type
352 The third argument of
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
358 Later POSIX drafts have \fIsocklen_t *\fP,
359 and so do the Single UNIX Specification and glibc2.
360 Quoting Linus Torvalds:
362 .\" .I fails: only italicizes a single line
363 "_Any_ sane library _must_ have "socklen_t" be the same size
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.
371 \fIhas\fP to be the same size as "int" because that's what the BSD socket
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)."
389 This page is part of release 3.65 of the Linux
392 A description of the project,
393 and information about reporting bugs,
395 \%http://www.kernel.org/doc/man\-pages/.