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 .Dd April 30, 2023
  29 .Dt LISTEN 2
  30 .Os
  31 .Sh NAME
  32 .Nm listen
  33 .Nd listen for connections on a socket
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/socket.h
  38 .Ft int
  39 .Fn listen "int s" "int backlog"
  40 .Sh DESCRIPTION
  41 To accept connections, a socket
  42 is first created with
  43 .Xr socket 2 ,
  44 a willingness to accept incoming connections and
  45 a queue limit for incoming connections are specified with
  46 .Fn listen ,
  47 and then the connections are
  48 accepted with
  49 .Xr accept 2 .
  50 The
  51 .Fn listen
  52 system call applies only to sockets of type
  53 .Dv SOCK_STREAM
  54 or
  55 .Dv SOCK_SEQPACKET .
  56 .Pp
  57 The
  58 .Fa backlog
  59 argument defines the maximum length the queue of
  60 pending connections may grow to.
  61 The real maximum queue length will be 1.5 times more than the value
  62 specified in the
  63 .Fa backlog
  64 argument.
  65 A subsequent
  66 .Fn listen
  67 system call on the listening socket allows the caller to change the maximum
  68 queue length using a new
  69 .Fa backlog
  70 argument.
  71 If a connection
  72 request arrives with the queue full the client may
  73 receive an error with an indication of
  74 .Er ECONNREFUSED ,
  75 or, in the case of TCP, the connection will be
  76 silently dropped.
  77 .Pp
  78 Current queue lengths of listening sockets can be queried using
  79 .Xr netstat 1
  80 command.
  81 .Pp
  82 Note that before
  83 .Fx 4.5
  84 and the introduction of the syncache,
  85 the
  86 .Fa backlog
  87 argument also determined the length of the incomplete
  88 connection queue, which held TCP sockets in the process
  89 of completing TCP's 3-way handshake.
  90 These incomplete connections
  91 are now held entirely in the syncache, which is unaffected by
  92 queue lengths.
  93 Inflated
  94 .Fa backlog
  95 values to help handle denial
  96 of service attacks are no longer necessary.
  97 .Pp
  98 The
  99 .Xr sysctl 3
 100 MIB variable
 101 .Va kern.ipc.soacceptqueue
 102 specifies a hard limit on
 103 .Fa backlog ;
 104 if a value greater than
 105 .Va kern.ipc.soacceptqueue
 106 or less than zero is specified,
 107 .Fa backlog
 108 is silently forced to
 109 .Va kern.ipc.soacceptqueue .
 110 .Pp
 111 If the listen queue overflows, the kernel will emit a syslog message
 112 using default priority LOG_DEBUG (7).
 113 The
 114 .Xr sysctl 3
 115 MIB variable
 116 .Va kern.ipc.sooverprio
 117 may be used to change this priority to any value in a range of 0..7
 118 (LOG_EMERG..LOG_DEBUG).
 119 See
 120 .Xr syslog 3
 121 for details.
 122 It may be set to -1 to disable these messages.
 123 .Pp
 124 The variable
 125 .Va kern.ipc.sooverinterval
 126 specifies a per-socket limit on how often the kernel will emit these messages.
 127 .Sh INTERACTION WITH ACCEPT FILTERS
 128 When accept filtering is used on a socket, a second queue will
 129 be used to hold sockets that have connected, but have not yet
 130 met their accept filtering criteria.
 131 Once the criteria has been
 132 met, these sockets will be moved over into the completed connection
 133 queue to be
 134 .Xr accept 2 Ns ed .
 135 If this secondary queue is full and a
 136 new connection comes in, the oldest socket which has not yet met
 137 its accept filter criteria will be terminated.
 138 .Pp
 139 This secondary queue, like the primary listen queue, is sized
 140 according to the
 141 .Fa backlog
 142 argument.
 143 .Sh RETURN VALUES
 144 .Rv -std listen
 145 .Sh ERRORS
 146 The
 147 .Fn listen
 148 system call
 149 will fail if:
 150 .Bl -tag -width Er
 151 .It Bq Er EBADF
 152 The argument
 153 .Fa s
 154 is not a valid descriptor.
 155 .It Bq Er EDESTADDRREQ
 156 The socket is not bound to a local address, and the protocol does not
 157 support listening on an unbound socket.
 158 .It Bq Er EINVAL
 159 The socket is already connected, or in the process of being connected.
 160 .It Bq Er ENOTSOCK
 161 The argument
 162 .Fa s
 163 is not a socket.
 164 .It Bq Er EOPNOTSUPP
 165 The socket is not of a type that supports the operation
 166 .Fn listen .
 167 .El
 168 .Sh SEE ALSO
 169 .Xr netstat 1 ,
 170 .Xr accept 2 ,
 171 .Xr connect 2 ,
 172 .Xr socket 2 ,
 173 .Xr sysctl 3 ,
 174 .Xr syslog 3 ,
 175 .Xr sysctl 8 ,
 176 .Xr accept_filter 9
 177 .Sh HISTORY
 178 The
 179 .Fn listen
 180 system call appeared in
 181 .Bx 4.2 .
 182 The ability to configure the maximum
 183 .Fa backlog
 184 at run-time, and to use a negative
 185 .Fa backlog
 186 to request the maximum allowable value, was introduced in
 187 .Fx 2.2 .
 188 The
 189 .Va kern.ipc.somaxconn
 190 .Xr sysctl 3
 191 has been replaced with
 192 .Va kern.ipc.soacceptqueue
 193 in
 194 .Fx 10.0
 195 to prevent confusion about its actual functionality.
 196 The original
 197 .Xr sysctl 3
 198 .Va kern.ipc.somaxconn
 199 is still available but hidden from a
 200 .Xr sysctl 3
 201 -a output so that existing applications and scripts continue to work.