man2/listen.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" All rights reserved.
   4 .\"
   5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   6 .\"
   7 .\"     $Id: listen.2,v 1.6 1999/05/18 14:10:32 freitag Exp $
   8 .\"
   9 .\" Modified Fri Jul 23 22:07:54 1993 by Rik Faith <faith@cs.unc.edu>
  10 .\" Modified 950727 by aeb, following a suggestion by Urs Thuermann
  11 .\" <urs@isnogud.escape.de>
  12 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  13 .\" Modified 1998 by Andi Kleen
  14 .\" Modified 11 May 2001 by Sam Varshavchik <mrsam@courier-mta.com>
  15 .\"
  16 .\"
  17 .TH LISTEN 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  18 .SH NAME
  19 listen \- listen for connections on a socket
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <sys/socket.h>
  26 .PP
  27 .BI "int listen(int " sockfd ", int " backlog );
  28 .fi
  29 .SH DESCRIPTION
  30 .BR listen ()
  31 marks the socket referred to by
  32 .I sockfd
  33 as a passive socket, that is, as a socket that will
  34 be used to accept incoming connection requests using
  35 .BR accept (2).
  36 .PP
  37 The
  38 .I sockfd
  39 argument is a file descriptor that refers to a socket of type
  40 .B SOCK_STREAM
  41 or
  42 .BR SOCK_SEQPACKET .
  43 .PP
  44 The
  45 .I backlog
  46 argument defines the maximum length
  47 to which the queue of pending connections for
  48 .I sockfd
  49 may grow.
  50 If a connection request arrives when the queue is full, the client
  51 may receive an error with an indication of
  52 .B ECONNREFUSED
  53 or, if the underlying protocol supports retransmission, the request may be
  54 ignored so that a later reattempt at connection succeeds.
  55 .SH RETURN VALUE
  56 On success, zero is returned.
  57 On error, \-1 is returned, and
  58 .I errno
  59 is set to indicate the error.
  60 .SH ERRORS
  61 .TP
  62 .B EADDRINUSE
  63 Another socket is already listening on the same port.
  64 .TP
  65 .B EADDRINUSE
  66 (Internet domain sockets)
  67 The socket referred to by
  68 .I sockfd
  69 had not previously been bound to an address and,
  70 upon attempting to bind it to an ephemeral port,
  71 it was determined that all port numbers in the ephemeral port range
  72 are currently in use.
  73 See the discussion of
  74 .I /proc/sys/net/ipv4/ip_local_port_range
  75 in
  76 .BR ip (7).
  77 .TP
  78 .B EBADF
  79 The argument
  80 .I sockfd
  81 is not a valid file descriptor.
  82 .TP
  83 .B ENOTSOCK
  84 The file descriptor
  85 .I sockfd
  86 does not refer to a socket.
  87 .TP
  88 .B EOPNOTSUPP
  89 The socket is not of a type that supports the
  90 .BR listen ()
  91 operation.
  92 .SH STANDARDS
  93 POSIX.1-2001, POSIX.1-2008, 4.4BSD
  94 .RB ( listen ()
  95 first appeared in 4.2BSD).
  96 .SH NOTES
  97 To accept connections, the following steps are performed:
  98 .RS 4
  99 .IP 1. 4
 100 A socket is created with
 101 .BR socket (2).
 102 .IP 2.
 103 The socket is bound to a local address using
 104 .BR bind (2),
 105 so that other sockets may be
 106 .BR connect (2)ed
 107 to it.
 108 .IP 3.
 109 A willingness to accept incoming connections and a queue limit for incoming
 110 connections are specified with
 111 .BR listen ().
 112 .IP 4.
 113 Connections are accepted with
 114 .BR accept (2).
 115 .RE
 116 .PP
 117 The behavior of the
 118 .I backlog
 119 argument on TCP sockets changed with Linux 2.2.
 120 Now it specifies the queue length for
 121 .I completely
 122 established sockets waiting to be accepted,
 123 instead of the number of incomplete connection requests.
 124 The maximum length of the queue for incomplete sockets
 125 can be set using
 126 .IR /proc/sys/net/ipv4/tcp_max_syn_backlog .
 127 When syncookies are enabled there is no logical maximum
 128 length and this setting is ignored.
 129 See
 130 .BR tcp (7)
 131 for more information.
 132 .PP
 133 If the
 134 .I backlog
 135 argument is greater than the value in
 136 .IR /proc/sys/net/core/somaxconn ,
 137 then it is silently capped to that value.
 138 Since Linux 5.4, the default in this file is 4096;
 139 in earlier kernels, the default value is 128.
 140 In kernels before 2.4.25, this limit was a hard coded value,
 141 .BR SOMAXCONN ,
 142 with the value 128.
 143 .\" The following is now rather historic information (MTK, Jun 05)
 144 .\" Don't rely on this value in portable applications since BSD
 145 .\" (and some BSD-derived systems) limit the backlog to 5.
 146 .SH EXAMPLES
 147 See
 148 .BR bind (2).
 149 .SH SEE ALSO
 150 .BR accept (2),
 151 .BR bind (2),
 152 .BR connect (2),
 153 .BR socket (2),
 154 .BR socket (7)