fixes #846 Document IPC public API

1 files changed, 85 insertions, 1 deletions

diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index a1d19b5f..6b8a09f3 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -71,10 +71,11 @@ In addition to the options listed here, transports and protocols will generally
 have some of their own options, which will be documented with the transport
 or protocol.
 
-=== Options
+=== Generic Options
 
 In the following list of options, the name of the option is supplied,
 along with the data type of the underlying value.
+
 Some options are only meaningful or supported in certain contexts; for
 example there is no single meaningful address for a socket, since sockets
 can have multiple dialers and endpoints associated with them.
@@ -319,6 +320,11 @@ This read-only option is used to obtain the name of the socket's protocol.
 This read-only option is used to obtain the name of the peer protocol for
 the socket.
 
+=== TCP Options
+
+The following options are generally application to objects making use of
+TCP/IP communications.
+
 [[NNG_OPT_TCP_NODELAY]]
 ((`NNG_OPT_TCP_NODELAY`))::
 (`bool`)
@@ -363,6 +369,84 @@ First, it can be used to detect dead peers on an otherwise quiescent network.
 Second, it can be used to keep connection table entries in NAT and other
 middleware from being expiring due to lack of activity.
 
+=== IPC Options
+
+The following options are meaningful for IPC communications.
+
+NOTE: Most of these options are platform-specific, and may not be available
+on every platform.
+
+[[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
+permissions that are used on the UNIX domain socket created by that 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`.
++
+IMPORTANT: Not all systems validate these permissions.
+In particular, illumos and Solaris are known to ignore these permission
+settings when connecting.
++
+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.
++
+TIP: The best practice for limiting access is to place the socket in a
+directory writable only by the server, and only readable and searchable
+by clients.
+All mainstream POSIX systems will fail to permit a client to connect
+to a socket located in a directory for which the client lacks search (execute)
+permission.
++
+TIP: Also consider using the `NNG_OPT_IPC_PEER_UID` property from within a
+a pipe notification callback (`<<nng_pipe_notify.3#,nng_pipe_notify()>>`)
+to validate peer credentials.
+
+[[NNG_OPT_IPC_SECURITY_DESCRIPTOR]]((`NNG_OPT_IPC_SECURITY_DESCRIPTOR`))::
+(`PSECURITY_DESCRIPTOR`)
+This write-only option may be used on listeners on Windows platforms to
+configure the `SECURITY_DESCRIPTOR` that is used when creating the underlying
+named pipe.
+The value is a pointer, `PSECURITY_DESCRIPTOR`, and may only be
+applied to listeners that have not been started yet.
+
 == SEE ALSO
 
 [.text-left]