| .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1996-10-21 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 1998-2000 by Andi Kleen to match Linux 2.2 reality |
| .\" Modified 2002-04-23 by Roger Luethi <rl@hellgate.ch> |
| .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" 2008-12-04, mtk, Add documentation of accept4() |
| .\" |
| .TH ACCEPT 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| accept, accept4 \- accept a connection on a socket |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <sys/types.h>" " /* See NOTES */" |
| .B #include <sys/socket.h> |
| |
| .BI "int accept(int " sockfd ", struct sockaddr *" addr ", socklen_t *" addrlen ); |
| |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <sys/socket.h> |
| |
| .BI "int accept4(int " sockfd ", struct sockaddr *" addr , |
| .BI " socklen_t *" addrlen ", int " flags ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR accept () |
| system call is used with connection-based socket types |
| .RB ( SOCK_STREAM , |
| .BR SOCK_SEQPACKET ). |
| It extracts the first connection request on the queue of pending |
| connections for the listening socket, |
| .IR sockfd , |
| creates a new connected socket, and returns a new file |
| descriptor referring to that socket. |
| The newly created socket is not in the listening state. |
| The original socket |
| .I sockfd |
| is unaffected by this call. |
| .PP |
| The argument |
| .I sockfd |
| is a socket that has been created with |
| .BR socket (2), |
| bound to a local address with |
| .BR bind (2), |
| and is listening for connections after a |
| .BR listen (2). |
| |
| The argument |
| .I addr |
| is a pointer to a |
| .I sockaddr |
| structure. |
| This structure is filled in with the address of the peer socket, |
| as known to the communications layer. |
| The exact format of the address returned |
| .I addr |
| is determined by the socket's address family (see |
| .BR socket (2) |
| and the respective protocol man pages). |
| When |
| .I addr |
| is NULL, nothing is filled in; in this case, |
| .I addrlen |
| is not used, and should also be NULL. |
| |
| The |
| .I addrlen |
| argument is a value-result argument: |
| the caller must initialize it to contain the |
| size (in bytes) of the structure pointed to by |
| .IR addr ; |
| on return it will contain the actual size of the peer address. |
| |
| The returned address is truncated if the buffer provided is too small; |
| in this case, |
| .I addrlen |
| will return a value greater than was supplied to the call. |
| .PP |
| If no pending |
| connections are present on the queue, and the socket is not marked as |
| nonblocking, |
| .BR accept () |
| blocks the caller until a connection is present. |
| If the socket is marked |
| nonblocking and no pending connections are present on the queue, |
| .BR accept () |
| fails with the error |
| .BR EAGAIN |
| or |
| .BR EWOULDBLOCK . |
| .PP |
| In order to be notified of incoming connections on a socket, you can use |
| .BR select (2) |
| or |
| .BR poll (2). |
| A readable event will be delivered when a new connection is attempted and you |
| may then call |
| .BR accept () |
| to get a socket for that connection. |
| Alternatively, you can set the socket to deliver |
| .B SIGIO |
| when activity occurs on a socket; see |
| .BR socket (7) |
| for details. |
| .PP |
| For certain protocols which require an explicit confirmation, |
| such as |
| DECNet, |
| .BR accept () |
| can be thought of as merely dequeuing the next connection request and not |
| implying confirmation. |
| Confirmation can be implied by |
| a normal read or write on the new file descriptor, and rejection can be |
| implied by closing the new socket. |
| Currently, only |
| DECNet |
| has these semantics on Linux. |
| |
| If |
| .IR flags |
| is 0, then |
| .BR accept4 () |
| is the same as |
| .BR accept (). |
| The following values can be bitwise ORed in |
| .IR flags |
| to obtain different behavior: |
| .TP 16 |
| .B SOCK_NONBLOCK |
| Set the |
| .BR O_NONBLOCK |
| file status flag on the new open file description. |
| Using this flag saves extra calls to |
| .BR fcntl (2) |
| to achieve the same result. |
| .TP |
| .B SOCK_CLOEXEC |
| Set the close-on-exec |
| .RB ( FD_CLOEXEC ) |
| flag on the new file descriptor. |
| See the description of the |
| .B O_CLOEXEC |
| flag in |
| .BR open (2) |
| for reasons why this may be useful. |
| .SH RETURN VALUE |
| On success, |
| these system calls return a nonnegative integer that is a file descriptor |
| for the accepted socket. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SS Error handling |
| Linux |
| .BR accept () |
| (and |
| .BR accept4 ()) |
| passes already-pending network errors on the new socket |
| as an error code from |
| .BR accept (). |
| This behavior differs from other BSD socket |
| implementations. |
| For reliable operation the application should detect |
| the network errors defined for the protocol after |
| .BR accept () |
| and treat |
| them like |
| .B EAGAIN |
| by retrying. |
| In the case of TCP/IP, these are |
| .BR ENETDOWN , |
| .BR EPROTO , |
| .BR ENOPROTOOPT , |
| .BR EHOSTDOWN , |
| .BR ENONET , |
| .BR EHOSTUNREACH , |
| .BR EOPNOTSUPP , |
| and |
| .BR ENETUNREACH . |
| .SH ERRORS |
| .TP |
| .BR EAGAIN " or " EWOULDBLOCK |
| .\" Actually EAGAIN on Linux |
| The socket is marked nonblocking and no connections are |
| present to be accepted. |
| POSIX.1-2001 and POSIX.1-2008 |
| allow either error to be returned for this case, |
| and do not require these constants to have the same value, |
| so a portable application should check for both possibilities. |
| .TP |
| .B EBADF |
| .I sockfd |
| is not an open file descriptor. |
| .TP |
| .B ECONNABORTED |
| A connection has been aborted. |
| .TP |
| .B EFAULT |
| The |
| .I addr |
| argument is not in a writable part of the user address space. |
| .TP |
| .B EINTR |
| The system call was interrupted by a signal that was caught |
| before a valid connection arrived; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| Socket is not listening for connections, or |
| .I addrlen |
| is invalid (e.g., is negative). |
| .TP |
| .B EINVAL |
| .RB ( accept4 ()) |
| invalid value in |
| .IR flags . |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached. |
| .TP |
| .B ENFILE |
| The system-wide limit on the total number of open files has been reached. |
| .TP |
| .BR ENOBUFS ", " ENOMEM |
| Not enough free memory. |
| This often means that the memory allocation is limited by the socket buffer |
| limits, not by the system memory. |
| .TP |
| .B ENOTSOCK |
| The file descriptor |
| .I sockfd |
| does not refer to a socket. |
| .TP |
| .B EOPNOTSUPP |
| The referenced socket is not of type |
| .BR SOCK_STREAM . |
| .TP |
| .B EPROTO |
| Protocol error. |
| .PP |
| In addition, Linux |
| .BR accept () |
| may fail if: |
| .TP |
| .B EPERM |
| Firewall rules forbid connection. |
| .PP |
| In addition, network errors for the new socket and as defined |
| for the protocol may be returned. |
| Various Linux kernels can |
| return other errors such as |
| .BR ENOSR , |
| .BR ESOCKTNOSUPPORT , |
| .BR EPROTONOSUPPORT , |
| .BR ETIMEDOUT . |
| The value |
| .B ERESTARTSYS |
| may be seen during a trace. |
| .SH VERSIONS |
| The |
| .BR accept4 () |
| system call is available starting with Linux 2.6.28; |
| support in glibc is available starting with version 2.10. |
| .SH CONFORMING TO |
| .BR accept (): |
| POSIX.1-2001, POSIX.1-2008, |
| SVr4, 4.4BSD |
| .RB ( accept () |
| first appeared in 4.2BSD). |
| .\" The BSD man page documents five possible error returns |
| .\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). |
| .\" POSIX.1-2001 documents errors |
| .\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, |
| .\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. |
| .\" In addition, SUSv2 documents EFAULT and ENOSR. |
| |
| .BR accept4 () |
| is a nonstandard Linux extension. |
| .LP |
| On Linux, the new socket returned by |
| .BR accept () |
| does \fInot\fP inherit file status flags such as |
| .B O_NONBLOCK |
| and |
| .B O_ASYNC |
| from the listening socket. |
| This behavior differs from the canonical BSD sockets implementation. |
| .\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also |
| .\" do not inherit file status flags -- MTK Jun 05 |
| Portable programs should not rely on inheritance or noninheritance |
| of file status flags and always explicitly set all required flags on |
| the socket returned from |
| .BR accept (). |
| .SH NOTES |
| POSIX.1-2001 does not require the inclusion of |
| .IR <sys/types.h> , |
| and this header file is not required on Linux. |
| However, some historical (BSD) implementations required this header |
| file, and portable applications are probably wise to include it. |
| |
| There may not always be a connection waiting after a |
| .B SIGIO |
| is delivered or |
| .BR select (2) |
| or |
| .BR poll (2) |
| return a readability event because the connection might have been |
| removed by an asynchronous network error or another thread before |
| .BR accept () |
| is called. |
| If this happens, then the call will block waiting for the next |
| connection to arrive. |
| To ensure that |
| .BR accept () |
| never blocks, the passed socket |
| .I sockfd |
| needs to have the |
| .B O_NONBLOCK |
| flag set (see |
| .BR socket (7)). |
| .SS The socklen_t type |
| The third argument of |
| .BR accept () |
| was originally declared as an \fIint *\fP (and is that under libc4 and libc5 |
| and on many other systems like 4.x BSD, SunOS 4, SGI); a POSIX.1g draft |
| standard wanted to change it into a \fIsize_t *\fP, and that is what it is |
| for SunOS 5. |
| Later POSIX drafts have \fIsocklen_t *\fP, |
| and so do the Single UNIX Specification and glibc2. |
| Quoting Linus Torvalds: |
| |
| .\" .I fails: only italicizes a single line |
| "_Any_ sane library _must_ have "socklen_t" be the same size |
| as int. |
| Anything else breaks any BSD socket layer stuff. |
| POSIX initially \fIdid\fP make it a size_t, and I (and hopefully others, but |
| obviously not too many) complained to them very loudly indeed. |
| Making it a size_t is completely broken, exactly because size_t very |
| seldom is the same size as "int" on 64-bit architectures, for example. |
| And it |
| \fIhas\fP to be the same size as "int" because that's what the BSD socket |
| interface is. |
| Anyway, the POSIX people eventually got a clue, and created "socklen_t". |
| They shouldn't have touched it in the first place, but once they did |
| they felt it had to have a named type for some unfathomable reason |
| (probably somebody didn't like losing face over having done the original |
| stupid thing, so they silently just renamed their blunder)." |
| .SH EXAMPLE |
| See |
| .BR bind (2). |
| .SH SEE ALSO |
| .BR bind (2), |
| .BR connect (2), |
| .BR listen (2), |
| .BR select (2), |
| .BR socket (2), |
| .BR socket (7) |