libgslutil  1.2.3
Data Structures | Functions | Variables
Configuration file manipulation

Data Structures

struct  gslutil_cffile_tuple
 Configuration file tuple. More...
 
struct  gslutil_cffile_t
 Simple configuration file structure. More...
 

Functions

struct gslutil_cffile_tgslutil_cffile_load (const char *fname))
 Load configuration file. More...
 
int gslutil_cffile_save (const char *fname, const struct gslutil_cffile_t *cf))
 Save configuration file. More...
 
void gslutil_cffile_change_tuple (struct gslutil_cffile_tuple *tuple, const char *new_value))
 Change value of configuration file tuple. More...
 
struct gslutil_cffile_tgslutil_cffile_alloc (void))
 Allocate a new, empty configuration file structure. More...
 
void gslutil_cffile_free (struct gslutil_cffile_t *cf)
 Free a configuration file structure. More...
 
int gslutil_cffile_add_tuple (struct gslutil_cffile_t *cf, const char *name, const char *value))
 Add a new tuple to a configuration file structure. More...
 
int gslutil_cffile_remove_tuple_by_name (struct gslutil_cffile_t *cf, const char *name))
 Remove a tuple from a configuration file structure. More...
 
void gslutil_cffile_remove_tuple_by_pos (struct gslutil_cffile_t *cf, int pos))
 Remove a tuple from a configuration file structure. More...
 
struct gslutil_cffile_tuplegslutil_cffile_find_tuple (struct gslutil_cffile_t *cf, const char *name))
 Find a tuple by name. More...
 
char * gslutil_cffile_find_value (const struct gslutil_cffile_t *cf, const char *name))
 Get value from file. More...
 

Variables

const char *const gslutil_cffile_error
 Configuration file error reporting. More...
 

Detailed Description

A set of routines for dealing with simple, flat configuration files consisting of a number of string tuples. gslutil_cffile_load() loads a set of these tuples into memory. gslutil_cffile_save() writes a set of tuples to disk, attempting to keep the structure of the previous file intact. Any errors encountered will be described by the string gslutil_cffile_error.

The configuration file consists of a set of tuples, in the format:

# comment
name = value # comment

name is a single string token, without whitespace. value may not be blank, but may contain whitespace. Any whitespace before or after name is stripped. The ‘=’ symbol may or may not be surrounded by whitespace. Any whitespace before or after (but not within) value is stripped.

Any characters after a ‘#’ character (including the character itself) are considered to be comments and are ignored. Blank lines, or lines consisting only of whitespace, are skipped. Tuples may not be repeated (i.e. the name must be unique). Tuples are sorted lexically by name within the config structure.

When saving, any tuples in the new data with names matching tuples in the original file are simply updated so that the values match the new data. New tuples are appended to the end of the file. Tuples which exist on disk but not in the new data are commented out. The save routine tries to leave comments intact. Any syntactical errors in the original are commented out.

Function Documentation

◆ gslutil_cffile_load()

struct gslutil_cffile_t* gslutil_cffile_load ( const char *  fname)

Load configuration file.

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_cffile_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_cffile_save()

int gslutil_cffile_save ( const char *  fname,
const struct gslutil_cffile_t cf 
)

Save configuration file.

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

Saves the list of configuration tuples cf into the file name fname. If the file already exists, it is edited in a non-destructive manner (see Configuration files). In any case, the new file is written to a dotfile in the same directory first before being renamed with rename(2).

The only errors that can occur are disk I/O errors, which will be reported through the gslutil_cffile_error mechanism.

◆ gslutil_cffile_change_tuple()

void gslutil_cffile_change_tuple ( struct gslutil_cffile_tuple tuple,
const char *  new_value 
)

Change value of configuration file tuple.

Parameters
tuplePointer to tuple object to change.
new_valueThe new value to set.

Changes the value of the referenced tuple to be new_value. Will create a copy of the string, so the original need not persist. Uses safe_malloc(), so always succeeds.

◆ gslutil_cffile_alloc()

struct gslutil_cffile_t* gslutil_cffile_alloc ( void  )

Allocate a new, empty configuration file structure.

Returns
Pointer to new structure.

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

◆ gslutil_cffile_free()

void gslutil_cffile_free ( struct gslutil_cffile_t cf)

Free a configuration file structure.

Parameters
cfConfiguration tuple structure.

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

◆ gslutil_cffile_add_tuple()

int gslutil_cffile_add_tuple ( struct gslutil_cffile_t cf,
const char *  name,
const char *  value 
)

Add a new tuple to a configuration file structure.

Parameters
cfConfiguration tuple structure.
nameName of new tuple (must be unique).
valueValue of new tuple.
Return values
0on success.
-1on error (duplicate entry).

Adds a new tuple (name and value) to the structure cf. name must be unique; if a tuple already exists in cf with the same name, -1 will be returned. name and value are both copied, so the original string need not persist.

◆ gslutil_cffile_remove_tuple_by_name()

int gslutil_cffile_remove_tuple_by_name ( struct gslutil_cffile_t cf,
const char *  name 
)

Remove a tuple from a configuration file structure.

Parameters
cfConfiguration tuple structure.
nameName of tuple to remove.
Return values
0on success.
-1on error (no such tuple).

Removes a tuple with name name from cf, returning 0 if it was found or -1 if not.

◆ gslutil_cffile_remove_tuple_by_pos()

void gslutil_cffile_remove_tuple_by_pos ( struct gslutil_cffile_t cf,
int  pos 
)

Remove a tuple from a configuration file structure.

Parameters
cfConfiguration tuple structure.
posPosition within array (not checked).

Removes the tuple from array position pos from cf. pos is not bounds-checked. Passing an invalid value will crash your program.

◆ gslutil_cffile_find_tuple()

struct gslutil_cffile_tuple* gslutil_cffile_find_tuple ( struct gslutil_cffile_t cf,
const char *  name 
)

Find a tuple by name.

Parameters
cfConfiguration tuple structure.
nameName of tuple to find.
Returns
Pointer to tuple.
Return values
0if not found.

Searches for a tuple by name. Does a binary search. If no tuple with a matching name is found, returns 0.

◆ gslutil_cffile_find_value()

char* gslutil_cffile_find_value ( const struct gslutil_cffile_t cf,
const char *  name 
)

Get value from file.

Parameters
cfConfiguration tuple structure.
nameName of tuple to find.
Returns
Pointer to value.
Return values
0if not found.

Searches for a tuple by name. Does a binary search. If no tuple with a matching name is found, returns 0. Otherwise, returns a pointer to its value.

Variable Documentation

◆ gslutil_cffile_error

const char* const gslutil_cffile_error

Configuration file error reporting.

If any error is encountered while loading or saving a configuration file, this string will be set to hold a verbose description of the error.