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