libfossil
confdb.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED
5/*
6 Copyright 2013-2021 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13*/
14/** @file confdb.h
15
16 fossil-confdb.h declares APIs dealing with fossil's various
17 configuration option storage backends.
18*/
19
20#include "core.h" /* MUST come first b/c of config macros */
21
22#if defined(__cplusplus)
23extern "C" {
24#endif
25
26/**
27 A flag type for specifying which configuration backend a given API
28 should be applied to. Used by most of the fsl_config_XXX() APIS,
29 e.g. fsl_config_get_int32() and friends.
30
31 This type is named fsl_confdb_e (not the "db" part) because 3 of
32 the 4 fossil-supported config storage backends are databases. The
33 "versioned setting" backend, which deals with non-db local files,
34 was encapsulated into this API long after the db-related options
35 were
36*/
38/** Sentinel value. Not for use with public APIs. */
40/**
41 Signfies the global-level (per system user) configuration area.
42
43 Note that fsl_config_... APIs which use this do not currently open
44 that database on demand due to the potential for downstream
45 locking-related issues when the config db is left open, as well as
46 locking-related issues here when a separate client or instance is
47 holding that db open. That behaviour may change in the future.
48*/
50/**
51 Signfies the repository-level configuration area.
52*/
54/**
55 Signfies the checkout-level (a.k.a. "local") configuration area.
56*/
58
59/**
60 The obligatory special case...
61
62 Versionable settings are stored directly in SCM-controlled files,
63 each of which has the same name as the setting and lives in the
64 .fossil-settings directory of a checkout. Though versionable
65 settings _can_ be read from a non-checked-out repository, doing so
66 requires knowning which version to fetch and is horribly
67 inefficient, so there are currently no APIs for doing so.
68
69 Note that the APIs which read and write versioned settings do not
70 care whether those settings are valid for fossil(1).
71
72 Reminder to self: SQL to find the checkins in which a versioned
73 settings file was added or modified (ignoring renames and branches
74 and whatnot).
75
76 ```
77select strftime('%Y-%m-%d %H:%M:%S',e.mtime) mtime,
78b.rid, b.uuid from mlink m, filename f, blob b, event e
79where f.fnid=m.fnid
80and m.mid=b.rid
81and b.rid=e.objid
82and f.name='.fossil-settings/ignore-glob'
83order by e.mtime desc
84;
85 ```
86
87*/
89};
91
92/**
93 Returns the name of the db table associated with the given
94 mode. Results are undefined if mode is an invalid value. The
95 returned bytes are static and constant.
96
97 Returns NULL for the role FSL_CONFDB_VERSIONABLE.
98*/
100
101/**
102 Returns a handle to the db associates with the given fsl_confdb_e
103 value. Returns NULL if !f or if f has no db opened for that
104 configuration role. Results are undefined if mode is an invalid
105 value.
106
107 For FSL_CONFDB_VERSIONABLE it returns the results of fsl_cx_db(),
108 even though there is no database-side support for versionable files
109 (which live in files in a checkout).
110*/
112
113/**
114 Returns the int32 value of a property from one of f's config
115 dbs, as specified by the mode parameter. Returns dflt if !f, f
116 does not have the requested config db opened, no entry is found,
117 or on db-level errors.
118*/
120 int32_t dflt, char const * key );
121/**
122 int64_t counterpart of fsl_config_get_int32().
123*/
125 int64_t dflt, char const * key );
126
127/**
128 fsl_id_t counterpart of fsl_config_get_int32().
129*/
131 fsl_id_t dflt, char const * key );
132/**
133 double counterpart of fsl_config_get_int32().
134*/
136 double dflt, char const * key );
137
138
139/**
140 Boolean countertpart of fsl_config_get_int32().
141
142 fsl_str_bool() is used to determine the booleanness (booleanity?)
143 of a given config option.
144*/
146 bool dflt, char const * key );
147
148/**
149 A convenience form of fsl_config_get_buffer(). If it finds a
150 config entry it returns its value. If *len is not NULL then *len is
151 assigned the length of the returned string, in bytes (and is set to
152 0 if NULL is returned). Any errors encounters while looking for
153 the entry are suppressed and NULL is returned.
154
155 The returned memory must eventually be freed using fsl_free(). If
156 len is not NULL then it is set to the length of the returned
157 string. Returns NULL for any sort of error or for a NULL db value.
158
159 If capturing error state is important for a given use case, use
160 fsl_config_get_buffer() instead, which provides the same features
161 as this one but propagates any error state.
162*/
164 char const * key,
165 fsl_size_t * len );
166
167/**
168 The fsl_buffer-type counterpart of fsl_config_get_int32().
169
170 Replaces the contents of the given buffer (re-using any memory it
171 might have) with a value from a config region. Returns 0 on
172 success, FSL_RC_NOT_FOUND if no entry was found or the requested db
173 is not opened, FSL_RC_OOM on allocation errror.
174
175 If mode is FSL_CONFDB_VERSIONABLE, this operation requires
176 a checkout and returns (if possible) the contents of the file
177 named {CHECKOUT_ROOT}/.fossil-settings/{key}.
178
179 On any sort of error, including the inability to find or open
180 a versionable-settings file, non-0 is returned:
181
182 - FSL_RC_OOM on allocation error
183
184 - FSL_RC_NOT_FOUND if either the database referred to by mode is
185 not opened or a matching setting cannot be found.
186
187 - FSL_RC_ACCESS is a versionable setting file is found but cannot
188 be opened for reading.
189
190 - FSL_RC_NOT_A_CKOUT if mode is FSL_CONFDB_VERSIONABLE and no
191 checkout is opened.
192
193 - Potentially one of several db-related codes if reading a
194 non-versioned setting fails.
195
196 In the grand scheme of things, the inability to load a setting is
197 not generally an error, so clients are not expected to treat it as
198 fatal unless perhaps it returns FSL_RC_OOM, in which case it likely
199 is.
200*/
202 char const * key, fsl_buffer * const b );
203
204
205/**
206 If f has an opened checkout, this replaces b's contents (re-using
207 any existing memory) with an absolute path to the filename for that
208 setting: {CHECKOUT_ROOT}/.fossil-settings/{key}
209
210 This routine neither verifies that the given key is a valid
211 versionable setting name nor that the file exists: it's purely a
212 string operation.
213
214 Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no checkout
215 opened, FSL_RC_MISUSE if key is NULL, empty, or if
216 fsl_is_simple_pathname() returns false for the key, and FSL_RC_OOM
217 if appending to the buffer fails.
218 */
220
221/**
222 Sets a configuration variable in one of f's config databases, as
223 specified by the mode parameter. Returns 0 on success. val may
224 be NULL. Returns FSL_RC_MISUSE if !f, f does not have that
225 database opened, or !key, FSL_RC_RANGE if !key.
226
227 If mode is FSL_CONFDB_VERSIONABLE, it attempts to write/overwrite
228 the corresponding file in the current checkout.
229
230 If mem is NULL and mode is not FSL_CONFDB_VERSIONABLE then an SQL
231 NULL is bound instead of an empty blob. For FSL_CONFDB_VERSIONABLE
232 an empty file will be written for that case.
233
234 If mode is FSL_CONFDB_VERSIONABLE, this does NOT queue any
235 newly-created versionable setting file for inclusion into the
236 SCM. That is up to the caller. See
237 fsl_config_versionable_filename() for info about an additional
238 potential usage error case with FSL_CONFDB_VERSIONABLE.
239
240 Pedantic side-note: the input text is saved as-is. No trailing
241 newline is added when saving to FSL_CONFDB_VERSIONABLE because
242 doing so would require making a copy of the input bytes just to add
243 a newline to it. The non-text fsl_config_set_XXX() APIs add a
244 newline when writing to their values out to a versionable config
245 file because it costs them nothing to do so and text files "should"
246 have a trailing newline.
247
248 Potential TODO: if mode is FSL_CONFDB_VERSIONABLE and the key
249 contains directory components, e,g, "app/x", we should arguably use
250 fsl_mkdir_for_file() to create those components. As of this writing
251 (2021-03-14), no such config keys have ever been used in fossil.
252
253 @see fsl_config_versionable_filename()
254*/
256 char const * key, char const * val );
257
258/**
259 The blob counterpart of fsl_config_set_text(). If len is
260 negative then fsl_strlen(mem) is used to determine the length of
261 the memory.
262
263 If mem is NULL and mode is not FSL_CONFDB_VERSIONABLE then an SQL
264 NULL is bound instead of an empty blob. For FSL_CONFDB_VERSIONABLE
265 an empty file will be written for that case.
266*/
267FSL_EXPORT int fsl_config_set_blob( fsl_cx * const f, fsl_confdb_e mode, char const * key,
268 void const * mem, fsl_int_t len );
269/**
270 int32 counterpart of fsl_config_set_text().
271*/
273 char const * key, int32_t val );
274/**
275 int64 counterpart of fsl_config_set_text().
276*/
278 char const * key, int64_t val );
279/**
280 fsl_id_t counterpart of fsl_config_set_text().
281*/
283 char const * key, fsl_id_t val );
284/**
285 fsl_double counterpart of fsl_config_set_text().
286*/
288 char const * key, double val );
289/**
290 Boolean counterpart of fsl_config_set_text().
291
292 For compatibility with fossil conventions, the value will be saved
293 in the string form "on" or "off". When mode is
294 FSL_CONFDB_VERSIONABLE, that value will include a trailing newline.
295*/
297 char const * key, bool val );
298
299/**
300 "Unsets" (removes) the given key from the given configuration database.
301 It is not considered to be an error if the config table does not
302 contain that key.
303
304 Returns FSL_RC_UNSUPPORTED, without side effects, if mode is
305 FSL_CONFDB_VERSIONABLE. It "could" hypothetically remove a
306 checked-out copy of a versioned setting, then queue the file for
307 removal in the next checkin, but it does not do so. It might, in
308 the future, be changed to do so, or at least to remove the local
309 settings file.
310*/
312 char const * key );
313
314/**
315 Begins (or recurses) a transaction on the given configuration
316 database. Returns 0 on success, non-0 on error. On success,
317 fsl_config_transaction_end() must eventually be called with the
318 same parameters to pop the transaction stack. Returns
319 FSL_RC_MISUSE if no db handle is opened for the given
320 configuration mode. Assuming all arguments are valid, this
321 returns the result of fsl_db_txn_end() and propagates
322 any db-side error into the f object's error state.
323
324 This is primarily intended as an optimization when an app is
325 making many changes to a config database. It is not needed when
326 the app is only making one or two changes.
327
328 @see fsl_config_transaction_end()
329 @see fsl_db_txn_begin()
330*/
332
333/**
334 Pops the transaction stack pushed by
335 fsl_config_transaction_begin(). If rollback is true then the
336 transaction is set roll back, otherwise it is allowed to
337 continue (if recursive) or committed immediately (if not
338 recursive). Returns 0 on success, non-0 on error. Returns
339 FSL_RC_MISUSE if no db handle is opened for the given
340 configuration mode. Assuming all arguments are valid, this
341 returns the result of fsl_db_txn_end() and propagates
342 any db-side error into the f object's error state.
343
344 @see fsl_config_transaction_begin()
345 @see fsl_db_txn_end()
346*/
347FSL_EXPORT int fsl_config_transaction_end(fsl_cx * const f, fsl_confdb_e mode, bool rollback);
348
349/**
350 Populates li as a glob list from the given configuration key.
351 Uses (versionable/repo/global) config settings, in that order.
352 It is not an error if one or more of those sources is missing -
353 they are simply skipped.
354
355 Note that gets any new globs appended to it, as per
356 fsl_glob_list_append(), as opposed to replacing any existing
357 contents.
358
359 Returns 0 on success, but that only means that there were no
360 errors, not that any entries were necessarily added to li.
361
362 Arguably a bug: this function does not open the global config if
363 it was not already opened, but will use it if it is opened. This
364 function should arbuably open and close it in that case. That said,
365 there are cases which prohibit closing of the config db and this
366 function cannot know if one of those cases is active.
367*/
368FSL_EXPORT int fsl_config_globs_load(fsl_cx * const f, fsl_list * const li, char const * key);
369
370/**
371 Fetches the preferred name of the "global" db file for the current
372 user by assigning it to *zOut. Returns 0 on success, in which case
373 *zOut is updated and non-0 on error, in which case *zOut is not
374 modified. On success, ownership of *zOut is transferred to the
375 caller, who must eventually free it using fsl_free().
376
377 Errors include:
378
379 - FSL_RC_OOM on allocation error
380 - FSL_RC_NOT_FOUND (Windows only) if no relevant environment
381 variables are set from which to form the db path.
382
383 The locations searched for the database file are
384 platform-dependent...
385
386 Unix-like systems are searched in the following order:
387
388 1) If the FOSSIL_HOME environment var is set, use
389 $FOSSIL_HOME/.fossil.
390
391 2) If $HOME/.fossil already exists, use that.
392
393 3) If XDG_CONFIG_HOME environment var is set, use
394 $XDG_CONFIG_HOME/fossil.db.
395
396 4) If $HOME/.config is a directory, use $HOME/.config/fossil.db
397
398 5) Fall back to $HOME/.fossil (historical name).
399
400 Windows:
401
402 1) If $FOSSIL_HOME is set, use that directory.
403 2) If $LOCALAPPDATA is set, use that directory.
404 3) If $APPDATA is set, use that directory.
405 4) If $USERPROFILE is set, use that directory.
406 5) If $HOMEDRIVE and $HOMEPATH are set, use that directory.
407
408 If none of the above are set, FSL_RC_NOT_FOUND is returned.
409
410 The name `_fossil` is appended to the first of the above-listed
411 locations which is set in the environment.
412
413 All platforms:
414
415 Except where listed above, this function does not check whether the
416 file already exists or is a database.
417*/
419
420/**
421 A variant of fsl_config_get_int32() which can search through multiple
422 config sources in an order specified by the caller.
423
424 zCfg must be a NUL-terminated list of case-sensitive letters
425 corresponding to config sources: any of (c, r, v, g) for checkout,
426 repo, versionable, and global, respectively. Each source, if
427 available, is searched, in the order provided, until either the
428 given key is found in that source or no more sources are available,
429 in which case dflt is returned. Any missing sources are silently
430 skipped over (e.g. if 'c' is provided but no checkout is opened,
431 that is not considered an error by this function).
432
433 Errors are silently ignored and cause dflt to be returned.
434
435 @see fsl_configs_get_int64()
436 @see fsl_configs_get_id()
437 @see fsl_configs_get_bool()
438 @see fsl_configs_get_text()
439*/
440FSL_EXPORT int32_t fsl_configs_get_int32(fsl_cx * const f, char const * zCfg, int32_t dflt, char const * key);
441
442/**
443 The int64_t counterpart of fsl_configs_get_int32().
444*/
445FSL_EXPORT int64_t fsl_configs_get_int64(fsl_cx * const f, char const * zCfg, int64_t dflt, char const * key);
446
447/**
448 The fsl_id_t counterpart of fsl_configs_get_int32().
449*/
450FSL_EXPORT fsl_id_t fsl_configs_get_id(fsl_cx * const f, char const * zCfg, fsl_id_t dflt, char const * key);
451
452/**
453 The bool counterpart of fsl_configs_get_int32().
454*/
455FSL_EXPORT bool fsl_configs_get_bool(fsl_cx * const f, char const * zCfg, bool dflt, char const * key);
456
457/**
458 The double counterpart of fsl_configs_get_int32().
459*/
460FSL_EXPORT double fsl_configs_get_double(fsl_cx * const f, char const * zCfg, double dflt, char const * key);
461
462/**
463 The buffer counterpart of fsl_configs_get_int32(). This variant
464 collects, if found, its results in the given buffer (its memory, if
465 any, is reused by this routine). It returns 0 if an entry is found,
466 FSL_RC_OOM on buffer allocation error, and FSL_RC_NOT_FOUND if no
467 match is found in any of the listed sources (noting that missing
468 sources are silently skipped). The full range of errors reported by
469 fsl_config_get_buffer() is not supported here: only FSL_RC_OOM and
470 FSL_RC_NOT_FOUND are reported.
471
472 @see fsl_configs_get_text()
473*/
474FSL_EXPORT int fsl_configs_get_buffer( fsl_cx * const f, char const *zCfg,
475 char const * key, fsl_buffer * const b );
476
477/**
478 The C-string counterpart of fsl_configs_get_int32(). If the final
479 argument is not NULL then if a match is found then its length (in
480 bytes) is assigned to (*len). Returns NULL if no match is found.
481
482 If non-NULL is returned, ownership is transfered to the caller, who
483 must eventually pass the value to fsl_free().
484
485 Note that this function silently ignores any errors,
486 e.g. allocation failure for the result string will be reported by
487 returning NULL (which is indistinguishable from it not finding a
488 match).
489
490 @see fsl_configs_get_buffer()
491*/
492FSL_EXPORT char * fsl_configs_get_text(fsl_cx * const f, char const * zCfg, char const * key,
493 fsl_size_t * len);
494
495#if defined(__cplusplus)
496} /*extern "C"*/
497#endif
498#endif
499/* ORG_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED */
FSL_EXPORT bool fsl_configs_get_bool(fsl_cx *const f, char const *zCfg, bool dflt, char const *key)
The bool counterpart of fsl_configs_get_int32().
FSL_EXPORT fsl_id_t fsl_config_get_id(fsl_cx *const f, fsl_confdb_e mode, fsl_id_t dflt, char const *key)
fsl_id_t counterpart of fsl_config_get_int32().
FSL_EXPORT int fsl_config_set_double(fsl_cx *const f, fsl_confdb_e mode, char const *key, double val)
fsl_double counterpart of fsl_config_set_text().
FSL_EXPORT int fsl_config_set_id(fsl_cx *const f, fsl_confdb_e mode, char const *key, fsl_id_t val)
fsl_id_t counterpart of fsl_config_set_text().
FSL_EXPORT int fsl_config_set_text(fsl_cx *const f, fsl_confdb_e mode, char const *key, char const *val)
Sets a configuration variable in one of f's config databases, as specified by the mode parameter.
FSL_EXPORT int fsl_config_get_buffer(fsl_cx *const f, fsl_confdb_e mode, char const *key, fsl_buffer *const b)
The fsl_buffer-type counterpart of fsl_config_get_int32().
FSL_EXPORT int fsl_config_versionable_filename(fsl_cx *f, char const *key, fsl_buffer *b)
If f has an opened checkout, this replaces b's contents (re-using any existing memory) with an absolu...
FSL_EXPORT int64_t fsl_config_get_int64(fsl_cx *const f, fsl_confdb_e mode, int64_t dflt, char const *key)
int64_t counterpart of fsl_config_get_int32().
FSL_EXPORT int32_t fsl_configs_get_int32(fsl_cx *const f, char const *zCfg, int32_t dflt, char const *key)
A variant of fsl_config_get_int32() which can search through multiple config sources in an order spec...
FSL_EXPORT int64_t fsl_configs_get_int64(fsl_cx *const f, char const *zCfg, int64_t dflt, char const *key)
The int64_t counterpart of fsl_configs_get_int32().
FSL_EXPORT int fsl_config_set_blob(fsl_cx *const f, fsl_confdb_e mode, char const *key, void const *mem, fsl_int_t len)
The blob counterpart of fsl_config_set_text().
FSL_EXPORT double fsl_config_get_double(fsl_cx *const f, fsl_confdb_e mode, double dflt, char const *key)
double counterpart of fsl_config_get_int32().
FSL_EXPORT int fsl_config_unset(fsl_cx *const f, fsl_confdb_e mode, char const *key)
"Unsets" (removes) the given key from the given configuration database.
FSL_EXPORT int fsl_config_transaction_begin(fsl_cx *const f, fsl_confdb_e mode)
Begins (or recurses) a transaction on the given configuration database.
FSL_EXPORT int fsl_configs_get_buffer(fsl_cx *const f, char const *zCfg, char const *key, fsl_buffer *const b)
The buffer counterpart of fsl_configs_get_int32().
FSL_EXPORT fsl_db * fsl_config_for_role(fsl_cx *const f, fsl_confdb_e mode)
Returns a handle to the db associates with the given fsl_confdb_e value.
FSL_EXPORT int fsl_config_global_preferred_name(char **zOut)
Fetches the preferred name of the "global" db file for the current user by assigning it to *zOut.
FSL_EXPORT double fsl_configs_get_double(fsl_cx *const f, char const *zCfg, double dflt, char const *key)
The double counterpart of fsl_configs_get_int32().
fsl_confdb_e
A flag type for specifying which configuration backend a given API should be applied to.
Definition confdb.h:37
@ FSL_CONFDB_NONE
Sentinel value.
Definition confdb.h:39
@ FSL_CONFDB_REPO
Signfies the repository-level configuration area.
Definition confdb.h:53
@ FSL_CONFDB_VERSIONABLE
The obligatory special case...
Definition confdb.h:88
@ FSL_CONFDB_GLOBAL
Signfies the global-level (per system user) configuration area.
Definition confdb.h:49
@ FSL_CONFDB_CKOUT
Signfies the checkout-level (a.k.a.
Definition confdb.h:57
FSL_EXPORT fsl_id_t fsl_configs_get_id(fsl_cx *const f, char const *zCfg, fsl_id_t dflt, char const *key)
The fsl_id_t counterpart of fsl_configs_get_int32().
FSL_EXPORT char const * fsl_config_table_for_role(fsl_confdb_e mode)
Returns the name of the db table associated with the given mode.
FSL_EXPORT int fsl_config_set_int32(fsl_cx *const f, fsl_confdb_e mode, char const *key, int32_t val)
int32 counterpart of fsl_config_set_text().
FSL_EXPORT int fsl_config_set_bool(fsl_cx *const f, fsl_confdb_e mode, char const *key, bool val)
Boolean counterpart of fsl_config_set_text().
FSL_EXPORT char * fsl_configs_get_text(fsl_cx *const f, char const *zCfg, char const *key, fsl_size_t *len)
The C-string counterpart of fsl_configs_get_int32().
FSL_EXPORT int fsl_config_globs_load(fsl_cx *const f, fsl_list *const li, char const *key)
Populates li as a glob list from the given configuration key.
FSL_EXPORT int fsl_config_set_int64(fsl_cx *const f, fsl_confdb_e mode, char const *key, int64_t val)
int64 counterpart of fsl_config_set_text().
FSL_EXPORT int32_t fsl_config_get_int32(fsl_cx *const f, fsl_confdb_e mode, 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.
FSL_EXPORT int fsl_config_transaction_end(fsl_cx *const f, fsl_confdb_e mode, bool rollback)
Pops the transaction stack pushed by fsl_config_transaction_begin().
FSL_EXPORT bool fsl_config_get_bool(fsl_cx *const f, fsl_confdb_e mode, bool dflt, char const *key)
Boolean countertpart of fsl_config_get_int32().
FSL_EXPORT char * fsl_config_get_text(fsl_cx *const f, fsl_confdb_e mode, char const *key, fsl_size_t *len)
A convenience form of fsl_config_get_buffer().
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Definition config.h:192
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
This file declares the core SCM-related public APIs.
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
The main Fossil "context" type.
Definition internal.h:400
Db handle wrapper class.
Definition db.h:313
Generic list container type.
Definition util.h:156