File lc_process.3.in artifact 86242e9b99 part of check-in aa484e24b4

.TH LC_PROCESS 3 "25 Oct 04" "@PACKAGE_STRING@"
.SH NAME
lc_process \- Begin processing configuration files.

.SH SYNOPSIS
.B #include <libconfig.h>
.sp
.BI "int lc_process(int " argc ", char **" argv ", const char *" appname ", lc_conf_type_t " type ", const char *" extra ");"

.SH DESCRIPTION
The
.BR lc_process (3)
function begins processing of the command line arguments, environment variables, and command line options.
The
.I argc
and
.I argv
parameters should be in the same format as passed to the
.B main
function of your program.
The
.I appname
parameter should be a reasonable form of the name of the application.
The
.I type
parameter should describe the format of the configuration file (see below).
The
.I extra
parameter should list any extra configuration files to process.

Valid type parameter values:
.TP
LC_CONF_SECTION
This type of configuration file is similar to the Windows INI-file style.
An example configuration file:
.nf
	[section]
	variable = value
.fi

.TP
LC_CONF_APACHE
This type of configuration file is similar to the Apache configuration file.
An example configuration file:
.nf
	<Section argument>
		variable value
	</Section>
.fi

.TP
LC_CONF_SPACE
This is a simple, flat configuration file.  It has no section headers.
An example configuration file:
.nf
	variable value
.fi

.SH "RETURN VALUE"
On success 0 is returned, otherwise -1 is returned.

.SH EXAMPLE
.nf
#include <libconfig.h>
#include <stdlib.h>
#include <stdio.h>

int main(int argc, char **argv) {
	int lc_p_ret, lc_rv_ret;
	char *filename = NULL;

	lc_rv_ret = lc_register_var("File", LC_VAR_STRING,
	                            &filename, 'f');
	if (lc_rv_ret != 0) {
		fprintf(stderr, "Error registering variable: %i.\\n",
		        lc_geterrno());
		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);
	}

	if (filename != NULL) {
		printf("File specified was: %s\\n", filename);
	} else {
		printf("No filename specified.\\n");
	}

	return(EXIT_SUCCESS);
}
.fi

.SH "SEE ALSO"
.BR libconfig (3),
.BR lc_register_var (3),
.BR lc_register_callback (3),                          
.BR lc_geterrno (3),                                                                                                           
.BR lc_geterrstr (3),                                                                                                          
.BR lc_seterrstr (3),                                                                                                          
.BR lc_handle_type (3),
.BR lc_process_file (3),                                                                                                       
.BR lc_cleanup (3)