nn_symbol_info(3)

1NN_SYMBOL_INFO(3)                nanomsg 1.1.5               NN_SYMBOL_INFO(3)
2
3
4

NAME

6       nn_symbol_info - query the names and properties of nanomsg symbols
7

SYNOPSIS

9       #include <nanomsg/nn.h>
10
11       int nn_symbol_info (int i, struct nn_symbol_properties *buf, int
12       buflen);
13

DESCRIPTION

15       Retrieves the symbol name and value at index i. Indices start at 0. An
16       index has no significance to its associated symbol; the mappings may
17       change between library versions.
18
19       The nn_symbol_properties has the following definition:
20
21           struct nn_symbol_properties {
22
23               /*  The constant value  */
24               int value;
25
26               /*  The constant name  */
27               const char* name;
28
29               /*  The constant namespace, or zero for namespaces themselves */
30               int ns;
31
32               /*  The option type for socket option constants  */
33               int type;
34
35               /*  The unit for the option value for socket option constants  */
36               int unit;
37           };
38
39       More structure members may be added in future, but the input pointer
40       will be written only up to buflen so the ABI is forward-compatible.
41
42       Typically a client will iterate through the symbols until
43       nn_symbol_info returns NULL in order to collect all the symbols.
44
45       All symbols exposed by nn_symbol_info are available directly in the C
46       API, generally as preprocessor macros. Thus, this function is useful
47       mostly for language bindings that can’t parse the header file and rely
48       on retrieving the symbols at runtime.
49
50       Note that the NN_MSG symbol is not exported by the nn_symbol_info
51       function. First, it is a pointer rather than an integer; second, the
52       symbol is not supposed to be exported from language bindings to the
53       user. Instead, language bindings should provide the zero-copy
54       functionality in a language-specific way, if at all (zero-copy
55       functionality may not make sense for some languages/bindings).
56

AVAILABLE NAMESPACES

58       NN_NS_NAMESPACE
59           Equals to zero and denotes the NN_NS_* constants themselves
60
61       NN_NS_VERSION
62           Nanomsg version constants
63
64       NN_NS_DOMAIN
65           Socket domain (or address family) constants AF_SP, AF_SP_RAW
66
67       NN_NS_TRANSPORT
68           Transport name constants (used for socket options mainly)
69
70       NN_NS_PROTOCOL
71           Socket protocol constants
72
73       NN_NS_OPTION_LEVEL
74           Socket option level constants (NN_SOL_SOCKET)
75
76       NN_NS_SOCKET_OPTION
77           Socket options for NN_SOL_SOCKET level
78
79       NN_NS_TRANSPORT_OPTION
80           Socket options for transport level (used with transport constants)
81
82       NN_NS_OPTION_TYPE
83           The option types (described below)
84
85       NN_NS_FLAG
86           The nn_send/nn_recv flags (only NN_DONTWAIT for now)
87
88       NN_NS_ERROR
89           The errno values
90
91       NN_NS_LIMIT
92           Various nanomsg limits (only NN_SOCKADDR_MAX for now)
93
94       NN_NS_EVENT
95           Event flags (bit mask) for use with nn_poll (NN_POLLIN, NN_POLLOUT)
96

AVAILABLE OPTION TYPES

98       NN_TYPE_NONE
99           No type, is returned for constants that are not socket options
100
101       NN_TYPE_INT
102           The integer type
103
104       NN_TYPE_STR
105           String (char *) type
106
107       More types may be added in the future to nanomsg. You may enumerate all
108       of them using the nn_symbol_info itself by checking NN_NS_OPTION_TYPE
109       namespace.
110

AVAILABLE OPTION UNITS

112       NN_UNIT_NONE
113           No unit, is returned for constants that are not socket options, or
114           do not have any meaningful unit (strings, integer values)
115
116       NN_UNIT_BYTES
117           The option value is expressed in bytes
118
119       NN_UNIT_MILLISECONDS
120           The option value is expressed in milliseconds
121
122       NN_UNIT_PRIORITY
123           The option value is a priority, an integer from 1 to 16
124
125       NN_UNIT_BOOLEAN
126           The option value is boolean, an integer 0 or 1
127
128       More types may be added in the future to nanomsg. You may enumerate all
129       of them using the nn_symbol_info itself by checking NN_NS_OPTION_TYPE
130       namespace.
131

RETURN VALUE

133       If i is valid, returns the number of bytes stored at the structure. The
134       maximum value that can be returned is buflen.
135
136       If i is out-of-range, nn_symbol_info returns zero.
137

EXAMPLE

139           int i;
140           for (i = 0; ; ++i) {
141               struct nn_symbol_properties sym;
142               int rc = nn_symbol_info (i, &sym, sizeof (sym));
143               if(rc == 0)
144                   break;
145               assert (rc == sizeof (sym));
146               printf ("'%s' = %d\n", sym.name, sym.value);
147           }
148

AUTHORS

153       Paul Colomiets <paul@colomiets.name> Garrett D’Amore
154       <garrett@damore.org>
155
156
157
158                                  2023-01-19                 NN_SYMBOL_INFO(3)