From c2125c5b76be6edddf50282613bab6bb5038f777 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 29 Dec 2023 10:39:46 -0800 Subject: [PATCH] Add documentation for socket transport. --- docs/man/libnng.3.adoc | 1 + docs/man/nng.7.adoc | 1 + docs/man/nng_socket.7.adoc | 65 +++++++++++++++++++++++++++++ docs/man/nng_socket_pair.3supp.adoc | 53 +++++++++++++++++++++++ 4 files changed, 120 insertions(+) create mode 100644 docs/man/nng_socket.7.adoc create mode 100644 docs/man/nng_socket_pair.3supp.adoc diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 6f64de41c..c9df9c0d2 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -305,6 +305,7 @@ as a convenience to aid in creating portable applications. |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options |xref:nng_random.3supp.adoc[nng_random()]|get random number +|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc index 1097a5f8a..c0e1a6406 100644 --- a/docs/man/nng.7.adoc +++ b/docs/man/nng.7.adoc @@ -69,6 +69,7 @@ xref:nng_surveyor.7.adoc[nng_surveyor(7)]:: Surveyor side of survey protocol [horizontal] xref:nng_inproc.7.adoc[nng_inproc(7)]:: Intra-process transport xref:nng_ipc.7.adoc[nng_ipc(7)]:: Inter-process transport +xref:nng_socket.7.adoc[nng_socket(7)]:: BSD socket transport xref:nng_tls.7.adoc[nng_tls(7)]:: TLSv1.2 over TCP transport xref:nng_tcp.7.adoc[nng_tcp(7)]:: TCP (and TCPv6) transport xref:nng_ws.7.adoc[nng_ws(7)]:: WebSocket transport diff --git a/docs/man/nng_socket.7.adoc b/docs/man/nng_socket.7.adoc new file mode 100644 index 000000000..630076a18 --- /dev/null +++ b/docs/man/nng_socket.7.adoc @@ -0,0 +1,65 @@ += nng_socket(7) +// +// Copyright 2023 Staysail Systems, Inc. +// +// 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 - BSD Socket transport (experimental) + +== DESCRIPTION + +(((BSD Socket)))(((transport, _socket_))) +The ((_socket_ transport)) provides communication support between +peers across a arbitrary BSD sockets, such as those that are +created with xref:nng_socket_pair.3supp.adoc[`nng_socket_pair()`]. + +This transport only supports xref:nng_listener.5.adoc[listeners], using xref:nng_listener_create.3.adoc[`nng_listener_create()]. + +NOTE: Attempts to create a xref:nng_dialer.5.adoc[dialer] using this transport will result in `NNG_ENOTSUP`. + +The socket file descriptor is passed to the listener using the `NNG_OPT_SOCKET_FD` option (as an integer). +Setting this option (which is read-only and can be set multiple times) will cause the listener +to create a xref:nng_pipe.5.adoc[pipe] associated backed by the file descriptor. + +The protocol between peers using this pipe is at present compatible with the protocol used for the +xref:nng_tcp.7.adoc[TCP] transport, but this is an implementation detail and subject to change without notice. + +NOTE: This transport is *experimental*, and at present is only supported on POSIX platforms. + +=== Registration + +No special action is necessary to register this transport. + +=== URI Format + +(((URI, `socket://`))) +This transport uses the URL `socket://`, without further qualification. + +=== Socket Address + +Not documented. + +=== Transport Options + +The following transport option is available: + +((`NNG_OPT_SOCKET_FD`)):: + +(int) This is a write-only option, that may be set multiple times on a listener. +The listener will create a pipe backed by the given file descriptor passed as an argument. + +== SEE ALSO + +[.text-left] +xref:nng_socket_pair.3supp.adoc[nng_socket_pair(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_pipe.5.adoc[nng_pipe(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc new file mode 100644 index 000000000..063c9f0bd --- /dev/null +++ b/docs/man/nng_socket_pair.3supp.adoc @@ -0,0 +1,53 @@ += nng_socket_pair(3) +// +// Copyright 2023 Staysail Systems, Inc. +// +// 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_pair - create a connected pair of BSD sockets + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_socket_pair(int fds[2]); +---- + +== DESCRIPTION + +The `nng_socket_pair()` function creates a pair of connected BSD sockets. +These sockets, which are returned in the _fds_ array, are suitable for +use with the xref:nng_socket.7.adoc[_socket_] transport. + +On POSIX platforms, this is a thin wrapper around the standard `socketpair()` function, +using the `AF_UNIX` family and the `SOCK_STREAM` socket type. + +NOTE: At present only POSIX platforms implementing `socketpair()` are supported with this function. + +TIP: This function may be useful for creating a shared connection between a parent process and +a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: This platform does not support socket pairs. + +== SEE ALSO + +[.text-left] +xref:nng_socket.7.adoc[nng_socket(7)], +xref:nng.7.adoc[nng(7)]