]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
1e48734a | 2 | .\" and Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
3 | .\" All rights reserved. |
4 | .\" | |
47009d5e | 5 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
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> | |
c13182ef | 13 | .\" Modified 1998 by Andi Kleen |
fea681da | 14 | .\" Modified 11 May 2001 by Sam Varshavchik <mrsam@courier-mta.com> |
4989f80d | 15 | .\" |
fea681da | 16 | .\" |
45186a5d | 17 | .TH LISTEN 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
18 | .SH NAME |
19 | listen \- listen for connections on a socket | |
cebb3690 AC |
20 | .SH LIBRARY |
21 | Standard C library | |
8fc3b2cf | 22 | .RI ( libc ", " \-lc ) |
fea681da | 23 | .SH SYNOPSIS |
53a6b01d | 24 | .nf |
fea681da | 25 | .B #include <sys/socket.h> |
68e4db0a | 26 | .PP |
3e6b03a0 | 27 | .BI "int listen(int " sockfd ", int " backlog ); |
53a6b01d | 28 | .fi |
fea681da | 29 | .SH DESCRIPTION |
1e48734a MK |
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 | |
fea681da | 35 | .BR accept (2). |
efeece04 | 36 | .PP |
fea681da | 37 | The |
1e48734a MK |
38 | .I sockfd |
39 | argument is a file descriptor that refers to a socket of type | |
fea681da MK |
40 | .B SOCK_STREAM |
41 | or | |
42 | .BR SOCK_SEQPACKET . | |
efeece04 | 43 | .PP |
fea681da MK |
44 | The |
45 | .I backlog | |
1e48734a MK |
46 | argument defines the maximum length |
47 | to which the queue of pending connections for | |
cf0961b0 | 48 | .I sockfd |
1e48734a MK |
49 | may grow. |
50 | If a connection request arrives when the queue is full, the client | |
fea681da MK |
51 | may receive an error with an indication of |
52 | .B ECONNREFUSED | |
53 | or, if the underlying protocol supports retransmission, the request may be | |
1e48734a | 54 | ignored so that a later reattempt at connection succeeds. |
47297adb | 55 | .SH RETURN VALUE |
c13182ef MK |
56 | On success, zero is returned. |
57 | On error, \-1 is returned, and | |
fea681da | 58 | .I errno |
f6a4078b | 59 | is set to indicate the error. |
fea681da MK |
60 | .SH ERRORS |
61 | .TP | |
62 | .B EADDRINUSE | |
63 | Another socket is already listening on the same port. | |
64 | .TP | |
cbe3d857 MK |
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 | |
fea681da MK |
78 | .B EBADF |
79 | The argument | |
3e6b03a0 | 80 | .I sockfd |
d9cb0d7d | 81 | is not a valid file descriptor. |
fea681da MK |
82 | .TP |
83 | .B ENOTSOCK | |
deedfd97 | 84 | The file descriptor |
3e6b03a0 | 85 | .I sockfd |
deedfd97 | 86 | does not refer to a socket. |
fea681da MK |
87 | .TP |
88 | .B EOPNOTSUPP | |
89 | The socket is not of a type that supports the | |
884dda7b | 90 | .BR listen () |
fea681da | 91 | operation. |
3113c7f3 | 92 | .SH STANDARDS |
1ce7f0f2 | 93 | POSIX.1-2001, POSIX.1-2008, 4.4BSD |
89818883 MK |
94 | .RB ( listen () |
95 | first appeared in 4.2BSD). | |
a1d5f77c | 96 | .SH NOTES |
1e48734a MK |
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 | |
d9bfdb9c | 117 | The behavior of the |
a1d5f77c | 118 | .I backlog |
c4bb193f | 119 | argument on TCP sockets changed with Linux 2.2. |
a1d5f77c MK |
120 | Now it specifies the queue length for |
121 | .I completely | |
5edee420 MK |
122 | established sockets waiting to be accepted, |
123 | instead of the number of incomplete connection requests. | |
a1d5f77c | 124 | The maximum length of the queue for incomplete sockets |
5a2ff571 MK |
125 | can be set using |
126 | .IR /proc/sys/net/ipv4/tcp_max_syn_backlog . | |
a1d5f77c | 127 | When syncookies are enabled there is no logical maximum |
5a2ff571 | 128 | length and this setting is ignored. |
a1d5f77c MK |
129 | See |
130 | .BR tcp (7) | |
131 | for more information. | |
efeece04 | 132 | .PP |
5edee420 | 133 | If the |
fea681da | 134 | .I backlog |
5edee420 | 135 | argument is greater than the value in |
1197dd11 | 136 | .IR /proc/sys/net/core/somaxconn , |
46b47023 | 137 | then it is silently capped to that value. |
f44b0329 MK |
138 | Since Linux 5.4, the default in this file is 4096; |
139 | in earlier kernels, the default value is 128. | |
5edee420 MK |
140 | In kernels before 2.4.25, this limit was a hard coded value, |
141 | .BR SOMAXCONN , | |
142 | with the value 128. | |
884dda7b MK |
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. | |
a14af333 | 146 | .SH EXAMPLES |
f11e5e44 MK |
147 | See |
148 | .BR bind (2). | |
47297adb | 149 | .SH SEE ALSO |
fea681da | 150 | .BR accept (2), |
884dda7b | 151 | .BR bind (2), |
fea681da | 152 | .BR connect (2), |
5dfedcae MK |
153 | .BR socket (2), |
154 | .BR socket (7) |