126 lines
4.6 KiB
Text
126 lines
4.6 KiB
Text
= nng_ipc(7)
|
|
//
|
|
// 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
|
|
// 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_ipc - IPC transport
|
|
|
|
== SYNOPSIS
|
|
|
|
[source,c]
|
|
----
|
|
#include <nng/transport/ipc/ipc.h>
|
|
|
|
int nng_ipc_register(void);
|
|
----
|
|
|
|
== DESCRIPTION
|
|
|
|
(((IPC)))(((transport, _ipc_)))
|
|
The ((_ipc_ transport)) provides communication support between
|
|
sockets within different processes on the same host.
|
|
For POSIX platforms, this is implemented using ((UNIX domain sockets)).
|
|
For Windows, this is implemented using Windows ((Named Pipes)).
|
|
Other platforms may have different implementation strategies.
|
|
|
|
// We need to insert a reference to the nanomsg RFC.
|
|
|
|
=== Registration
|
|
|
|
This transport is generally built-in to the core, so
|
|
no extra steps to use it should be necessary.
|
|
|
|
=== URI Formats
|
|
|
|
==== Traditional Names
|
|
|
|
(((URI, `ipc://`)))
|
|
This transport uses URIs using the scheme `ipc://`, followed by a path
|
|
name in the file system where the socket or named pipe should be created.
|
|
|
|
TIP: On Windows, all names are prefixed by `\\.\pipe\` and do not
|
|
reside in the normal file system.
|
|
On POSIX platforms, the path is taken literally, and is relative to
|
|
the current directory, unless it begins with `/`, in which case it is
|
|
relative to the root directory.
|
|
|
|
NOTE: When using relative paths on POSIX systems, the address used and returned
|
|
in properties like `NNG_OPT_LOCADDR` and `NNG_OPT_URL` will also be relative.
|
|
Consequently, they will only be interpreted the same by processes that have
|
|
the same working directory.
|
|
To ensure maximum portability and safety, absolute paths are recommended
|
|
whenever possible.
|
|
|
|
NOTE: If compatibility with legacy _nanomsg_ applications is required,
|
|
then path names must not be longer than 122 bytes, including the final
|
|
`NUL` byte.
|
|
This is because legacy versions of _nanomsg_ cannot express URLs
|
|
longer than 128 bytes, including the `ipc://` prefix.
|
|
|
|
==== UNIX Aliases
|
|
|
|
(((URI, `unix://`)))
|
|
The `unix://` scheme is an alias for `ipc://` and can be used inter-changeably, but only
|
|
on POSIX systems.
|
|
|
|
The purpose of this scheme is to support a future transport making use of `AF_UNIX`
|
|
on Windows systems, at which time it will be necessary to discriminate between
|
|
the Named Pipes and the `AF_UNIX` based transports.
|
|
|
|
==== Abstract Names
|
|
|
|
(((URI, `abstract://`)))
|
|
On Linux, this transport also can support abstract sockets.
|
|
Abstract sockets use a URI-encoded name after the scheme, which allows arbitrary values to be conveyed
|
|
in the path, including embedded `NUL` bytes.
|
|
For example, the name `"a\0b"` would be represented as `abstract://a%00b`.
|
|
|
|
TIP: An empty name may be used with a listener to request "`auto bind`" be used to select a name.
|
|
In this case the system will allocate a free name.
|
|
The name assigned may be retrieved using `NNG_OPT_LOCADDR`.
|
|
|
|
NOTE: _NNG_ cannot represent an abstract socket with the empty name.
|
|
|
|
NOTE: Abstract names do not include the leading `NUL` byte used in the low-level socket address.
|
|
|
|
Abstract sockets do not have any representation in the file system, and are automatically freed by
|
|
the system when no longer in use.
|
|
Abstract sockets ignore socket permissions, but it is still possible to determine the credentials
|
|
of the peer with `NNG_OPT_PEER_UID`, etc.
|
|
|
|
=== Socket Address
|
|
|
|
When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure,
|
|
the actual structure is of type xref:nng_sockaddr_ipc.5.adoc[`nng_sockaddr_ipc`],
|
|
except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_sockaddr_abstract`].
|
|
|
|
=== Transport Options
|
|
|
|
The following transport options are supported by this transport,
|
|
where supported by the underlying platform.
|
|
|
|
* 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
|
|
|
|
[.text-left]
|
|
xref:nng_sockaddr.5.adoc[nng_sockaddr(5)],
|
|
xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
|
|
xref:nng_options.5.adoc[nng_options(5)],
|
|
xref:nng.7.adoc[nng(7)]
|