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 20.
If any other value is specified, the system automatically assigns
the closest value within the range. A
backlog
of 0 specifies only 1 pending connection is allowed at any given
time.
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 (see
socketx25(7)).
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))
MULTITHREAD USAGE
The
listen()
system call is thread-safe.
It has a cancellation point; and
it is async-cancel safe, async-signal safe, and fork-safe.
AUTHOR
listen()
was developed by HP and the University of California, Berkeley.
STANDARDS CONFORMANCE
listen(): XPG4
