NAME
listen — listen for connections on a socket
SYNOPSIS
#include <sys/socket.h>
int listen(int s, int backlog);
DESCRIPTION
To accept connections, a socket is first created using
socket(),
a queue for incoming connections is activated using
listen(),
and then connections are accepted using
accept().
listen()
applies only to unconnected sockets of type
SOCK_STREAM.
Except for AF_VME_LINK, if the socket has not been bound to a local port before
listen()
is invoked, the system automatically binds a local port
for the socket to listen on (see
inet(7F)).
For sockets in the address family
AF_CCITT and AF_VME_LINK,
the socket
must
be bound to an address by using
bind()
before connection establishment can continue, otherwise an
EADDREQUIRED
error is returned.
A listen queue is established for the socket specified by the
s
parameter, which is a socket descriptor.
backlog
defines the desirable queue length for pending connections.
The actual queue length may be greater than the specified
backlog.
If a connection request arrives
when the queue is full,
the client will receive an
ETIMEDOUT
error.
backlog
is limited to the range of 0 to
SOMAXCONN,
which is defined in
<sys/socket.h>.
SOMAXCONN
is currently set to 4096.
If any other value is specified, the system automatically assigns
the closest value within the range. Note that for
HP-UX BSD Sockets,
a
backlog
of 0 specifies only 1 pending connection is allowed at any given time.
For
X/Open Sockets,
a
backlog
of 0 specifies no further connection is allowed.
DEPENDENCIES
AF_CCITT
Call-acceptance can be controlled by the
X25_CALL_ACPT_APPROVAL
ioctl()
call described in
RETURN VALUE.
Upon successful completion,
listen()
returns 0; otherwise, it returns -1 and sets
errno
to indicate the error.
ERRORS
listen()
fails if any of the following conditions are encountered:
- EBADF
s
is not a valid file descriptor.
- EDESTADDRREQ
The socket
s
has not been bound to an address by using
bind().
- ENOTSOCK
s
is a valid file descriptor but it is not a socket.
- EOPNOTSUPP
The socket referenced by
s
does not support
listen().
- EINVAL
The socket has been shut down or is already connected.
WARNINGS
Linking binary objects compiled to
X/Open Sockets
specification and binary objects compiled to
HP-UX BSD Sockets
specification to the same executable may result in unexpected behavior,
including application abnormal termination and unexpected socket errors.
See
xopen_networking(7)
for details and remedy.
FUTURE DIRECTION
Currently, the default behavior is the
HP-UX BSD Sockets;
however, it might be changed to
X/Open Sockets
in a future release.
At that time, any
HP-UX BSD Sockets
behavior that is incompatible with
X/Open Sockets
might be obsoleted.
Applications that conform to the
X/Open specification now
will avoid migration problems (see
xopen_networking(7)).
AUTHOR
listen()
was developed by HP and the University of California, Berkeley.
STANDARDS CONFORMANCE
listen(): XPG4, UNIX 95, UNIX 03
Printable version
