diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/libnng.3.adoc | 5 | ||||
| -rw-r--r-- | docs/man/nng_ctx.5.adoc | 9 | ||||
| -rw-r--r-- | docs/man/nng_ctx_id.3.adoc | 50 | ||||
| -rw-r--r-- | docs/man/nng_dialer.5.adoc | 7 | ||||
| -rw-r--r-- | docs/man/nng_dialer_id.3.adoc | 51 | ||||
| -rw-r--r-- | docs/man/nng_listener.5.adoc | 7 | ||||
| -rw-r--r-- | docs/man/nng_listener_id.3.adoc | 51 | ||||
| -rw-r--r-- | docs/man/nng_pipe.5.adoc | 14 | ||||
| -rw-r--r-- | docs/man/nng_pipe_close.3.adoc | 2 | ||||
| -rw-r--r-- | docs/man/nng_pipe_id.3.adoc | 50 | ||||
| -rw-r--r-- | docs/man/nng_socket.5.adoc | 14 | ||||
| -rw-r--r-- | docs/man/nng_socket_id.3.adoc | 50 |
12 files changed, 308 insertions, 2 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 8df29861..149dc9f4 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -49,6 +49,7 @@ The following functions operate on sockets. |<<nng_recv.3#,nng_recv()>>|receive data |<<nng_send.3#,nng_send()>>|send data |<<nng_setopt.3#,nng_setopt()>>|set socket option +|<<nng_socket_id.3#,nng_socket_id()>>|get numeric socket identifier |=== === Connection Management @@ -61,16 +62,19 @@ Listeners accept incoming connection requets, and dialers make them. |<<nng_dialer_close.3#,nng_dialer_close()>>|close dialer |<<nng_dialer_create.3#,nng_dialer_create()>>|create dialer |<<nng_dialer_getopt.3#,nng_dialer_getopt()>>|get dialer option +|<<nng_dialer_id.3#,nng_dialer_id()>>|get numeric dialer identifier |<<nng_dialer_setopt.3#,nng_dialer_setopt()>>|set dialer option |<<nng_dialer_start.3#,nng_dialer_start()>>|start dialer |<<nng_listen.3#,nng_listen()>>|create and start listener |<<nng_listener_close.3#,nng_listener_close()>>|close listener |<<nng_listener_create.3#,nng_listener_create()>>|create listener |<<nng_listener_getopt.3#,nng_listener_getopt()>>|get listener option +|<<nng_listener_id.3#,nng_listener_id()>>|get numeric listener identifier |<<nng_listener_setopt.3#,nng_listener_setopt()>>|set listener option |<<nng_listener_start.3#,nng_listener_start()>>|start listener |<<nng_pipe_close.3#,nng_pipe_close()>>|close pipe |<<nng_pipe_getopt.3#,nng_pipe_getopt()>>|get pipe option +|<<nng_pipe_id.3#,nng_pipe_id()>>|get numeric pipe identifier |=== === Message Handling Functions @@ -205,6 +209,7 @@ concurrent applications. |=== |<<nng_ctx_close.3#,nng_ctx_close()>>|close context |<<nng_ctx_getopt.3#,nng_ctx_getopt()>>|get context option +|<<nng_ctx_id.3#,nng_ctx_id()>>|get numeric context identifier |<<nng_ctx_open.3#,nng_ctx_open()>>|create context |<<nng_ctx_recv.3#,nng_ctx_recv()>>|receive message using context asynchronously |<<nng_ctx_send.3#,nng_ctx_send()>>|send message using context asynchronously diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc index 98402738..ada117c3 100644 --- a/docs/man/nng_ctx.5.adoc +++ b/docs/man/nng_ctx.5.adoc @@ -81,6 +81,12 @@ are in use on the same socket is not supported, and may lead to unpredictable behavior. These asynchronous methods should not be mixed on the same socket. +[[NNG_CTX_INITIALIZER]] +=== Initialization + +A context may be initialized using the macro `NNG_CTX_INITIALIZER` +before it is opened, to prevent confusion with valid open contexts. + == EXAMPLE The following program fragment demonstrates the use of contexts to implement @@ -91,7 +97,7 @@ to the sender. ---- struct echo_context { - nng_ctx *ctx; + nng_ctx ctx; nng_aio *aio; enum { INIT, RECV, SEND } state; }; @@ -156,6 +162,7 @@ start_echo_service(nng_socket rep_socket) <<nng_ctx_close.3#,nng_ctx_close(3)>>, <<nng_ctx_open.3#,nng_ctx_open(3)>>, <<nng_ctx_getopt.3#,nng_ctx_getopt(3)>>, +<<nng_ctx_id.3#,nng_ctx_id(3)>>, <<nng_ctx_recv.3#,nng_ctx_recv(3)>>, <<nng_ctx_send.3#,nng_ctx_send(3)>>, <<nng_ctx_setopt.3#,nng_ctx_setopt(3)>>, diff --git a/docs/man/nng_ctx_id.3.adoc b/docs/man/nng_ctx_id.3.adoc new file mode 100644 index 00000000..56d9d7bd --- /dev/null +++ b/docs/man/nng_ctx_id.3.adoc @@ -0,0 +1,50 @@ += nng_ctx_id(3) +// +// 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_ctx_id - return numeric context identifier + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_ctx_id(nng_ctx c); +---- + +== DESCRIPTION + +The `nng_ctx_id()` function returns a positive identifier for the context _c_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A context is considered valid if it was ever opened with +<<nng_ctx_open.3#,`nng_ctx_open`>> function. +Contexts that are allocated on the stack or statically should be +initialized with the macro +<<nng_ctx.5#NNG_CTX_INITIALIZER,`NNG_CTX_INITIALIZER`>> to ensure that +they cannot be confused with a valid context before they are opened. + +== RETURN VALUES + +This function returns the positive value for the context identifier, or +`-1` if the context is invalid. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_ctx.5#,nng_ctx(5)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index 45c60bc9..3f742c21 100644 --- a/docs/man/nng_dialer.5.adoc +++ b/docs/man/nng_dialer.5.adoc @@ -58,12 +58,19 @@ Dialer objects may be destroyed by the <<nng_dialer_close.3#,`nng_pipe_close()`>> function. They are also closed when their "`owning`" socket is closed. +[[NNG_DIALER_INITIALIZER]] +=== Initialization + +A dialer may be initialized using the macro `NNG_DIALER_INITIALIZER` +before it is opened, to prevent confusion with valid open dialers. + == SEE ALSO <<nng_dial.3#,nng_dial(3)>>, <<nng_dialer_close.3#,nng_dialer_close(3)>>, <<nng_dialer_create.3#,nng_dialer_create(3)>>, <<nng_dialer_getopt.3#,nng_dialer_getopt(3)>>, +<<nng_dialer_id.3#,nng_dialer_id(3)>>, <<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>, <<nng_dialer_start.3#,nng_dialer_start(3)>>, <<nng_listener.5#,nng_listener(5)>>, diff --git a/docs/man/nng_dialer_id.3.adoc b/docs/man/nng_dialer_id.3.adoc new file mode 100644 index 00000000..cf8936b5 --- /dev/null +++ b/docs/man/nng_dialer_id.3.adoc @@ -0,0 +1,51 @@ += nng_dialer_id(3) +// +// 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_dialer_id - return numeric dialer identifier + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_dialer_id(nng_dialer d); +---- + +== DESCRIPTION + +The `nng_dialer_id()` function returns a positive identifier for the dialer _d_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A dialer is considered valid if it was ever created with the +<<nng_dialer_create.3#,`nng_dialer_create`>> or +<<nng_dial.3#,`nng_dial`>> functions. +Dialers that are allocated on the stack or statically should be +initialized with the macro +<<nng_ctx.5#NNG_DIALER_INITIALIZER,`NNG_DIALER_INITIALIZER`>> to ensure that +they cannot be confused with a valid dialer before they are created properly. + +== RETURN VALUES + +This function returns the positive value for the dialer identifier, or +`-1` if the dialer is invalid. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_dialer.5#,nng_dialer(5)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc index 558eb920..e7187a61 100644 --- a/docs/man/nng_listener.5.adoc +++ b/docs/man/nng_listener.5.adoc @@ -55,12 +55,19 @@ Listener objects may be destroyed by the <<nng_listener_close.3#,`nng_listener_close()`>> function. They are also closed when their "`owning`" socket is closed. +[[NNG_LISTENER_INITIALIZER]] +=== Initialization + +A listener may be initialized using the macro `NNG_LISTENER_INITIALIZER` +before it is opened, to prevent confusion with valid open listener. + == SEE ALSO <<nng_listen.3#,nng_listen(3)>>, <<nng_listener_close.3#,nng_listener_close(3)>>, <<nng_listener_create.3#,nng_listener_create(3)>>, <<nng_listener_getopt.3#,nng_listener_getopt(3)>>, +<<nng_listener_id.3#,nng_listener_id(3)>>, <<nng_listener_setopt.3#,nng_listener_setopt(3)>>, <<nng_listener_start.3#,nng_listener_start(3)>>, <<nng_dialer.5#,nng_dialer(5)>>, diff --git a/docs/man/nng_listener_id.3.adoc b/docs/man/nng_listener_id.3.adoc new file mode 100644 index 00000000..44404e14 --- /dev/null +++ b/docs/man/nng_listener_id.3.adoc @@ -0,0 +1,51 @@ += nng_listener_id(3) +// +// 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_listener_id - return numeric listener identifier + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_listener_id(nng_listener l); +---- + +== DESCRIPTION + +The `nng_listener_id()` function returns a positive identifier for the +listener _l_, if it is valid. +Otherwise it returns `-1`. + +NOTE: A listener is considered valid if it was ever created with the +<<nng_listener_create.3#,`nng_listener_create`>> or +<<nng_listen.3#,`nng_listen`>> functions. +listeners that are allocated on the stack or statically should be +initialized with the macro +<<nng_ctx.5#NNG_LISTENER_INITIALIZER,`NNG_LISTENER_INITIALIZER`>> to ensure that +they cannot be confused with a valid listener before they are created properly. + +== RETURN VALUES + +This function returns the positive value for the listener identifier, or +`-1` if the listener is invalid. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_listener.5#,nng_listener(5)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index 39247fbd..a7423884 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -51,11 +51,25 @@ Pipe objects may be destroyed by the They are also closed when their "`owning`" dialer or listener is closed, or when the remote peer closes the underlying connection. +[[NNG_PIPE_INITIALIZER]] +=== Initialization + +A pipe may be initialized using the macro `NNG_PIPE_INITIALIZER` +before it is opened, to prevent confusion with valid open pipes. + +For example: + +[source, c] +---- +nng_pipe p = NNG_PIPE_INITIALIZER; +---- + == SEE ALSO <<nng_msg_get_pipe.3#,nng_msg_get_pipe(3)>>, <<nng_pipe_close.3#,nng_pipe_close(3)>>, <<nng_pipe_getopt.3#,nng_pipe_getopt(3)>>, +<<nng_pipe_id.3#,nng_pipe_id(3)>>, <<nng_dialer.5#,nng_dialer(5)>>, <<nng_listener.5#,nng_listener(5)>>, <<nng_options.5#,nng_options(5)>>, diff --git a/docs/man/nng_pipe_close.3.adoc b/docs/man/nng_pipe_close.3.adoc index 598e143a..2128caec 100644 --- a/docs/man/nng_pipe_close.3.adoc +++ b/docs/man/nng_pipe_close.3.adoc @@ -19,7 +19,7 @@ nng_pipe_close - close pipe ---- #include <nng/nng.h> -int nng_pipe_close(nng_socket s); +int nng_pipe_close(nng_pipe p); ---- == DESCRIPTION diff --git a/docs/man/nng_pipe_id.3.adoc b/docs/man/nng_pipe_id.3.adoc new file mode 100644 index 00000000..b327dac2 --- /dev/null +++ b/docs/man/nng_pipe_id.3.adoc @@ -0,0 +1,50 @@ += nng_pipe_id(3) +// +// 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_pipe_id - return numeric pipe identifier + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_pipe_id(nng_pipe p); +---- + +== DESCRIPTION + +The `nng_pipe_id()` function returns a positive identifier for the pipe _p_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A pipe is considered valid if it was ever opened with +<<nng_pipe_open.3#,`nng_pipe_open`>> function. +Pipes that are allocated on the stack or statically should be +initialized with the macro +<<nng_pipe.5#NNG_PIPE_INITIALIZER,`NNG_PIPE_INITIALIZER`>> to ensure that +they cannot be confused with a valid pipe before they are opened. + +== RETURN VALUES + +This function returns the positive value for the pipe identifier, or +`-1` if the pipe is invalid. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_pipe.5#,nng_pipe(5)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 4711495f..2d8d7256 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -44,12 +44,26 @@ Each `nng_socket` is created by a protocol-specific constructor, such as When the socket is no longer needed, it can be closed with <<nng_close.3#,`nng_close()`>>. +[[NNG_SOCKET_INITIALIZER]] +=== Initialization + +A socket may be initialized using the macro `NNG_SOCKET_INITIALIZER` +before it is opened, to prevent confusion with valid open sockets. + +For example: + +[source, c] +---- +nng_socket s = NNG_SOCKET_INITIALIZER; +---- + == SEE ALSO <<libnng.3#,libnng(3)>>, <<nng_close.3#,nng_close(3)>>, <<nng_getopt.3#,nng_getopt(3)>>, <<nng_setopt.3#,nng_setopt(3)>>, +<<nng_socket_id.3#,nng_socket_id(3)>>, <<nng_dialer.5#,nng_dialer(5)>>, <<nng_listener.5#,nng_listener(5)>>, <<nng_options.5#,nng_options(5)>>, diff --git a/docs/man/nng_socket_id.3.adoc b/docs/man/nng_socket_id.3.adoc new file mode 100644 index 00000000..b5acc98b --- /dev/null +++ b/docs/man/nng_socket_id.3.adoc @@ -0,0 +1,50 @@ += nng_socket_id(3) +// +// 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_socket_id - return numeric socket identifier + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> + +int nng_socket_id(nng_socket s); +---- + +== DESCRIPTION + +The `nng_socket_id()` function returns a positive identifier for the socket _s_, +if it is valid. +Otherwise it returns `-1`. + +NOTE: A socket is considered valid if it was ever opened with a protocol +constructor, such as the <<nng_req0_open.3#,`nng_req0_open`>> function. +Sockets that are allocated on the stack or statically should be +initialized with the macro +<<nng_socket.5#NNG_SOCKET_INITIALIZER,`NNG_SOCKET_INITIALIZER`>> to ensure that +they cannot be confused with a valid socket before they are opened. + +== RETURN VALUES + +This function returns the positive value for the socket identifier, or +`-1` if the socket is invalid. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_socket.5#,nng_socket(5)>>, +<<nng.7#,nng(7)>> |