title: nng_ctx(5)

summary: protocol context

text:
# nng_ctx(5)

## NAME
nng_ctx - protocol context

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_ctx_s nng_ctx
```

## DESCRIPTION
An nng_ctx is a handle to an underlying context object, which keeps the protocol state for some stateful protocols. The purpose of a separate context object is to permit applications to share a single socket, with its various underlying dialers, listeners, and pipes, while still benefiting from separate state tracking.

For example, a req context will contain the request ID of any sent request, a timer to retry the request on failure, and so forth. A separate context on the same socket can have similar data, but corresponding to a completely different request.

Important The nng_ctx structure is always passed by value (both

for input parameters and return values), and should be treated opaquely. Passing structures this way gives the compiler a chance to perform accurate type checks in functions passing values of this type.

All contexts share the same socket, and so some options, as well as the underlying transport details, will be common to all contexts on that socket.

Note Not every protocol supports separate contexts.

See the protocol-specific documentation for further details about whether contexts are supported, and details about what options are supported for contexts.

Protocols that make use of contexts will also have a default context that is used when the socket global operations are used. Operations using the global context will generally not interfere with any other contexts, except that certain socket options may affect socket global behavior.

Historically, applications wanting to use a stateful protocol concurrently would have to resort to raw mode sockets, which bypasses much of the various protocol handling, leaving it to up to the application to do so. Contexts make it possible to still benefit from advanced protocol handling, including timeouts, retries, and matching requests to responses, while doing so concurrently.

Note Raw mode sockets do not support contexts, since

there is generally no state tracked for them, and thus contexts make no sense.

Tip Contexts are an excellent mechanism to use when building concurrent

applications, and should be used in lieu of raw mode sockets when possible.

Important Use of file descriptor polling (with descriptors

obtained using the NNG_OPT_RECVFD or NNG_OPT_SENDFD options) while contexts are in use on the same socket is not supported, and may lead to unpredictable behavior. These asynchronous methods should not be mixed on the same socket.

### Initialization
A context may be initialized using the macro NNG_CTX_INITIALIZER before it is opened, to prevent confusion with valid open contexts.

## EXAMPLE
The following program fragment demonstrates the use of contexts to implement a concurrent rep service that simply echos messages back to the sender.

```
struct echo_context {

    nng_ctx ctx;

    nng_aio *aio;

    enum { INIT, RECV, SEND } state;
};
void
echo(void *arg)
{

    struct echo_context *ec = arg;

    switch (ec->state) {

    case INIT:

        ec->state = RECV;

        nng_ctx_recv(ec->ctx, ec->aio);

        return;

    case RECV:

        if (nng_aio_result(ec->aio) != 0) {

            // ... handle error

        }

        // We reuse the message on the ec->aio

        ec->state = SEND;

        nng_ctx_send(ec->ctx, ec->aio);

        return;

    case SEND:

        if (nng_aio_result(ec->aio) != 0) {

            // ... handle error

        }

        ec->state = RECV;

        nng_ctx_recv(ec->ctx, ec->aio);

        return;

    }
}
```

Given the above fragment, the following example shows setting up the service. It assumes that the socket has already been created and any transports set up as well with functions such as nng_dial() or nng_listen().

```
#define CONCURRENCY 1024
static struct echo_context ecs[CONCURRENCY];
void
start_echo_service(nng_socket rep_socket)
{

    for (int i = 0; i < CONCURRENCY; i++) {

        // error checks elided for clarity

        nng_ctx_open(&ecs[i].ctx, rep_socket);

        nng_aio_alloc(&ecs[i].aio, echo, ecs+i);

        ecs[i].state = INIT;

        echo(ecs+i); // start it running

    }
}
```

## SEE ALSO
libnng(3), nng_ctx_close(3), nng_ctx_open(3), nng_ctx_get(3), nng_ctx_id(3), nng_ctx_recv(3), nng_ctx_recvmsg(3), nng_ctx_send(3), nng_ctx_sendmsg(3), nng_ctx_set(3), nng_dialer(5), nng_listener(5), nng_socket(5), nng_options(5), nng(7)


package: libnng-devel

title: nng_dialer(5)

summary: dialer

text:
# nng_dialer(5)

## NAME
nng_dialer - dialer

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_dialer_s nng_dialer;
```

## DESCRIPTION
An nng_dialer is a handle to a dialer object, which is responsible for creating a single nng_pipe at a time by establishing an outgoing connection.

If the connection is broken, or fails, the dialer object will automatically attempt to reconnect, and will keep doing so until the dialer or socket is destroyed.

Dialer objects are created by the nng_dialer_create() or nng_dial() functions, and are always associated with a single nng_socket.

Important The nng_dialer structure is always passed by value (both

for input parameters and return values), and should be treated opaquely. Passing structures this way gives the compiler a chance to perform accurate type checks in functions passing values of this type.

Tip A given nng_socket may have multiple dialer

objects, multiple listener objects, or even some of both.

Tip The client/server relationship described by dialer/listener is

completely orthogonal to any similar relationship in the protocols. For example, a rep socket may use a dialer to connect to a listener on an req socket. This orthogonality can lead to innovative solutions to otherwise challenging communications problems.

Dialer objects may be destroyed by the nng_dialer_close() function. They are also closed when their associated socket is closed.

### Initialization
A dialer may be initialized using the macro NNG_DIALER_INITIALIZER before it is opened, to prevent confusion with valid open dialers.

## SEE ALSO
nng_dial(3), nng_dialer_close(3), nng_dialer_create(3), nng_dialer_getopt(3), nng_dialer_id(3), nng_dialer_setopt(3), nng_dialer_start(3), nng_listener(5), nng_pipe(5), nng_socket(5), nng(7)

branch: sisyphus


title: nng_duration(5)

summary: relative time in milliseconds

text:
# nng_duration(5)

## NAME
nng_duration - relative time in milliseconds

## SYNOPSIS

```
#include <nng/nng.h>
typedef int32_t nng_duration;
#define NNG_DURATION_INFINITE (-1)
#define NNG_DURATION_DEFAULT  (-2)
#define NNG_DURATION_ZERO     (0)
```

## DESCRIPTION
An nng_duration is a relative time, measured in milliseconds. This type is most often used in conjunction with timers and timeouts.

A couple of special values have been set aside, and carry special meanings.

NNG_DURATION_DEFAULT

Indicates a context-specific default value should be used.

NNG_DURATION_INFINITE

Effectively an infinite duration; used most often to disable timeouts.

NNG_DURATION_ZERO

Zero length duration; used to perform a single polling operation.

## SEE ALSO
nng_options(5), nng(7)


title: nng_iov(5)

summary: scatter/gather element

text:
# nng_iov(5)

## NAME
nng_iov - scatter/gather element

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct {

    void * iov_buf;

    size_t iov_len;
} nng_iov;
```

## DESCRIPTION
An nng_iov structure represents a single element in a scatter/gather array. Some operations can use arrays of these to access different regions of memory in a single operation. For example, it may be useful to send a message with header data from one part of memory, and a user payload from another.

The operations that do this typically store an array of these in an nng_aio structure using the nng_aio_set_iov() function.

The following structure members are present:

iov_buf

This is a pointer to the first byte within the memory being referenced by this scatter/gather element.

iov_len

This is the size in bytes of this scatter/gather element.

## SEE ALSO
nng_aio_set_iov(3), nng_aio(5), nng(7)


title: nng_ipc_options(5)

summary: IPC\-specific options

text:
# nng_ipc_options(5)

## NAME
nng_ipc_options - IPC-specific options

## SYNOPSIS

```
#include <nng/nng.h>
#define NNG_OPT_IPC_PEER_GID            "ipc:peer-gid"
#define NNG_OPT_IPC_PEER_PID            "ipc:peer-pid"
#define NNG_OPT_IPC_PEER_UID            "ipc:peer-uid"
#define NNG_OPT_IPC_PEER_ZONEID         "ipc:peer-zoneid"
#define NNG_OPT_IPC_PERMISSIONS         "ipc:permissions"
#define NNG_OPT_IPC_SECURITY_DESCRIPTOR "ipc:security-descriptor"
```

## DESCRIPTION
This page documents the various standard options that can be set or retrieved on objects using IPC.

The option names should always be used by their symbolic definitions.

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, or may 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 the following options is platform-specific,

as the implementations of IPC are quite different on Windows and POSIX systems.

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.

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.

### Common Platform Specific Options
The following options are supported by this transport when the underlying platform supports them:

•NNG_OPT_PEER_GID (also available as NNG_OPT_IPC_PEER_GID)

•NNG_OPT_PEER_PID (also available as NNG_OPT_IPC_PEER_PID)

•NNG_OPT_PEER_UID (also available as NNG_OPT_IPC_PEER_UID)

•NNG_OPT_PEER_ZONEID (also available as NNG_OPT_IPC_PEER_ZONEID)

### Inherited Options
Generally, the following option values are also available when appropriate for the context:

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

## SEE ALSO
nng_dialer_get(3), nng_dialer_set(3), nng_listener_get(3), nng_listener_set(3), nng_pipe_get(3), nng_options(5) nng(7), nng_ipc(7)


title: nng_listener(5)

summary: listener

text:
# nng_listener(5)

## NAME
nng_listener - listener

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_listener_s nng_listener;
```

## DESCRIPTION
An nng_listener is a handle to a listener object, which is responsible for creating nng_pipe objects by accepting incoming connections. A given listener object may create many pipes at the same time, much like an HTTP server can have many connections to multiple clients simultaneously.

Listener objects are created by the nng_listener_create() or nng_listen() functions, and are always associated with a single nng_socket.

Important The nng_listener structure is always passed by value (both

for input parameters and return values), and should be treated opaquely. Passing structures this way gives the compiler a chance to perform accurate type checks in functions passing values of this type.

Tip A given nng_socket may have multiple listener

objects, multiple dialer objects, or even some of both.

Tip The client/server relationship described by dialer/listener is

completely orthogonal to any similar relationship in the protocols. For example, a rep socket may use a dialer to connect to a listener on an req socket. This orthogonality can lead to innovative solutions to otherwise challenging communications problems.

Listener objects may be destroyed by the nng_listener_close() function. They are also closed when their associated socket is closed.

### Initialization
A listener may be initialized using the macro NNG_LISTENER_INITIALIZER before it is opened, to prevent confusion with valid open listener.

## SEE ALSO
nng_listen(3), nng_listener_close(3), nng_listener_create(3), nng_listener_getopt(3), nng_listener_id(3), nng_listener_setopt(3), nng_listener_start(3), nng_dialer(5), nng_pipe(5), nng_socket(5), nng(7)


title: nng_msg(5)

summary: message

text:
# nng_msg(5)

## NAME
nng_msg - message

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_msg nng_msg;
```

## DESCRIPTION
An nng_msg represents a single message sent between Scalability Protocols peers. Messages internally have a body, containing the application supplied payload, and a header, containing protocol specific routing and similar related information.

Tip Using message-oriented functions is a good way to reduce the likelihood

of data copies and improve application performance.

Messages are allocated using the nng_msg_alloc() function, and are deallocated using the nng_msg_free() function.

In addition there are other functions used to access message contents, including adding data to either the beginning or end of the message, automatic data conversion, and removing data from the beginning or end. These functions are designed to try to avoid copying message contents by making use of scratch areas at the beginning and end of the message.

## SEE ALSO
nng_aio_get_msg(3), nng_aio_set_msg(3), nng_msg_alloc(3), nng_msg_body(3), nng_msg_dup(3), nng_msg_free(3), nng_msg_header(3), nng_msg_header_len(3), nng_msg_len(3), nng_msg_capacity(3), nng_msg_reserve(3), nng_msg_realloc(3), nng_recvmsg(3), nng_sendmsg(3), nng_strerror(3), nng(7)


title: nng_options(5)

text:
# nng_options(5)

## NAME
nng_options - socket, dialer, listener, and pipe options

## SYNOPSIS

```
#include <nng/nng.h>
#define NNG_OPT_SOCKNAME      "socket-name"
#define NNG_OPT_RAW           "raw"
#define NNG_OPT_PROTO         "protocol"
#define NNG_OPT_PROTONAME     "protocol-name"
#define NNG_OPT_PEER          "peer"
#define NNG_OPT_PEERNAME      "peer-name"
#define NNG_OPT_RECVBUF       "recv-buffer"
#define NNG_OPT_SENDBUF       "send-buffer"
#define NNG_OPT_RECVFD        "recv-fd"
#define NNG_OPT_SENDFD        "send-fd"
#define NNG_OPT_RECVTIMEO     "recv-timeout"
#define NNG_OPT_SENDTIMEO     "send-timeout"
#define NNG_OPT_LOCADDR       "local-address"
#define NNG_OPT_REMADDR       "remote-address"
#define NNG_OPT_URL           "url"
#define NNG_OPT_MAXTTL        "ttl-max"
#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
This page documents the various standard options that can be set or retrieved on objects.

Sockets (nng_socket objects) use the functions nng_socket_get() and nng_socket_set() to set and retrieve option values.

Dialers (nng_dialer objects) use the functions nng_dialer_get() and nng_dialer_set() to set and retrieve option values.

Listeners (nng_listener objects) use the functions nng_listener_get() and nng_listener_set() to set and retrieve option values.

Pipes (nng_pipe objects) can only retrieve option values using the nng_pipe_get() function.

Other object types may have additional methods to access these options.

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.

### 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. An attempt has been made to include details about such restrictions in the description of the option.

NNG_OPT_LOCADDR

(nng_sockaddr) This read-only option may be used on listeners, dialers and connected pipes, and represents the local address used for communication. NOTE: Not all transports support this option, and some transports may support it on listeners but not dialers. When used on a TCP dialer, this option is used to configure the source IP address that will be used when initiating outgoing connections. The specific port number will be ignored, however, and the system will choose a random ephemeral port instead.

NNG_OPT_RAW

(bool) This read-only option indicates whether the socket is in raw mode. If true, the socket is in raw mode, and if false the socket is in normal mode.

Raw mode sockets generally do not have any protocol-specific semantics applied to them; instead the application is expected to perform such semantics itself. (For example, in normal mode a rep socket would automatically copy message headers from a received message to the corresponding reply, whereas in raw mode this is not done.) See Raw Mode for more details.

Note This option is deprecated. Use the nng_socket_raw function instead.

NNG_OPT_RECONNMINT

(nng_duration) This is the minimum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners.

NNG_OPT_RECONNMAXT

(nng_duration) This is the maximum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. If this is non-zero, then the time between successive connection attempts will start at the value of NNG_OPT_RECONNMINT, and grow exponentially, until it reaches this value. If this value is zero, then no exponential back-off between connection attempts is done, and each attempt will wait the time specified by NNG_OPT_RECONNMINT. This can be set on a socket, but it can also be overridden on an individual dialer. The option is irrelevant for listeners.

NNG_OPT_RECVBUF

(int) This is the depth of the socket’s receive buffer as a number of messages. Messages received by a transport may be buffered until the application has accepted them for delivery. This value must be an integer between 0 and 8192, inclusive. NOTE: Not all protocols support buffering received messages. For example req can only deal with a single reply at a time.

NNG_OPT_RECVFD

(int) This read-only option is used to obtain an integer file descriptor suitable for use with poll() <http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html>, select() <http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html>, (or on Windows systems WSAPoll() <https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx>) and similar functions. This descriptor will be readable when a message is available for receiving on the socket. When no message is ready for receiving, then this file descriptor will not be readable.

Important Applications should never attempt to read or write to the

returned file descriptor.

Important This option is incompatible with

nng_ctx contexts and should not be used on a socket where they are in use.

Tip While this option may help applications integrate into existing polling

loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. See nng_aio_alloc().

NNG_OPT_RECVMAXSZ

(size_t) This is the maximum message size that the will be accepted from a remote peer. If a peer attempts to send a message larger than this, then the message will be discarded. If the value of this is zero, then no limit on message sizes is enforced. This option exists to prevent certain kinds of denial-of-service attacks, where a malicious agent can claim to want to send an extraordinarily large message, without sending any data. This option can be set for the socket, but may be overridden for on a per-dialer or per-listener basis.

Important Applications on hostile networks should set this to a non-zero

value to prevent denial-of-service attacks.

Important This option should be set before any listeners or dialers are added.

Ideally this option should be set on specific dialers or listeners; setting it on the socket globally is deprecated behavior, and might not work in a future release, or might only work for endpoints that have not yet been created. (Maximum receive sizes might be negotiated during connection establishment for future transports, which means that the option needs to be set before any connections are established.)

Note Some transports may have further message size restrictions.

NNG_OPT_RECVTIMEO

(nng_duration) This is the socket receive timeout in milliseconds. When no message is available for receiving at the socket for this period of time, receive operations will fail with a return value of NNG_ETIMEDOUT.

NNG_OPT_REMADDR

(nng_sockaddr) This read-only option may be used on dialers and connected pipes, and represents the address of a remote peer. Not all transports support this option.

NNG_OPT_SENDBUF

(int) This is the depth of the socket send buffer as a number of messages. Messages sent by an application may be buffered by the socket until a transport is ready to accept them for delivery. This value must be an integer between 0 and 8192, inclusive.

Note Not all protocols support buffering sent messages.

For example, req can only have a single request outstanding at a time (per context).

NNG_OPT_SENDFD

(int) This read-only option is used to obtain an integer file descriptor suitable for use with poll() <http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html>, select() <http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html>, (or on Windows systems WSAPoll() <https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx>) and similar functions.

This descriptor will be readable when the socket is able to accept a message for sending without blocking. When the socket is no longer able to accept such messages without blocking, the descriptor will not be readable.

Important Applications should never attempt to read or write to the

returned file descriptor; use should be limited to polling system calls only.

Important This option is incompatible with

nng_ctx contexts and should not be used on a socket where they are in use.

Tip While this option may help applications integrate into existing polling

loops, it is more efficient, and often easier, to use the asynchronous I/O objects instead. See nng_aio_alloc().

NNG_OPT_SENDTIMEO

(nng_duration) This is the socket send timeout in milliseconds. When a message cannot be queued for delivery by the socket for this period of time (such as if send buffers are full), the operation will fail with a return value of NNG_ETIMEDOUT.

NNG_OPT_SOCKNAME

(string) This the socket name. By default, this is a string corresponding to the value of the socket. The string must fit within 64-bytes, including the terminating NUL byte. The value is intended for application use, and is not used for anything in the library itself.

NNG_OPT_MAXTTL

(int) This is the maximum number of times a message may traverse across a nng_device() forwarders. The intention here is to prevent forwarding loops in device chains. When this is supported, it can have a value between 1 and 255, inclusive.

Note Not all protocols support this option.

Those that do generally have a default value of 8.

Tip Each node along a forwarding path may have its own value for the

maximum time-to-live, and performs its own checks before forwarding a message. Therefore it is helpful if all nodes in the topology use the same value for this option.

NNG_OPT_URL

(string) This read-only option is used to obtain the URL with which a listener or dialer was configured. Accordingly it can only be used with dialers, listeners, and pipes.

Note Some transports will canonify URLs before returning them to the

application.

NNG_OPT_PROTO

(int) This read-only option is used to obtain the 16-bit number for the socket’s protocol.

Note This option is deprecated. Use the nng_socket_proto_id function instead.

NNG_OPT_PEER

(int) This read-only option is used to obtain the 16-bit number of the peer protocol for the socket.

Note This option is deprecated. Use the nng_socket_peer_id function instead.

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

(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

(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

(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

(string) This read-only option is used to obtain the name of the peer protocol for the socket.

Note This option is deprecated. Use the nng_socket_peer_name function instead.

NNG_OPT_PROTONAME

(string) This read-only option is used to obtain the name of the socket’s protocol.

Note This option is deprecated. Use the nng_socket_proto_name function instead.

## SEE ALSO
nng_dialer_get(3), nng_dialer_set(3), nng_listener_get(3), nng_listener_set(3), nng_pipe_get(3), nng_socket_get(3), nng_socket_set(3), nng_ipc_options(5), nng_tcp_options(5), nng_tls_options(5), nng(7)


title: nng_pipe(5)

summary: communications pipe

text:
# nng_pipe(5)

## NAME
nng_pipe - communications pipe

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_pipe_s nng_pipe;
```

## DESCRIPTION
An nng_pipe is a handle to a pipe object, which can be thought of as a single connection. (In most cases this is actually the case — the pipe is an abstraction for a single TCP or IPC connection.) Pipes are associated with either the listener or dialer that created them, and therefore are also automatically associated with a single socket.

Important The nng_pipe structure is always passed by value (both

for input parameters and return values), and should be treated opaquely. Passing structures this way gives the compiler a chance to perform accurate type checks in functions passing values of this type.

Tip Most applications should never concern themselves with individual pipes.

However it is possible to access a pipe when more information about the source of a message is needed, or when more control is required over message delivery.

Pipe objects are created by dialers (nng_dialer objects) and listeners (nng_listener objects).

Pipe objects may be destroyed by the nng_pipe_close() function. They are also closed when the dialer or listener that created them is closed, or when the remote peer closes the underlying connection.

### Initialization
A pipe may be initialized using the macro NNG_PIPE_INITIALIZER before it is opened, to prevent confusion with valid open pipes.

For example:

```
nng_pipe p = NNG_PIPE_INITIALIZER;
```

## SEE ALSO
nng_msg_get_pipe(3), nng_pipe_close(3), nng_pipe_getopt(3), nng_pipe_dialer(3), nng_pipe_id(3), nng_pipe_listener(3), nng_pipe_socket(3), nng_dialer(5), nng_listener(5), nng_options(5), nng(7)


title: nng_sockaddr(5)

summary: socket address

text:
# nng_sockaddr(5)

## NAME
nng_sockaddr - socket address

## SYNOPSIS

```
#include <nng/nng.h>
typedef union nng_sockaddr {

    uint16_t              s_family;

    nng_sockaddr_ipc      s_ipc;

    nng_sockaddr_inproc   s_inproc;

    nng_sockaddr_in       s_in;

    nng_sockaddr_in6      s_in6;

    nng_sockaddr_zt       s_zt;

    nng_sockaddr_abstract s_abstract;
} nng_sockaddr;
enum sockaddr_family {

    NNG_AF_UNSPEC   = 0,

    NNG_AF_INPROC   = 1,

    NNG_AF_IPC      = 2,

    NNG_AF_INET     = 3,

    NNG_AF_INET6    = 4,

    NNG_AF_ZT       = 5,

    NNG_AF_ABSTRACT = 6
};
```

## DESCRIPTION
An nng_sockaddr is a structure used for representing the addresses used by underlying transports, such as TCP/IP addresses, IPC paths, and so forth.

The name sockaddr is based on its similarity with POSIX struct sockaddr, but in NNG, these addresses are more closely affiliated with instances of nng_pipe than of nng_socket. The naming confusion is unfortunate.

This structure is actually a union, with different members for different types of addresses.

Every member structure has as its first element a uint16_t field containing the address family. This overlaps the s_family member of the union, and indicates which specific member should be used.

The values of s_family are as follows:

NNG_AF_UNSPEC

Invalid address, no other valid fields.

NNG_AF_INPROC

Address for intraprocess communication (nng_inproc(7)). The s_inproc member is valid.

NNG_AF_IPC

Address for interprocess communication (nng_ipc(7)). The s_path member is valid.

NNG_AF_INET

Address for TCP/IP (v4) communication. The s_in member is valid.

NNG_AF_INET6

Address for TCP/IP (v6) communication. The s_in6 member is valid.

NNG_AF_ZT

Address for ZeroTier transport (nng_zerotier(7)). The s_zt member is valid.

NNG_AF_ABSTRACT

Address for an abstract UNIX domain socket. The s_abstract member is valid.

Please see the manual pages for each individual type for more information.

## SEE ALSO
nng_sockaddr_abstract(5), nng_sockaddr_in(5), nng_sockaddr_in6(5), nng_sockaddr_inproc(5), nng_sockaddr_ipc(5), nng_sockaddr_zt(5), nng(7)


title: nng_sockaddr_abstract(5)

summary: abstract IPC socket address

text:
# nng_sockaddr_abstract(5)

## NAME
nng_sockaddr_abstract - abstract IPC socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_ABSTRACT = 6,
};
typedef struct {

    uint16_t sa_family;

    uint16_t sa_len;

    char     sa_name[107];
} nng_sockaddr_abstract;
```

## DESCRIPTION

An nng_sockaddr_abstract is the flavor of nng_sockaddr used to represent addresses associated with IPC communication using “abstract” sockets.

Abstract sockets are only supported on Linux at present. These sockets have a name that is simply an array of bytes, with no special meaning. Abstract sockets also have no presence in the file system, do not honor any permissions, and are automatically cleaned up by the operating system when no longer in use.

Note Support for abstract sockets is a new feature in NNG, and it is only available on Linux.

As such their use is not recommended for portable applications.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_ABSTRACT.

sa_len

This field provides the name of the length stored in sa_name.

sa_name

This field holds the name of the abstract socket. The bytes of name can have any value, including zero.

Note The name does not include the leading NUL byte used on Linux to discriminate between

abstract and path name sockets.

### Auto Bind
An empty value (sa_len equal to zero) can be used on listening sockets to request the system allocate a name. On Linux systems, this will result in a name with either 5 or 8 hexadecimal ASCII characters. The name chosen can be obtained by retrieving the NNG_OPT_LOCADDR option on the listening entity.

Note Because a zero length name is used to indicate auto bind be used, it is impossible to specify

an actual empty name. This name are not supported by NNG, although the underlying system can support it. The use of that name is inadvisable anyway.

## SEE ALSO
nng_sockaddr(5), nng_ipc(7) nng(7)


title: nng_sockaddr_in(5)

summary: IPv4 socket address

text:
# nng_sockaddr_in(5)

## NAME
nng_sockaddr_in - IPv4 socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_INET = 3,
};
typedef struct {

    uint16_t sa_family;

    uint16_t sa_port;

    uint32_t sa_addr;
} nng_sockaddr_in;
```

## DESCRIPTION
An nng_sockaddr_in is the flavor of nng_sockaddr used to represent TCP (and sometimes UDP) addresses, including the Internet Protocol (IP) address and port number.

This structure is used with IPv4 addresses. A different structure, nng_sockaddr_in6, is used for IPv6 addresses.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_INET.

sa_port

This field holds the TCP or UDP port number, in network byte-order. A zero value here is used when no specific port number is indicated.

sa_addr

This field holds the IP address in network-byte order.

Tip The sa_port and sa_addr fields are in network-byte order to

facilitate their use with system APIs such as inet_ntop(). Most platforms use some form of BSD-derived network API, which uses network-byte order in the various structures (such as sockaddr_in).

Important This field appears similar to BSD sockaddr_in, but it is

not the same, and they may not be used interchangeably.

## SEE ALSO
nng_sockaddr(5), nng_sockaddr_in6(5), nng_tcp(7), nng(7)


title: nng_sockaddr_in6(5)

summary: IPv6 socket address

text:
# nng_sockaddr_in6(5)

## NAME
nng_sockaddr_in6 - IPv6 socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_INET6 = 4,
};
typedef struct {

    uint16_t sa_family;

    uint16_t sa_port;

    uint8_t  sa_addr[16];

    uint32_t sa_scope;
} nng_sockaddr_in6;
```

## DESCRIPTION
An nng_sockaddr_in6 is the flavor of nng_sockaddr used to represent TCP (and sometimes UDP) addresses, including the Internet Protocol (IP) address and port number.

This structure is used with IPv6 addresses. A different structure, nng_sockaddr_in, is used for IPv4 addresses.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_INET6.

sa_port

This field holds the TCP or UDP port number, in network byte-order. A zero value here is used when no specific port number is indicated.

sa_addr

This field holds the IP address in network-byte order.

sa_scope

This is the scope, and is typically used with link local addresses to identify a specific interface. The details of this are specific to the operating system. This value is presented identically to the underlying system’s, including any byte order considerations.

Tip The sa_port and sa_addr fields are in network-byte order to

facilitate their use with system APIs such as inet_ntop(). Most platforms use some form of BSD-derived network API, which uses network-byte order in the various structures (such as sockaddr_in6).

Important This field appears similar to BSD sockaddr_in6, but it is

not the same, and they may not be used interchangeably.

## SEE ALSO
nng_sockaddr(5), nng_sockaddr_in(5), nng_tcp(7), nng(7)


title: nng_sockaddr_inproc(5)

summary: inproc socket address

text:
# nng_sockaddr_inproc(5)

## NAME
nng_sockaddr_inproc - inproc socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_INPROC = 1,
};
typedef struct {

    uint16_t sa_family;

    uint16_t sa_name[128];
} nng_sockaddr_inproc;
```

## DESCRIPTION
An nng_sockaddr_inproc is the flavor of nng_sockaddr used to represent addresses associated with intra-process communication using the inproc transport.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_INPROC.

sa_name

This field holds an arbitrary C string, which is the name of the address. The string must be NUL terminated, but no other restrictions exist.

Tip In order to ensure maximum compatibility, applications should avoid

hard coding the size of the sa_name member explicitly, but use the sizeof operator to determine its actual size at compile time. Furthermore, the size is guaranteed to be at least 128.

## SEE ALSO
nng_sockaddr(5), nng_inproc(7) nng(7)


title: nng_sockaddr_ipc(5)

summary: IPC socket address

text:
# nng_sockaddr_ipc(5)

## NAME
nng_sockaddr_ipc - IPC socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_IPC = 2,
};
typedef struct {

    uint16_t sa_family;

    char     sa_path[128];
} nng_sockaddr_ipc;
```

## DESCRIPTION

An nng_sockaddr_ipc is the flavor of nng_sockaddr used to represent addresses associated with IPC communication using the ipc transport.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_IPC.

sa_path

This field holds the C string corresponding to path name where the IPC socket is located. For systems using UNIX domain sockets, this will be a path name in the file system, where the UNIX domain socket is located. For Windows systems, this is the path name of the Named Pipe, without the leading \\.pipe\ portion, which will be automatically added.

Note At this time, there is no support for abstract sockets.

Tip In order to ensure maximum compatibility, applications should avoid hard coding the size of the sa_path member explicitly, but use the

sizeof operator to determine its actual size at compile time. Furthermore, the size is guaranteed to be at least 128, but paths of this length may not be supported on all systems.

Tip Portable applications should restrict themselves to path names of not more than 90 bytes. Most systems have

limits around 100 bytes, but at least one system (HP-UX) is restricted to not more than 92 bytes including the NUL.

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.

## SEE ALSO
nng_sockaddr(5), nng_ipc(7) nng(7)


title: nng_sockaddr_zt(5)

summary: ZeroTier socket address

text:
# nng_sockaddr_zt(5)

## NAME
nng_sockaddr_zt - ZeroTier socket address

## SYNOPSIS

```
#include <nng/nng.h>
enum sockaddr_family {

    NNG_AF_ZT = 5,
};
typedef struct {

    uint16_t sa_family;

    uint64_t sa_nwid;

    uint64_t sa_nodeid;

    uint32_t sa_port;
} nng_sockaddr_zt;
```

## DESCRIPTION
An nng_sockaddr_zt is the flavor of nng_sockaddr used to represent ZeroTier addresses, including the port number used by the zt transport.

Important The ZeroTier transport, and the details of this structure,

are still considered experimental, and subject to change.

The following structure members are present:

sa_family

This field will always have the value NNG_AF_ZT.

sa_nwid

This field holds the ZeroTier network number (or ID). This value is in native byte order.

sa_nodeid

This field holds the ZeroTier node ID. This value is in native byte order, and only the lower 40 bits are significant. (ZeroTier node numbers are 40 bits long.) A zero value here is used for a wild-card to indicate that the caller’s own node number be used.

sa_port

This field holds the port number used by the zt transport to distinguish different sockets. This value in native byte order. A zero value here indicates that a port number should be chosen randomly from the ephemeral ports. Only the lower 24 bits of the port number are used.

Note ZeroTier port numbers are in native byte order, and are larger

than TCP/IP port numbers. They are also not part of the ZeroTier protocol itself, but defined by the Scalability Protocols binding for them.

## SEE ALSO
nng_sockaddr(5), nng_zerotier(7), nng(7)


title: nng_socket(5)

summary: socket handle

text:
# nng_socket(5)

## NAME
nng_socket - socket handle

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_socket_s nng_socket;
```

## DESCRIPTION
An nng_socket is a handle to an underlying socket object. All communication between the application and remote Scalability Protocol peers is done through sockets. A given socket can have multiple dialers (nng_dialer) and/or listeners (nng_listener), and multiple pipes (nng_pipe), and may be connected to multiple transports at the same time. However, a given socket will have exactly one protocol associated with it, and is responsible for any state machines or other protocol-specific logic.

Important The nng_socket structure is always passed by value (both

for input parameters and return values), and should be treated opaquely. Passing structures this way gives the compiler a chance to perform accurate type checks in functions passing values of this type.

Each nng_socket is created by a protocol-specific constructor, such as nng_rep_open(). When the socket is no longer needed, it can be closed with nng_close().

### Initialization
A socket may be initialized using the macro NNG_SOCKET_INITIALIZER before it is opened, to prevent confusion with valid open sockets.

For example:

```
nng_socket s = NNG_SOCKET_INITIALIZER;
```

## SEE ALSO
libnng(3), nng_close(3), nng_getopt(3), nng_setopt(3), nng_socket_id(3), nng_dialer(5), nng_listener(5), nng_options(5), nng(7)


title: nng_stat(5)

summary: statistic

text:
# nng_stat(5)

## NAME
nng_stat - statistic

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_stat nng_stat;
```

## DESCRIPTION
An nng_stat represents a statistic. All statistics have names (nng_stat_name()) and descriptions (nng_stat_desc()), and are typed (nng_stat_type()).

Most statistics are numeric, and thus carry a value (nng_stat_value()) and frequently also a unit that the value measures (nng_stat_unit()).

Some statistics however, are simply strings (nng_stat_string()), and thus carry no numeric value.

Statistics are organized as a tree, and any given statistic can have siblings (nng_stat_next()). Note however that generally only NNG_STAT_SCOPE statistics, which are act as placeholders in the tree (and carry no value), will have children (nng_stat_child()).

A tree of statistics is collected using nng_stats_get(), and can be freed when no longer needed with nng_stats_free(). This collection process is generally performed in a way to minimize impact to running operations, but there is still some impact caused by collection of statistics.

The time when a statistic’s value is captured can be obtained using nng_stat_timestamp(), which is useful for measuring rates of change in certain statistics.

Note The presence, names, and meanings of any given statistic are

subject to change at any time. These statistics are provided as an aid for debugging, and should generally not be relied upon for programmatic behaviors.

Note Statistics may be disabled by build-time configuration options,

in order to reduce program size and run-time overheads.

## SEE ALSO
libnng(3), nng_stats_free(3), nng_stats_get(3), nng_stat_child(3), nng_stat_desc(3), nng_stat_find(3), nng_stat_find_dialer(3), nng_stat_find_listener(3), nng_stat_find_socket(3), nng_stat_name(3), nng_stat_next(3), nng_stat_string(3), nng_stat_timestamp(3), nng_stat_type(3), nng_stat_unit(3), nng_stat_value(3), nng(7)


title: nng_stream(5)

summary: byte stream

text:
# nng_stream(5)

## NAME
nng_stream - byte stream

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_stream nng_stream;
```

## DESCRIPTION
An nng_stream represents a byte stream. This may correspond to an underlying connection such a TCP connection or a connected UNIX domain socket or named pipe.

Note The nng_stream object is used for raw byte stream connections, and

should not be confused with a pipe object created on socket using the nng_listen(), nng_dial() or related functions.

These objects are created either establishing an outgoing connection with nng_stream_dialer_dial() or by accepting in incoming connection with nng_stream_listener_accept().

Byte streams are reliable in that data will not be delivered out of order, or with portions missing.

Data can be sent using nng_stream_send() or received with nng_stream_recv().

When the connection is no longer needed, it should be freed with nng_stream_free().

Tip It is possible to close the connection, without freeing it, by

using nng_stream_close().

Byte streams may, depending on the underlying technology, support various options, which can be accessed using the nng_stream_get() and nng_stream_set() family of functions.

## SEE ALSO
libnng(3), nng_stream_close(3str), nng_stream_dialer_dial(3str), nng_stream_free(3str), nng_stream_get(3str), nng_stream_listener_accept(3str), nng_stream_recv(3str), nng_stream_send(3str), nng_stream_set(3str), nng_options(5), nng(7),


title: nng_stream_dialer(5)

summary: byte stream dialer

text:
# nng_stream_dialer(5)

## NAME
nng_stream_dialer - byte stream dialer

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_stream_dialer nng_stream_dialer;
```

## DESCRIPTION
An nng_stream_dialer is a handle to a dialer for byte streams, and is responsible for creating nng_stream objects (corresponding to connected byte streams) by connecting to remote peers.

Note The nng_stream_dialer object is used for low-level byte stream

connections, and should not be confused with a high-level nng_dialer object.

## SEE ALSO
nng_stream_dialer_alloc(3str), nng_stream_dialer_close(3str), nng_stream_dialer_dial(3str), nng_stream_dialer_free(3str), nng_stream(5), nng_stream_listener(5)


title: nng_stream_listener(5)

summary: byte stream listener

text:
# nng_stream_listener(5)

## NAME
nng_stream_listener - byte stream listener

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_stream_listener nng_stream_listener;
```

## DESCRIPTION
An nng_stream_listener is a handle to a byte stream listener, which is responsible for accepting incoming connections and creating corresponding nng_stream from them.

Note The nng_stream_listener object is a low-level object for

raw byte stream connections, and should not be confused with a high-level nng_listener object.

## SEE ALSO
nng_stream_listener_accept(3str), nng_stream_listener_alloc(3str), nng_stream_listener_close(3str), nng_stream_listener_free(3str), nng_stream_listener_listen(3str), nng_stream(5), nng_stream_dialer(5)


title: nng_tcp_options(5)

summary: TCP\-specific options

text:
# nng_tcp_options(5)

## NAME
nng_tcp_options - TCP-specific options

## SYNOPSIS

```
#include <nng/nng.h>
#define NNG_OPT_TCP_NODELAY    "tcp-nodelay"
#define NNG_OPT_TCP_KEEPALIVE  "tcp-keepalive"
#define NNG_OPT_TCP_BOUND_PORT "tcp-bound-port"
```

## DESCRIPTION
This page documents the various standard options that can be set or retrieved on objects using TCP.

The option names should always be used by their symbolic definitions.

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, or may have other access restrictions. An attempt has been made to include details about such restrictions in the description of the option.

The following options are generally application to objects making use of TCP/IP communications.

### TCP Options
NNG_OPT_TCP_NODELAY

(bool) This option is used to disable (or enable) the use of Nagle’s algorithm for TCP connections.

Note This setting may apply to transports that are built on top of TCP.

See the transport documentation for each transport for details.

When true (the default), messages are sent immediately by the underlying TCP stream without waiting to gather more data.

When false, Nagle’s algorithm is enabled, and the TCP stream may wait briefly in attempt to coalesce messages. Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, but it comes at a cost to latency.

When used on a dialer or a listener, the value affects how newly created connections will be configured.

NNG_OPT_TCP_KEEPALIVE

(bool) This option is used to enable the sending of keep-alive messages on the underlying TCP stream. This option is false by default.

Note This setting may apply to transports that are built on top of TCP.

See the transport documentation for each transport for details.

When enabled, if no messages are seen for a period of time, then a zero length TCP message is sent with the ACK flag set in an attempt to tickle some traffic from the peer. If none is still seen (after some platform-specific number of retries and timeouts), then the remote peer is presumed dead, and the connection is closed.

When used on a dialer or a listener, the value affects how newly created connections will be configured.

Tip This option has two purposes.

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.

NNG_OPT_TCP_BOUND_PORT

(int) This option is available on listeners, after the listern has bound to a port, and provides the port bound to in native byte order. This is most useful when using a listener with an ephemeral port (configured by using port 0 at configuration time), as it allows the caller to determine the actual ephemeral port that was chosen by the system. While the value is of type int, it will be a legal TCP port number, that is a value between 1 and 65535, inclusive.

### Inherited Options
Generally, the following option values are also available for TCP objects, when appropriate for the context:

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

## SEE ALSO
nng_tcp_dialer_getopt(3tcp), nng_tcp_dialer_setopt(3tcp), nng_tcp_getopt(3tcp), nng_tcp_listener_getopt(3tcp), nng_tcp_listener_setopt(3tcp), nng_tcp_setopt(3tcp), nng_options(5) nng(7)


title: nng_tls_config(5)

summary: TLS configuration object

text:
# nng_tls_config(5)

## NAME
nng_tls_config - TLS configuration object

## SYNOPSIS

```
#include <nng/supplemental/tls/tls.h>
typedef struct nng_tls_config nng_tls_config;
```

## DESCRIPTION
An nng_tls_config represents a single TLS configuration object, which can be used to configure TLS servers and clients.

Configuration data includes details such as certificate chains used for validation of remote peers, local key and certificate material, server names, and so forth. Additionally, a configuration can be used either in client mode, or in server mode.

Configuration objects may be shared, and are reference counted. However once a configuration is used, it enters a read-only state that precludes further modifications to the configuration.

Messages are allocated using the nng_tls_config_alloc() function, and are deallocated using the nng_tls_config_free() function.

## SEE ALSO
nng_tls_config_alloc(3tls), nng_tls_config_auth_mode(3tls), nng_tls_config_ca_chain(3tls), nng_tls_config_own_cert(3tls), nng_tls_config_free(3tls), nng_tls_config_hold(3tls), nng_tls_config_server_name(3tls), nng(7)


title: nng_tls_engine(5)

summary: TLS engine implementation

text:
# nng_tls_engine(5)

## NAME
nng_tls_engine - TLS engine implementation

## SYNOPSIS

```
#include <nng/supplemental/tls/tls.h>
#include <nng/supplemental/tls/engine.h>
typedef struct nng_tls_engine_s nng_tls_engine;
```

## DESCRIPTION
The TLS engine API is provided for developers wishing to implement their own implementation of TLS, or to adapt a 3rd party TLS implementation to the work with NNG.

Information about the existing TLS engine can be obtained from the functions nng_tls_engine_name(), nng_tls_engine_description(), and nng_tls_engine_fips_mode() functions.

At this time, there is no further documentation on implementing a TLS engine oneself, but existing source code may be a guide. The primary interfaces are located in the <nng/supplemental/tls/engine.h> header file.

## SEE ALSO
nng_tls_engine_description(3tls), nng_tls_engine_fips_mode(3tls), nng_tls_engine_name(3tls), nng_tls_config(5), nng(7)


title: nng_tls_options(5)

summary: TLS\-specific options

text:
# nng_tls_options(5)

## NAME
nng_tls_options - TLS-specific options

## SYNOPSIS

```
#include <nng/nng.h>
#define NNG_OPT_TLS_AUTH_MODE      "tls-authmode"
#define NNG_OPT_TLS_CA_FILE        "tls-ca-file"
#define NNG_OPT_TLS_CERT_KEY_FILE  "tls-cert-key-file"
#define NNG_OPT_TLS_CONFIG         "tls-config"
#define NNG_OPT_TLS_SERVER_NAME    "tls-server-name"
#define NNG_OPT_TLS_VERIFIED       "tls-verified"
#define NNG_OPT_TLS_PEER_CN        "tls-peer-cn"
#define NNG_OPT_TLS_PEER_ALT_NAMES "tls-peer-alt-names"
```

## DESCRIPTION
This page documents the various standard options that can be set or retrieved on objects using TLS.

The option names should always be used by their symbolic definitions.

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, or may have other access restrictions. An attempt has been made to include details about such restrictions in the description of the option.

### TLS Options

Note Options for configuring TLS are deprecated and may

not be present in a future release. These options are NNG_OPT_TLS_AUTH_MODE, NNG_OPT_TLS_CA_FILE, NNG_OPT_TLS_CERT_KEY_FILE, and NNG_OPT_TLS_SERVER_NAME. Applications should switch to using the NNG_OPT_TLS_CONFIG option and working with nng_tls_config objects.

NNG_OPT_TLS_AUTH_MODE

(int) Write-only option used to configure the authentication mode used. See nng_tls_config_auth_mode() for more details.

NNG_OPT_TLS_CA_FILE

(string) Write-only option naming a file containing certificates to use for peer validation. See nng_tls_config_ca_file() for more information.

NNG_OPT_TLS_CERT_KEY_FILE

(string) Write-only option naming a file containing the local certificate and associated private key. The private key used must be unencrypted. See nng_tls_config_own_cert() for more information.

NNG_OPT_TLS_CONFIG

(nng_tls_config *) This option references the underlying TLS configuration object. A hold is placed on the underlying configuration object before returning it.

Note The caller should release the hold with

nng_tls_config_free() when it no longer needs the TLS configuration object.

NNG_OPT_TLS_SERVER_NAME

(string) This write-only option is used to specify the name of the server. When used with a dialer, this potentially configures SNI (server name indication, which is used as a hint by a multihosting server to choose the appropriate certificate to provide) and also is used to validate the name presented in the server’s x509 certificate.

NNG_OPT_TLS_VERIFIED

(bool) This read-only option indicates whether the remote peer has been properly verified using TLS authentication. May return incorrect results if peer authentication is disabled.

NNG_OPT_TLS_PEER_CN

(string) This read-only option returns the common name of the peer certificate. May return incorrect results if peer authentication is disabled.

NNG_OPT_TLS_PEER_ALT_NAMES

(string) This read-only option returns string list with the subject alternative names of the peer certificate. May return incorrect results if peer authentication is disabled.

### Inherited Options
Generally, the following option values are also available for TLS objects, when appropriate for the context:

•NNG_OPT_LOCADDR

•NNG_OPT_REMADDR

•NNG_OPT_TCP_KEEPALIVE

•NNG_OPT_TCP_NODELAY

## SEE ALSO
nng_options(5) nng_tcp_options(5) nng_tls_config(5), nng(7)


title: nng_url(5)

summary: Universal Resource Locator object

text:
# nng_url(5)

## NAME
nng_url - Universal Resource Locator object

## SYNOPSIS

```
#include <nng/nng.h>
typedef struct nng_url {

    char *u_rawurl;

    char *u_scheme;

    char *u_userinfo;

    char *u_host;

    char *u_hostname;

    char *u_port;

    char *u_path;

    char *u_query;

    char *u_fragment;

    char *u_requri;
} nng_url;
```

## DESCRIPTION
An nng_url is a structure used for representing URLs. These structures are created by parsing string formatted URLs with nng_url_parse().

Applications may access individual fields, but must not free or alter them, as the underlying memory is managed by the library.

The fields are as follows:

u_rawurl

The unparsed URL string. This will never be NULL.

u_scheme

The URL scheme, such as "http" or "inproc". Always lower case. This will never be NULL.

u_userinfo

This username and password if supplied in the URL string. Will be NULL when not present.

u_host

The full host part of the URL, including the port if present (separated by a colon.)

u_hostname

The name of the host, and may be the empty string in some cases.

u_port

The port. May be empty if irrelevant or not specified.

u_path

The path, typically used with HTTP or WebSockets. Will be empty string if not specified.

u_query

The query info (typically following ? in the URL.) Will be NULL if not present.

u_fragment

This is used for specifying an anchor, the part after # in a URL. Will be NULL if not present.

u_requri

The full Request-URI (path[?query][#fragment]). Will be the empty string if not specified.

Note Other fields may also be present, but only those documented here are safe for application use.

Tip More information about Universal Resource Locators can be found in

RFC 3986 <https://tools.ietf.org/html/rfc3986>.

## SEE ALSO
nng_url_clone(3), nng_url_free(3), nng_url_parse(3), nng(7)


title: r2test.conf(5)

text:
# r2test.conf(5)

## NAME
r2test.conf - OpenR2 r2test program configuration file

## SYNOPSIS
/etc/openr2/r2test.conf

## DESCRIPTION
This file defines the behavior of the r2test program

This file works pretty much like Asterisk zapata.conf file, the channel parameter will create a R2 context with the specified range of channels and will take all the preceding parameters as configuration.

## SYNTAX
No spaces are allowed in parameter definition, lines starting with # or spaces will be ignored

This definition will not be read properly

param = value

This definition will be read fine

param=value

## OPTIONS
category=<NATIONAL_SUBSCRIBER, NATIONAL_PRIORITY_SUBSCRIBER, INTERNATIONAL_SUBSCRIBER, INTERNATIONAL_PRIORITY_SUBSCRIBER>

Defines the call category of subscriber. Defaults to NATIONAL_SUBSCRIBER

loglevel=<all,error,warning,debug,notice,cas,mf,stack,nothing>

Defines the log level for debugging purposes. Defaults to all error, warning, debug, notice These options are self-descriptive

cas is for logging ABCD CAS tx and rx

mf is for logging of the Multi Frequency tones

stack is for very verbose output of the channel and context call stack, only useful if you are debugging a crash or want to learn how the library works. The stack logging will be only enabled if the OpenR2 library was compiled with -DOR2_TRACE_STACKS

all is a special value to log all the activity

nothing is a clean-up value, in case you want to not log any activity for a channel or group of channels

You can mix up values, like: loglevel=error,debug,mf to log just error, debug and multi frequency messages

callfile=<yes|no>

Call files useful to debug signaling issues are dumped in the current directory if this parameter is enabled. Defaults to no

variant=<br,mx,ar,itu>

R2 country variant. Defaults to mx

maxani

How much ANI to expect. Defaults to 10

maxdnis

How much DNIS to expect. Defaults to 4

getanifirst=<yes|no>

Whether or not we want to request ANI first. Defaults to no

usedahdimf=<yes|no>

Whether to use the built-in OpenR2 MF tone generation or DAHDI MF tone generation. DAHDI is faster since it does not require to copy user space buffers to the kernel, however this option will only be available when the configure script detects DAHDI support for MF R2 tone generation. Defaults to no

mfthreshold

MF threshold in milliseconds. This is the amount of time a R2 MF signal is required to be ON or OFF after has been detected to be handled. 0 means as soon as we detect a signal we handle it. This aids when a buggy generator or detector causes small false positives. Defaults to 0

mfbacktimeout

MF backward timeout in milliseconds to use OpenR2 default just specify any negative number or comment this line. Defaults to -1

meteringpulsetimeout

Value in milliseconds for the metering pulse timeout, any negative value means default. Defaults to -1

collectcalls=<yes|no>

Whether to accept collect calls (see also doubleanswer). Defaults to no

doubleanswer=<yes|no>

This option are related but independent of collectcalls. If you have problems to block collect calls using Group B signals (collectcalls), enable this option. Defaults to no

immediateaccept=<yes|no>

Whether to skip Group B/II signals and go directly to the accepted state for an incoming call. Defaults to no

advancedprotocolfile

This option is for advanced users only! Define a file that contains hacks to R2 protocol. This allow advanced users to fine tune the library or make test with specific scenarios to include in the library in the future.

playaudio=<yes|no>

This feature allows you to play an alaw audio file for incoming/outgoing calls. Defaults to no

audiofile

If you set playaudio=yes you should provide the path to the audio file

channel

Define range of channels to configure using previous options. The channel range must be specified, unless you will use only one channel. If this option is specified after dnid, cid and caller that options will be used. Defaults to channel=1-15

channel=17-31

dnid

Defines the destination number. Only used if .B caller = yes

cid

Defines the caller id number. Only used if .B caller = yes

caller=<yes|no>

Whether or not the group of channels will start a call to the specified dnid. Defaults to yes

## FILES
/etc/openr2/r2test.conf

/etc/openr2/r2proto.conf

## SEE ALSO
r2test(8)

## AUTHOR
This manual page was written by Alexandre Cavalcante Alencar

<alexandre.alencar@gmail.com>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.


title: pkcs11.conf(5)

summary: Configuration files for PKCS#11 modules

text:
# pkcs11.conf(5)

## NAME
pkcs11.conf - Configuration files for PKCS#11 modules

## DESCRIPTION
The pkcs11.conf configuration files are a standard way to configure PKCS#11 modules.

## FILE FORMAT
A complete configuration consists of several files. These files are text files. Since p11-kit is built to be used in all sorts of environments and at very low levels of the software stack, we cannot make use of high level configuration APIs that you may find on a modern desktop.

Each setting in the config file is specified consists of a name and a value. The name is a simple string consisting of characters and dashes. The name consists of alpha numeric characters, dot, hyphen and underscore.

The value is specified after the name on the same line, separated from it by a : (colon). White space between the name and value is ignored.

Blank lines are ignored. White space at the beginning or end of lines is stripped. Lines that begin with a # character are ignored as comments. Comments are not recognized when they come after a value on a line.

A fictitious module configuration file might look like:

```
module: module.so
# Here is a comment
managed: true
setting.2: A long value with text.
x-custom : text
```

## MODULE CONFIGURATION
Each configured PKCS#11 module has its own config file. These files can be placed in various locations.

The filename of the configuration file may consist of upper and lowercase letters underscore, comma, dash and dots. The first characters needs to be an alphanumeric, the filename should end with a .module extension.

Most importantly each config file specifies the path of the PKCS#11 module to load. A module config file has the following fields:

module:

The filename of the PKCS#11 module to load. This should include an extension like .so If this value is blank, then the module will be ignored. This can be used in the user configs to override loading of a module specified in the system configuration.

If this is a relative path, then the module will be loaded from the default module directory.

critical:

Set to yes if the module is critical and required to load. If a critical module fails to load or initialize, then the loading process for all registered modules will abort and return an error code. This argument is optional and defaults to no.

enable-in:

A comma and/or space separated list of names of programs that this module should only be loaded in. The module will not be loaded for other programs using p11-kit. The base name of the process executable should be used here, for example seahorse, ssh. This option can also be used to control whether the module will be loaded by the proxy module. To enable loading only from the proxy module, specify p11-kit-proxy as the value.

This is not a security feature. The argument is optional. If not present, then any process will load the module.

disable-in:

A comma and/or space separated list of names of programs that this module should not be loaded in. The module will be loaded for any other programs using p11-kit. The base name of the process executable should be used here, for example firefox, thunderbird-bin. This option can also be used to control whether the module will be loaded by the proxy module. To disable loading from the proxy module, specify p11-kit-proxy as the value.

This is not a security feature. The argument is optional. If not present, then any process will load the module.

managed:

Set to no if the module is not to be managed by p11-kit. Making a module unmanaged is not recommended, and will cause problems if multiple callers in a single process share a PKCS#11 module. This argument is optional and defaults to yes.

priority:

The value should be an integer. When lists of modules are returned to a caller of p11-kit, modules with a higher number are sorted first. When applications search modules for certificates, keys and trust policy information, this setting will affect what find first. This argument is optional, and defaults to zero. Modules with the same priority option will be sorted alphabetically.

remote:

Instead of loading the PKCS#11 module locally, run the module remotely. Specify a command to run, prefixed with | a pipe. The command must speak the p11-kit remoting protocol on its standard in and standard out. For example:

```
remote: |ssh user@remote p11-kit remote /path/to/module.so
```

Other forms of remoting will appear in later p11-kit releases.

trust-policy:

Set to yes to use use this module as a source of trust policy information such as certificate anchors and blocklists.

log-calls:

Set to yes to write a log to stderr of all the calls into the module. This is only supported for managed modules. This argument is optional and defaults to no.

server-address:

A socket address which the p11-kit server is listening on. Only applicable to the p11-kit-client module. This option can be overridden with the P11_KIT_SERVER_ADDRESS environment variable.

Do not specify both enable-in and disable-in for the same module.

Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

## GLOBAL CONFIGURATION
A global configuration may also be present. This file contains settings that are not related to a single PKCS#11 module. The location(s) of the global configuration are described below. The global configuration file can contain the following fields:

user-config:

This will be equal to one of the following values: none, merge, only.

managed:

Set to yes or no to force all modules to be managed or unmanaged by p11-kit. Setting this setting in a global configuration file will override the managed setting in the individual module configuration files. Making modules unmanaged is not recommended, and will cause problems if multiple callers in a single process share a PKCS#11 module. This argument is optional.

log-calls:

Set to yes to write a log to stderr of all the calls into all configured modules. This is only supported for managed modules. This argument is optional.

Other fields may be present, but it is recommended that field names that are not specified in this document start with a x- prefix.

## CONFIGURATION FILES
Each configured PKCS#11 module has its own config file. These files are placed in a directory. In addition a global config file exists. There is a system configuration consisting of the various module config files and a file for global configuration. Optionally each user can provide additional configuration or override the system configuration.

The system global configuration file is usually in /etc/pkcs11/pkcs11.conf and the user global configuration file is in ~/.config/pkcs11/pkcs11.conf in the user's home directory.

The module config files are usually located in the /etc/pkcs11/modules directory, with one configuration file per module. In addition the ~/.config/pkcs11/modules directory can be used for modules installed by the user.

Note that user configuration files are not loaded from the home directory if running inside a setuid or setgid program.

The default system config file and module directory can be changed when building p11-kit. Always lookup these paths using pkg-config.

## SEE ALSO
p11-kit(8)

Further details available in the p11-kit online documentation at https://p11-glue.github.io/p11-glue/p11-kit/manual/.


papersize

package: libpaper

title: papersize(5)

summary: specify preferred paper size

text:
# papersize(5)

## NAME
papersize - specify preferred paper size

## SYNOPSYS
/etc/papersize

## DESCRIPTION
The papersize file is used to specify the preferred paper size to use by available commands and programs generating documents.

The format of this file is extremely simple: whitespace and anything starting with `#' is ignored, and the name of the paper is the first string found; the case in the name of the paper does not import (see CAVEATS section however).

## PAPER NAMES
The following names are commonly understood by programs: a3, a4, a5, b5, letter, legal, executive, note and 11x17.

Additional paper names that one may encounter are: a0, a1, a2, a6, a7, a8, a9, a10, b0, b1, b2, b3, b4, tabloid, statement, note, halfletter, halfexecutive, folio, quarto, ledger, archA, archB, archC, archD, archE, flsa, flse, csheet, dsheet, esheet and 10x14.

The value of the papersize file can be overrideen by looking in order at the PAPERSIZE environment variable, then at the contents of the file specified by the PAPERCONF environment variable. If the papersize file does not exist, programs using the paper library default to using letter as a fall-back value

## CAVEATS
This manual page documents the format of the papersize file that is read by the libpaper library. Some programs that read this file do not yet use the library and may have trouble ignoring whitespace and comments in the file; they may also require that the paper names use a specific capitalization.

## DOCUMENTATION
Yves Arrouye <arrouye@debian.org>

## SEE ALSO
paperconf(1)

paperconfig(8)


paperspecs

title: paperspecs(5)

summary: paper size specifications

text:
# paperspecs(5)

## NAME
paperspecs - paper size specifications

## DESCRIPTION
A CSV format list of the paper size specifications used by paper. Each line contains the following fields:

NAME,WIDTH,HEIGHT,UNIT

Valid units are: pt (PostScript points), mm, in.

A size may be defined more than once. Only the first definition is normally used. This means that the user's paperspecs file overrides sizes in the system file (see below).

Multiple definitions are also used to allow inexact definitions to be looked up by size. For example, the LC_PAPER mechanism available on some systems defines paper sizes in whole numbers of millimetres, which results in a definition for Letter size that does not exactly match the definition in inches.

## FILES
/etc/paperspecs

System list of paper sizes.

$XDG_CONFIG_HOME/paperspecs

User's list of paper sizes. This is prepended to the system list.

## BUGS
The CSV format is restricted: quotes are not allowed; hence, fields cannot be escaped.

## CREDITS
The original list of paper names came from Ghostscript 3.68's gs_stadt.ps.

## AUTHOR
Reuben Thomas <rrt@sc3d.org>

## SEE ALSO
paper(1)


passwdqc.conf

package: libpasswdqc

title: passwdqc.conf(5)

summary: libpasswdqc configuration file

text:
# passwdqc.conf(5)

## NAME
passwdqc.conf — libpasswdqc configuration file

## DESCRIPTION
libpasswdqc is a simple password strength checking library. In addition to checking regular passwords, it offers support for passphrases and can provide randomly generated ones. A passwdqc.conf configuration file may be used to override default libpasswdqc settings.

## FORMAT
A passwdqc.conf file consists of 0 or more lines of the following format:

option=value

Empty lines and lines beginning with “#” are ignored. Whitespace characters between the option, “=”, and value are not allowed.

## DIRECTIVE OPTIONS
config=FILE

Load the specified configuration FILE in the passwdqc.conf format. This file may define any options described in this manual, including load of yet another configuration file, but loops are not allowed.

## PASSWORD QUALITY CONTROL OPTIONS
min=N0,N1,N2,N3,N4

(default: min=disabled,24,11,8,7) The minimum allowed password lengths for different kinds of passwords/passphrases. The keyword disabled can be used to disallow passwords of a given kind regardless of their length. Each subsequent number is required to be no larger than the preceding one. N0 is used for passwords consisting of characters from one character class only. The character classes are: digits, lower-case letters, upper-case letters, and other characters. There is also a special class for non-ASCII characters, which could not be classified, but are assumed to be non-digits.

N1 is used for passwords consisting of characters from two character classes that do not meet the requirements for a passphrase.

N2 is used for passphrases. Note that besides meeting this length requirement, a passphrase must also consist of a sufficient number of words (see the passphrase option below).

N3 and N4 are used for passwords consisting of characters from three and four character classes, respectively.

When calculating the number of character classes, upper-case letters used as the first character and digits used as the last character of a password are not counted.

In addition to being sufficiently long, passwords are required to contain enough different characters for the character classes and the minimum length they have been checked against.

max=N

(default: max=72) The maximum allowed password length. This can be used to prevent users from setting passwords that may be too long for some system services. The value 8 is treated specially: if max is set to 8, passwords longer than 8 characters will not be rejected, but will be truncated to 8 characters for the strength checks and the user will be warned. This is to be used with the traditional DES-based password hashes, which truncate the password at 8 characters. It is important that you do set max=8 if you are using the traditional hashes, or some weak passwords will pass the checks.

passphrase=N

(default: passphrase=3) The number of words required for a passphrase, or 0 to disable the support for user-chosen passphrases.

match=N

(default: match=4) The length of common substring required to conclude that a password is at least partially based on information found in a character string, or 0 to disable the substring search. Note that the password will not be rejected once a weak substring is found; it will instead be subjected to the usual strength requirements with the weak substring partially discounted. The substring search is case-insensitive and is able to detect and remove a common substring spelled backwards.

similar=permit|deny

(default: similar=deny) Whether a new password is allowed to be similar to the old one. The passwords are considered to be similar when there is a sufficiently long common substring and the new password with the substring partially discounted would be weak.

wordlist=FILE

Deny passwords that are based on lines of the tiny external text FILE, which can reasonably be e.g. a list of a few thousand common passwords. Common dictionary words may also reasonably be included, especially in a local language other than English, or longer yet common English words. (passwdqc includes a list of a few thousand common English words of lengths from 3 to 6 built in. Any word list possibly specified with this option is used in addition to the built-in word list.) Substring matching and discounting will be used if the match setting above is non-zero. Please note that this is very inefficient, and isn't to be used with large wordlists.

denylist=FILE

Deny passwords or passphrases directly appearing in the tiny external text FILE. That file can reasonably be e.g. a list of common passwords if only a relaxed policy is desired and stricter checks are thus disabled (using their separate options). Such policy would only be somewhat effective against online/remote attacks, but not against offline attacks on hashed passwords.

filter=FILE

Deny passwords or passphrases directly appearing in a maybe huge binary filter FILE created with pwqfilter. This is very efficient, needing at most two random disk reads per query. A filter created from millions of leaked passwords can reasonably be used on top of passwdqc's other checks to further reduce the number of passing yet weak passwords without causing unreasonable inconvenience (as e.g. higher minimum lengths and character set requirements could).

random=N[,only]

(default: random=47) The size of randomly-generated passphrases in bits (24 to 136), or 0 to disable this feature. Any passphrase that contains the offered randomly-generated string will be allowed regardless of other possible restrictions. The only modifier can be used to disallow user-chosen passwords.

## PAM MODULE OPTIONS
enforce=none|users|everyone

(default: enforce=everyone) The PAM module can be configured to warn of weak passwords only, but not actually enforce strong passwords. The users setting is like everyone for all PAM services except chpasswd and passwd. For these two PAM services users will enforce strong passwords for invocations by non-root users only.

non-unix

Normally, the PAM module uses getpwnam(3) to obtain the user's personal login information and use that during the password strength checks. This behavior can be disabled with the non-unix option.

retry=N

(default: retry=3) The number of times the PAM module will ask for a new password if the user fails to provide a sufficiently strong password and enter it twice the first time.

ask_oldauthtok[=update]

Ask for the old password as well. Normally, the PAM module leaves this task for subsequent modules. With no argument, the ask_oldauthtok option will cause the PAM module to ask for the old password during the preliminary check phase. If the ask_oldauthtok option is specified with the update argument, the PAM module will do that during the update phase.

check_oldauthtok

This tells the PAM module to validate the old password before giving a new password prompt. Normally, this task is left for subsequent modules. The primary use for this option is when ask_oldauthtok=update is also specified, in which case no other module gets a chance to ask for and validate the password. Of course, this will only work with UNIX passwords.

use_first_pass, use_authtok

Use the new password obtained by other modules stacked before the PAM module. This disables user interaction within the PAM module. The only difference between use_first_pass and use_authtok is that the former is incompatible with ask_oldauthtok.

noaudit

If audit is enabled at build time, the PAM module logs audit events once user tries to change their credentials. This option disables that audit logging.

## FILES
/etc/passwdqc.conf (not read unless this suggested file location is specified with the config=/etc/passwdqc.conf option).

## SEE ALSO
getpwnam(3), libpasswdqc(3), pam_passwdqc(8).

https://www.openwall.com/passwdqc/

## AUTHORS
The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer ⟨solar at openwall.com⟩. This manual page was derived from pam_passwdqc(8). The latter, derived from the author's documentation, was written for the FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program.


pcap-savefile

package: libpcap-devel

title: pcap-savefile(5)

summary: libpcap savefile format

text:
# pcap-savefile(5)

## NAME
pcap-savefile - libpcap savefile format

## DESCRIPTION
NOTE: applications and libraries should, if possible, use libpcap to read savefiles, rather than having their own code to read savefiles. If, in the future, a new file format is supported by libpcap, applications and libraries using libpcap to read savefiles will be able to read the new format of savefiles, but applications and libraries using their own code to read savefiles will have to be changed to support the new file format.

``Savefiles'' read and written by libpcap and applications using libpcap start with a per-file header. The format of the per-file header is:

Magic number

Major version

Minor version

Reserved1

Reserved2

Snapshot length

Link-layer header type and additional information

The per-file header length is 24 octets.

All fields in the per-file header are in the byte order of the host writing the file. Normally, the first field in the per-file header is a 4-byte magic number, with the value 0xa1b2c3d4. The magic number, when read by a host with the same byte order as the host that wrote the file, will have the value 0xa1b2c3d4, and, when read by a host with the opposite byte order as the host that wrote the file, will have the value 0xd4c3b2a1. That allows software reading the file to determine whether the byte order of the host that wrote the file is the same as the byte order of the host on which the file is being read, and thus whether the values in the per-file and per-packet headers need to be byte-swapped.

If the magic number has the value 0xa1b23c4d (with the two nibbles of the two lower-order bytes of the magic number swapped), which would be read as 0xa1b23c4d by a host with the same byte order as the host that wrote the file and as 0x4d3cb2a1 by a host with the opposite byte order as the host that wrote the file, the file format is the same as for regular files, except that the time stamps for packets are given in seconds and nanoseconds rather than seconds and microseconds.

Following this are:

A 2-byte file format major version number; the current version number is 2.

A 2-byte file format minor version number; the current version number is 4.

A 4-byte not used - SHOULD be filled with 0 by pcap file writers, and MUST be ignored by pcap file readers. This value was documented by some older implementations as "gmt to local correction" or "time zone offset". Some older pcap file writers stored non-zero values in this field.

A 4-byte not used - SHOULD be filled with 0 by pcap file writers, and MUST be ignored by pcap file readers. This value was documented by some older implementations as "accuracy of timestamps". Some older pcap file writers stored non-zero values in this field.

A 4-byte number giving the "snapshot length" of the capture; packets longer than the snapshot length are truncated to the snapshot length, so that, if the snapshot length is N, only the first N bytes of a packet longer than N bytes will be saved in the capture.

A 4-byte number giving the link-layer header type for packets in the capture and optional additional information.

This format of this field is:

```
                     1                   2                   3

 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|FCS len|R|P|     Reserved3     |        Link-layer type        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

The field is shown as if it were in the byte order of the host reading or writing the file, with bit 0 being the most-significant bit of the field and bit 31 being the least-significant bit of the field.

Link-layer type (16 bits): A 16-bit value giving the link-layer header type for packets in the file; see pcap-linktype(7) for the LINKTYPE_ values that can appear in this field.

Reserved3 (10 bits): not used - MUST be set to zero by pcap writers, and MUST NOT be interpreted by pcap readers; a reader SHOULD treat a non-zero value as an error.

P (1 bit): A bit that, if set, indicates that the Frame Check Sequence (FCS) length value is present and, if not set, indicates that the FCS value is not present.

R (1 bit): not used - MUST be set to zero by pcap writers, and MUST NOT be interpreted by pcap readers; a reader SHOULD treat a non-zero value as an error.

FCS len (4 bits): A 4-bit unsigned value giving the number of 16-bit (2-octet) words of FCS that are appended to each packet, if the P bit is set; if the P bit is not set, and the FCS length is not indicated by the link-layer type value, the FCS length is unknown. The valid values of the FCS len field are between 0 and 15; Ethernet, for example, would have an FCS length value of 2, corresponding to a 4-octet FCS.

Following the per-file header are zero or more packets; each packet begins with a per-packet header, which is immediately followed by the raw packet data. The format of the per-packet header is:

Time stamp, seconds value

Time stamp, microseconds or nanoseconds value

Length of captured packet data

Un-truncated length of the packet data

The per-packet header length is 16 octets.

All fields in the per-packet header are in the byte order of the host writing the file. The per-packet header begins with a time stamp giving the approximate time the packet was captured; the time stamp consists of a 4-byte value, giving the time in seconds since January 1, 1970, 00:00:00 UTC, followed by a 4-byte value, giving the time in microseconds or nanoseconds since that second, depending on the magic number in the file header. Following that are a 4-byte value giving the number of bytes of captured data that follow the per-packet header and a 4-byte value giving the number of bytes that would have been present had the packet not been truncated by the snapshot length. The two lengths will be equal if the number of bytes of packet data are less than or equal to the snapshot length.

## SEE ALSO
pcap(3PCAP)


package: libpmem-devel

title: pmem_ctl(5)

summary: interface for examination and modification of the library\(cqs

text:
# pmem_ctl(5)

## NAME
ctl - interface for examination and modification of the library’s internal state.

## DESCRIPTION
The CTL namespace is organized in a tree structure. Starting from the root, each node can be either internal, containing other elements, or a leaf. Internal nodes themselves can only contain other nodes and cannot be entry points. There are two types of those nodes: named and indexed. Named nodes have string identifiers. Indexed nodes represent an abstract array index and have an associated string identifier. The index itself is provided by the user. A collection of indexes present on the path of an entry point is provided to the handler functions as name and index pairs.

Entry points are the leaves of the CTL namespace structure. Each entry point can read from the internal state, write to the internal state, exec a function or a combination of these operations.

The entry points are listed in the following format:

name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type

A description of pmem_ctl functions can be found on the libpmemobj_ctl_get(3) manual page.

## CTL EXTERNAL CONFIGURATION
In addition to direct function call, each write entry point can also be set using two alternative methods.

The first method is to load a configuration directly from the PMEMOBJ_CONF environment variable. A properly formatted ctl config string is a single-line sequence of queries separated by `;':

```
query0;query1;...;queryN

```

A single query is constructed from the name of the ctl write entry point and the argument, separated by `=':

```
entry_point=entry_point_argument

```

The entry point argument type is defined by the entry point itself, but there are three predefined primitives:

```
*) integer: represented by a sequence of [0-9] characters that form

    a single number.
*) boolean: represented by a single character: y/n/Y/N/0/1, each

    corresponds to true or false. If the argument contains any

    trailing characters, they are ignored.
*) string: a simple sequence of characters.

```

There are also complex argument types that are formed from the primitives separated by a `,':

```
first_arg,second_arg

```

In summary, a full configuration sequence looks like this:

```
(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);

```

As an example, to set both prefault at_open and at_create variables:

```
PMEMOBJ_CONF="prefault.at_open=1;prefault.at_create=1"

```

The second method of loading an external configuration is to set the PMEMOBJ_CONF_FILE environment variable to point to a file that contains a sequence of ctl queries. The parsing rules are all the same, but the file can also contain white-spaces and comments.

To create a comment, simply use `#' anywhere in a line and everything afterwards, until a new line, will be ignored.

An example configuration file:

```
#########################
# My pmemobj configuration
#########################
#
# Global settings:
prefault. # modify the behavior of pre-faulting

    at_open = 1; # prefault when the pool is opened
prefault.

    at_create = 0; # but don't prefault when it's created
# Per-pool settings:
# ...

```

## SEE ALSO
libpmemobj_ctl_get(3) and https://pmem.io


poolset

package: libpmempool-devel

title: poolset(5)

text:
# poolset(5)

## NAME
poolset - persistent memory pool configuration file format

## SYNOPSIS

```
mypool.set

```

## DESCRIPTION
Depending on the configuration of the system, the available non-volatile memory space may be divided into multiple memory devices. In such case, the maximum size of the transactional object store could be limited by the capacity of a single memory device. Therefore, libpmemobj(7) allows building object stores spanning multiple memory devices by creation of persistent memory pools consisting of multiple files, where each part of such a pool set may be stored on a different pmem-aware filesystem.

To improve reliability and eliminate single point of failure, libpmemobj(7) also allows all the data written to a persistent memory pool to be copied to local pool replicas, thereby providing backup for the persistent memory pool by producing a mirrored pool set. In practice, the pool replicas may be considered as binary copies of the “master” pool set.

The set file for each type of pool is a plain text file. Lines in the file are formatted as follows:

- The first line of the file must be the literal string “PMEMPOOLSET”

- The pool parts are specified, one per line, in the format:

size pathname

- Replica sections, if any, start with the literal string “REPLICA”. See REPLICAS, below, for further details.

- Pool set options, if any, start with literal string OPTION. See POOL SET OPTIONS below for details.

- Lines starting with “#” are considered comments and are ignored.

The size must be compliant with the format specified in IEC 80000-13, IEEE 1541 or the Metric Interchange Format. These standards accept SI units with obligatory B - kB, MB, GB, ... (multiplier by 1000) suffixes, and IEC units with optional “iB” - KiB, MiB, GiB, ..., K, M, G, ... - (multiplier by 1024) suffixes.

pathname must be an absolute pathname.

The pathname of a part can point to a Device DAX. Device DAX is the device-centric analogue of Filesystem DAX. It allows memory ranges to be allocated and mapped without need of an intervening file system.

Pools created on Device DAX have additional options and restrictions:

- The size may be set to “AUTO”, in which case the size of the device will be automatically resolved at pool creation time.

- To concatenate more than one Device DAX device into a single pool set, the configured internal alignment of the devices must be 4KiB, unless the SINGLEHDR or NOHDRS option is used in the pool set file. See POOL SET OPTIONS below for details.

Please see ndctl-create-namespace(1) for more information on Device DAX, including how to configure desired alignment.

The minimum file size of each part of the pool set is defined as PMEMOBJ_MIN_PART in <libpmemobj.h>

The net pool size of the pool set is equal to:

```
net_pool_size = sum_over_all_parts(page_aligned_part_size - 4KiB) + 4KiB

```

where

```
page_aligned_part_size = part_size & ~(page_size - 1)

```

Note that page size is OS specific. For more information please see sysconf(3).

The minimum net pool size of a pool set is defined as PMEMOBJ_MIN_POOL in <libpmemobj.h>

Here is an example “mypool.set” file:

```
PMEMPOOLSET
OPTION NOHDRS
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2

```

The files in the set may be created by running one of the following commands. To create a obj pool:

```
$ pmempool create obj mypool.set

```

## REPLICAS
Sections defining replica sets are optional. There may be multiple replica sections.

Replica sections begin with a line containing only the literal string “REPLICA”, followed by one or more pool part lines as described above.

Here is an example “myobjpool.set” file with replicas:

```
PMEMPOOLSET
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2
# local replica
REPLICA
500G /mountpoint3/mymirror.part0
200G /mountpoint4/mymirror.part1

```

The files in the object pool set may be created by running the following command:

```
$ pmempool create --layout="mylayout" obj myobjpool.set

```

## POOL SET OPTIONS
Pool set options can appear anywhere after the line with PMEMPOOLSET string. Pool set file can contain several pool set options. The following options are supported:

•

SINGLEHDR

If the SINGLEHDR option is used, only the first part in each replica contains the pool part internal metadata. In that case the effective size of a replica is the sum of sizes of all its part files decreased once by 4096 bytes.

When using the SINGLEHDR option, one can concatenate more than one Device DAX devices with any internal alignments in one replica.

Using the SINGLEHDR option has important implications for data integrity checking and recoverability in case of a pool set damage. See pmempool_sync() API for more information about pool set recovery.

## DIRECTORIES
Providing a directory as a part’s pathname allows the pool to dynamically create files and consequently removes the user-imposed limit on the size of the pool.

The size argument of a part in a directory poolset becomes the size of the address space reservation required for the pool. In other words, the size argument is the maximum theoretical size of the mapping. This value can be freely increased between instances of the application, but decreasing it below the real required space will result in an error when attempting to open the pool.

The directory must NOT contain user created files with extension .pmem, otherwise the behavior is undefined. If a file created by the library within the directory is in any way altered (resized, renamed) the behavior is undefined.

A directory poolset must exclusively use directories to specify paths - combining files and directories will result in an error. A single replica can consist of one or more directories. If there are multiple directories, the address space reservation is equal to the sum of the sizes.

The order in which the files are created is unspecified, but the library will try to maintain equal usage of the directories.

By default pools grow in 128 megabyte increments.

Only poolsets with the SINGLEHDR option can safely use directories.

## NOTES
Creation of all the parts of the pool set and the associated replica sets can be done with the pmemobj_create(3) function, or by using the pmempool(1) utility.

Restoring data from a replica can be done by using the pmempool-sync(1) command or the pmempool_sync() API from the libpmempool(7) library.

Modifications of a pool set file configuration can be done by using the pmempool-transform(1) command or the pmempool_transform() API from the libpmempool(7) library.

When creating a pool set consisting of multiple files, or when creating a replicated pool set, the path argument passed to pmemobj_create(3) must point to the special set file that defines the pool layout and the location of all the parts of the pool set.

When opening a pool set consisting of multiple files, or when opening a replicated pool set, the path argument passed to pmemobj_open(3) must point to the same set file that was used for pool set creation.

## SEE ALSO
ndctl-create-namespace(1), pmemobj_create(3), sysconf(3), libpmemobj(7) and https://pmem.io