= nng_stream_listener_listen(3str)
//
// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
// Copyright 2019 Devolutions <info@devolutions.net>
//
// 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_stream_listener_listen - bind listener to configured address

== SYNOPSIS

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

int nng_stream_listener_listen(nng_stream_listener *l);
----

== DESCRIPTION

The `nng_stream_listener_listen()` attempts to bind the listener _l_
to the local address specified when the listener was created.

This must generally be done before accepting incoming connections using
xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`].

For some transports this will also perform other actiosn.  For example,
with TCP listeners it will configure the 
underlying port into passive mode, ready to
accept an incoming connection, and established a listen queue
for receiving incoming connections.

If binding the listener requires allocation of an address (for example
when a TCP port number of zero is specified, indicating that an
ephemeral port should be used), this operation will allocate that
resource.
This can permit retrieval of the selected address using
xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`],
typically with the
xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option.

== RETURN VALUES

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

== ERRORS

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

== SEE ALSO

[.text-left]
xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_stream_listener.5.adoc[nng_stream_listener(5)]
