aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/man/CMakeLists.txt2
-rw-r--r--docs/man/libnng.3.adoc1
-rw-r--r--docs/man/nng.7.adoc1
-rw-r--r--docs/man/nng_ipc.7.adoc10
-rw-r--r--docs/man/nng_ipc_options.5.adoc64
-rw-r--r--docs/man/nng_options.5.adoc64
-rw-r--r--docs/man/nng_socket.7.adoc74
-rw-r--r--docs/man/nng_socket_pair.3supp.adoc53
8 files changed, 205 insertions, 64 deletions
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index a33d4ee8..17d43c8e 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -302,6 +302,7 @@ if (NNG_ENABLE_DOC)
nng_mtx_unlock
nng_opts_parse
nng_random
+ nng_socket_pair
nng_thread_create
nng_thread_destroy
nng_thread_set_name
@@ -388,6 +389,7 @@ if (NNG_ENABLE_DOC)
nng_rep
nng_req
nng_respondent
+ nng_socket
nng_sub
nng_surveyor
nng_tcp
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 6f64de41..c9df9c0d 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 1097a5f8..c0e1a640 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_ipc.7.adoc b/docs/man/nng_ipc.7.adoc
index 856a00ac..c085e4d2 100644
--- a/docs/man/nng_ipc.7.adoc
+++ b/docs/man/nng_ipc.7.adoc
@@ -1,6 +1,6 @@
= nng_ipc(7)
//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 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
@@ -107,14 +107,14 @@ except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_so
The following transport options are supported by this transport,
where supported by the underlying platform.
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_GID[`NNG_OPT_IPC_PEER_GID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_PID[`NNG_OPT_IPC_PEER_PID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_UID[`NNG_OPT_IPC_PEER_UID`]
-* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PEER_ZONEID[`NNG_OPT_IPC_PEER_ZONEID`]
* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PERMISSIONS[`NNG_OPT_IPC_PERMISSIONS`]
* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_SECURITY_DESCRIPTOR[`NNG_OPT_IPC_SECURITY_DESCRIPTOR`]
* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`]
* xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`]
== SEE ALSO
diff --git a/docs/man/nng_ipc_options.5.adoc b/docs/man/nng_ipc_options.5.adoc
index 72f383ea..516fbe80 100644
--- a/docs/man/nng_ipc_options.5.adoc
+++ b/docs/man/nng_ipc_options.5.adoc
@@ -1,6 +1,6 @@
= nng_ipc_options(5)
//
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
// Copyright 2019 Devolutions <info@devolutions.net>
//
@@ -43,43 +43,9 @@ have other access restrictions.
An attempt has been made to include details about such restrictions in the
description of the option.
-NOTE: The availability of any of the following options is platform-specific,
+NOTE: The availability of the following options is platform-specific,
as the implementations of IPC are quite different on Windows and POSIX systems.
-=== IPC Options
-
-[[NNG_OPT_IPC_PEER_GID]]((`NNG_OPT_IPC_PEER_GID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's primary
-group id.
-This is the effective group id of the peer when either the underlying
-`listen()` or `connect()` calls were made, and is not forgeable.
-This option is generally only available on POSIX systems.
-
-[[NNG_OPT_IPC_PEER_PID]]((`NNG_OPT_IPC_PEER_PID`))::
-(`uint64_t`)
-This read-only option provides the the process id
-of the connected peer.
-This option is only available on Windows, Linux, and certain other systems.
-+
-NOTE: Applications should not assume that the process ID does not change,
-as it is possible (although unsupported!) for a nefarious process to pass a
-file descriptor between processes.
-However, it is not possible for a nefarious application to forge the identity
-of a well-behaved one using this method.
-
-[[NNG_OPT_IPC_PEER_UID]]((`NNG_OPT_IPC_PEER_UID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's user id.
-This is the effective user id of the peer when either the underlying
-`listen()` or `connect()` calls were made, and is not forgeable.
-This option is generally only available on POSIX systems.
-
-[[NNG_OPT_IPC_PEER_ZONEID]]((`NNG_OPT_IPC_PEER_ZONEID`))::
-(`uint64_t`)
-This read-only option provides a connected peer's the zone id.
-Zones (and this option) are only supported on Solaris and illumos systems.
-
[[NNG_OPT_IPC_PERMISSIONS]]((`NNG_OPT_IPC_PERMISSIONS`))::
(`int`)
This write-only option may be applied to a listener to configure the
@@ -115,10 +81,18 @@ named pipe.
The value is a pointer, `PSECURITY_DESCRIPTOR`, and may only be
applied to listeners that have not been started yet.
+=== Common Platform Specific Options
+
+The following options are supported by this transport when the underlying platform supports them:
+
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`] (also available as `NNG_OPT_IPC_PEER_GID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`] (also available as `NNG_OPT_IPC_PEER_PID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`] (also available as `NNG_OPT_IPC_PEER_UID`)
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`] (also available as `NNG_OPT_IPC_PEER_ZONEID`)
+
=== Inherited Options
-Generally, the following option values are also available for TLS objects,
-when appropriate for the context:
+Generally, the following option values are also available when appropriate for the context:
* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
@@ -126,11 +100,11 @@ when appropriate for the context:
== SEE ALSO
[.text-left]
-xref:nng_ipc_dialer_getopt.3ipc.adoc[nng_ipc_dialer_getopt(3ipc)],
-xref:nng_ipc_dialer_setopt.3ipc.adoc[nng_ipc_dialer_setopt(3ipc)],
-xref:nng_ipc_getopt.3ipc.adoc[nng_ipc_getopt(3ipc)],
-xref:nng_ipc_listener_getopt.3ipc.adoc[nng_ipc_listener_getopt(3ipc)],
-xref:nng_ipc_listener_setopt.3ipc.adoc[nng_ipc_listener_setopt(3ipc)],
-xref:nng_ipc_setopt.3ipc.adoc[nng_ipc_setopt(3ipc)],
+xref:nng_dialer_get.3.adoc[nng_dialer_get(3)],
+xref:nng_dialer_set.3.adoc[nng_dialer_set(3)],
+xref:nng_listener_get.3.adoc[nng_listener_get(3)],
+xref:nng_listener_set.3.adoc[nng_listener_set(3)],
+xref:nng_pipe_get.3.adoc[nng_pipe_get(3)],
xref:nng_options.5.adoc[nng_options(5)]
-xref:nng.7.adoc[nng(7)]
+xref:nng.7.adoc[nng(7)],
+xref:nng_ipc.7.adoc[nng_ipc(7)]
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index e4e5124d..dd971f9f 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -1,6 +1,6 @@
= nng_options(5)
//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
// Copyright 2019 Devolutions <info@devolutions.net>
//
@@ -39,6 +39,10 @@ nng_options - socket, dialer, listener, and pipe options
#define NNG_OPT_RECVMAXSZ "recv-size-max"
#define NNG_OPT_RECONNMINT "reconnect-time-min"
#define NNG_OPT_RECONNMAXT "reconnect-time-max"
+#define NNG_OPT_PEER_GID "ipc:peer-gid"
+#define NNG_OPT_PEER_PID "ipc:peer-pid"
+#define NNG_OPT_PEER_UID "ipc:peer-uid"
+#define NNG_OPT_PEER_ZONEID "ipc:peer-zoneid"
----
== DESCRIPTION
@@ -328,27 +332,59 @@ This read-only option is used to obtain the 16-bit number for the socket's proto
This read-only option is used to obtain the 16-bit number of the
peer protocol for the socket.
-[[NNG_OPT_PROTONAME]]
-((`NNG_OPT_PROTONAME`))::
-(string)
-This read-only option is used to obtain the name of the socket's protocol.
+[[NNG_OPT_PEER_GID]]
+((`NNG_OPT_PEER_GID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's primary group id, when known.
+This is the effective group id of the peer when either the underlying
+`listen()` or `connect()` calls were made, and is not forgeable.
+This option is generally only available on POSIX systems, only on certain transports.
+
+[[NNG_OPT_PEER_PID]]
+((`NNG_OPT_PEER_PID`))::
+(`uint64_t`)
+This read-only option provides the process id of the connected peer, when known.
+This option is only available on certain platforms and transports.
++
+NOTE: Applications should not assume that the process ID does not change,
+as it may be possible for a process to pass a file descriptor between processes.
+However, it is not possible for a nefarious application to forge the identity
+of a well-behaved one using this method.
+
+[[NNG_OPT_PEER_UID]]
+((`NNG_OPT_PEER_UID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's user id.
+This is the effective user id of the peer when either the underlying
+`listen()` or `connect()` calls were made, and cannot be forged.
+This option is generally only available on POSIX systems, on certain transports.
+
+[[NNG_OPT_PEER_ZONEID]]
+((`NNG_OPT_PEER_ZONEID`))::
+(`uint64_t`)
+This read-only option provides a connected peer's the zone id.
+Zones (and this option) are only supported on Solaris and illumos systems, on select transports.
[[NNG_OPT_PEERNAME]]
((`NNG_OPT_PEERNAME`))::
(string)
-This read-only option is used to obtain the name of the peer protocol for
-the socket.
+This read-only option is used to obtain the name of the peer protocol for the socket.
+
+[[NNG_OPT_PROTONAME]]
+((`NNG_OPT_PROTONAME`))::
+(string)
+This read-only option is used to obtain the name of the socket's protocol.
== SEE ALSO
[.text-left]
-xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)],
-xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)],
-xref:nng_getopt.3.adoc[nng_getopt(3)],
-xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
-xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)],
-xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
-xref:nng_setopt.3.adoc[nng_setopt(3)],
+xref:nng_dialer_get.3.adoc[nng_dialer_get(3)],
+xref:nng_dialer_set.3.adoc[nng_dialer_set(3)],
+xref:nng_listener_get.3.adoc[nng_listener_get(3)],
+xref:nng_listener_set.3.adoc[nng_listener_set(3)],
+xref:nng_pipe_get.3.adoc[nng_pipe_get(3)],
+xref:nng_socket_get.3.adoc[nng_socket_get(3)],
+xref:nng_socket_set.3.adoc[nng_socket_set(3)],
xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
xref:nng_tls_options.5.adoc[nng_tls_options(5)],
diff --git a/docs/man/nng_socket.7.adoc b/docs/man/nng_socket.7.adoc
new file mode 100644
index 00000000..f575eed7
--- /dev/null
+++ b/docs/man/nng_socket.7.adoc
@@ -0,0 +1,74 @@
+= nng_socket(7)
+//
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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
+
+The socket address will be of family `NNG_AF_UNSPEC`.
+There are no further socket details available.
+
+=== 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.
+
+Additionally, the following options may be supported on pipes when the platform supports them:
+
+* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`]
+* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`]
+
+== 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_options.5.adoc[nng_options(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 00000000..063c9f0b
--- /dev/null
+++ b/docs/man/nng_socket_pair.3supp.adoc
@@ -0,0 +1,53 @@
+= nng_socket_pair(3)
+//
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
+//
+// 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 <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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)]
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-18 09:51:28 +0000