From 2a4a14646f95b21cbc8f9b5bef8d76cd0fe04fec Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 31 Dec 2024 11:50:48 -0800 Subject: docs: progress on socket document conversion --- docs/man/nng_bus_open.3.adoc | 52 ------------------------- docs/man/nng_pair_open.3.adoc | 72 ---------------------------------- docs/man/nng_pub_open.3.adoc | 53 ------------------------- docs/man/nng_pull_open.3.adoc | 53 ------------------------- docs/man/nng_push_open.3.adoc | 53 ------------------------- docs/man/nng_rep_open.3.adoc | 53 ------------------------- docs/man/nng_req_open.3.adoc | 55 -------------------------- docs/man/nng_respondent_open.3.adoc | 56 -------------------------- docs/man/nng_socket.5.adoc | 71 --------------------------------- docs/man/nng_sub_open.3.adoc | 53 ------------------------- docs/man/nng_surveyor_open.3.adoc | 54 ------------------------- docs/ref/api/aio.md | 4 +- docs/ref/api/sock.md | 78 +++++++++++++++++++++++++++++++++++++ docs/ref/xref.md | 28 ++++++++++++- 14 files changed, 106 insertions(+), 629 deletions(-) delete mode 100644 docs/man/nng_bus_open.3.adoc delete mode 100644 docs/man/nng_pair_open.3.adoc delete mode 100644 docs/man/nng_pub_open.3.adoc delete mode 100644 docs/man/nng_pull_open.3.adoc delete mode 100644 docs/man/nng_push_open.3.adoc delete mode 100644 docs/man/nng_rep_open.3.adoc delete mode 100644 docs/man/nng_req_open.3.adoc delete mode 100644 docs/man/nng_respondent_open.3.adoc delete mode 100644 docs/man/nng_socket.5.adoc delete mode 100644 docs/man/nng_sub_open.3.adoc delete mode 100644 docs/man/nng_surveyor_open.3.adoc diff --git a/docs/man/nng_bus_open.3.adoc b/docs/man/nng_bus_open.3.adoc deleted file mode 100644 index 3477a903..00000000 --- a/docs/man/nng_bus_open.3.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_bus_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_bus_open - create bus socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_bus0_open(nng_socket *s); - -int nng_bus0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_bus0_open()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_bus0_open_raw()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode, and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_bus.7.adoc[nng_bus(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pair_open.3.adoc b/docs/man/nng_pair_open.3.adoc deleted file mode 100644 index 20348123..00000000 --- a/docs/man/nng_pair_open.3.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= nng_pair_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_pair_open - create pair socket - -== SYNOPSIS - -.Version 0 -[source,c] ----- -#include - -int nng_pair0_open(nng_socket *s); - -int nng_pair0_open_raw(nng_socket *s); ----- - -.Version 1 -[source,c] ----- -#include - -int nng_pair1_open(nng_socket *s); - -int nng_pair1_open_raw(nng_socket *s); - -int nng_pair1_open_poly(nng_socktet *s); ----- - -== DESCRIPTION - -The `nng_pair0_open()` and `nng_pair1_open()` functions -create a xref:nng_pair.7.adoc[_pair_] version 0 or version 1 -xref:nng_socket.5.adoc[socket] and return it at the location pointed to by _s_. - -The `nng_pair0_open_raw()` and `nng_pair1_open_raw()` functions -create a xref:nng_pair.7.adoc[_pair_] version 0 or version 1 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and return it at the location pointed to by _s_. - -The `nng_pair1_open_poly()` function opens a pair version 1 socket in -polyamorous mode. - -NOTE: Polyamorous mode is deprecated and should not be used in new applications. -The `nng_pair1_open_poly()` function will likely be removed in a future release. - -== RETURN VALUES - -These functions returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_pair.7.adoc[nng_pair(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pub_open.3.adoc b/docs/man/nng_pub_open.3.adoc deleted file mode 100644 index c9f3b5b5..00000000 --- a/docs/man/nng_pub_open.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_pub_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_pub_open - create pub socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_pub0_open(nng_socket *s); - -int nng_pub0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_pub0_open()` function creates a xref:nng_pub.7.adoc[_pub_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_pub0_open_raw()` function creates a xref:nng_pub.7.adoc[_pub_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_pub.7.adoc[nng_pub(7)], -xref:nng_sub.7.adoc[nng_sub(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pull_open.3.adoc b/docs/man/nng_pull_open.3.adoc deleted file mode 100644 index 12f85978..00000000 --- a/docs/man/nng_pull_open.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_pull_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_pull_open - create pull socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_pull0_open(nng_socket *s); - -int nng_pull0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_pull0_open()` function creates a xref:nng_pull.7.adoc[_pull_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_pull0_open_raw()` function creates a xref:nng_pull.7.adoc[_pull_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_pull.7.adoc[nng_pull(7)], -xref:nng_push.7.adoc[nng_push(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_push_open.3.adoc b/docs/man/nng_push_open.3.adoc deleted file mode 100644 index 1b1635ef..00000000 --- a/docs/man/nng_push_open.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_push_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_push_open - create push socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_push0_open(nng_socket *s); - -int nng_push0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_push0_open()` function creates a xref:nng_push.7.adoc[_push_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_push0_open_raw()` function creates a xref:nng_push.7.adoc[_push_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_pull.7.adoc[nng_pull(7)], -xref:nng_push.7.adoc[nng_push(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_rep_open.3.adoc b/docs/man/nng_rep_open.3.adoc deleted file mode 100644 index dd62201d..00000000 --- a/docs/man/nng_rep_open.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_rep_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_rep_open - create rep socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_rep0_open(nng_socket *s); - -int nng_rep0_open_raw(nng_socket *); ----- - -== DESCRIPTION - -The `nng_rep0_open()` function creates a xref:nng_rep.7.adoc[_rep_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_rep0_open_raw()` function creates a xref:nng_rep.7.adoc[_rep_] version 0 -xref:nng_socket.5.adoc[socket] -in xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_rep.7.adoc[nng_rep(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_req_open.3.adoc b/docs/man/nng_req_open.3.adoc deleted file mode 100644 index 0fd07944..00000000 --- a/docs/man/nng_req_open.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_req_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_req_open - create req socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_req0_open(nng_socket *s); - -int nng_req0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_req0_open()` function creates a xref:nng_req.7.adoc[_req_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_req0_open_raw()` function creates a xref:nng_req.7.adoc[_req_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode -and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_rep.7.adoc[nng_rep(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_respondent_open.3.adoc b/docs/man/nng_respondent_open.3.adoc deleted file mode 100644 index 5a5167d2..00000000 --- a/docs/man/nng_respondent_open.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_respondent_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_respondent_open - create respondent socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_respondent0_open(nng_socket *s); - -int nng_respondent0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_respondent0_open()` function creates a -xref:nng_respondent.7.adoc[_respondent_] -version 0 xref:nng_socket.5.adoc[socket] and returns it at the location -pointed to by _s_. - -The `nng_respondent0_open_raw()` function creates a -xref:nng_respondent.7.adoc[_respondent_] -version 0 xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_respondent.7.adoc[nng_respondent(7)], -xref:nng_surveyor.7.adoc[nng_surveyor(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc deleted file mode 100644 index c80a4dcd..00000000 --- a/docs/man/nng_socket.5.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_socket(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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 - socket handle - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_socket_s nng_socket; ----- - -== DESCRIPTION - -An `nng_socket`(((socket))) is a handle to an underlying socket object. -All communication between the application and remote Scalability Protocol -peers is done through sockets. -A given socket can have multiple dialers (xref:nng_dialer.5.adoc[`nng_dialer`]) -and/or listeners (xref:nng_listener.5.adoc[`nng_listener`]), and multiple -pipes (xref:nng_pipe.5.adoc[`nng_pipe`]), and -may be connected to multiple transports at the same time. -However, a given socket will have exactly one protocol associated with it, -and is responsible for any state machines or other protocol-specific logic. - -IMPORTANT: The `nng_socket` 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. - -Each `nng_socket` is created by a protocol-specific constructor, such as -xref:nng_rep_open.3.adoc[`nng_rep_open()`]. -When the socket is no longer needed, it can be closed with -xref:nng_close.3.adoc[`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 - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_close.3.adoc[nng_close(3)], -xref:nng_socket_get.3.adoc[nng_socket_get(3)], -xref:nng_socket_id.3.adoc[nng_socket_id(3)], -xref:nng_socket_set.3.adoc[nng_socket_set(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_sub_open.3.adoc b/docs/man/nng_sub_open.3.adoc deleted file mode 100644 index ea01673c..00000000 --- a/docs/man/nng_sub_open.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_sub_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_sub_open - create sub socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_sub0_open(nng_socket *s); - -int nng_sub0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_sub0_open()` function creates a xref:nng_sub.7.adoc[_sub_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_sub0_open_raw()` function creates a xref:nng_sub.7.adoc[_sub_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_pub.7.adoc[nng_pub(7)], -xref:nng_sub.7.adoc[nng_sub(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_surveyor_open.3.adoc b/docs/man/nng_surveyor_open.3.adoc deleted file mode 100644 index cd648f65..00000000 --- a/docs/man/nng_surveyor_open.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_surveyor_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// 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_surveyor_open - create surveyor socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_surveyor0_open(nng_socket *s); - -int nng_surveyor0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_surveyor0_open()` function creates a xref:nng_surveyor.7.adoc[_surveyor_] -version 0 xref:nng_socket.5.adoc[socket] and returns it at the location -pointed to by _s_. - -The `nng_surveyor0_open_raw()` function creates a xref:nng_surveyor.7.adoc[_surveyor_] -version 0 xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_respondent.7.adoc[nng_respondent(7)], -xref:nng_surveyor.7.adoc[nng_surveyor(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md index 58c8e4f9..1e6f76fa 100644 --- a/docs/ref/api/aio.md +++ b/docs/ref/api/aio.md @@ -290,7 +290,7 @@ void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov); ``` {{hi:`nng_iov`}} -Some asynchronous operations, such as those dealing with [streams], use {{i:scatter}} or {{i:gather}} +Some asynchronous operations, such as those dealing with [streams][stream], use {{i:scatter}} or {{i:gather}} vectors, where data to be transferred is either gathered from multiple separate regions of memory, or scattered into separate regions of memory. For example a message may have a header located at one location in memory, and a payload located in another. @@ -310,7 +310,7 @@ and if necessary resubmit the operation with a suitably updated vector of `nng_i [Synchronization][synchronization], [Threads][thread], -[Streams][streams], +[Streams][stream], [Time][time] {{#include ../xref.md}} diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md index afadcb42..59570240 100644 --- a/docs/ref/api/sock.md +++ b/docs/ref/api/sock.md @@ -49,6 +49,84 @@ or altered. It is guaranteed to remain valid while this library is present. The {{i:`nng_socket_raw`}} function determines whether the socket is in [raw mode][raw] or not, storing `true` in _raw_ if it is, or `false` if it is not. +## Opening a Socket + +```c +int nng_bus0_open(nng_socket *s); +int nng_pub0_open(nng_socket *s); +int nng_pull0_open(nng_socket *s); +int nng_push0_open(nng_socket *s); +int nng_rep0_open(nng_socket *s); +int nng_req0_open(nng_socket *s); +int nng_respondent0_open(nng_socket *s); +int nng_sub0_open(nng_socket *s); +int nng_surveyor0_open(nng_socket *s); +``` + +These functions open a socket, returning it in _s_. +The constructors for sockets are protocol specific so please refer to protocol documentation +for more specific information. + +The following functions open a socket in normal mode: + +- {{i:`nng_bus0_open`}} - [BUS][bus] version 0 +- {{i:`nng_pair0_open`}} - [PAIR][pair] version 0 +- {{i:`nng_pair1_open`}} - [PAIR][pair] version 1 +- {{i:`nng_pair1_open_poly`}} - [PAIR][pair] version 1, [polyamorous] mode +- {{i:`nng_pub0_open`}} - [PUB][pub] version 0 +- {{i:`nng_pull0_open`}} - [PULL][pull] version 0 +- {{i:`nng_push0_open`}} - [PUSH][push] version 0 +- {{i:`nng_rep0_open`}} - [REP][rep] version 0 +- {{i:`nng_req0_open`}} - [REQ][req] version 0 +- {{i:`nng_respondent0_open`}} - [RESPONDENT][respondent] version 0 +- {{i:`nng_sub0_open`}} - [SUB][sub] version 0 +- {{i:`nng_surveyor0_open`}} - [SURVEYOR][surveyor] version 0 + +## Raw Mode Sockets + +```c +int nng_bus0_open_raw(nng_socket *s); +int nng_pub0_open_raw(nng_socket *s); +int nng_pull0_open_raw(nng_socket *s); +int nng_push0_open_raw(nng_socket *s); +int nng_rep0_open_raw(nng_socket *s); +int nng_req0_open_raw(nng_socket *s); +int nng_respondent0_open_raw(nng_socket *s); +int nng_sub0_open_raw(nng_socket *s); +int nng_surveyor0_open_raw(nng_socket *s); +``` + +{{hi:raw mode}} +Raw mode sockets are used in circumstances when the application needs direct access +to the message headers to control the protocol details. + +Such sockets require greater sophistication on the part of the application to use, +as the application must process the protocol headers specifically. +The details of the protocol headers, and requirements, are described in the protocol +documentation for each protocol. + +Raw mode sockets do not have any kind of state machine associated with them, as all of +the protocol specific processing must be performed by the application. + +> [!TIP] +> Most applications do not need to use raw sockets. +> The notable exception is when using [`nng_device`], which requires raw sockets. +> To obtain asynchronous behavior, consider using [contexts][context] instead. + +The following functions open a socket in [raw] mode: + +- {{i:`nng_bus0_open_raw`}} - [BUS][bus] version 0, raw mode +- {{i:`nng_pair0_open_raw`}} - [PAIR][pair] version 0, raw mode +- {{i:`nng_pair1_open_raw`}} - [PAIR][pair] version 1, raw mode +- {{i:`nng_pub0_open_raw`}} - [PUB][pub] version 0, raw mode +- {{i:`nng_pull0_open_raw`}} - [PULL][pull] version 0, raw mode +- {{i:`nng_push0_open_raw`}} - [PUSH][push] version 0, raw mode +- {{i:`nng_rep0_open_raw`}} - [REP][rep] version 0, raw mode +- {{i:`nng_req0_open_raw`}} - [REP][req] version 0, raw mode +- {{i:`nng_respondent0_open_raw`}} - [RESPONDENT][respondent] version 0, raw mode +- {{i:`nng_sub0_open_raw`}} - [SUB][sub] version 0, raw mode +- {{i:`nng_surveyor0_open_raw`}} - [SURVEYOR][surveyor] version 0, raw mode + ## Polling Socket Events ```c diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 15db26f5..12146752 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -114,6 +114,28 @@ [`nng_sub0_ctx_unsubscribe`]: /TODO.md [`nng_sub0_socket_subscribe`]: /TODO.md [`nng_sub0_socket_unsubscribe`]: /TODO.md +[`nng_bus0_open`]: /api/sock.md#opening-a-socket +[`nng_pair0_open`]: /api/sock.md#opening-a-socket +[`nng_pair1_open`]: /api/sock.md#opening-a-socket +[`nng_pair1_poly_open`]: /api/sock.md#opening-a-socket +[`nng_pub0_open`]: /api/sock.md#opening-a-socket +[`nng_pull0_open`]: /api/sock.md#opening-a-socket +[`nng_push0_open`]: /api/sock.md#opening-a-socket +[`nng_rep0_open`]: /api/sock.md#opening-a-socket +[`nng_req0_open`]: /api/sock.md#opening-a-socket +[`nng_respondent0_open`]: /api/sock.md#opening-a-socket +[`nng_sub0_open`]: /api/sock.md#opening-a-socket +[`nng_surveyor0_open`]: /api/sock.md#opening-a-socket +[`nng_bus0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_pub0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_pair0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_pair1_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_pull0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_push0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_rep0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_req0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_sub0_open_raw`]: /api/sock.md#raw-mode-sockets +[`nng_surveyor0_open_raw`]: /api/sock.md#raw-mode-sockets [`nng_dialer_set_tls`]: /TODO.md [`nng_dialer_get_tls`]: /TODO.md [`nng_listener_set_tls`]: /TODO.md @@ -134,6 +156,7 @@ [`nng_tls_config`]: /TODO.md [`nng_tls_config_own_cert`]: /TODO.md [`nng_listener_set_security_descriptor`]: /TODO.md +[`nng_device`]: /TODO.md @@ -214,14 +237,14 @@ [aio]: /api/aio.md -[raw]: /TODO.md +[raw]: /api/sock.md#raw-mode-sockets [pipe]: /TODO.md [socket]: /TODO.md [context]: /TODO.md [dialer]: /TODO.md [listener]: /TODO.md [message]: /api/msg.md -[streams]: /api/stream.md +[stream]: /api/stream.md [message-body]: /api/msg.md#message-body [message-header]: /api/msg.md#message-header [synchronization]: /api/synch.md @@ -232,3 +255,4 @@ [time]: /api/time.md [error]: /api/errors.md [duration]: /api/time.md#duration-type +[polyamorous]: /proto/pair.md#polyamorous-mode -- cgit v1.2.3-70-g09d2