1nn_symbol_info(3)
2=================
3
4NAME
5----
6nn_symbol_info - query the names and properties of nanomsg symbols
7
8
9SYNOPSIS
10--------
11*#include <nanomsg/nn.h>*
12
13*int nn_symbol_info (int 'i', struct nn_symbol_properties '*buf', int 'buflen');*
14
15
16DESCRIPTION
17-----------
18Retrieves the symbol name and value at index 'i'.  Indices start at 0.  An index
19has no significance to its associated symbol; the mappings may change between
20library versions.
21
22The nn_symbol_properties has the following definition:
23
24----
25struct nn_symbol_properties {
26
27    /*  The constant value  */
28    int value;
29
30    /*  The constant name  */
31    const char* name;
32
33    /*  The constant namespace, or zero for namespaces themselves */
34    int ns;
35
36    /*  The option type for socket option constants  */
37    int type;
38
39    /*  The unit for the option value for socket option constants  */
40    int unit;
41};
42----
43
44More structure members may be added in future, but the input pointer will be
45written only up to 'buflen' so the ABI is forward-compatible.
46
47Typically a client will iterate through the symbols until nn_symbol_info
48returns NULL in order to collect all the symbols.
49
50All symbols exposed by 'nn_symbol_info' are available directly in the C API,
51generally as preprocessor macros.  Thus, this function is useful mostly for
52language bindings that can't parse the header file and rely on retrieving the
53symbols at runtime.
54
55Note that the NN_MSG symbol is not exported by the 'nn_symbol_info' function.
56First, it is a pointer rather than an integer; second, the symbol is not
57supposed to be exported from language bindings to the user. Instead, language
58bindings should provide the zero-copy functionality in a language-specific way,
59if at all (zero-copy functionality may not make sense for some
60languages/bindings).
61
62AVAILABLE NAMESPACES
63--------------------
64*NN_NS_NAMESPACE*::
65Equals to zero and denotes the NN_NS_* constants themselves
66*NN_NS_VERSION*::
67Nanomsg version constants
68*NN_NS_DOMAIN*::
69Socket domain (or address family) constants AF_SP, AF_SP_RAW
70*NN_NS_TRANSPORT*::
71Transport name constants (used for socket options mainly)
72*NN_NS_PROTOCOL*::
73Socket protocol constants
74*NN_NS_OPTION_LEVEL*::
75Socket option level constants (NN_SOL_SOCKET)
76*NN_NS_SOCKET_OPTION*::
77Socket options for NN_SOL_SOCKET level
78*NN_NS_TRANSPORT_OPTION*::
79Socket options for transport level (used with transport constants)
80*NN_NS_OPTION_TYPE*::
81The option types (described below)
82*NN_NS_FLAG*::
83The nn_send/nn_recv flags (only NN_DONTWAIT for now)
84*NN_NS_ERROR*::
85The errno values
86*NN_NS_LIMIT*::
87Various nanomsg limits (only NN_SOCKADDR_MAX for now)
88*NN_NS_EVENT*::
89Event flags (bit mask) for use with nn_poll (NN_POLLIN, NN_POLLOUT)
90
91AVAILABLE OPTION TYPES
92----------------------
93*NN_TYPE_NONE*::
94No type, is returned for constants that are not socket options
95*NN_TYPE_INT*::
96The integer type
97*NN_TYPE_STR*::
98String (char *) type
99
100More types may be added in the future to nanomsg. You may enumerate all of them
101using the 'nn_symbol_info' itself by checking 'NN_NS_OPTION_TYPE' namespace.
102
103AVAILABLE OPTION UNITS
104----------------------
105*NN_UNIT_NONE*::
106No unit, is returned for constants that are not socket options, or do not have
107any meaningful unit (strings, integer values)
108*NN_UNIT_BYTES*::
109The option value is expressed in bytes
110*NN_UNIT_MILLISECONDS*::
111The option value is expressed in milliseconds
112*NN_UNIT_PRIORITY*::
113The option value is a priority, an integer from 1 to 16
114*NN_UNIT_BOOLEAN*::
115The option value is boolean, an integer 0 or 1
116
117More types may be added in the future to nanomsg. You may enumerate all of them
118using the 'nn_symbol_info' itself by checking 'NN_NS_OPTION_TYPE' namespace.
119
120
121RETURN VALUE
122------------
123If 'i' is valid, returns the number of bytes stored at the structure. The
124maximum value that can be returned is 'buflen'.
125
126If 'i' is out-of-range, nn_symbol_info returns zero.
127
128
129EXAMPLE
130-------
131
132----
133int i;
134for (i = 0; ; ++i) {
135    struct nn_symbol_properties sym;
136    int rc = nn_symbol_info (i, &sym, sizeof (sym));
137    if(rc == 0)
138        break;
139    assert (rc == sizeof (sym));
140    printf ("'%s' = %d\n", sym.name, sym.value);
141}
142----
143
144SEE ALSO
145--------
146<<nn_symbol#,nn_symbol(3)>>
147<<nn_errno#,nn_errno(3)>>
148<<nn_strerror#,nn_strerror(3)>>
149<<nanomsg#,nanomsg(7)>>
150
151
152AUTHORS
153-------
154link:mailto:paul@colomiets.name[Paul Colomiets]
155link:mailto:garrett@damore.org[Garrett D'Amore]
156