1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 1999, Sun Microsystems,
   4 .\" Inc. All Rights Reserved
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH LISTEN 3SOCKET "Nov 8, 1999"
   9 .SH NAME
  10 listen \- listen for connections on a socket
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  15 #include <sys/types.h>
  16 #include <sys/socket.h>
  17 
  18 \fBint\fR \fBlisten\fR(\fBint\fR \fIs\fR, \fBint\fR \fIbacklog\fR);
  19 .fi
  20 
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 To accept connections, a socket is first created with  \fBsocket\fR(3SOCKET), a
  25 backlog for incoming connections is specified with \fBlisten()\fR and then the
  26 connections are accepted with  \fBaccept\fR(3SOCKET). The \fBlisten()\fR call
  27 applies only to sockets of type \fBSOCK_STREAM\fR or \fBSOCK_SEQPACKET\fR.
  28 .sp
  29 .LP
  30 The \fIbacklog\fR parameter defines the maximum length the queue of pending
  31 connections may grow to.
  32 .sp
  33 .LP
  34 If a connection request arrives with the queue full, the client will receive an
  35 error with an indication of \fBECONNREFUSED\fR for  \fBAF_UNIX\fR sockets. If
  36 the underlying protocol supports retransmission,  the connection request may be
  37 ignored so that retries may succeed. For \fBAF_INET\fR and
  38 \fBAF_INET6\fRsockets, the \fBTCP\fR will retry the connection. If the
  39 \fIbacklog\fR is not cleared by the time the tcp times out, the connect will
  40 fail with \fBETIMEDOUT\fR.
  41 .SH RETURN VALUES
  42 .sp
  43 .LP
  44 A \fB0\fR return value indicates success; \fB\(mi1\fR indicates an error.
  45 .SH ERRORS
  46 .sp
  47 .LP
  48 The call fails if:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBEBADF\fR\fR
  53 .ad
  54 .RS 14n
  55 The argument \fIs\fR is not a valid file descriptor.
  56 .RE
  57 
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBENOTSOCK\fR\fR
  62 .ad
  63 .RS 14n
  64 The argument \fIs\fR is not a socket.
  65 .RE
  66 
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBEOPNOTSUPP\fR\fR
  71 .ad
  72 .RS 14n
  73 The socket is not of a type that supports the operation \fBlisten()\fR.
  74 .RE
  75 
  76 .SH ATTRIBUTES
  77 .sp
  78 .LP
  79 See \fBattributes\fR(5) for descriptions of the following attributes:
  80 .sp
  81 
  82 .sp
  83 .TS
  84 box;
  85 c | c
  86 l | l .
  87 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  88 _
  89 MT-Level        Safe
  90 .TE
  91 
  92 .SH SEE ALSO
  93 .sp
  94 .LP
  95 \fBaccept\fR(3SOCKET), \fBconnect\fR(3SOCKET), \fBsocket\fR(3SOCKET),
  96 \fBattributes\fR(5), \fBsocket.h\fR(3HEAD)
  97 .SH NOTES
  98 .sp
  99 .LP
 100 There is currently no \fIbacklog\fR limit.