Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 349 insertions, 0 deletions

diff --git a/man/man2/accept.2 b/man/man2/accept.2
new file mode 100644
index 0000000..196700a
--- /dev/null
+++ b/man/man2/accept.2
@@ -0,0 +1,349 @@
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr ,
+.BI "           socklen_t *_Nullable restrict " addrlen );
+.P
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
+.B #include <sys/socket.h>
+.P
+.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.
+.P
+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).
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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 .
+.P
+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.
+.P
+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
+.B ENOBUFS
+.TQ
+.B 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.
+.P
+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)).
+.P
+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)