aboutsummaryrefslogtreecommitdiff
path: root/sftp_server/libconfig/lc_register_callback.3.in
diff options
context:
space:
mode:
Diffstat (limited to 'sftp_server/libconfig/lc_register_callback.3.in')
-rw-r--r--sftp_server/libconfig/lc_register_callback.3.in233
1 files changed, 233 insertions, 0 deletions
diff --git a/sftp_server/libconfig/lc_register_callback.3.in b/sftp_server/libconfig/lc_register_callback.3.in
new file mode 100644
index 00000000..92a450a9
--- /dev/null
+++ b/sftp_server/libconfig/lc_register_callback.3.in
@@ -0,0 +1,233 @@
+.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
+The
+.IR var
+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
+.IR var
+may be prefixed with "*." to indicate that the object can occur in any section or subsection.
+.RE
+
+.TP
+.IR "const char opt"
+.RS
+The
+.IR opt
+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.
+.RE
+
+.TP
+.IR "lc_var_type_t type"
+.RS
+The
+.IR type
+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.
+.RE
+
+.TP
+.IR "int (*callback)(...)"
+.RS
+The
+.IR callback
+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.
+.RE
+
+.TP
+.IR "void *extra"
+.RS
+The
+.IR extra
+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.
+.RE
+
+The arguments to the function specified as
+.IR callback
+are as follows:
+.TP
+.I "const char *shortvar"
+.RS
+The
+.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
+The
+.I arguments
+parameter provides the arguments passed to the variable, currently only sections may have arguments.
+This may be
+.B NULL
+if there were no arguments specified, or if arguments were not applicable.
+.RE
+.TP
+.I "const char *value"
+.RS
+The
+.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
+To indicate a regular variable in a configuration file.
+.IP LC_FLAGS_CMDLINE
+To indicate a command line option has been used to invoke this option.
+.IP LC_FLAGS_SECTIONSTART
+To indicate that this command represents the beginning of a section.
+.IP LC_FLAGS_SECTIONEND
+To indicate that this command represents the end of a section.
+.RE
+.TP
+.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.
+
+
+.SH "RETURN VALUE"
+On success 0 is returned, otherwise -1 is returned.
+
+.SH EXAMPLE
+.nf
+#include <libconfig.h>
+#include <strings.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+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 (flags != LC_FLAGS_SECTIONSTART) {
+ fprintf(stderr, "IfModule can only be used as a \\
+ section.\\n");
+ return(LC_CBRET_ERROR);
+ }
+ if (arguments == NULL) {
+ fprintf(stderr, "You must specify an argument to \\
+ IfModule.\\n");
+ return(LC_CBRET_ERROR);
+ }
+
+ printf("IfModule %s\\n", arguments);
+
+ if (strcasecmp(arguments, "MyModule") == 0) {
+ return(LC_CBRET_IGNORESECTION);
+ }
+
+ return(LC_CBRET_OKAY);
+}
+
+int main(int argc, char **argv) {
+ int lc_rc_ret = 0, lc_p_ret;
+
+ lc_rc_ret = lc_register_callback("*.IfModule", 0, LC_VAR_NONE,
+ callback_ifmodule, NULL);
+
+ if (lc_rc_ret != 0) {
+ fprintf(stderr, "Error registering callback.\\n");
+ return(EXIT_FAILURE);
+ }
+
+ lc_p_ret = lc_process(argc, argv, "example", LC_CONF_APACHE,
+ NULL);
+
+ lc_cleanup();
+
+ if (lc_p_ret != 0) {
+ fprintf(stderr, "Error processing configuration: \\
+ %s\\n", lc_geterrstr());
+ return(EXIT_FAILURE);
+ }
+
+ return(EXIT_SUCCESS);
+}
+.fi
+
+.SH ERRORS
+.TP
+.B ENOMEM
+Memory could not be allocated to create the needed internal structures.
+
+.SH "SEE ALSO"
+.BR lc_register_var (3),
+.BR lc_geterrno (3),
+.BR lc_geterrstr (3),
+.BR lc_cleanup (3),
+.BR lc_process_file (3),
+.BR lc_process (3)