Debian Codegraph @

upstream/debian-trixie/man2/listen.2

raw
1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" and Copyright (C) 2007, Michael Kerrisk <[email protected]>
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 <[email protected]>
10 .\" Modified 950727 by aeb, following a suggestion by Urs Thuermann
11 .\" <[email protected]>
12 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <[email protected]>
13 .\" Modified 1998 by Andi Kleen
14 .\" Modified 11 May 2001 by Sam Varshavchik <[email protected]>
15 .\"
16 .\"
17 .TH listen 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
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 .P
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 .P
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-2008.
94 .SH HISTORY
95 POSIX.1-2001, 4.4BSD
96 (first appeared in 4.2BSD).
97 .SH NOTES
98 To accept connections, the following steps are performed:
99 .RS 4
100 .IP (1) 5
101 A socket is created with
102 .BR socket (2).
103 .IP (2)
104 The socket is bound to a local address using
105 .BR bind (2),
106 so that other sockets may be
107 .BR connect (2)ed
108 to it.
109 .IP (3)
110 A willingness to accept incoming connections and a queue limit for incoming
111 connections are specified with
112 .BR listen ().
113 .IP (4)
114 Connections are accepted with
115 .BR accept (2).
116 .RE
117 .P
118 The behavior of the
119 .I backlog
120 argument on TCP sockets changed with Linux 2.2.
121 Now it specifies the queue length for
122 .I completely
123 established sockets waiting to be accepted,
124 instead of the number of incomplete connection requests.
125 The maximum length of the queue for incomplete sockets
126 can be set using
127 .IR /proc/sys/net/ipv4/tcp_max_syn_backlog .
128 When syncookies are enabled there is no logical maximum
129 length and this setting is ignored.
130 See
131 .BR tcp (7)
132 for more information.
133 .P
134 If the
135 .I backlog
136 argument is greater than the value in
137 .IR /proc/sys/net/core/somaxconn ,
138 then it is silently capped to that value.
139 Since Linux 5.4, the default in this file is 4096;
140 in earlier kernels, the default value is 128.
141 Before Linux 2.4.25, this limit was a hard coded value,
142 .BR SOMAXCONN ,
143 with the value 128.
144 .\" The following is now rather historic information (MTK, Jun 05)
145 .\" Don't rely on this value in portable applications since BSD
146 .\" (and some BSD-derived systems) limit the backlog to 5.
147 .SH EXAMPLES
148 See
149 .BR bind (2).
150 .SH SEE ALSO
151 .BR accept (2),
152 .BR bind (2),
153 .BR connect (2),
154 .BR socket (2),
155 .BR socket (7)