1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved.
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd August 2, 2018
  23 .Dt LISTEN 3C
  24 .Os
  25 .Sh NAME
  26 .Nm listen
  27 .Nd listen for connections on a socket
  28 .Sh LIBRARY
  29 .Lb libc
  30 .Sh SYNOPSIS
  31 .In sys/types.h
  32 .In sys/socket.h
  33 .Ft int
  34 .Fo listen
  35 .Fa "int s"
  36 .Fa "int backlog"
  37 .Fc
  38 .Sh DESCRIPTION
  39 To accept connections, a socket is first created with
  40 .Xr socket 3C ,
  41 a backlog for incoming connections is specified with
  42 .Fn listen
  43 and then the connections are accepted with
  44 .Xr accept 3C .
  45 The
  46 .Fn listen
  47 call applies only to sockets of type
  48 .Dv SOCK_STREAM
  49 or
  50 .Dv SOCK_SEQPACKET .
  51 .Pp
  52 The
  53 .Fa backlog
  54 parameter defines the maximum length the queue of pending connections may grow
  55 to.
  56 .Pp
  57 If a connection request arrives with the queue full, the client will receive an
  58 error with an indication of
  59 .Er ECONNREFUSED
  60 for
  61 .Dv AF_UNIX
  62 sockets.
  63 If the underlying protocol supports retransmission, the connection request may
  64 be ignored so that retries may succeed.
  65 For
  66 .Dv AF_INET
  67 and
  68 .Dv AF_INET6
  69 sockets, the TCP will retry the connection.
  70 If the
  71 .Fa backlog
  72 is not cleared by the time the tcp times out, the connect will fail with
  73 .Er ETIMEDOUT .
  74 .Sh RETURN VALUES
  75 A 0 return value indicates success; -1 indicates an error.
  76 .Sh ERRORS
  77 The call fails if:
  78 .Bl -tag -width Er
  79 .It Bq Er EBADF
  80 The argument
  81 .Fa s
  82 is not a valid file descriptor.
  83 .It Bq Er ENOTSOCK
  84 The argument
  85 .Fa s
  86 is not a socket.
  87 .It Bq Er EOPNOTSUPP
  88 The socket is not of a type that supports the operation
  89 .Fn listen .
  90 .El
  91 .Sh MT-LEVEL
  92 .Sy Safe
  93 .Sh SEE ALSO
  94 .Xr accept 3C ,
  95 .Xr connect 3C ,
  96 .Xr socket 3C ,
  97 .Xr socket.h 3HEAD ,
  98 .Xr attributes 5
  99 .Sh NOTES
 100 There is currently no
 101 .Fa backlog
 102 limit.