diff options
Diffstat (limited to 'docs/man')
| -rw-r--r-- | docs/man/nng_pipe.5.adoc | 79 | ||||
| -rw-r--r-- | docs/man/nng_pipe_close.3.adoc | 52 | ||||
| -rw-r--r-- | docs/man/nng_pipe_dialer.3.adoc | 47 | ||||
| -rw-r--r-- | docs/man/nng_pipe_id.3.adoc | 50 | ||||
| -rw-r--r-- | docs/man/nng_pipe_listener.3.adoc | 47 | ||||
| -rw-r--r-- | docs/man/nng_pipe_notify.3.adoc | 93 | ||||
| -rw-r--r-- | docs/man/nng_pipe_socket.3.adoc | 46 |
7 files changed, 0 insertions, 414 deletions
diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc deleted file mode 100644 index 79530dfd..00000000 --- a/docs/man/nng_pipe.5.adoc +++ /dev/null @@ -1,79 +0,0 @@ -= nng_pipe(5) -// -// Copyright 2020 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 - communications pipe - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -typedef struct nng_pipe_s nng_pipe; ----- - -== DESCRIPTION - -(((pipe)))(((connection))) -An `nng_pipe` is a handle to a pipe object, which can be thought of as a single -connection. -(In most cases this is actually the case -- the pipe is an abstraction for a -single TCP or IPC connection.) -Pipes are associated with either the listener or dialer that created them, -and therefore are also automatically associated with a single socket. - -IMPORTANT: The `nng_pipe` structure is always passed by value (both -for input parameters and return values), and should be treated opaquely. -Passing structures this way gives the compiler a chance to perform -accurate type checks in functions passing values of this type. - -TIP: Most applications should never concern themselves with individual pipes. -However it is possible to access a pipe when more information about the -source of a message is needed, or when more control is required over -message delivery. - -Pipe objects are created by dialers (xref:nng_dialer.5.adoc[`nng_dialer`] objects) -and listeners (xref:nng_listener.5.adoc[`nng_listener`] objects). - -Pipe objects may be destroyed by the -xref:nng_pipe_close.3.adoc[`nng_pipe_close()`] function. -They are also closed when the dialer or listener that created them 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 - -[.text-left] -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], -xref:nng_pipe_close.3.adoc[nng_pipe_close(3)], -xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], -xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer(3)], -xref:nng_pipe_id.3.adoc[nng_pipe_id(3)], -xref:nng_pipe_listener.3.adoc[nng_pipe_listener(3)], -xref:nng_pipe_socket.3.adoc[nng_pipe_socket(3)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_close.3.adoc b/docs/man/nng_pipe_close.3.adoc deleted file mode 100644 index a8de660f..00000000 --- a/docs/man/nng_pipe_close.3.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_pipe_close(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_close - close pipe - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -int nng_pipe_close(nng_pipe p); ----- - -== DESCRIPTION - -The `nng_pipe_close()` function closes the supplied pipe, _p_. -Messages that have been submitted for sending may be flushed or delivered, -depending upon the transport. - -Further attempts to use the pipe after this call returns will result -in `NNG_ECLOSED`. - -TIP: Pipes are automatically closed when their creator closes, or when the -remote peer closes the underlying connection. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The pipe _p_ is already closed or was never opened. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_dialer.3.adoc b/docs/man/nng_pipe_dialer.3.adoc deleted file mode 100644 index c2a68c5e..00000000 --- a/docs/man/nng_pipe_dialer.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_pipe_dialer(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_dialer - return dialer that created pipe - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -nng_dialer nng_pipe_dialer(nng_pipe p); ----- - -== DESCRIPTION - -The `nng_pipe_dialer()` function returns the xref:nng_dialer.5.adoc[`nng_dialer`] -that created the pipe _p_. -If the pipe was not created by a dialer, then the returned value will -have an identifier (xref:nng_dialer_id.3.adoc[`nng_dialer_id()`]) of `-1`. - -== RETURN VALUES - -This function returns the dialer that created the pipe, unless it was -not created by a dialer, in which case a value initialized with -`NNG_DIALER_INITIALIZER` will be returned. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_id.3.adoc b/docs/man/nng_pipe_id.3.adoc deleted file mode 100644 index 9b8e8ee6..00000000 --- a/docs/man/nng_pipe_id.3.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= 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 created by the socket. -Pipes that are allocated on the stack or statically should be -initialized with the macro -xref:nng_pipe.5.adoc#NNG_PIPE_INITIALIZER[`NNG_PIPE_INITIALIZER`] to ensure that -they cannot be confused with a valid pipe. - -== RETURN VALUES - -This function returns the positive value for the pipe identifier, or -`-1` if the pipe is invalid. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_listener.3.adoc b/docs/man/nng_pipe_listener.3.adoc deleted file mode 100644 index 78ae0500..00000000 --- a/docs/man/nng_pipe_listener.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_pipe_listener(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_listener - return listener that created pipe - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -nng_listener nng_pipe_listener(nng_pipe p); ----- - -== DESCRIPTION - -The `nng_pipe_listener()` function returns the xref:nng_listener.5.adoc[`nng_listener`] -that created the pipe _p_. -If the pipe was not created by a listener, then the returned value will -have an identifier (xref:nng_listener_id.3.adoc[`nng_listener_id()`]) of `-1`. - -== RETURN VALUES - -This function returns the listener that created the pipe, unless it was -not created by a listener, in which case a value initialized with -`NNG_LISTENER_INITIALIZER` will be returned. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc deleted file mode 100644 index cd7250f7..00000000 --- a/docs/man/nng_pipe_notify.3.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= nng_pipe_notify(3) -// -// 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_pipe_notify - register pipe notification callback - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -typedef enum { - NNG_PIPE_EV_ADD_PRE, - NNG_PIPE_EV_ADD_POST, - NNG_PIPE_EV_REM_POST, -} nng_pipe_ev; - -typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *); - -int nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg); ----- - -== DESCRIPTION - -The `nng_pipe_notify()` function registers the callback function _cb_ -to be called whenever a xref:nng_pipe.5.adoc[pipe] the pipe event specified by -_ev_ occurs on the socket _s_. -The callback _cb_ will be passed _arg_ as its final argument. - -A different callback may be supplied for each event. -Each event may have at most one callback registered. -Registering a callback implicitly unregisters any previously registered. - -The following pipe events are supported: - -`NNG_PIPE_EV_ADD_PRE`:: This event occurs after a connection and negotiation -has completed, but before the pipe is added to the socket. -If the pipe is closed (using xref:nng_pipe_close.3.adoc[`nng_pipe_close()`]) at -this point, the socket will never see the pipe, and no further events will -occur for the given pipe. - -`NNG_PIPE_EV_ADD_POST`:: This event occurs after the pipe is fully added to -the socket. -Prior to this time, it is not possible to communicate over the pipe with -the socket. - -`NNG_PIPE_EV_REM_POST`:: This event occurs after the pipe has been removed -from the socket. -The underlying transport may be closed at this point, and it is not -possible communicate using this pipe. - -WARNING: The callback _cb_ function must *not* attempt to perform any -accesses to the socket, as it is called with a lock on the socket held! -Doing so would thus result in a deadlock. - -TIP: The callback _cb_ may close a pipe for any reason by simply closing -it using xref:nng_pipe_close.3.adoc[`nng_pipe_close()`]. -This might be done before the pipe is added to the socket (during -`NNG_PIPE_EV_ADD_PRE`), for example, if the remote peer is not authorized. - -TIP: It is possible to register the same _cb_ and _arg_ for different events -by calling this function separately for different values of _ev_. - -NOTE: This function ignores invalid values for _ev_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The socket _s_ does not refer to an open socket. - -== SEE ALSO - -[.text-left] -xref:nng_pipe_close.3.adoc[nng_pipe_close(3)], -xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_socket.3.adoc b/docs/man/nng_pipe_socket.3.adoc deleted file mode 100644 index 755ed776..00000000 --- a/docs/man/nng_pipe_socket.3.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_pipe_socket(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_socket - return owning socket for pipe - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -nng_socket nng_pipe_socket(nng_pipe p); ----- - -== DESCRIPTION - -The `nng_pipe_socket()` function returns the xref:nng_socket.5.adoc[`nng_socket`] -associated with the pipe _p_. - -NOTE: The returned socket may be closed or in the process of closing, in -which case it will not be usable with other functions. - -== RETURN VALUES - -This function returns the socket associated with the pipe. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] |
