libgslutil  1.2.3
Data Structures | Functions
Sectioned configuration file manipulation

Data Structures

struct  gslutil_cffile2_subsection
 Structure for subsection of a configuration file. More...
 
struct  gslutil_cffile2_t
 Structure for configuration file with subsections. More...
 

Functions

struct gslutil_cffile2_tgslutil_cffile2_load (const char *fname))
 Load configuration file with sections. More...
 
int gslutil_cffile2_save (const char *fname, const struct gslutil_cffile2_t *cf2))
 Save configuration file with sections. More...
 
struct gslutil_cffile2_tgslutil_cffile2_alloc (void))
 Allocate new, empty configuration file structure with sections. More...
 
void gslutil_cffile2_free (struct gslutil_cffile2_t *cf)
 Free a configuration file structure with sections. More...
 
int gslutil_cffile2_add_subsection (struct gslutil_cffile2_t *cf, const char *name))
 Add subsection to configuration file structure. More...
 
struct gslutil_cffile_tgslutil_cffile2_get_subsection (struct gslutil_cffile2_t *cf, const char *name))
 Get pointer to subsection by name. More...
 
struct gslutil_cffile_tuplegslutil_cffile2_get_tuple (struct gslutil_cffile2_t *cf, const char *section_name, const char *entry_name)))
 Get tuple from subsection. More...
 
char * gslutil_cffile2_get_value (const struct gslutil_cffile2_t *cf, const char *section_name, const char *entry_name)))
 Get value from subsection. More...
 

Detailed Description

A set of routines for dealing with flat configuration files consisting of a number of string tuples divided into sections. gslutil_cffile2_load() loads a set of these tuples into memory, categorised by section. gslutil_cffile2_save() writes these sets of tuples to disk. Any errors encountered will be described by the string gslutil_cffile_error.

See Configuration file manipulation for the tuple format. Subsections are indicated in the file by a string marked with square brackets. The string is the subsection title, and must be unique within the configuration file. For example:

name = value         # stored as global
[subsection1]
name = value
[subsection2]
name = value

When parsed with gslutil_cffile2_load, this will result in a struct gslutil_cffile2_t with a single global tuple and two named subsections each with a single tuple.

Function Documentation

◆ gslutil_cffile2_load()

struct gslutil_cffile2_t* gslutil_cffile2_load ( const char *  fname)

Load configuration file with sections.

Parameters
fnameFilename.
Returns
Pointer to newly-allocated configuration file structure.
Return values
0on error (and see gslutil_cffile_error).

Loads tuples from a configuration file named fname. If the loading succeeds, a new gslutil_cffile_t is allocated and returned as the result. Pass this to gslutil_cffile2_free() when finished to free any memory associated with it.

On error, no structure is allocated, 0 is returned, and a verbose human-readable error message is written into gslutil_cffile_error.

◆ gslutil_cffile2_save()

int gslutil_cffile2_save ( const char *  fname,
const struct gslutil_cffile2_t cf2 
)

Save configuration file with sections.

Parameters
fnameFilename.
cf2Configuration structure.
Return values
0on success.
-1on error (and see gslutil_cffile_error).

Saves the configuration file cf2 to fname. On error, leaves ‘fname’ unchanged and returns -1, setting gslutil_cffile_error.

Warning
This saving routine is less satisfactory than gslutil_cffile_save, as it does not make any effort to retain the original comments or structure.

◆ gslutil_cffile2_alloc()

struct gslutil_cffile2_t* gslutil_cffile2_alloc ( void  )

Allocate new, empty configuration file structure with sections.

Returns
Pointer to new structure.

Allocates a new, empty configuration file structure. Uses safe_malloc(), so always succeeds.

◆ gslutil_cffile2_free()

void gslutil_cffile2_free ( struct gslutil_cffile2_t cf)

Free a configuration file structure with sections.

Parameters
cfConfiguration file structure.

Frees the configuration file structure cf and all of its constituent tuples and subsections. Accepts null values for cf.

◆ gslutil_cffile2_add_subsection()

int gslutil_cffile2_add_subsection ( struct gslutil_cffile2_t cf,
const char *  name 
)

Add subsection to configuration file structure.

Parameters
cfConfiguration file structure.
nameName of subsection.
Return values
0on success.
-1on error (duplicate subsection name).

Adds an empty subsection to the configuration file structure cf. The new subsection will have a name copied from the string name. If a subsection with a matching name already exists, cf is not altered and -1 is returned.

◆ gslutil_cffile2_get_subsection()

struct gslutil_cffile_t* gslutil_cffile2_get_subsection ( struct gslutil_cffile2_t cf,
const char *  name 
)

Get pointer to subsection by name.

Parameters
cfConfiguration file structure.
nameName of subsection.
Returns
Pointer to subsection.
Return values
0if not found.

Gets a pointer to the subsection of cf named name. If not found, returns 0. This is a linear lookup.

◆ gslutil_cffile2_get_tuple()

struct gslutil_cffile_tuple* gslutil_cffile2_get_tuple ( struct gslutil_cffile2_t cf,
const char *  section_name,
const char *  entry_name 
)

Get tuple from subsection.

Parameters
cfConfiguration file structure.
section_nameName of subsection.
entry_nameName of configuration entry.
Returns
Pointer to tuple.
Return values
0if not found.

Gets a pointer to the tuple named entry_name in the subsection of cf named section_name. If not found, returns 0.

◆ gslutil_cffile2_get_value()

char* gslutil_cffile2_get_value ( const struct gslutil_cffile2_t cf,
const char *  section_name,
const char *  entry_name 
)

Get value from subsection.

Parameters
cfConfiguration file structure.
section_nameName of subsection.
entry_nameName of configuration entry.
Returns
Pointer to value.
Return values
0if not found.

Gets a pointer to the value of the tuple named entry_name in the subsection of cf named section_name. If not found, returns 0.

If section_name is 0 then the global section is searched.