1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
.TH LC_REGISTER_CALLBACK 3 "25 Oct 04" "@PACKAGE_STRING@"
.SH NAME
lc_register_callback \- Register a function for callback in config processing.
.SH SYNOPSIS
.B #include <libconfig.h>
.sp
.BI "int lc_register_callback(const char *" var ", char " opt ", lc_var_type_t " type ", int (*callback)(const char *, const char *, const char *, const char *, lc_flags_t, void *), void *" extra);
.SH DESCRIPTION
The
.B lc_register_callback
function registers a function to be called when
.IR var
is encounted in a configuration file, command line, or environment variable.
The parameters are as follows:
.TP
.IR "const char *var"
.RS
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
.TH LC_REGISTER_CALLBACK 3 "25 Oct 04" "@PACKAGE_STRING@"
.SH NAME
lc_register_callback \- Register a function for callback in config processing.
.SH SYNOPSIS
.B #include <libconfig.h>
.sp
.BI "int lc_register_callback(const char *" var ", char " opt ", lc_var_type_t " type ", int (*callback)(const char *, const char *, const char *, const char *, lc_flags_t, void *), void *" extra);
.SH DESCRIPTION
The
.BR lc_register_callback (3)
function registers a function to be called when
.IR var
is encounted in a configuration file, command line, or environment variable.
The parameters are as follows:
.TP
.IR "const char *var"
.RS
|
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
|
.I shortvar
parameter is the local variable name, provided as a convience. It is the portion of the variable name after the first "dot" (.) in the fully qualified variable name. The "dot" (.) value in the fully qualified variable name indicates a section or subsection that the variable belongs to.
This may be
.B NULL
if the
.IR var
parameter to
.BI lc_register_callback (3)
was
.B NULL
too.
.RE
.TP
.I "const char *var"
.RS
The
.I var
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
if the
.IR var
parameter to
.BI lc_register_callback (3)
was
.B NULL
too.
.RE
.TP
.I "const char *arguments"
.RS
|
|
|
|
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
|
.I shortvar
parameter is the local variable name, provided as a convience. It is the portion of the variable name after the first "dot" (.) in the fully qualified variable name. The "dot" (.) value in the fully qualified variable name indicates a section or subsection that the variable belongs to.
This may be
.B NULL
if the
.IR var
parameter to
.BR lc_register_callback (3)
was
.B NULL
too.
.RE
.TP
.I "const char *var"
.RS
The
.I var
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
if the
.IR var
parameter to
.BR lc_register_callback (3)
was
.B NULL
too.
.RE
.TP
.I "const char *arguments"
.RS
|
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
.I value
parameter provides the value of the variable specified.
This may be
.B NULL
if no value was specified. Values are required if the
.IR type
parameter to
.BI lc_register_callback (3)
was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
.RE
.TP
.I "lc_flags_t flags"
.RS
The flags parameter provides information about the type of command being called. The valid values are:
.IP LC_FLAGS_VAR
|
|
|
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
.I value
parameter provides the value of the variable specified.
This may be
.B NULL
if no value was specified. Values are required if the
.IR type
parameter to
.BR lc_register_callback (3)
was not specified as one of LC_VAR_NONE, LC_VAR_SECTION, LC_VAR_SECTIONSTART, or LC_VAR_SECTIONEND.
.RE
.TP
.I "lc_flags_t flags"
.RS
The flags parameter provides information about the type of command being called. The valid values are:
.IP LC_FLAGS_VAR
|
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
|
.I "void *extra"
.RS
The
.I extra
parameter is just a copy of the
.IR extra
parameter passed to
.BI lc_register_callback (3)
when the callback was registered.
.RE
The
.IR callback
function should return one of three values:
.TP
LC_CBRET_IGNORESECTION
Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
.TP
LC_CBRET_OKAY
Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
.TP
LC_CBRET_ERROR
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
.BI lc_process (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.
"RETURN VALUE"
On success 0 is returned, otherwise -1 is returned.
.SH EXAMPLE
|
|
|
|
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
|
.I "void *extra"
.RS
The
.I extra
parameter is just a copy of the
.IR extra
parameter passed to
.BR lc_register_callback (3)
when the callback was registered.
.RE
The
.IR callback
function should return one of three values:
.TP
LC_CBRET_IGNORESECTION
Returning LC_CBRET_IGNORESECTION from a callback that begins a section causes the entire section to be ignored without generating an error.
.TP
LC_CBRET_OKAY
Returning LC_CBRET_OKAY from a callback indicates that all went well and further processing may continue.
.TP
LC_CBRET_ERROR
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
.BR lc_process (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.
"RETURN VALUE"
On success 0 is returned, otherwise -1 is returned.
.SH EXAMPLE
|