Custom modules - conffile reference

The config file is the common mechanism for the user to specify settings and parameters. Pretty much everything should either be in there, or else in a file named by the config. It is strictly read-only; only the user may change the values in these files.

It is divided into sections: normally, each module will read data from its own section. However, it can also read other sections - for instance, every module looks in the [PLC] section for the semaphore keys and the list of points.

Retrieving values

conffile_get_{value/table}[_sec][_type]

The arguments are as follows:

If there is an explicit section (_sec), it comes first.

The next argument (or first, if there's no section) is the name of the variable or table to be retrieved.

In the case of a table, the next two arguments are the row and the column numbers. (In some languages, the whole table will be returned as a two-dimensional array instead.)

If the type mark is omitted, the value is returned as a string, allocated with malloc(), or NULL if the value is not found (no such variable or table, or not that many rows or columns). For the other type marks (_i32, _u32, _f32 and _d), the function takes a further four arguments: a pointer to the variable where the result is to be stored, a minimum, a maximum, and the default value to be used if the variable is not found. The function then returns a zero if the variable could be converted or if it was not found and the default is used, and non-zero if there was a problem.

In weakly typed languages, the type mark will not be available and all values will be returned as strings. If exceptions are available, they will be used to signal nonexistent values, otherwise empty strings will be returned (or as conventional for the language).

There is an additional set of functions for tables,

conffile_get_table_[rows/rowlen][_sec]

These return the number of rows in a table, or the length of a particular row. They return zero if there's no such table or row. Languages that return the whole table as a 2-d array will not have these functions.

Prototypes

char *conffile_get_value(const char *name);
int conffile_get_value_i32(const char *name,
                           i32 *val, i32 min_val, i32 max_val, i32 def_val);
int conffile_get_value_u32(const char *name,
                           u32 *val, u32 min_val, u32 max_val, u32 def_val);
int conffile_get_value_f32(const char *name,
                           f32 *val, f32 min_val, f32 max_val, f32 def_val);
int conffile_get_value_d  (const char *name,
                           double *val, double min_val,
                           double max_val, double def_val);

char *conffile_get_value_sec(const char*section, const char *name);
int conffile_get_value_sec_i32(const char *section, const char *name,
                               i32 *val, i32 min_val, i32 max_val, i32 def_val);
int conffile_get_value_sec_u32(const char *section, const char *name,
                               u32 *val, u32 min_val, u32 max_val, u32 def_val);
int conffile_get_value_sec_f32(const char *section, const char *name,
                               f32 *val, f32 min_val, f32 max_val, f32 def_val);
int conffile_get_value_sec_d  (const char *section, const char *name,
                               double *val, double min_val,
                               double max_val, double def_val);

char *conffile_get_table(const char *name, int row, int col);
int conffile_get_table_i32(const char *name, int row, int col, 
                           i32 *val, i32 min_val, i32 max_val, i32 def_val);
int conffile_get_table_u32(const char *name, int row, int col,
                           u32 *val, u32 min_val, u32 max_val, u32 def_val);
int conffile_get_table_f32(const char *name, int row, int col,
                           f32 *val, f32 min_val, f32 max_val, f32 def_val);

int conffile_get_table_rows(const char *name);
int conffile_get_table_rowlen(const char *name, int row);

char *conffile_get_table_sec(const char *section, const char *name,
			     int row, int col);
int conffile_get_table_sec_i32(const char *section, const char *name, 
                               int row, int col, 
                               i32 *val, i32 min_val, i32 max_val, i32 def_val);
int conffile_get_table_sec_u32(const char *section, const char *name, 
                               int row, int col, 
                               u32 *val, u32 min_val, u32 max_val, u32 def_val);
int conffile_get_table_sec_f32(const char *section, const char *name, 
                               int row, int col, 
                               f32 *val, f32 min_val, f32 max_val, f32 def_val);

int conffile_get_table_rows_sec(const char *section, const char *name);
int conffile_get_table_rowlen_sec(const char *section, const char *name,
				   int row);

Other conffile functions

It's also possible to obtain the name of the nth variable in the config, using conffile_var_by_index(). For debugging, the config can be dumped with conffile_dump().

I have no idea what the conffile_parse_i32() function is or how it differs from conffile_get_value_i32().

$Date: 2004/12/28 05:32:09 $