accept — accept a connection on a socket
#include <sys/types.h> #include <sys/socket.h>
int
accept( |
int | sockfd, |
struct sockaddr * | addr, | |
socklen_t * | addrlen) ; |
The accept
() system call is
used with connection-based socket types (SOCK_STREAM
, SOCK_SEQPACKET
). It extracts the first
connection request on the queue of pending connections,
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 sockfd
is unaffected by this
call.
The argument sockfd
is a socket that has
been created with socket(2), bound to a local
address with bind(2), and is listening
for connections after a listen(2).
The argument addr
is a pointer to a 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 addr
is determined by the socket's address family (see socket(2) and the
respective protocol man pages). The addrlen
argument is a
value-result argument: it should initially contain the size
of the structure pointed to by addr
; on return it will contain
the actual length (in bytes) of the address returned. When
addr
is NULL nothing
is filled in.
If no pending connections are present on the queue, and
the socket is not marked as non-blocking, accept
() blocks the caller until a
connection is present. If the socket is marked non-blocking
and no pending connections are present on the queue,
accept
() fails with the error
EAGAIN.
In order to be notified of incoming connections on a
socket, you can use select(2) or poll(2). A readable event
will be delivered when a new connection is attempted and you
may then call accept
() to get a
socket for that connection. Alternatively, you can set the
socket to deliver SIGIO
when
activity occurs on a socket; see socket(7) for details.
For certain protocols which require an explicit
confirmation, such as DECNet, 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.
There may not always be a connection waiting after a
SIGIO
is delivered or select(2) or poll(2) return a
readability event because the connection might have been
removed by an asynchronous network error or another thread
before accept
() is called. If
this happens then the call will block waiting for the next
connection to arrive. To ensure that accept
() never blocks, the passed socket
sockfd
needs to have
the O_NONBLOCK
flag set (see
socket(7)).
On success, accept
() returns
a non-negative integer that is a descriptor for the accepted
socket. On error, −1 is returned, and errno
is set appropriately.
Linux accept
() passes
already-pending network errors on the new socket as an error
code from accept
(). This
behaviour differs from other BSD socket implementations. For
reliable operation the application should detect the network
errors defined for the protocol after accept
() and treat them like EAGAIN by retrying. In case of TCP/IP
these are ENETDOWN,
EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH.
accept
() shall fail if:
The socket is marked non-blocking and no connections are present to be accepted.
The descriptor is invalid.
A connection has been aborted.
The system call was interrupted by a signal that was caught before a valid connection arrived.
Socket is not listening for connections, or
addrlen
is
invalid (e.g., is negative).
The per-process limit of open file descriptors has been reached.
The system limit on the total number of open files has been reached.
The descriptor references a file, not a socket.
The referenced socket is not of type SOCK_STREAM
.
accept
() may fail if:
The addr
argument is not in a writable part of the user address
space.
Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory.
Protocol error.
Linux accept
() may fail
if:
Firewall rules forbid connection.
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 ENOSR, ESOCKTNOSUPPORT, EPROTONOSUPPORT, ETIMEDOUT. The value ERESTARTSYS
may be seen during a trace.
SVr4, 4.4BSD, (accept
()
first appeared in 4.2BSD), POSIX.1-2001.
On Linux, the new socket returned by accept
() does not
inherit file status flags
such as O_NONBLOCK
and
O_ASYNC
from the listening
socket. This behaviour differs from the canonical BSD sockets
implementation. Portable programs should not rely on
inheritance or non-inheritance of file status flags and
always explicitly set all required flags on the socket
returned from accept
().
The third argument of accept
() was originally declared as an `int
*' (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 `size_t *', and that is
what it is for SunOS 5. Later POSIX drafts have `socklen_t
*', and so do the Single Unix Specification and glibc2.
Quoting Linus Torvalds:
"_Any_ sane library _must_ have "socklen_t" be the same
size as int. Anything else breaks any BSD socket layer stuff.
POSIX initially did
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 has
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)."
bind(2), connect(2), listen(2), select(2), socket(2)
|