= nng_ipc(7)
//
// 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_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
_nng_ 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

The _ipc_ transport is generally built-in to the _nng_ core, so
no extra steps to use it should be necessary.

=== URI Format

(((URI, `ipc://`)))
This transport uses URIs using the scheme `ipc://`, followed by
an absolute 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
occupy the normal file system.
On POSIX platforms, the path is taken literally,
and is relative to the root directory.

NOTE: If compatibility with legacy _nanomsg_ applications is required,
then pathnames 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.

NOTE: Legacy _nanomsg_ supported relative IPC path names; modern _nng_ does not.
Therefore, always use an absolute path name if interoperability is required.

=== Socket Address

When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure,
the actual structure is of type `<<nng_sockaddr_ipc.5#,nng_sockaddr_ipc>>`.

=== Transport Options

((`NNG_OPT_IPC_PERMISSIONS`))::

This write-only option may be used to configure the permissions that
are used on the UNIX domain socket created by a listener.
This property is only supported on POSIX systems.
The value is of type `int`, representing the normal permission bits
on a file, such as `0600` (typically meaning read-write to the owner, and
no permissions for anyone else.)
The default is system-specific, most often `0644`.

NOTE: Normally both read and write permission will be necessary for a
peer dialer to connect.
See your system documentation for UNIX domain sockets for more information.

NOTE: The _umask_ of the process is *not* applied to these bits.

((`NNG_OPT_IPC_SECURITY_DESCRIPTOR`))::

This write-only option may be used on Windows platforms to configure
the `SECURITY_DESCRIPTOR` that is used when creating the underying
named pipe.
The value is a pointer, `PSECURITY_DESCRIPTOR`, and may only be
applied to listeners that have not been started yet.

== SEE ALSO

<<nng_sockaddr.5#,nng_sockaddr(5)>>,
<<nng.7#,nng(7)>>
