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