NAME

       listen — listen for connections on a socket

LIBRARY

       Standard C Library (libc, -lc)

SYNOPSIS

       #include <sys/types.h>
       #include <sys/socket.h>

       int
       listen(int s, int backlog);

DESCRIPTION

       To  accept  connections,  a  socket  is  first  created  with socket(2), a willingness to accept incoming
       connections and a queue limit for  incoming  connections  are  specified  with  listen(),  and  then  the
       connections  are  accepted  with  accept(2).   The  listen()  system call applies only to sockets of type
       SOCK_STREAM or SOCK_SEQPACKET.

       The backlog argument defines the maximum length the queue of pending connections may grow to.   The  real
       maximum  queue  length  will  be  1.5  times  more  than  the value specified in the backlog argument.  A
       subsequent listen() system call on the listening socket allows the caller to  change  the  maximum  queue
       length  using a new backlog argument.  If a connection request arrives with the queue full the client may
       receive an error with an indication of ECONNREFUSED, or, in the case  of  TCP,  the  connection  will  be
       silently dropped.

       Current queue lengths of listening sockets can be queried using netstat(1) command.

       Note  that  before FreeBSD 4.5 and the introduction of the syncache, the backlog argument also determined
       the length of the incomplete connection queue, which held TCP sockets in the process of completing  TCP's
       3-way handshake.  These incomplete connections are now held entirely in the syncache, which is unaffected
       by  queue  lengths.   Inflated  backlog  values  to  help  handle denial of service attacks are no longer
       necessary.

       The sysctl(3) MIB variable kern.ipc.somaxconn specifies a hard limit on backlog; if a value greater  than
       kern.ipc.somaxconn or less than zero is specified, backlog is silently forced to kern.ipc.somaxconn.

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 met their accept filtering criteria.  Once the criteria has been  met,  these
       sockets  will  be  moved  over  into the completed connection queue to be accept(2)ed.  If this secondary
       queue is full and a new connection comes in, the oldest socket which has not yet met  its  accept  filter
       criteria will be terminated.

       This secondary queue, like the primary listen queue, is sized according to the backlog argument.

RETURN VALUES

       The  listen()  function  returns  the  value  0 if successful; otherwise the value -1 is returned and the
       global variable errno is set to indicate the error.

ERRORS

       The listen() system call will fail if:

       [EBADF]            The argument s is not a valid descriptor.

       [EINVAL]           The socket is already connected, or in the process of being connected.

       [ENOTSOCK]         The argument s is not a socket.

       [EOPNOTSUPP]       The socket is not of a type that supports the operation listen().

SEE ALSO

       netstat(1), accept(2), connect(2), socket(2), sysctl(3), sysctl(8), accept_filter(9)

HISTORY

       The listen() system call appeared in 4.2BSD.  The ability to configure the maximum backlog  at  run-time,
       and to use a negative backlog to request the maximum allowable value, was introduced in FreeBSD 2.2.

Debian                                           August 29, 2005                                       LISTEN(2)