Socket Addresses

typedef union nng_sockaddr {
    uint16_t              s_family;
    nng_sockaddr_ipc      s_ipc;
    nng_sockaddr_inproc   s_inproc;
    nng_sockaddr_in6      s_in6;
    nng_sockaddr_in       s_in;
    nng_sockaddr_abstract s_abstract;
    nng_sockaddr_storage  s_storage;
} nng_sockaddr;

enum nng_sockaddr_family {
    NNG_AF_UNSPEC   = 0,
    NNG_AF_INPROC   = 1,
    NNG_AF_IPC      = 2,
    NNG_AF_INET     = 3,
    NNG_AF_INET6    = 4,
    NNG_AF_ABSTRACT = 5
};

An nng_sockaddr is used to represent the addresses used by underlying transports, such as TCP/IP addresses, IPC paths, and in-process names.

Note

The name sockaddr reflects its similarity to POSIX struct sockaddr. In NNG, these addresses are more closely associated with nng_pipe and transport endpoints than with sockets.

The structure is a union with different members for different address types. Every member structure has a uint16_t address family as its first field. This overlaps the s_family member of the union and indicates which member is valid.

The s_storage member reserves enough space to store any supported socket address family. Applications should use the family-specific members instead when inspecting an address.

In-Process Addresses

typedef struct nng_sockaddr_inproc {
    uint16_t sa_family;
    char     sa_name[NNG_MAXADDRLEN];
} nng_sockaddr_inproc;

An nng_sockaddr_inproc is the flavor of nng_sockaddr used for addresses associated with the inproc transport.

The sa_family field is always NNG_AF_INPROC.

The sa_name field holds an arbitrary NUL-terminated C string identifying the in-process address. No other restrictions are placed on the name.

Tip

Applications should use the sizeof operator instead of hard coding the size of the sa_name member. The size is guaranteed to be at least 128.

IPC Addresses

typedef struct nng_sockaddr_path nng_sockaddr_ipc;

struct nng_sockaddr_path {
    uint16_t sa_family;
    char     sa_path[NNG_MAXADDRLEN];
};

An nng_sockaddr_ipc is the flavor of nng_sockaddr used for traditional path-based addresses associated with the IPC transport.

The sa_family field is always NNG_AF_IPC.

The sa_path field holds a NUL-terminated C string corresponding to the path where the IPC socket is located. On systems using UNIX domain sockets, this is a path in the file system. On Windows systems, this is the named pipe path without the leading \\.\pipe\ portion, which NNG adds automatically.

Tip

Applications should use the sizeof operator instead of hard coding the size of the sa_path member. The size is guaranteed to be at least 128, but paths of this length may not be supported on every system.

Tip

Portable applications should restrict themselves to path names of not more than 90 bytes. Many systems have limits around 100 bytes, and some systems have smaller limits.

Note

If compatibility with legacy nanomsg applications is required, path names must not be longer than 122 bytes, including the final NUL byte. Legacy versions of nanomsg cannot express URLs longer than 128 bytes, including the ipc:// prefix.

Abstract Addresses

typedef struct nng_sockaddr_abstract {
    uint16_t sa_family;
    uint16_t sa_len;
    uint8_t  sa_name[107];
} nng_sockaddr_abstract;

An nng_sockaddr_abstract is the flavor of nng_sockaddr used to represent abstract socket addresses for the IPC transport.

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

The sa_family field is always NNG_AF_ABSTRACT.

The sa_len field gives the number of bytes stored in sa_name.

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

Note

The name does not include the leading NUL byte used on Linux to distinguish abstract socket addresses from path-based socket addresses.

Note

Abstract sockets are Linux-specific. They are not recommended for portable applications.

IPv4 Addresses

typedef struct nng_sockaddr_in {
    uint16_t sa_family;
    uint16_t sa_port;
    uint32_t sa_addr;
} nng_sockaddr_in;

An nng_sockaddr_in is the flavor of nng_sockaddr used for IPv4 addresses, including the IP address and TCP or UDP port number. IPv6 addresses use nng_sockaddr_in6 instead.

The sa_family field is always NNG_AF_INET.

The sa_port field holds the TCP or UDP port number in network byte order. A zero value indicates that no specific port number is specified.

The sa_addr field holds the IPv4 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.

Important

Although this structure appears similar to BSD sockaddr_in, it is not the same type, and the two may not be used interchangeably.

IPv6 Addresses

typedef struct nng_sockaddr_in6 {
    uint16_t sa_family;
    uint16_t sa_port;
    uint32_t sa_scope;
    uint8_t  sa_addr[16];
} nng_sockaddr_in6;

An nng_sockaddr_in6 is the flavor of nng_sockaddr used for IPv6 addresses, including the IP address and TCP or UDP port number. IPv4 addresses use nng_sockaddr_in instead.

The sa_family field is always NNG_AF_INET6.

The sa_port field holds the TCP or UDP port number in network byte order. A zero value indicates that no specific port number is specified.

The sa_scope field is the IPv6 scope identifier. It is typically used with link-local addresses to identify a specific interface. The details of this value are platform-specific.

The sa_addr field holds the IPv6 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.

Important

Although this structure appears similar to BSD sockaddr_in6, it is not the same type, and the two may not be used interchangeably.

Format an Address

#define NNG_MAXADDRSTRLEN (NNG_MAXADDRLEN + 16)

const char *nng_str_sockaddr(const nng_sockaddr *sa, char *buf, size_t bufsz);

The nng_str_sockaddr function provides a displayable representation of the socket address sa in the buffer buf, which has room for bufsz bytes including the terminating NUL byte. The function returns buf.

If the buffer is too small, the result will be truncated. A buffer of NNG_MAXADDRSTRLEN bytes is sufficient to avoid typical truncations, although very long IPC paths can still be truncated.

As long as bufsz is greater than zero, the result will be NUL-terminated.

Important

The string produced by nng_str_sockaddr is intended for display in logs and diagnostics. It is not intended to be parsed, and the display format may change without notice.

Address Port

uint32_t nng_sockaddr_port(const nng_sockaddr *sa);

The nng_sockaddr_port function returns the port number associated with sa in native byte order.

For NNG_AF_INET and NNG_AF_INET6 addresses, this is the TCP or UDP port. For address families that do not have a port number, zero is returned.

Compare Addresses

bool nng_sockaddr_equal(const nng_sockaddr *sa1, const nng_sockaddr *sa2);

The nng_sockaddr_equal function returns true if sa1 and sa2 represent the same address, or false otherwise.

Hash an Address

uint64_t nng_sockaddr_hash(const nng_sockaddr *sa);

The nng_sockaddr_hash function returns a non-zero 64-bit hash value for sa.

This value is intended for building indexes, such as with the ID map. Collisions are possible. The hash value is not portable between systems and may not be portable between versions of NNG.