copyediting for Usenix manuals

[unix-history] / usr / src / lib / libc / sys / listen.2

.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)listen.2	8.2 (Berkeley) %G%
.\"
.Dd 
.Dt LISTEN 2
.Os BSD 4.2
.Sh NAME
.Nm listen
.Nd listen for connections on a socket
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Ft int
.Fn listen "int s" "int backlog"
.Sh DESCRIPTION
To accept connections, a socket
is first created with
.Xr socket 2 ,
a willingness to accept incoming connections and
a queue limit for incoming connections are specified with
.Fn listen ,
and then the connections are
accepted with
.Xr accept 2 .
The
.Fn listen
call applies only to sockets of type
.Dv SOCK_STREAM
or
.Dv SOCK_SEQPACKET.
.Pp
The
.Fa backlog
parameter defines the maximum length the queue of
pending connections may grow to.
If a connection
request arrives with the queue full the client may
receive an error with an indication of
.Er ECONNREFUSED ,
or, if the underlying protocol supports retransmission,
the request may be ignored so that retries may succeed.
.Sh RETURN VALUES
A 0 return value indicates success; -1 indicates an error.
.Sh ERRORS
.Fn Listen 
will fail if:
.Bl -tag -width [EOPNOTSUPP]
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is not a socket.
.It Bq Er EOPNOTSUPP
The socket is not of a type that supports the operation
.Fn listen .
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr connect 2 ,
.Xr socket 2
.Sh BUGS
The
.Fa backlog
is currently limited (silently) to 5.
.Sh HISTORY
The
.Nm
function call appeared in
.Bx 4.2 .