Changes To Manual for lc_register_callback

Changes to "Manual for lc_register_callback" between 2014-11-24 20:10:46 and 2014-11-24 20:11:50





































































































































































































































1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
<H2>NAME</H2>
lc_register_callback - Register a function for callback in config processing.
<P>
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B>#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;</B>
<P>
<B>int lc_register_callback(const char *</B><I>var</I><B>, char </B><I>opt</I><B>, lc_var_type_t </B><I>type</I><B>, int (*</B><I>callback</I><B>)(const char *, const char *, const char *, const char *, lc_flags_t, void *), void *</B><I>extra</I><B>);</B>
<P>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
The
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
function registers a function to be called when
<I>var</I>
is encounted in a configuration file, command line, or environment variable.
The parameters are as follows:
<DL COMPACT>
<DT><I>const char *var</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>var</I>
parameter indicates the name of the variable to register for a callback when encountered in a configuration file, the environment, or as a long option.  The
<I>var</I>
may be prefixed with &quot;*.&quot; to indicate that the object can occur in any section or subsection.
</DL>
<P>
<DT><I>const char opt</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>opt</I>
parameter indicates the single charectar short option to use from the command line to invoke the register callback.  A value of 0 indicates that no short option is acceptable.
</DL>
<P>
<DT><I>lc_var_type_t type</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>type</I>
parameter indicates the type of values that are acceptable for this callback.  A value of LC_VAR_NONE means that the command will accept no arguments, while a value of LC_VAR_UNKNOWN indicates that it's not known whether or not an argument is applicable, this will also disable command line processing.  Any other value is currently ignored.
</DL>
<P>
<DT><I>int (*callback)(...)</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>callback</I>
parameter indicates the name of the function to invoke when the above parameters are met.  The specified function should take 6 parameters, see below for more information.  This value may not be NULL.
</DL>
<P>
<DT><I>void *extra</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>extra</I>
parameter is a pointer that can be used to pass data to the callback upon invocation, it will not be mangled or examined by any function.
</DL>
<P>
The arguments to the function specified as
<I>callback</I>
are as follows:
<DT><I>const char *shortvar</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>shortvar</I>
parameter is the local variable name, provided as a convience.  It is the portion of the variable name after the first &quot;dot&quot; (.) in the fully qualified variable name.  The &quot;dot&quot; (.) value in the fully qualified variable name indicates a section or subsection that the variable belongs to.
This may be
<B>NULL</B>
if the
<I>var</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was
<B>NULL</B>
too.
</DL>
<DT><I>const char *var</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>var</I>
parameter is the fully qualified variable name.  It includes in the prefix any sections and subsections that contain this variable.
This may be
<B>NULL</B>
if the
<I>var</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was
<B>NULL</B>
too.
</DL>
<DT><I>const char *arguments</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>arguments</I>
parameter provides the arguments passed to the variable, currently only sections may have arguments.
This may be
<B>NULL</B>
if there were no arguments specified, or if arguments were not applicable.
</DL>
<DT><I>const char *value</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>value</I>
parameter provides the value of the variable specified.
This may be
<B>NULL</B>
if no value was specified.  Values are required if the
<I>type</I>
parameter to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
</DL>
<DT><I>lc_flags_t flags</I>
<DD>
<DL COMPACT><DT><DD>
The flags parameter provides information about the type of command being called.  The valid values are:
<DL COMPACT>
<DT>LC_FLAGS_VAR<DD>
To indicate a regular variable in a configuration file.
<DT>LC_FLAGS_CMDLINE<DD>
To indicate a command line option has been used to invoke this option.
<DT>LC_FLAGS_SECTIONSTART<DD>
To indicate that this command represents the beginning of a section.
<DT>LC_FLAGS_SECTIONEND<DD>
To indicate that this command represents the end of a section.
</DL>
</DL>
<DT><I>void *extra</I>
<DD>
<DL COMPACT><DT><DD>
The
<I>extra</I>
parameter is just a copy of the
<I>extra</I>
parameter passed to
<B><A HREF="wiki/Manual for lc_register_callback">lc_register_callback</A></B>(3)
when the callback was registered.
</DL>
<P>
The
<I>callback</I>
function should return one of three values:
<DT>LC_CBRET_IGNORESECTION<DD>
Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
<DT>LC_CBRET_OKAY<DD>
Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
<DT>LC_CBRET_ERROR<DD>
Returnning LC_CBRET_ERROR from a callback indicates that the command failed for some reason, the error will be passed back down the chain back to the
<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(3)
call that began processing the configuration data.  If LC_CBRET_ERROR is returned from a callback that begins a section, the entire section is ignored.  If LC_CBRET_ERROR is returned from a callback that ends a section, the error is ignored.
<P>
<P>
</DL>
<A NAME="lbAE">&nbsp;</A>
<H2>RETURN VALUE</H2>
On success 0 is returned, otherwise -1 is returned.
<P>
<A NAME="lbAF">&nbsp;</A>
<H2>EXAMPLE</H2>
<PRE>
#include &lt;<A HREF="artifact/7c61a9805e664fde7943807af8d5e164e7cebdb6">libconfig.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/strings.h">strings.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/stdlib.h">stdlib.h</A>&gt;
#include &lt;<A HREF="file:/usr/include/stdio.h">stdio.h</A>&gt;
int callback_ifmodule(const char *shortvar, const char *var,
                      const char *arguments, const char *value,
                      lc_flags_t flags, void *extra) {
        if (flags == LC_FLAGS_SECTIONEND) {
                return(LC_CBRET_OKAY);
        }
        if (arguments == NULL) {
                lc_seterrstr(&quot;You must specify an argument to \
                              IfModule.&quot;);
                return(LC_CBRET_ERROR);
        }
        printf(&quot;IfModule %s\n&quot;, arguments);
        if (strcasecmp(arguments, &quot;MyModule&quot;) == 0) {
                return(LC_CBRET_IGNORESECTION);
        }
        return(LC_CBRET_OKAY);
}
int main(int argc, char **argv) {
        int lc_rc_ret, lc_p_ret;
        lc_rc_ret = lc_register_callback(&quot;*.IfModule&quot;, 0, LC_VAR_SECTION,
                                         callback_ifmodule, NULL);
        if (lc_rc_ret != 0) {
                fprintf(stderr, &quot;Error registering callback.\n&quot;);
                return(EXIT_FAILURE);
        }
        lc_p_ret = lc_process(argc, argv, &quot;example&quot;, LC_CONF_APACHE,
                              NULL);
        lc_cleanup();
        if (lc_p_ret != 0) {
                fprintf(stderr, &quot;Error processing configuration: \
                        %s\n&quot;, lc_geterrstr());
                return(EXIT_FAILURE);
        }
        return(EXIT_SUCCESS);
}
</PRE>
<P>
<A NAME="lbAG">&nbsp;</A>
<H2>ERRORS</H2>
<DL COMPACT>
<DT><B>ENOMEM</B>
<DD>
Memory could not be allocated to create the needed internal structures.
<P>
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="wiki/Manual">libconfig</A></B>(3),
<B><A HREF="wiki/Manual for lc_register_var">lc_register_var</A></B>(3),
<B><A HREF="wiki/Manual for lc_geterrno">lc_geterrno</A></B>(3),
<B><A HREF="wiki/Manual for lc_geterrstr">lc_geterrstr</A></B>(3),
<B><A HREF="wiki/Manual for lc_seterrstr">lc_seterrstr</A></B>(3),
<B><A HREF="wiki/Manual for lc_handle_type">lc_handle_type</A></B>(3),
<B><A HREF="wiki/Manual for lc_process">lc_process</A></B>(3),
<B><A HREF="wiki/Manual for lc_process_file">lc_process_file</A></B>(3),
<B><A HREF="wiki/Manual for lc_cleanup">lc_cleanup</A></B>(3)
<P>