libfossil
fossil-confdb.h File Reference
#include "fossil-core.h"

Go to the source code of this file.

Data Structures

struct  fsl_config_ctrl
 Holds metadata for fossil-defined configuration settings. More...
 

Typedefs

typedef enum fsl_confdb_t fsl_confdb_t
 
typedef struct fsl_config_ctrl fsl_config_ctrl
 

Enumerations

enum  fsl_confdb_t {
  FSL_CONFDB_GLOBAL = 1,
  FSL_CONFDB_REPO = 2,
  FSL_CONFDB_CKOUT = 3,
  FSL_CONFDB_VERSIONED = 4,
  FSL_CONFDB_METADATA = 5
}
 A flag type for specifying which configuration database a given API should be applied to. More...
 

Functions

FSL_EXPORT fsl_config_ctrl const * fsl_config_ctrl_get (char const *key)
 If key is the name of a fossil-defined config key, this returns the fsl_config_ctrl value describing that configuration property, else it returns NULL. More...
 
FSL_EXPORT fsl_dbfsl_config_for_role (fsl_cx *f, fsl_confdb_t mode)
 Returns a handle to the db associates with the given fsl_confdb_t value. More...
 
FSL_EXPORT char fsl_config_get_bool (fsl_cx *f, fsl_confdb_t mode, char dflt, char const *key)
 Boolean countertpart of fsl_config_get_int32(). More...
 
FSL_EXPORT int fsl_config_get_buffer (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_buffer *b)
 fsl_buffer counterpart of fsl_config_get_text(). More...
 
FSL_EXPORT int fsl_config_get_buffer2 (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_buffer *b)
 fsl_buffer counterpart of fsl_config_get_text2(). More...
 
FSL_EXPORT fsl_double_t fsl_config_get_double (fsl_cx *f, fsl_confdb_t mode, fsl_double_t dflt, char const *key)
 fsl_double_t counterpart of fsl_config_get_int32(). More...
 
FSL_EXPORT fsl_id_t fsl_config_get_id (fsl_cx *f, fsl_confdb_t mode, fsl_id_t dflt, char const *key)
 fsl_id_t counterpart of fsl_config_get_int32(). More...
 
FSL_EXPORT fsl_int32_t fsl_config_get_int32 (fsl_cx *f, fsl_confdb_t mode, fsl_int32_t dflt, char const *key)
 Returns the int32 value of a property from one of f's config dbs, as specified by the mode parameter. More...
 
FSL_EXPORT fsl_int64_t fsl_config_get_int64 (fsl_cx *f, fsl_confdb_t mode, fsl_int64_t dflt, char const *key)
 int64_t counterpart of fsl_config_get_int32(). More...
 
FSL_EXPORT char * fsl_config_get_text (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_size_t *len)
 The string-type counterpart of fsl_config_get_int32(). More...
 
FSL_EXPORT char * fsl_config_get_text2 (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_size_t *len)
 Like fsl_config_get_text() with one notable exception: regardless of the mode parameter if key refers to a versionable property and such a property is readable in the current checkout, the contents of that versioned property is returned (as per fsl_config_get_versionable()), otherwise this behaves exactly like fsl_config_get_text(). More...
 
FSL_EXPORT int fsl_config_get_versionable (fsl_cx *f, char const *key, char **pOut)
 Tries to load a "versionable property" in a file named CKOUT/.fossil-settings/KEY, where CKOUT is the root directory of f's current checkout and key is the name of a versionable configuration setting. More...
 
FSL_EXPORT int fsl_config_globs_load (fsl_cx *f, fsl_list *li, char const *key)
 Populates li as a glob list from the given configuration key. More...
 
FSL_EXPORT char fsl_config_has_versionable (fsl_cx *f, char const *key)
 Returns true if f's current checkout contains the given versionable configuration setting, else false. More...
 
FSL_EXPORT char const * fsl_config_key_default_value (char const *key)
 If key refers to a fossil-defined configuration setting, this returns its default value as a NUL-terminated string. More...
 
FSL_EXPORT char fsl_config_key_is_valid (char const *key)
 Returns true if key is the name of a config property as defined by fossil(1). More...
 
FSL_EXPORT char fsl_config_key_is_versionable (char const *key)
 Returns true if key is the name of a versionable property, as defined by fossil(1). More...
 
FSL_EXPORT int fsl_config_set_blob (fsl_cx *f, fsl_confdb_t mode, char const *key, void const *mem, fsl_int_t len)
 The blob counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_bool (fsl_cx *f, fsl_confdb_t mode, char const *key, char val)
 Boolean counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_double (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_double_t val)
 fsl_double counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_id (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_id_t val)
 fsl_id_t counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_int32 (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_int32_t val)
 int32 counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_int64 (fsl_cx *f, fsl_confdb_t mode, char const *key, fsl_int64_t val)
 int64 counterpart of fsl_config_set_text(). More...
 
FSL_EXPORT int fsl_config_set_text (fsl_cx *f, fsl_confdb_t mode, char const *key, char const *val)
 Sets a configuration variable in one of f's config databases, as specified by the mode parameter. More...
 
FSL_EXPORT char const * fsl_config_table_for_role (fsl_confdb_t mode)
 Returns the name of the db table associated with the given mode. More...
 
FSL_EXPORT int fsl_config_transaction_begin (fsl_cx *f, fsl_confdb_t mode)
 Begins (or recurses) a transaction on the given configuration database. More...
 
FSL_EXPORT int fsl_config_transaction_end (fsl_cx *f, fsl_confdb_t mode, char rollback)
 Pops the transaction stack pushed by fsl_config_transaction_begin(). More...
 
FSL_EXPORT int fsl_config_unset (fsl_cx *f, fsl_confdb_t mode, char const *key)
 "Unsets" (removes) the given key from the given configuration database. More...
 

Typedef Documentation

typedef enum fsl_confdb_t fsl_confdb_t

Definition at line 59 of file fossil-confdb.h.

Definition at line 279 of file fossil-confdb.h.

Enumeration Type Documentation

A flag type for specifying which configuration database a given API should be applied to.

Used by fsl_config_get_int32() and friends.

Enumerator
FSL_CONFDB_GLOBAL 

Signfies the global-level (per system user) configuration area.

FSL_CONFDB_REPO 

Signfies the repository-level configuration area.

FSL_CONFDB_CKOUT 

Signfies the checkout-level (a.k.a.

"local") configuration area.

FSL_CONFDB_VERSIONED 

Signifies the versioned-level (via ".fossil-settings") configuration area.

FSL_CONFDB_METADATA 

Signifies the default-level (and other settings metadata) configuration area.

This are is read-only, and only contains the publicly documented settings.

Definition at line 36 of file fossil-confdb.h.

Function Documentation

FSL_EXPORT fsl_config_ctrl const* fsl_config_ctrl_get ( char const *  key)

If key is the name of a fossil-defined config key, this returns the fsl_config_ctrl value describing that configuration property, else it returns NULL.

FSL_EXPORT fsl_db* fsl_config_for_role ( fsl_cx f,
fsl_confdb_t  mode 
)

Returns a handle to the db associates with the given fsl_confdb_t value.

Returns NULL if !f or if f has no db opened for that configuration role. Results are undefined if mode is an invalid value.

FSL_EXPORT char fsl_config_get_bool ( fsl_cx f,
fsl_confdb_t  mode,
char  dflt,
char const *  key 
)

Boolean countertpart of fsl_config_get_int32().

fsl_str_bool() is used to determine the booleanness (booleanity?) of a given config option.

FSL_EXPORT int fsl_config_get_buffer ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_buffer b 
)

fsl_buffer counterpart of fsl_config_get_text().

Appends the value from the config table to b. Returns 0 on success, FSL_RC_NOT_FOUND if no row was found or the requested db is not opened, FSL_RC_OOM on allocation errror.

FSL_EXPORT int fsl_config_get_buffer2 ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_buffer b 
)

fsl_buffer counterpart of fsl_config_get_text2().

Appends the value from the config table to b. Returns 0 on success, FSL_RC_NOT_FOUND if no row was found or the requested db is not opened, FSL_RC_OOM on allocation errror.

FSL_EXPORT fsl_double_t fsl_config_get_double ( fsl_cx f,
fsl_confdb_t  mode,
fsl_double_t  dflt,
char const *  key 
)

fsl_double_t counterpart of fsl_config_get_int32().

FSL_EXPORT fsl_id_t fsl_config_get_id ( fsl_cx f,
fsl_confdb_t  mode,
fsl_id_t  dflt,
char const *  key 
)

fsl_id_t counterpart of fsl_config_get_int32().

FSL_EXPORT fsl_int32_t fsl_config_get_int32 ( fsl_cx f,
fsl_confdb_t  mode,
fsl_int32_t  dflt,
char const *  key 
)

Returns the int32 value of a property from one of f's config dbs, as specified by the mode parameter.

Returns dflt if !f, f does not have the requested config db opened, no entry is found, or on db-level errors.

FSL_EXPORT fsl_int64_t fsl_config_get_int64 ( fsl_cx f,
fsl_confdb_t  mode,
fsl_int64_t  dflt,
char const *  key 
)

int64_t counterpart of fsl_config_get_int32().

FSL_EXPORT char* fsl_config_get_text ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_size_t len 
)

The string-type counterpart of fsl_config_get_int32().

Returns a copy of the configuration value if it finds one, else returns NULL.

The returned memory must eventually be freed using fsl_free(). If len is not NULL then it is set to the length of the returned string. Returns NULL for any sort of error or for a NULL db value.

FSL_EXPORT char* fsl_config_get_text2 ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_size_t len 
)

Like fsl_config_get_text() with one notable exception: regardless of the mode parameter if key refers to a versionable property and such a property is readable in the current checkout, the contents of that versioned property is returned (as per fsl_config_get_versionable()), otherwise this behaves exactly like fsl_config_get_text().

FSL_EXPORT int fsl_config_get_versionable ( fsl_cx f,
char const *  key,
char **  pOut 
)

Tries to load a "versionable property" in a file named CKOUT/.fossil-settings/KEY, where CKOUT is the root directory of f's current checkout and key is the name of a versionable configuration setting.

If it finds one and it can read the file's contents, it returns 0 and assigns *pOut to the contents, which are owned by the caller, who must eventually fsl_free() them. As a special case, if an empty file is read, 0 is returned but *pOut will be NULL.

On any sort of error, non-0 is returned. In the grand scheme of things, the inability to load a versionable setting is not truly any error, so f's error state is not updated by this function and clients are not expected to treat it as fatal unless perhaps it returns FSL_RC_OOM, in which case it likely is.

Note that versionable properties are always treated as strings, and there is not (yet) a family of getter APIs for various value types as there is for the db-level configuration storage.

Example usage:

1 char const * rv = NULL;
2 int rc = fsl_config_get_versionable(f, "ignore-glob", &rv);
3 if(rc){
4 // error. Just for example's sake:
5 assert(!rv);
6 }else{
7 assert(rv);
8 ...use rv...
9 }
FSL_EXPORT int fsl_config_globs_load ( fsl_cx f,
fsl_list li,
char const *  key 
)

Populates li as a glob list from the given configuration key.

Uses (versionable/repo/global) config settings, in that order. It is not an error if one or more of those sources is missing - they are simply skipped.

Note that gets any new globs appended to it, as per fsl_glob_list_append(), as opposed to replacing any existing contents.

Returns 0 on success, but that only means that there were no errors, not that any entries were necessarily added to li.

Arguably a bug: this function does not open the global config if it was not already opened, but will use it if it is opened. This function should arbuably open and close it in that case.

FSL_EXPORT char fsl_config_has_versionable ( fsl_cx f,
char const *  key 
)

Returns true if f's current checkout contains the given versionable configuration setting, else false.

See also
fsl_config_ctrl
FSL_EXPORT char const* fsl_config_key_default_value ( char const *  key)

If key refers to a fossil-defined configuration setting, this returns its default value as a NUL-terminated string.

Its bytes are static and immutable. Returns NULL if key is not a known configuration key.

FSL_EXPORT char fsl_config_key_is_valid ( char const *  key)

Returns true if key is the name of a config property as defined by fossil(1).

FSL_EXPORT char fsl_config_key_is_versionable ( char const *  key)

Returns true if key is the name of a versionable property, as defined by fossil(1).

FSL_EXPORT int fsl_config_set_blob ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
void const *  mem,
fsl_int_t  len 
)

The blob counterpart of fsl_config_set_text().

If len is negative then fsl_strlen(mem) is used to determine the length of the memory.

If mem is NULL then an SQL NULL is bound instead of an empty blob.

FSL_EXPORT int fsl_config_set_bool ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
char  val 
)

Boolean counterpart of fsl_config_set_text().

See fsl_str_bool() for what string values are considered to be "true" vs "false".

FSL_EXPORT int fsl_config_set_double ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_double_t  val 
)

fsl_double counterpart of fsl_config_set_text().

FSL_EXPORT int fsl_config_set_id ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_id_t  val 
)

fsl_id_t counterpart of fsl_config_set_text().

FSL_EXPORT int fsl_config_set_int32 ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_int32_t  val 
)

int32 counterpart of fsl_config_set_text().

FSL_EXPORT int fsl_config_set_int64 ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
fsl_int64_t  val 
)

int64 counterpart of fsl_config_set_text().

FSL_EXPORT int fsl_config_set_text ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key,
char const *  val 
)

Sets a configuration variable in one of f's config databases, as specified by the mode parameter.

Returns 0 on success. val may be NULL. Returns FSL_RC_MISUSE if !f, f does not have that database opened, or !key, FSL_RC_RANGE if !key.

If val is NULL then an SQL NULL is bound instead of an empty string.

FSL_EXPORT char const* fsl_config_table_for_role ( fsl_confdb_t  mode)

Returns the name of the db table associated with the given mode.

Results are undefined if mode is an invalid value. The returned bytes are static and constant.

FSL_EXPORT int fsl_config_transaction_begin ( fsl_cx f,
fsl_confdb_t  mode 
)

Begins (or recurses) a transaction on the given configuration database.

Returns 0 on success, non-0 on error. On success, fsl_config_transaction_end() must eventually be called with the same parameters to pop the transaction stack. Returns FSL_RC_MISUSE if no db handle is opened for the given configuration mode. Assuming all arguments are valid, this returns the result of fsl_db_transaction_end() and propagates any db-side error into the f object's error state.

This is primarily intended as an optimization when an app is making many changes to a config database. It is not needed when the app is only making one or two changes.

See also
fsl_config_transaction_end()
fsl_db_transaction_begin()
FSL_EXPORT int fsl_config_transaction_end ( fsl_cx f,
fsl_confdb_t  mode,
char  rollback 
)

Pops the transaction stack pushed by fsl_config_transaction_begin().

If rollback is true then the transaction is set roll back, otherwise it is allowed to continue (if recursive) or committed immediately (if not recursive). Returns 0 on success, non-0 on error. Returns FSL_RC_MISUSE if no db handle is opened for the given configuration mode. Assuming all arguments are valid, this returns the result of fsl_db_transaction_end() and propagates any db-side error into the f object's error state.

See also
fsl_config_transaction_begin()
fsl_db_transaction_end()
FSL_EXPORT int fsl_config_unset ( fsl_cx f,
fsl_confdb_t  mode,
char const *  key 
)

"Unsets" (removes) the given key from the given configuration database.

It is not considered to be an error if the config table does not contain that key.