NAME
parse_param - parameter parsing from parameter file objects
SYNOPSIS
#include "brttutil.h"
int
parse_param (Pf *pf, char *name, int type, int need, void *val)
DESCRIPTION
This is an interface to a parameter file object (see
pf(3))
that allows specific parameters to be parsed. It is similar
in function to the
pfget(3) routines. However, unlike some
of the
pfget(3) routines,
parse_param will always return
regardless of whether or not a name is found or is of the
expected type. Also, the application programmer has control
of how errors are determined through the
need argument.
The parameter file object to be parsed is specified in pf.
The name of the parameter is specified in name.
The expected type of the parameter is specified in type
which must be one of the following values:
-
P_SINT
The pf parameter is an integer number and is returned in a short int.
-
P_LINT
The pf parameter is an integer number and is returned in a int.
-
P_FLT
The pf parameter is a floating double number and is returned in a float.
-
P_DBL
The pf parameter is a floating double number and is returned in a double.
-
P_STR
The pf parameter is a string and is returned in a char *. Note that with this type parse_param
always makes a copy of the string and sets the copied string pointer in the return (i.e.
val should be a char ** in the calling program).
It is therefore safe to use in any way but the application program has the responsibility
for managing the memory associated with the string.
-
P_STRCP
The pf parameter is a string and is copied into an already allocated char array. Note that
with this type it is the responsibility of the user to insure that the previousaly allocated
string array is of sufficient size.
val should be a char * in the calling program.
-
P_BOOL
The pf parameter is a boolean and is returned in a int. The actual parameter file
object value is read as a string and parsed as a boolean according to the following
rules: if the pf string is 0 or n or no or f or false
(case insensitive) then the returned integet is 0, otherwise the returned integer is 1.
-
P_TBL
The pf parameter is a Tbl and is returned in a Tbl * using pfget_tbl(3).
The Tbl returned in this type will only contain strings and cannot be used
in nested parameter file constructs unless it is at an end-point (leaf) of the nesting.
Note that pfget_tbl(3) returns a newly allocated Tbl pointer and it is the responsibility of
the application program to manage this memory. When the Tbl is not longer needed, it should
be freed with a call to freetbl(3).
-
P_TBLPF
The pf parameter is a Tbl and is returned in a Pf * using pfget(3).
This is what should be used to parse a Tbl that contains other nested parameter
file objects, like other Tbls and Arrs. Note that this is internally allocated
within the original Pf object and should not be managed by the application program.
The returned Pf * from a Tbl can usually only be parsed properly by
using pfget(3) directly. The reason is that in this type of Pf object there
are no names. pfget(3) is set up to parse these peculiar Pf objects by
specifying a coerced integer table entry value in place of the normal Pf name.
-
P_ARR
The pf parameter is a Arr and is returned in a Arr * using pfget_arr(3).
The Arr returned in this type will only contain key-value strings and cannot be used
in nested parameter file constructs unless it is at an end-point (leaf) of the nesting.
Note that pfget_arr(3) returns a newly allocated Arr pointer and it is the responsibility of
the application program to manage this memory. When the Arr is not longer needed, it should
be freed with a call to freearr(3).
-
P_ARRPF
The pf parameter is a Arr and is returned in a Pf * using pfget(3).
This is what should be used to parse a Arr that contains other nested parameter
file objects, like other Tbls and Arrs. Note that this is internally allocated
within the original Pf object and should not be managed by the application program.
The returned Pf * can be parsed like any other parameter file object.
If the need flag is set, then parse_param will return an error if the parameter
is not found or is not of the expected type. If the need flag is not set, then parse_param
will silently return without an error if the parameter is not found, leaving val untouched. This can be used for
overriding parameters that were set somewhere else, like in a "default" section of the original
parameter file. The parameter value is returned in *val according to the type definitions above.
RETURN VALUES
parse_param returns 0 if OK
or -1 if there is an error.
If there is an error, then messages are left
on the error register.
LIBRARY
-lbrttutil
SEE ALSO
pf(3),
pfget(3)
AUTHOR
Danny Harvey