mirror of https://github.com/mkerrisk/man-pages
173 lines
5.4 KiB
Groff
173 lines
5.4 KiB
Groff
.\" Copyright (c) 1983, 1991 The Regents of the University of California.
|
|
.\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $Id: listen.2,v 1.6 1999/05/18 14:10:32 freitag Exp $
|
|
.\"
|
|
.\" Modified Fri Jul 23 22:07:54 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" Modified 950727 by aeb, following a suggestion by Urs Thuermann
|
|
.\" <urs@isnogud.escape.de>
|
|
.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified 1998 by Andi Kleen
|
|
.\" Modified 11 May 2001 by Sam Varshavchik <mrsam@courier-mta.com>
|
|
.\"
|
|
.\"
|
|
.TH LISTEN 2 2008-11-20 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
listen \- listen for connections on a socket
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.BR "#include <sys/types.h>" " /* See NOTES */"
|
|
.br
|
|
.B #include <sys/socket.h>
|
|
.sp
|
|
.BI "int listen(int " sockfd ", int " backlog );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR listen ()
|
|
marks the socket referred to by
|
|
.I sockfd
|
|
as a passive socket, that is, as a socket that will
|
|
be used to accept incoming connection requests using
|
|
.BR accept (2).
|
|
|
|
The
|
|
.I sockfd
|
|
argument is a file descriptor that refers to a socket of type
|
|
.B SOCK_STREAM
|
|
or
|
|
.BR SOCK_SEQPACKET .
|
|
|
|
The
|
|
.I backlog
|
|
argument defines the maximum length
|
|
to which the queue of pending connections for
|
|
.I sockfd
|
|
may grow.
|
|
If a connection request arrives when the queue is full, the client
|
|
may receive an error with an indication of
|
|
.B ECONNREFUSED
|
|
or, if the underlying protocol supports retransmission, the request may be
|
|
ignored so that a later reattempt at connection succeeds.
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EADDRINUSE
|
|
Another socket is already listening on the same port.
|
|
.TP
|
|
.B EBADF
|
|
The argument
|
|
.I sockfd
|
|
is not a valid descriptor.
|
|
.TP
|
|
.B ENOTSOCK
|
|
The argument
|
|
.I sockfd
|
|
is not a socket.
|
|
.TP
|
|
.B EOPNOTSUPP
|
|
The socket is not of a type that supports the
|
|
.BR listen ()
|
|
operation.
|
|
.SH "CONFORMING TO"
|
|
4.4BSD, POSIX.1-2001.
|
|
The
|
|
.BR listen ()
|
|
function call first appeared in 4.2BSD.
|
|
.SH NOTES
|
|
To accept connections, the following steps are performed:
|
|
.RS 4
|
|
.IP 1. 4
|
|
A socket is created with
|
|
.BR socket (2).
|
|
.IP 2.
|
|
The socket is bound to a local address using
|
|
.BR bind (2),
|
|
so that other sockets may be
|
|
.BR connect (2)ed
|
|
to it.
|
|
.IP 3.
|
|
A willingness to accept incoming connections and a queue limit for incoming
|
|
connections are specified with
|
|
.BR listen ().
|
|
.IP 4.
|
|
Connections are accepted with
|
|
.BR accept (2).
|
|
.RE
|
|
.PP
|
|
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.
|
|
|
|
The behavior of the
|
|
.I backlog
|
|
argument on TCP sockets changed with Linux 2.2.
|
|
Now it specifies the queue length for
|
|
.I completely
|
|
established sockets waiting to be accepted,
|
|
instead of the number of incomplete connection requests.
|
|
The maximum length of the queue for incomplete sockets
|
|
can be set using
|
|
.IR /proc/sys/net/ipv4/tcp_max_syn_backlog .
|
|
When syncookies are enabled there is no logical maximum
|
|
length and this setting is ignored.
|
|
See
|
|
.BR tcp (7)
|
|
for more information.
|
|
|
|
If the
|
|
.I backlog
|
|
argument is greater than the value in
|
|
.IR /proc/sys/net/core/somaxconn ,
|
|
then it is silently truncated to that value;
|
|
the default value in this file is 128.
|
|
In kernels before 2.4.25, this limit was a hard coded value,
|
|
.BR SOMAXCONN ,
|
|
with the value 128.
|
|
.\" The following is now rather historic information (MTK, Jun 05)
|
|
.\" Don't rely on this value in portable applications since BSD
|
|
.\" (and some BSD-derived systems) limit the backlog to 5.
|
|
.SH EXAMPLE
|
|
See
|
|
.BR bind (2).
|
|
.SH "SEE ALSO"
|
|
.BR accept (2),
|
|
.BR bind (2),
|
|
.BR connect (2),
|
|
.BR socket (2),
|
|
.BR socket (7)
|