mirror of https://github.com/mkerrisk/man-pages
370 lines
10 KiB
Groff
370 lines
10 KiB
Groff
.\" 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 2021-08-27 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
accept, accept4 \- accept a connection on a socket
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/socket.h>
|
|
.PP
|
|
.BI "int accept(int " sockfd ", struct sockaddr *restrict " addr ,
|
|
.BI " socklen_t *restrict " addrlen );
|
|
.PP
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
.B #include <sys/socket.h>
|
|
.PP
|
|
.BI "int accept4(int " sockfd ", struct sockaddr *restrict " addr ,
|
|
.BI " socklen_t *restrict " 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).
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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),
|
|
.BR poll (2),
|
|
or
|
|
.BR epoll (7).
|
|
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
|
|
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 open file description (see
|
|
.BR open (2))
|
|
referred to by the new file descriptor.
|
|
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 file descriptor
|
|
for the accepted socket (a nonnegative integer).
|
|
On error, \-1 is returned,
|
|
.I errno
|
|
is set to indicate the error, and
|
|
.I addrlen
|
|
is left unchanged.
|
|
.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 EPERM
|
|
Firewall rules forbid connection.
|
|
.TP
|
|
.B EPROTO
|
|
Protocol error.
|
|
.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.
|
|
.PP
|
|
.BR accept4 ()
|
|
is a nonstandard Linux extension.
|
|
.PP
|
|
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
|
|
There may not always be a connection waiting after a
|
|
.B SIGIO
|
|
is delivered or
|
|
.BR select (2),
|
|
.BR poll (2),
|
|
or
|
|
.BR epoll (7)
|
|
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)).
|
|
.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.
|
|
.\"
|
|
.SS The socklen_t type
|
|
In the original BSD sockets implementation (and on other older systems)
|
|
.\" such as Linux libc4 and libc5, SunOS 4, SGI
|
|
the third argument of
|
|
.BR accept ()
|
|
was declared as an \fIint\ *\fP.
|
|
A POSIX.1g draft
|
|
standard wanted to change it into a \fIsize_t\ *\fPC;
|
|
.\" SunOS 5 has 'size_t *'
|
|
later POSIX standards and glibc 2.x have
|
|
.IR "socklen_t\ * ".
|
|
.SH EXAMPLES
|
|
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)
|