Debian Codegraph @

upstream/debian-unstable/man2/listen.2

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