'\" te
.\"  Copyright 1989 AT&T
.\" Copyright (C) 1999, Sun Microsystems,
.\" Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LISTEN 3SOCKET "Nov 8, 1999"
.SH NAME
listen \- listen for connections on a socket
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
#include <sys/types.h>
#include <sys/socket.h>

\fBint\fR \fBlisten\fR(\fBint\fR \fIs\fR, \fBint\fR \fIbacklog\fR);
.fi

.SH DESCRIPTION
.sp
.LP
To accept connections, a socket is first created with  \fBsocket\fR(3SOCKET), a
backlog for incoming connections is specified with \fBlisten()\fR and then the
connections are accepted with  \fBaccept\fR(3SOCKET). The \fBlisten()\fR call
applies only to sockets of type \fBSOCK_STREAM\fR or \fBSOCK_SEQPACKET\fR.
.sp
.LP
The \fIbacklog\fR parameter defines the maximum length the queue of pending
connections may grow to.
.sp
.LP
If a connection request arrives with the queue full, the client will receive an
error with an indication of \fBECONNREFUSED\fR for  \fBAF_UNIX\fR sockets. If
the underlying protocol supports retransmission,  the connection request may be
ignored so that retries may succeed. For \fBAF_INET\fR and
\fBAF_INET6\fRsockets, the \fBTCP\fR will retry the connection. If the
\fIbacklog\fR is not cleared by the time the tcp times out, the connect will
fail with \fBETIMEDOUT\fR.
.SH RETURN VALUES
.sp
.LP
A \fB0\fR return value indicates success; \fB\(mi1\fR indicates an error.
.SH ERRORS
.sp
.LP
The call fails if:
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 14n
The argument \fIs\fR is not a valid file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBENOTSOCK\fR\fR
.ad
.RS 14n
The argument \fIs\fR is not a socket.
.RE

.sp
.ne 2
.na
\fB\fBEOPNOTSUPP\fR\fR
.ad
.RS 14n
The socket is not of a type that supports the operation \fBlisten()\fR.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBaccept\fR(3SOCKET), \fBconnect\fR(3SOCKET), \fBsocket\fR(3SOCKET),
\fBattributes\fR(5), \fBsocket.h\fR(3HEAD)
.SH NOTES
.sp
.LP
There is currently no \fIbacklog\fR limit.