Check-in [660883b103]
Overview
Comment:Additional man pages created, and cleaned up
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 660883b103b7e76ece436fc09155407aecbf8ab6
User & Date: rkeene on 2004-10-28 23:18:03
Other Links: manifest | tags
Context
2004-10-28
23:55
Updated the way configure looks for how to build shared objects. libconfig version 0.0.4 check-in: affd29c5ef user: rkeene tags: trunk
23:18
Additional man pages created, and cleaned up check-in: 660883b103 user: rkeene tags: trunk
22:39
Added an environment parser. Cleaned up some memory leaks. Made lc_process() cleanup, so calling lc_process() twice will do nothing. check-in: d7ae2bcb59 user: rkeene tags: trunk
Changes

Modified lc_geterrno.3.in from [da39a3ee5e] to [85df2eb346].





















































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
.TH LC_GETERRNO 3 "25 Oct 04" "@PACKAGE_STRING@"
.SH NAME
lc_geterrno \- Retrieve a numeric error code.

.SH SYNOPSIS
.B #include <libconfig.h>
.sp
.BI "lc_err_t lc_geterrno(void);"

.SH DESCRIPTION
The
.BR lc_geterrno (3)
function returns the last numeric error code set as an
.IR "lc_err_t"
which is an enumerated type and can be cast to any integer type.

The
.IR lc_err_t
type specifies the following defined values:
.TP
LC_ERR_NONE
No error was found.  Success.
.TP
LC_ERR_INVCMD
A command was specified for which there was no handler.
.TP
LC_ERR_INVSECTION
A section was specified for which there was no handler.
.TP
LC_ERR_INVDATA
A value that does not make sense was specified, such as a non-existant type to the
.BR lc_process_file (3)
function.
.TP
LC_ERR_BADFORMAT
An invalid format was detected, such as no argument where on was expected, or a value passed to a boolean-specified variable whose value was not one of: enable, true, yes, on, y, 1, disable, false, off, no, n, 0.
.TP
LC_ERR_CANTOPEN
Unable to open a specified file.
.TP
LC_ERR_CALLBACK
A callback function returned an error (LC_CBRET_ERROR).
.TP
LC_ERR_ENOMEM
Memory could not be allocated for internal structures.

.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);
	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 lc_register_var (3),
.BR lc_register_callback (3),
.BR lc_geterrstr (3),
.BR lc_process (3),
.BR lc_register_var (3)

Modified lc_geterrstr.3.in from [da39a3ee5e] to [e9149b39ec].



















































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
.TH LC_GETERRSTR 3 "25 Oct 04" "@PACKAGE_STRING@"
.SH NAME
lc_geterrstr \- Retrieve a human readable error message.

.SH SYNOPSIS
.B #include <libconfig.h>
.sp
.BI "char *lc_geterrstr(void);"

.SH DESCRIPTION
The
.BR lc_geterrstr (3)
function returns a string describing the last error code set.

.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: %s.\\n",
		        lc_geterrstr());
		return(EXIT_FAILURE);
	}

	lc_p_ret = lc_process(argc, argv, "example", LC_CONF_APACHE,
	                      NULL);
	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 lc_register_var (3),
.BR lc_register_callback (3),
.BR lc_geterrno (3),
.BR lc_process (3),
.BR lc_register_var (3)

Modified lc_register_callback.3.in from [57f2b8a256] to [d1718088de].

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