diff options
Diffstat (limited to 'man2/accept.2')
| -rw-r--r-- | man2/accept.2 | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/man2/accept.2 b/man2/accept.2 new file mode 100644 index 0000000..340fdb8 --- /dev/null +++ b/man2/accept.2 @@ -0,0 +1,347 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" 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 2023-04-05 "Linux man-pages 6.05.01" +.SH NAME +accept, accept4 \- accept a connection on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.PP +.BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr , +.BI " socklen_t *_Nullable 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 *_Nullable restrict " addr , +.BI " socklen_t *_Nullable 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 +.B 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 +.I flags +is 0, then +.BR accept4 () +is the same as +.BR accept (). +The following values can be bitwise ORed in +.I flags +to obtain different behavior: +.TP 16 +.B SOCK_NONBLOCK +Set the +.B 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 +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 STANDARDS +.TP +.BR accept () +POSIX.1-2008. +.TP +.BR accept4 () +Linux. +.SH HISTORY +.TP +.BR accept () +POSIX.1-2001, 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. +.TP +.BR accept4 () +Linux 2.6.28, +glibc 2.10. +.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) |