lib/libc/sys/listen.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)listen.2      8.2 (Berkeley) 12/11/93
  29 .\"
  30 .Dd April 30, 2023
  31 .Dt LISTEN 2
  32 .Os
  33 .Sh NAME
  34 .Nm listen
  35 .Nd listen for connections on a socket
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/socket.h
  40 .Ft int
  41 .Fn listen "int s" "int backlog"
  42 .Sh DESCRIPTION
  43 To accept connections, a socket
  44 is first created with
  45 .Xr socket 2 ,
  46 a willingness to accept incoming connections and
  47 a queue limit for incoming connections are specified with
  48 .Fn listen ,
  49 and then the connections are
  50 accepted with
  51 .Xr accept 2 .
  52 The
  53 .Fn listen
  54 system call applies only to sockets of type
  55 .Dv SOCK_STREAM
  56 or
  57 .Dv SOCK_SEQPACKET .
  58 .Pp
  59 The
  60 .Fa backlog
  61 argument defines the maximum length the queue of
  62 pending connections may grow to.
  63 The real maximum queue length will be 1.5 times more than the value
  64 specified in the
  65 .Fa backlog
  66 argument.
  67 A subsequent
  68 .Fn listen
  69 system call on the listening socket allows the caller to change the maximum
  70 queue length using a new
  71 .Fa backlog
  72 argument.
  73 If a connection
  74 request arrives with the queue full the client may
  75 receive an error with an indication of
  76 .Er ECONNREFUSED ,
  77 or, in the case of TCP, the connection will be
  78 silently dropped.
  79 .Pp
  80 Current queue lengths of listening sockets can be queried using
  81 .Xr netstat 1
  82 command.
  83 .Pp
  84 Note that before
  85 .Fx 4.5
  86 and the introduction of the syncache,
  87 the
  88 .Fa backlog
  89 argument also determined the length of the incomplete
  90 connection queue, which held TCP sockets in the process
  91 of completing TCP's 3-way handshake.
  92 These incomplete connections
  93 are now held entirely in the syncache, which is unaffected by
  94 queue lengths.
  95 Inflated
  96 .Fa backlog
  97 values to help handle denial
  98 of service attacks are no longer necessary.
  99 .Pp
 100 The
 101 .Xr sysctl 3
 102 MIB variable
 103 .Va kern.ipc.soacceptqueue
 104 specifies a hard limit on
 105 .Fa backlog ;
 106 if a value greater than
 107 .Va kern.ipc.soacceptqueue
 108 or less than zero is specified,
 109 .Fa backlog
 110 is silently forced to
 111 .Va kern.ipc.soacceptqueue .
 112 .Pp
 113 If the listen queue overflows, the kernel will emit a syslog message
 114 using default priority LOG_DEBUG (7).
 115 The
 116 .Xr sysctl 3
 117 MIB variable
 118 .Va kern.ipc.sooverprio
 119 may be used to change this priority to any value in a range of 0..7
 120 (LOG_EMERG..LOG_DEBUG).
 121 See
 122 .Xr syslog 3
 123 for details.
 124 It may be set to -1 to disable these messages.
 125 .Pp
 126 The variable
 127 .Va kern.ipc.sooverinterval
 128 specifies a per-socket limit on how often the kernel will emit these messages.
 129 .Sh INTERACTION WITH ACCEPT FILTERS
 130 When accept filtering is used on a socket, a second queue will
 131 be used to hold sockets that have connected, but have not yet
 132 met their accept filtering criteria.
 133 Once the criteria has been
 134 met, these sockets will be moved over into the completed connection
 135 queue to be
 136 .Xr accept 2 Ns ed .
 137 If this secondary queue is full and a
 138 new connection comes in, the oldest socket which has not yet met
 139 its accept filter criteria will be terminated.
 140 .Pp
 141 This secondary queue, like the primary listen queue, is sized
 142 according to the
 143 .Fa backlog
 144 argument.
 145 .Sh RETURN VALUES
 146 .Rv -std listen
 147 .Sh ERRORS
 148 The
 149 .Fn listen
 150 system call
 151 will fail if:
 152 .Bl -tag -width Er
 153 .It Bq Er EBADF
 154 The argument
 155 .Fa s
 156 is not a valid descriptor.
 157 .It Bq Er EDESTADDRREQ
 158 The socket is not bound to a local address, and the protocol does not
 159 support listening on an unbound socket.
 160 .It Bq Er EINVAL
 161 The socket is already connected, or in the process of being connected.
 162 .It Bq Er ENOTSOCK
 163 The argument
 164 .Fa s
 165 is not a socket.
 166 .It Bq Er EOPNOTSUPP
 167 The socket is not of a type that supports the operation
 168 .Fn listen .
 169 .El
 170 .Sh SEE ALSO
 171 .Xr netstat 1 ,
 172 .Xr accept 2 ,
 173 .Xr connect 2 ,
 174 .Xr socket 2 ,
 175 .Xr sysctl 3 ,
 176 .Xr syslog 3 ,
 177 .Xr sysctl 8 ,
 178 .Xr accept_filter 9
 179 .Sh HISTORY
 180 The
 181 .Fn listen
 182 system call appeared in
 183 .Bx 4.2 .
 184 The ability to configure the maximum
 185 .Fa backlog
 186 at run-time, and to use a negative
 187 .Fa backlog
 188 to request the maximum allowable value, was introduced in
 189 .Fx 2.2 .
 190 The
 191 .Va kern.ipc.somaxconn
 192 .Xr sysctl 3
 193 has been replaced with
 194 .Va kern.ipc.soacceptqueue
 195 in
 196 .Fx 10.0
 197 to prevent confusion about its actual functionality.
 198 The original
 199 .Xr sysctl 3
 200 .Va kern.ipc.somaxconn
 201 is still available but hidden from a
 202 .Xr sysctl 3
 203 -a output so that existing applications and scripts continue to work.