libfossil
fossil-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(NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED
5 /*
6  Copyright (c) 2013 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program is distributed in the hope that it will be useful,
13  but without any warranty; without even the implied warranty of
14  merchantability or fitness for a particular purpose.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  ******************************************************************************
21  This file declares public APIs for working with fossil's persistent
22  configuration settings.
23 */
24 
25 #include "fossil-core.h" /* MUST come first b/c of config macros */
26 
27 #if defined(__cplusplus)
28 extern "C" {
29 #endif
30 
31 /**
32  A flag type for specifying which configuration database a given
33  API should be applied to. Used by fsl_config_get_int32() and
34  friends.
35 */
37 /**
38  Signfies the global-level (per system user) configuration area.
39 */
41 /**
42  Signfies the repository-level configuration area.
43 */
45 /**
46  Signfies the checkout-level (a.k.a. "local") configuration area.
47 */
49 /**
50  Signifies the versioned-level (via ".fossil-settings") configuration area.
51 */
53 /**
54  Signifies the default-level (and other settings metadata) configuration area.
55  This are is read-only, and only contains the publicly documented settings.
56 */
58 };
60 
61 /**
62  Returns the name of the db table associated with the given
63  mode. Results are undefined if mode is an invalid value. The
64  returned bytes are static and constant.
65 */
66 FSL_EXPORT char const * fsl_config_table_for_role(fsl_confdb_t mode);
67 
68 /**
69  Returns a handle to the db associates with the given fsl_confdb_t
70  value. Returns NULL if !f or if f has no db opened for that
71  configuration role. Results are undefined if mode is an invalid
72  value.
73 */
74 FSL_EXPORT fsl_db * fsl_config_for_role(fsl_cx * f, fsl_confdb_t mode);
75 
76 /**
77  Returns the int32 value of a property from one of f's config
78  dbs, as specified by the mode parameter. Returns dflt if !f, f
79  does not have the requested config db opened, no entry is found,
80  or on db-level errors.
81 */
82 FSL_EXPORT fsl_int32_t fsl_config_get_int32( fsl_cx * f, fsl_confdb_t mode,
83  fsl_int32_t dflt, char const * key );
84 /**
85  int64_t counterpart of fsl_config_get_int32().
86 */
87 FSL_EXPORT fsl_int64_t fsl_config_get_int64( fsl_cx * f, fsl_confdb_t mode,
88  fsl_int64_t dflt, char const * key );
89 
90 /**
91  fsl_id_t counterpart of fsl_config_get_int32().
92 */
93 FSL_EXPORT fsl_id_t fsl_config_get_id( fsl_cx * f, fsl_confdb_t mode,
94  fsl_id_t dflt, char const * key );
95 /**
96  fsl_double_t counterpart of fsl_config_get_int32().
97 */
98 FSL_EXPORT fsl_double_t fsl_config_get_double( fsl_cx * f, fsl_confdb_t mode,
99  fsl_double_t dflt, char const * key );
100 
101 
102 /**
103  Boolean countertpart of fsl_config_get_int32().
104 
105  fsl_str_bool() is used to determine the booleanness (booleanity?)
106  of a given config option.
107 */
108 FSL_EXPORT char fsl_config_get_bool( fsl_cx * f, fsl_confdb_t mode,
109  char dflt, char const * key );
110 
111 /**
112  The string-type counterpart of fsl_config_get_int32().
113 
114  Returns a copy of the configuration value if it finds one, else
115  returns NULL.
116 
117  The returned memory must eventually be freed using
118  fsl_free(). If len is not NULL then it is set to the length of
119  the returned string. Returns NULL for any sort of error or for a
120  NULL db value.
121 */
122 FSL_EXPORT char * fsl_config_get_text( fsl_cx * f, fsl_confdb_t mode,
123  char const * key, fsl_size_t * len );
124 
125 /**
126  Like fsl_config_get_text() with one notable exception: regardless
127  of the mode parameter if key refers to a versionable property
128  and such a property is readable in the current checkout, the
129  contents of that versioned property is returned (as per
130  fsl_config_get_versionable()), otherwise this behaves exactly
131  like fsl_config_get_text().
132 */
133 FSL_EXPORT char * fsl_config_get_text2( fsl_cx * f, fsl_confdb_t mode,
134  char const * key, fsl_size_t * len );
135 
136 
137 /**
138  fsl_buffer counterpart of fsl_config_get_text(). Appends the
139  value from the config table to b. Returns 0 on success,
140  FSL_RC_NOT_FOUND if no row was found or the requested db is not
141  opened, FSL_RC_OOM on allocation errror.
142 */
143 FSL_EXPORT int fsl_config_get_buffer( fsl_cx * f, fsl_confdb_t mode,
144  char const * key, fsl_buffer * b );
145 
146 /**
147  fsl_buffer counterpart of fsl_config_get_text2(). Appends the
148  value from the config table to b. Returns 0 on success,
149  FSL_RC_NOT_FOUND if no row was found or the requested db is not
150  opened, FSL_RC_OOM on allocation errror.
151 */
152 FSL_EXPORT int fsl_config_get_buffer2( fsl_cx * f, fsl_confdb_t mode,
153  char const * key, fsl_buffer * b );
154 
155 
156 /**
157  Sets a configuration variable in one of f's config databases, as
158  specified by the mode parameter. Returns 0 on success. val may
159  be NULL. Returns FSL_RC_MISUSE if !f, f does not have that
160  database opened, or !key, FSL_RC_RANGE if !key.
161 
162  If val is NULL then an SQL NULL is bound instead of an empty
163  string.
164 */
165 FSL_EXPORT int fsl_config_set_text( fsl_cx * f, fsl_confdb_t mode, char const * key, char const * val );
166 
167 /**
168  The blob counterpart of fsl_config_set_text(). If len is
169  negative then fsl_strlen(mem) is used to determine the length of
170  the memory.
171 
172  If mem is NULL then an SQL NULL is bound instead of an empty
173  blob.
174 */
175 FSL_EXPORT int fsl_config_set_blob( fsl_cx * f, fsl_confdb_t mode, char const * key,
176  void const * mem, fsl_int_t len );
177 /**
178  int32 counterpart of fsl_config_set_text().
179 */
180 FSL_EXPORT int fsl_config_set_int32( fsl_cx * f, fsl_confdb_t mode,
181  char const * key, fsl_int32_t val );
182 /**
183  int64 counterpart of fsl_config_set_text().
184 */
185 FSL_EXPORT int fsl_config_set_int64( fsl_cx * f, fsl_confdb_t mode,
186  char const * key, fsl_int64_t val );
187 /**
188  fsl_id_t counterpart of fsl_config_set_text().
189 */
190 FSL_EXPORT int fsl_config_set_id( fsl_cx * f, fsl_confdb_t mode,
191  char const * key, fsl_id_t val );
192 /**
193  fsl_double counterpart of fsl_config_set_text().
194 */
195 FSL_EXPORT int fsl_config_set_double( fsl_cx * f, fsl_confdb_t mode,
196  char const * key, fsl_double_t val );
197 /**
198  Boolean counterpart of fsl_config_set_text().
199 
200  See fsl_str_bool() for what string values are considered to be
201  "true" vs "false".
202 */
203 FSL_EXPORT int fsl_config_set_bool( fsl_cx * f, fsl_confdb_t mode,
204  char const * key, char val );
205 
206 /**
207  "Unsets" (removes) the given key from the given configuration database.
208  It is not considered to be an error if the config table does not
209  contain that key.
210 */
211 FSL_EXPORT int fsl_config_unset( fsl_cx * f, fsl_confdb_t mode, char const * key );
212 
213 /**
214  Begins (or recurses) a transaction on the given configuration
215  database. Returns 0 on success, non-0 on error. On success,
216  fsl_config_transaction_end() must eventually be called with the
217  same parameters to pop the transaction stack. Returns
218  FSL_RC_MISUSE if no db handle is opened for the given
219  configuration mode. Assuming all arguments are valid, this
220  returns the result of fsl_db_transaction_end() and propagates
221  any db-side error into the f object's error state.
222 
223  This is primarily intended as an optimization when an app is
224  making many changes to a config database. It is not needed when
225  the app is only making one or two changes.
226 
227  @see fsl_config_transaction_end()
228  @see fsl_db_transaction_begin()
229 */
230 FSL_EXPORT int fsl_config_transaction_begin(fsl_cx * f, fsl_confdb_t mode);
231 
232 /**
233  Pops the transaction stack pushed by
234  fsl_config_transaction_begin(). If rollback is true then the
235  transaction is set roll back, otherwise it is allowed to
236  continue (if recursive) or committed immediately (if not
237  recursive). Returns 0 on success, non-0 on error. Returns
238  FSL_RC_MISUSE if no db handle is opened for the given
239  configuration mode. Assuming all arguments are valid, this
240  returns the result of fsl_db_transaction_end() and propagates
241  any db-side error into the f object's error state.
242 
243  @see fsl_config_transaction_begin()
244  @see fsl_db_transaction_end()
245 */
246 FSL_EXPORT int fsl_config_transaction_end(fsl_cx * f, fsl_confdb_t mode, char rollback);
247 
248 /**
249  Holds metadata for fossil-defined configuration settings.
250 
251  @see fsl_config_ctrl_get()
252  @see fsl_config_has_versionable()
253  @see fsl_config_get_versionable()
254  @see fsl_config_key_is_valid()
255  @see fsl_config_key_is_versionable()
256  @see fsl_config_key_default_value()
257 */
259  /** Name of the setting */
260  char const *name;
261  /**
262  Historical (fossil(1)) internal variable name used by
263  db_set(). Not currently used by this impl.
264  */
265  char const *var;
266  /**
267  Historical (HTML UI). Width of display. 0 for boolean values.
268  */
269  int width;
270  /**
271  Is this setting versionable?
272  */
274  /**
275  Default value
276  */
277  char const *def;
278 };
280 
281 /**
282  If key is the name of a fossil-defined config key, this returns
283  the fsl_config_ctrl value describing that configuration property,
284  else it returns NULL.
285 */
286 FSL_EXPORT fsl_config_ctrl const * fsl_config_ctrl_get(char const * key);
287 
288 /**
289  Returns true if key is the name of a config property
290  as defined by fossil(1).
291 */
292 FSL_EXPORT char fsl_config_key_is_valid(char const * key);
293 
294 
295 /**
296  Returns true if key is the name of a versionable property,
297  as defined by fossil(1).
298 */
299 FSL_EXPORT char fsl_config_key_is_versionable(char const * key);
300 
301 /**
302  If key refers to a fossil-defined configuration setting, this
303  returns its default value as a NUL-terminated string. Its bytes are
304  static and immutable. Returns NULL if key is not a known
305  configuration key.
306 */
307 FSL_EXPORT char const * fsl_config_key_default_value(char const * key);
308 
309 /**
310  Tries to load a "versionable property" in a file named
311  CKOUT/.fossil-settings/KEY, where CKOUT is the root directory of
312  f's current checkout and key is the name of a versionable
313  configuration setting.
314 
315  If it finds one and it can read the file's contents, it returns 0
316  and assigns *pOut to the contents, which are owned by the caller,
317  who must eventually fsl_free() them. As a special case, if an
318  empty file is read, 0 is returned but *pOut will be NULL.
319 
320  On any sort of error, non-0 is returned. In the grand scheme of
321  things, the inability to load a versionable setting is not truly
322  any error, so f's error state is not updated by this function and
323  clients are not expected to treat it as fatal unless perhaps it
324  returns FSL_RC_OOM, in which case it likely is.
325 
326  Note that versionable properties are always treated as strings,
327  and there is not (yet) a family of getter APIs for various value
328  types as there is for the db-level configuration storage.
329 
330  Example usage:
331 
332  @code
333  char const * rv = NULL;
334  int rc = fsl_config_get_versionable(f, "ignore-glob", &rv);
335  if(rc){
336  // error. Just for example's sake:
337  assert(!rv);
338  }else{
339  assert(rv);
340  ...use rv...
341  }
342  @endcode
343 
344 */
345 FSL_EXPORT int fsl_config_get_versionable( fsl_cx * f, char const * key, char **pOut );
346 
347 /**
348  Returns true if f's current checkout contains the given
349  versionable configuration setting, else false.
350 
351  @see fsl_config_ctrl
352 */
353 FSL_EXPORT char fsl_config_has_versionable( fsl_cx * f, char const * key );
354 
355 /**
356  Populates li as a glob list from the given configuration key.
357  Uses (versionable/repo/global) config settings, in that order.
358  It is not an error if one or more of those sources is missing -
359  they are simply skipped.
360 
361  Note that gets any new globs appended to it, as per
362  fsl_glob_list_append(), as opposed to replacing any existing
363  contents.
364 
365  Returns 0 on success, but that only means that there were no
366  errors, not that any entries were necessarily added to li.
367 
368  Arguably a bug: this function does not open the global config if
369  it was not already opened, but will use it if it is opened. This
370  function should arbuably open and close it in that case.
371 */
372 FSL_EXPORT int fsl_config_globs_load(fsl_cx * f, fsl_list * li, char const * key);
373 
374 
375 #if defined(__cplusplus)
376 } /*extern "C"*/
377 #endif
378 #endif
379 /* NET_FOSSIL_SCM_FSL_CONFDB_H_INCLUDED */
fsl_uint_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Signfies the global-level (per system user) configuration area.
Definition: fossil-confdb.h:40
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().
int fsl_int32_t
Definition: fossil-config.h:81
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_confdb_t
A flag type for specifying which configuration database a given API should be applied to...
Definition: fossil-confdb.h:36
The main Fossil "context" type.
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 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-term...
char const * def
Default value.
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().
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_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...
Db handle wrapper class.
Definition: fossil-db.h:105
#define FSL_EXPORT
Definition: fossil-config.h:19
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...
Generic list container type.
Definition: fossil-util.h:150
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.
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().
char const * name
Name of the setting.
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 char fsl_config_has_versionable(fsl_cx *f, char const *key)
Returns true if f's current checkout contains the given versionable configuration setting...
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().
Signifies the default-level (and other settings metadata) configuration area.
Definition: fossil-confdb.h:57
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.
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.
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
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 ...
int versionable
Is this setting versionable?
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().
A general-purpose buffer class, analog to Fossil v1's Blob class, but it is not called fsl_blob to av...
Definition: fossil-util.h:632
Signfies the repository-level configuration area.
Definition: fossil-confdb.h:44
long long int fsl_int64_t
Definition: fossil-config.h:94
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.
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.
int width
Historical (HTML UI).
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().
fsl_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...
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().
double fsl_double_t
fsl_double_t is the double type used by the library.
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().
char const * var
Historical (fossil(1)) internal variable name used by db_set().
FSL_EXPORT int fsl_config_transaction_begin(fsl_cx *f, fsl_confdb_t mode)
Begins (or recurses) a transaction on the given configuration database.
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 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...
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().
Holds metadata for fossil-defined configuration settings.
Signfies the checkout-level (a.k.a.
Definition: fossil-confdb.h:48
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().
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).
Signifies the versioned-level (via ".fossil-settings") configuration area.
Definition: fossil-confdb.h:52