1994-05-27 05:00:24 +00:00
|
|
|
.\" Copyright (c) 1983, 1991, 1993
|
|
|
|
.\" The Regents of the University of California. 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.
|
2017-02-28 23:42:47 +00:00
|
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
1994-05-27 05:00:24 +00:00
|
|
|
.\" 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.
|
|
|
|
.\"
|
2023-04-30 20:14:30 +00:00
|
|
|
.Dd April 30, 2023
|
1994-05-27 05:00:24 +00:00
|
|
|
.Dt LISTEN 2
|
2001-07-10 13:41:46 +00:00
|
|
|
.Os
|
1994-05-27 05:00:24 +00:00
|
|
|
.Sh NAME
|
|
|
|
.Nm listen
|
|
|
|
.Nd listen for connections on a socket
|
2000-04-21 09:42:15 +00:00
|
|
|
.Sh LIBRARY
|
|
|
|
.Lb libc
|
1994-05-27 05:00:24 +00:00
|
|
|
.Sh SYNOPSIS
|
2001-10-01 16:09:29 +00:00
|
|
|
.In sys/socket.h
|
1994-05-27 05:00:24 +00:00
|
|
|
.Ft int
|
|
|
|
.Fn listen "int s" "int backlog"
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
To accept connections, a socket
|
|
|
|
is first created with
|
|
|
|
.Xr socket 2 ,
|
|
|
|
a willingness to accept incoming connections and
|
|
|
|
a queue limit for incoming connections are specified with
|
|
|
|
.Fn listen ,
|
|
|
|
and then the connections are
|
|
|
|
accepted with
|
|
|
|
.Xr accept 2 .
|
|
|
|
The
|
|
|
|
.Fn listen
|
2002-12-18 09:22:32 +00:00
|
|
|
system call applies only to sockets of type
|
1994-05-27 05:00:24 +00:00
|
|
|
.Dv SOCK_STREAM
|
|
|
|
or
|
2001-02-01 16:38:02 +00:00
|
|
|
.Dv SOCK_SEQPACKET .
|
1994-05-27 05:00:24 +00:00
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Fa backlog
|
2002-12-19 09:40:28 +00:00
|
|
|
argument defines the maximum length the queue of
|
1994-05-27 05:00:24 +00:00
|
|
|
pending connections may grow to.
|
2005-08-29 10:23:46 +00:00
|
|
|
The real maximum queue length will be 1.5 times more than the value
|
|
|
|
specified in the
|
|
|
|
.Fa backlog
|
|
|
|
argument.
|
|
|
|
A subsequent
|
|
|
|
.Fn listen
|
|
|
|
system call on the listening socket allows the caller to change the maximum
|
|
|
|
queue length using a new
|
|
|
|
.Fa backlog
|
|
|
|
argument.
|
1994-05-27 05:00:24 +00:00
|
|
|
If a connection
|
|
|
|
request arrives with the queue full the client may
|
|
|
|
receive an error with an indication of
|
|
|
|
.Er ECONNREFUSED ,
|
2002-05-08 18:19:01 +00:00
|
|
|
or, in the case of TCP, the connection will be
|
|
|
|
silently dropped.
|
|
|
|
.Pp
|
2005-08-29 10:23:46 +00:00
|
|
|
Current queue lengths of listening sockets can be queried using
|
|
|
|
.Xr netstat 1
|
|
|
|
command.
|
|
|
|
.Pp
|
2002-05-29 15:53:01 +00:00
|
|
|
Note that before
|
|
|
|
.Fx 4.5
|
|
|
|
and the introduction of the syncache,
|
|
|
|
the
|
2002-05-08 18:19:01 +00:00
|
|
|
.Fa backlog
|
2002-12-19 09:40:28 +00:00
|
|
|
argument also determined the length of the incomplete
|
2002-05-08 18:19:01 +00:00
|
|
|
connection queue, which held TCP sockets in the process
|
2002-05-29 15:53:01 +00:00
|
|
|
of completing TCP's 3-way handshake.
|
|
|
|
These incomplete connections
|
2002-05-08 18:19:01 +00:00
|
|
|
are now held entirely in the syncache, which is unaffected by
|
2002-05-29 15:53:01 +00:00
|
|
|
queue lengths.
|
|
|
|
Inflated
|
2002-05-08 18:19:01 +00:00
|
|
|
.Fa backlog
|
|
|
|
values to help handle denial
|
|
|
|
of service attacks are no longer necessary.
|
1995-11-03 18:34:38 +00:00
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Xr sysctl 3
|
|
|
|
MIB variable
|
2012-10-20 12:53:14 +00:00
|
|
|
.Va kern.ipc.soacceptqueue
|
1995-11-03 18:34:38 +00:00
|
|
|
specifies a hard limit on
|
|
|
|
.Fa backlog ;
|
2001-02-01 16:38:02 +00:00
|
|
|
if a value greater than
|
2012-10-20 12:53:14 +00:00
|
|
|
.Va kern.ipc.soacceptqueue
|
2022-10-12 02:33:00 +00:00
|
|
|
or less than zero is specified,
|
1995-11-03 18:34:38 +00:00
|
|
|
.Fa backlog
|
|
|
|
is silently forced to
|
2012-10-20 12:53:14 +00:00
|
|
|
.Va kern.ipc.soacceptqueue .
|
2020-04-14 15:38:18 +00:00
|
|
|
.Pp
|
2023-04-30 20:14:30 +00:00
|
|
|
If the listen queue overflows, the kernel will emit a syslog message
|
|
|
|
using default priority LOG_DEBUG (7).
|
2020-04-14 15:38:18 +00:00
|
|
|
The
|
|
|
|
.Xr sysctl 3
|
|
|
|
MIB variable
|
2023-04-30 20:14:30 +00:00
|
|
|
.Va kern.ipc.sooverprio
|
|
|
|
may be used to change this priority to any value in a range of 0..7
|
|
|
|
(LOG_EMERG..LOG_DEBUG).
|
|
|
|
See
|
|
|
|
.Xr syslog 3
|
|
|
|
for details.
|
|
|
|
It may be set to -1 to disable these messages.
|
|
|
|
.Pp
|
|
|
|
The variable
|
2020-04-14 15:38:18 +00:00
|
|
|
.Va kern.ipc.sooverinterval
|
|
|
|
specifies a per-socket limit on how often the kernel will emit these messages.
|
2002-05-08 18:19:01 +00:00
|
|
|
.Sh INTERACTION WITH ACCEPT FILTERS
|
|
|
|
When accept filtering is used on a socket, a second queue will
|
|
|
|
be used to hold sockets that have connected, but have not yet
|
2002-05-29 15:53:01 +00:00
|
|
|
met their accept filtering criteria.
|
|
|
|
Once the criteria has been
|
2002-05-08 18:19:01 +00:00
|
|
|
met, these sockets will be moved over into the completed connection
|
2002-05-29 15:53:01 +00:00
|
|
|
queue to be
|
|
|
|
.Xr accept 2 Ns ed .
|
|
|
|
If this secondary queue is full and a
|
2002-05-08 18:19:01 +00:00
|
|
|
new connection comes in, the oldest socket which has not yet met
|
|
|
|
its accept filter criteria will be terminated.
|
|
|
|
.Pp
|
|
|
|
This secondary queue, like the primary listen queue, is sized
|
2002-05-29 15:53:01 +00:00
|
|
|
according to the
|
2002-05-08 18:19:01 +00:00
|
|
|
.Fa backlog
|
2002-12-19 09:40:28 +00:00
|
|
|
argument.
|
1994-05-27 05:00:24 +00:00
|
|
|
.Sh RETURN VALUES
|
2001-08-09 13:32:13 +00:00
|
|
|
.Rv -std listen
|
1994-05-27 05:00:24 +00:00
|
|
|
.Sh ERRORS
|
2002-12-18 09:22:32 +00:00
|
|
|
The
|
|
|
|
.Fn listen
|
|
|
|
system call
|
1994-05-27 05:00:24 +00:00
|
|
|
will fail if:
|
2000-05-04 13:09:25 +00:00
|
|
|
.Bl -tag -width Er
|
1994-05-27 05:00:24 +00:00
|
|
|
.It Bq Er EBADF
|
|
|
|
The argument
|
|
|
|
.Fa s
|
|
|
|
is not a valid descriptor.
|
2014-07-15 02:21:51 +00:00
|
|
|
.It Bq Er EDESTADDRREQ
|
|
|
|
The socket is not bound to a local address, and the protocol does not
|
|
|
|
support listening on an unbound socket.
|
2003-01-17 19:25:27 +00:00
|
|
|
.It Bq Er EINVAL
|
|
|
|
The socket is already connected, or in the process of being connected.
|
1994-05-27 05:00:24 +00:00
|
|
|
.It Bq Er ENOTSOCK
|
|
|
|
The argument
|
|
|
|
.Fa s
|
|
|
|
is not a socket.
|
|
|
|
.It Bq Er EOPNOTSUPP
|
|
|
|
The socket is not of a type that supports the operation
|
|
|
|
.Fn listen .
|
|
|
|
.El
|
|
|
|
.Sh SEE ALSO
|
2005-08-29 10:23:46 +00:00
|
|
|
.Xr netstat 1 ,
|
1994-05-27 05:00:24 +00:00
|
|
|
.Xr accept 2 ,
|
|
|
|
.Xr connect 2 ,
|
1995-11-03 18:34:38 +00:00
|
|
|
.Xr socket 2 ,
|
1996-02-11 22:38:05 +00:00
|
|
|
.Xr sysctl 3 ,
|
2023-04-30 20:14:30 +00:00
|
|
|
.Xr syslog 3 ,
|
2002-05-29 15:53:01 +00:00
|
|
|
.Xr sysctl 8 ,
|
|
|
|
.Xr accept_filter 9
|
1994-05-27 05:00:24 +00:00
|
|
|
.Sh HISTORY
|
|
|
|
The
|
1996-08-22 23:31:07 +00:00
|
|
|
.Fn listen
|
2002-12-18 09:22:32 +00:00
|
|
|
system call appeared in
|
1994-05-27 05:00:24 +00:00
|
|
|
.Bx 4.2 .
|
1995-11-03 18:34:38 +00:00
|
|
|
The ability to configure the maximum
|
|
|
|
.Fa backlog
|
|
|
|
at run-time, and to use a negative
|
|
|
|
.Fa backlog
|
1996-05-23 01:05:25 +00:00
|
|
|
to request the maximum allowable value, was introduced in
|
|
|
|
.Fx 2.2 .
|
2012-10-20 12:53:14 +00:00
|
|
|
The
|
|
|
|
.Va kern.ipc.somaxconn
|
|
|
|
.Xr sysctl 3
|
|
|
|
has been replaced with
|
|
|
|
.Va kern.ipc.soacceptqueue
|
|
|
|
in
|
|
|
|
.Fx 10.0
|
2012-10-20 19:38:22 +00:00
|
|
|
to prevent confusion about its actual functionality.
|
2012-10-20 12:53:14 +00:00
|
|
|
The original
|
|
|
|
.Xr sysctl 3
|
|
|
|
.Va kern.ipc.somaxconn
|
|
|
|
is still available but hidden from a
|
|
|
|
.Xr sysctl 3
|
|
|
|
-a output so that existing applications and scripts continue to work.
|