.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	From: @(#)listen.2	8.2 (Berkeley) 12/11/93
.\" %FreeBSD: src/lib/libc/sys/listen.2,v 1.27 2003/01/17 19:25:27 tmm Exp %
.\"
.\" $FreeBSD$
.\" WORD: 3-way handshake	3 ウェイハンドシェーク (tcpdump.1)
.Dd May 8, 2002
.Dt LISTEN 2
.Os
.Sh 名称
.Nm listen
.Nd ソケット上の接続をリスンする
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In sys/socket.h
.Ft int
.Fn listen "int s" "int backlog"
.Sh 解説
.Xr socket 2
で最初にソケットが作成され、
着信接続を受け入れる意思および着信接続用の待ち行列限界が
.Fn listen
で指定された後、接続が
.Xr accept 2
で受け入れられます。
.Fn listen
システムコールは、タイプが
.Dv SOCK_STREAM
または
.Dv SOCK_SEQPACKET
のソケットにだけ適用されます。
.Pp
.Fa backlog
引数は、延期中の接続の待ち行列を伸ばす際の最大長を定義します。
待ち行列が満杯のときに接続要求が到着すると、クライアントは
.Er ECONNREFUSED
を示すエラーを受信する可能性があります。
TCP の場合は、接続は黙って落とされます。
.Pp
.Fx 4.5
以前で syncache が導入されるまでは、
.Fa backlog
引数は不完全な接続の待ち行列の長さも定義していました。
この待ち行列には、TCP の 3 ウェイハンドシェークを完了させるべく処理中の
TCP ソケットが保持されています。
これらの不完全な接続は、現在すべて syncache に保持され、
これは待ち行列の長さに影響されません。
.Fa backlog
値を増やすことによりサービス不能攻撃に対処する必要は、もはやありません。
.Pp
.Xr sysctl 3
MIB 変数
.Dq Va kern.ipc.somaxconn
は
.Fa backlog
のハードリミットを指定します。
.Va kern.ipc.somaxconn
より大きい値、または 0 より小さい値が指定されている場合、
.Fa backlog
の指定は無視されて
.Va kern.ipc.somaxconn
の値にされます。
.Sh ACCEPT フィルタとの相互作用
ソケットに対して accept フィルタを使用すると、
接続済みであるものの accept フィルタの基準にまだ合致しないソケットを
保持するための第 2 の待ち行列が使用されます。
ひとたび基準に合致すれば、これらのソケットは接続完了済の待ち行列に移動され、
.Xr accept 2
の対象になります。
第 2 の待ち行列が満杯のときに新規接続が到着すると、
accept フィルタの基準にまだ合致しない最古のソケットが終了されます。
.Pp
この第 2 の待ち行列は、第 1 の listen 待ち行列のように、
.Fa backlog
引数に従って大きさが変わります。
.Sh 戻り値
.Rv -std listen
.Sh エラー
.Fn listen
システムコールは次の場合に処理を失敗します:
.Bl -tag -width Er
.It Bq Er EBADF
引数
.Fa s
が有効な記述子ではありません。
.It Bq Er EINVAL
そのソケットはすでに接続されているか、接続確立中です。
.It Bq Er ENOTSOCK
引数
.Fa s
がソケットではありません。
.It Bq Er EOPNOTSUPP
ソケットが、
.Fn listen
をサポートするタイプではありません。
.El
.Sh 関連項目
.Xr accept 2 ,
.Xr connect 2 ,
.Xr socket 2 ,
.Xr sysctl 3 ,
.Xr sysctl 8 ,
.Xr accept_filter 9
.Sh 歴史
.Fn listen
システムコールは
.Bx 4.2
で登場しました。
実行時に最大
.Fa backlog
を設定できる機能、および許容できる最大値を指定する場合に負の
.Fa backlog
を使用する機能は
.Fx 2.2
で登場しました。