The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> listen - listen for socket connections and limit the queue of incoming connections

#### SYNOPSIS

> ``#include <sys/socket.h>
> int listen(int` socket`, int` backlog`);
> ``

#### DESCRIPTION

> The listen() function shall mark a connection-mode socket, specified by the socket argument, as accepting connections.

> The backlog argument provides a hint to the implementation which the implementation shall use to limit the number of outstanding connections in the socket's listen queue. Implementations may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog argument value shall result in a larger or equal length of the listen queue. Implementations shall support values of backlog up to SOMAXCONN, defined in <sys/socket.h>.

> The implementation may include incomplete connections in its listen queue. The limits on the number of incomplete connections and completed connections queued may be different.

> The implementation may have an upper limit on the length of the listen queue-either global or per accepting socket. If backlog exceeds this limit, the length of the listen queue is set to the limit.

> If listen() is called with a backlog argument value that is less than 0, the function behaves as if it had been called with a backlog argument value of 0.

> A backlog argument of 0 may allow the socket to accept connections, in which case the length of the listen queue may be set to an implementation-defined minimum value.

> The socket in use may require the process to have appropriate privileges to use the listen() function.

#### RETURN VALUE

> Upon successful completions, listen() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.

#### ERRORS

> The listen() function shall fail if:

> [EBADF]
>   The socket argument is not a valid file descriptor.
> [EDESTADDRREQ]
>   The socket is not bound to a local address, and the protocol does not support listening on an unbound socket.
> [EINVAL]
>   The socket is already connected.
> [ENOTSOCK]
>   The socket argument does not refer to a socket.
> [EOPNOTSUPP]
>   The socket protocol does not support listen().

> The listen() function may fail if:

> [EACCES]
>   The calling process does not have appropriate privileges.
> [EINVAL]
>   The socket has been shut down.
> [ENOBUFS]
>   Insufficient resources are available in the system to complete the call.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> accept, connect, socket

> XBD <sys/socket.h>

#### CHANGE HISTORY

> First released in Issue 6. Derived from the XNS, Issue 5.2 specification.

> The DESCRIPTION is updated to describe the relationship of SOMAXCONN and the backlog argument.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]