= nng_tcp_listener_listen(3tcp)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_tcp_listener_listen - bind listener to TCP port

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>
#include <nng/supplemental/tcp/tcp.h>

int nng_tcp_listener_listen(nng_tcp_listener l, nng_sockaddr *sa);
----

== DESCRIPTION

The `nng_tcp_listener_listen()` attempts to bind the listener _l_
to the local address specified by _sa_, which must be in the
`NNG_AF_INET` or `NNG_AF_INET6` address family.

This also sets the underlying port into passive mode, ready to
accept an incoming connection, and established a listen queue
for receiving incoming connections.  (The queue depth is system
specific, but typically 128.)

The actual IPv4 or IPv6 address in _sa_ may refer either to a locally
configured interface address, or to a zero-valued adddress to indicate
that all interfaces on the system should be bound.

The TCP port number may also be zero.  In this case the system will
choose a free TCP port at random, and use it.
The _sa_ will be updated with the port chosen.

== RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

== ERRORS

[horizontal]
`NNG_EADDRINUSE`:: The address specified by _sa_ is already in use.
`NNG_EADDRINVAL`:: The address specified by _sa_ is invalid or unavailable.
`NNG_ECLOSED`:: The listener _l_ has been closed.
`NNG_ESTATE`:: The listener _l_ is already bound.

== SEE ALSO

[.text-left]
<<nng_strerror.3#,nng_strerror(3)>>,
<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>,
<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>,
<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>,
<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>,
<<nng_sockaddr.5#,nng_sockaddr(5)>>,
<<nng_tcp_listener.5#,nng_tcp_listener(5)>>
