libfossil
core.h File Reference

This file declares the core SCM-related public APIs. More...

#include <stdbool.h>
#include "fossil-scm/util.h"
#include <time.h>
Include dependency graph for core.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  fsl_cx_config
 A part of the configuration used by fsl_cx_init() and friends. More...
struct  fsl_lib_configurable_t
 This type, accessible to clients via the fsl_lib_configurable global, contains configuration-related data for the library which can be swapped out by clients. More...
struct  fsl_msg
 A message object type for use with fsl_sc::status(). More...
struct  fsl_msg_blob
 Message payload type for FSL_MSG_type_blob. More...
struct  fsl_msg_listener
 Client callback info for receiving various events during fossil sync processing. More...

Namespaces

namespace  fsl
 The fsl namespace is reserved for an eventual C++ wrapper for the API.

Macros

#define E(N, V)
#define E(N, V, H)
#define E(NAME, VAL, IGNORED)
#define FSL__WARN_OOM   fsl_report_oom_impl
#define fsl_cx_config_empty_m
 fsl_cx_config instance initialized with defaults, intended for const-copy initialization.
#define fsl_cx_txn_end(F, RollbackMode)
#define fsl_msg_empty_m
 fsl_msg instance intended for const-copy initialization.
#define fsl_msg_listener_empty_m   { .callback=0, .state=0 }
#define fsl_msg_map(E)
 Expands to a mapping of all fsl_msg types by invoking E(NAME,VALUE,PayloadDescription) for each one.
#define fsl_rc_e_map(E)
 A macro which invokes its argument (a macro name) to expand to all possible values of fsl_rc_e entries.
#define fsl_report_oom   fsl_report_oom_impl
#define fsl_report_oom_impl   fprintf(stderr,"OOM @ %s:%d\n", __FILE__, __LINE__)
 An internal helper macro to help localize OOM error reports (which are most often side effects of other issues, rather than being real OOM cases).
#define fsl_satype_e_map(E)
 Invokes macro E with 2 arguments one time for each of the core fsl_satype_e entries.

Typedefs

typedef enum fsl_configset_e fsl_configset_e
typedef struct fsl_cx fsl_cx
typedef struct fsl_cx_config fsl_cx_config
typedef enum fsl_cx_flags_e fsl_cx_flags_e
typedef struct fsl_cx_init_opt fsl_cx_init_opt
typedef struct fsl_db fsl_db
typedef enum fsl_dbrole_e fsl_dbrole_e
typedef enum fsl_fileperm_e fsl_fileperm_e
typedef enum fsl_glob_category_e fsl_glob_category_e
typedef enum fsl_hashpolicy_e fsl_hashpolicy_e
typedef struct fsl_lib_configurable_t fsl_lib_configurable_t
typedef struct fsl_msg fsl_msg
typedef struct fsl_msg_blob fsl_msg_blob
typedef enum fsl_msg_e fsl_msg_e
typedef int(* fsl_msg_f) (fsl_msg const *msg, void *state)
 A callback for use with the library's message-passing subsystem, to provide feedback during potentially long-running work, in particular synchronization with a remote.
typedef struct fsl_msg_listener fsl_msg_listener
typedef enum fsl_rc_e fsl_rc_e
typedef enum fsl_satype_e fsl_satype_e
typedef int(* fsl_see_key_f) (void *pState, const char *zDbFile, fsl_buffer *pOut, int *keyType)
 EXPERIMENTAL and subject to change.
typedef enum fsl_see_keytype_e fsl_see_keytype_e
typedef struct fsl_stmt fsl_stmt
typedef struct fsl__xfer fsl_xfer
 A "transfer context" type used by many of the sync transfer APIs.

Enumerations

enum  fsl_buildinfo_e {
  FSL_BUILDINFO_VERSION ,
  FSL_BUILDINFO_VERSION_HASH ,
  FSL_BUILDINFO_VERSION_TIMESTAMP ,
  FSL_BUILDINFO_CONFIG_TIMESTAMP
}
 Flags for use with fsl_buildinfo(). More...
enum  fsl_configset_e {
  FSL_CONFSET_NONE = 0x000000 ,
  FSL_CONFIGSET_CSS = 0x000001 ,
  FSL_CONFIGSET_SKIN = 0x000002 ,
  FSL_CONFIGSET_TKT = 0x000004 ,
  FSL_CONFIGSET_PROJ = 0x000008 ,
  FSL_CONFIGSET_SHUN = 0x000010 ,
  FSL_CONFIGSET_USER = 0x000020 ,
  FSL_CONFIGSET_ADDR = 0x000040 ,
  FSL_CONFIGSET_XFER = 0x000080 ,
  FSL_CONFIGSET_ALL = 0x0000ff ,
  FSL_CONFIGSET_OVERWRITE = 0x100000 ,
  FSL_CONFIGSET_OLDFORMAT = 0x200000
}
 Bitmask values specifying "configuration sets". More...
enum  fsl_cx_flags_e {
  FSL_CX_F_NONE = 0 ,
  FSL_CX_F_CALC_R_CARD = 0x01 ,
  FSL_CX_F_SKIP_UNKNOWN_CROSSLINKS = 0x02 ,
  FSL_CX_F_ALLOW_WINDOWS_RESERVED_NAMES = 0x04 ,
  FSL_CX_F_MANIFEST_CACHE = 0x08 ,
  FSL_CX_F_BLOB_CACHE = 0x10 ,
  FSL_CX_F_IS_OPENING_CKOUT = 0x100 ,
  FSL_CX_F_DEFAULTS = FSL_CX_F_MANIFEST_CACHE | FSL_CX_F_BLOB_CACHE
}
 Runtime-configurable flags for a fsl_cx instance. More...
enum  fsl_dbrole_e {
  FSL_DBROLE_NONE = 0 ,
  FSL_DBROLE_CONFIG = 0x01 ,
  FSL_DBROLE_REPO = 0x02 ,
  FSL_DBROLE_CKOUT = 0x04 ,
  FSL_DBROLE_MAIN = 0x08 ,
  FSL_DBROLE_TEMP = 0x10
}
 This enum defines type ID tags with which the API tags fsl_db instances so that the library can figure out which DB is which. More...
enum  fsl_fileperm_e {
  FSL_FILE_PERM_REGULAR = 0 ,
  FSL_FILE_PERM_EXE = 0x1 ,
  FSL_FILE_PERM_LINK = 0x2
}
 File permissions flags supported by fossil manifests. More...
enum  fsl_glob_category_e {
  FSL_GLOBS_INVALID = 0 ,
  FSL_GLOBS_IGNORE = 0x01 ,
  FSL_GLOBS_CRNL = 0x02 ,
  FSL_GLOBS_BINARY = 0x04 ,
  FSL_GLOBS_ANY = 0xFF
}
 A collection of bitmaskable values indicating categories of fossil-standard glob sets. More...
enum  fsl_hashpolicy_e {
  FSL_HPOLICY_SHA1 = 0 ,
  FSL_HPOLICY_AUTO = 1 ,
  FSL_HPOLICY_SHA3 = 2 ,
  FSL_HPOLICY_SHA3_ONLY = 3 ,
  FSL_HPOLICY_SHUN_SHA1 = 4
}
 List of hash policy values. More...
enum  fsl_msg_e { fsl_msg_map =(E) }
 Message type flags Indicators for use with fsl_sc::status, fsl_xfer_emit(), and friends. More...
enum  fsl_rc_e { fsl_rc_e_map =(E) }
 Most functions in this library which return an int return result codes from the fsl_rc_e enum. More...
enum  fsl_satype_e {
  fsl_satype_e_map ,
  FSL_SATYPE_EVENT = FSL_SATYPE_TECHNOTE ,
  FSL_SATYPE_BRANCH_START = 100
}
 An enumeration of the types of structural artifacts used by Fossil. More...
enum  fsl_see_keytype_e {
  FSL_SEE_KEYTYPE_NONE = 0 ,
  FSL_SEE_KEYTYPE_PLAIN = 1 ,
  FSL_SEE_KEYTYPE_BINARY = 2 ,
  FSL_SEE_KEYTYPE_HEXKEY = 3 ,
  FSL_SEE_KEYTYPE_TEXTKEY = 4
}
 SQLite Encryption Extension (SEE) key types for use with fsl_see_key_f(). More...

Functions

FSL_EXPORT char const * fsl_buildinfo (enum fsl_buildinfo_e what)
 Fetches the piece of library-level build information specified by its argument.
FSL_EXPORT int fsl_close_dbs (fsl_cx *f)
 Shorthand for calling both fsl_close_scm_dbs() and, if it succeeds, fsl_config_close().
FSL_EXPORT int fsl_close_scm_dbs (fsl_cx *f)
 Closes any opened repository and/or checkout database(s) opened by f, freeing any associated resources and clearing out f's current user name.
FSL_EXPORT int fsl_config_close (fsl_cx *f)
 Closes/detaches the database connection opened by fsl_config_open().
FSL_EXPORT int fsl_config_open (fsl_cx *f, char const *dbName)
 Opens the given database file as f's configuration database.
FSL_EXPORT bool fsl_cx_allows_symlinks (fsl_cx *f, bool forceRecheck)
 Returns true if f has the "allow-symlinks" repo-level configuration option set to a truthy value, else returns false.
FSL_EXPORT void fsl_cx_case_sensitive_set (fsl_cx *f, bool caseSensitive)
 Sets the case-sensitivity flag for f to the given value.
FSL_EXPORT char const * fsl_cx_ckout_dir_name (fsl_cx const *f, fsl_size_t *len)
 If f has an opened checkout db (from fsl_ckout_open_dir()) then this function returns the directory part of the path for the checkout, including (for historical and internal convenience reasons) a trailing slash.
FSL_EXPORT int fsl_cx_confirm (fsl_cx *f, fsl_confirm_detail const *detail, fsl_confirm_response *outAnswer)
 If fsl_cx_confirmer() was used to install a confirmer callback in f then this routine calls that confirmer and returns its result code and its answer via *outAnswer.
FSL_EXPORT void fsl_cx_confirmer (fsl_cx *f, fsl_confirmer const *newConfirmer, fsl_confirmer *prevConfirmer)
 Installs or (if f is NULL) uninstalls a confirmation callback for use by operations on f which require user confirmation.
FSL_EXPORT void fsl_cx_confirmer_get (fsl_cx const *f, fsl_confirmer *dest)
 Stores a bitwise copy of f's current confirmer object into *dest.
FSL_EXPORT fsl_db * fsl_cx_db (fsl_cx *f)
 Returns a handle to f's main db (which may or may not have any relationship to the repo/checkout/config databases - that's unspecified!), or NULL if f has no opened repo or checkout db.
FSL_EXPORT fsl_db * fsl_cx_db_ckout (fsl_cx *f)
 If f is not NULL and has had a checkout opened via fsl_ckout_open_dir() or similar, this returns a pointer to that database, else it returns NULL.
FSL_EXPORT fsl_db * fsl_cx_db_config (fsl_cx *f)
 If f has an opened configuration db then its handle is returned, else 0 is returned.
FSL_EXPORT char const * fsl_cx_db_file_ckout (fsl_cx const *f, fsl_size_t *len)
 If f is not NULL and has a checkout db opened then this function returns its name.
FSL_EXPORT char const * fsl_cx_db_file_config (fsl_cx const *f, fsl_size_t *len)
 Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened config db, if any.
FSL_EXPORT char const * fsl_cx_db_file_for_role (fsl_cx const *f, fsl_dbrole_e r, fsl_size_t *len)
 Similar to fsl_cx_db_file_ckout() and friends except that it applies to db file implied by the specified role (2nd parameter).
FSL_EXPORT char const * fsl_cx_db_file_repo (fsl_cx const *f, fsl_size_t *len)
 Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened repository db, if any.
FSL_EXPORT fsl_db * fsl_cx_db_repo (fsl_cx *f)
 If f is not NULL and has had its repo opened via fsl_repo_open(), fsl_ckout_open_dir(), or similar, this returns a pointer to that database, else it returns NULL.
FSL_EXPORT int fsl_cx_emit (fsl_cx *const f, fsl_msg_e type, void const *p)
 If f has a fsl_msg listener, a fsl_msg composed from the given type and payload is passed to the the listener and its result is returned, else this is a no-op and 0 is returned.
int fsl_cx_emitf (fsl_cx *f, fsl_msg_e type, char const *zFmt,...)
 Elipsis counterpart of fsl_cx_emitfv().
int fsl_cx_emitfv (fsl_cx *f, fsl_msg_e type, char const *zFmt, va_list args)
 va_list counterpart of fsl_cx_emit() which emits a fsl_appendf()-formatted message as a string or a buffer, depending on the message type.
FSL_EXPORT fsl_error * fsl_cx_err_e (fsl_cx *f)
 Non-const counterpart of fsl_cx_err_ec().
FSL_EXPORT fsl_error const * fsl_cx_err_ec (fsl_cx const *f)
 Returns f's error object.
FSL_EXPORT int fsl_cx_err_get (fsl_cx *f, char const **str, fsl_size_t *len)
 Fetches the error state from f.
FSL_EXPORT int fsl_cx_err_report (fsl_cx *f, bool addNewline)
 If f has error state then it outputs its error state to its output channel and returns the result of fsl_output().
FSL_EXPORT void fsl_cx_err_reset (fsl_cx *f)
 Resets's f's error state, basically equivalent to fsl_cx_err_set(f,0,NULL).
FSL_EXPORT int fsl_cx_err_set (fsl_cx *f, int code, char const *fmt,...)
 Sets the Fossil error state to the given error code and fsl_appendf()-style format string/arguments.
FSL_EXPORT int fsl_cx_err_set_e (fsl_cx *f, fsl_error *err)
 Replaces f's error state with the contents of err, taking over any memory owned by err (but not err itself).
FSL_EXPORT int fsl_cx_err_setv (fsl_cx *f, int code, char const *fmt, va_list args)
 va_list counterpart to fsl_cx_err_set().
FSL_EXPORT int fsl_cx_exec (fsl_cx *f, char const *sql,...)
 Convenience form of fsl_db_exec() which uses f's main db handle.
FSL_EXPORT int fsl_cx_exec_multi (fsl_cx *f, char const *sql,...)
 The fsl_db_exec_multi() counterpart of fsl_cx_exec().
FSL_EXPORT int fsl_cx_exec_multiv (fsl_cx *f, char const *sql, va_list args)
 va_list counterpart of fsl_cx_exec_multi().
FSL_EXPORT int fsl_cx_execv (fsl_cx *f, char const *sql, va_list args)
 va_list counterpart of fsl_cx_exec().
FSL_EXPORT int fsl_cx_filename_cmp (fsl_cx *f, char const *z1, char const *z2)
 Compares two strings, represumably filenames, using either fsl_strcmp() or fsl_stricmp(), depending on f's filename case-sensitivity setting.
FSL_EXPORT char const * fsl_cx_filename_collation (fsl_cx const *f)
 If f is set to use case-sensitive filename handling, returns a pointer to an empty string, otherwise a pointer to the string "COLLATE nocase" is returned.
FSL_EXPORT void fsl_cx_finalize (fsl_cx *f)
 Frees all memory associated with f, which must have been allocated/initialized using fsl_cx_malloc(), fsl_cx_init(), or equivalent, or created on the stack and properly initialized (via fsl_cx_init() or copy-constructed from fsl_cx_empty).
FSL_EXPORT fsl_flag32_t fsl_cx_flag_set (fsl_cx *f, fsl_flag32_t flags, bool enable)
 Sets or unsets one or more option flags on the given fossil context.
FSL_EXPORT fsl_flag32_t fsl_cx_flags_get (fsl_cx const *f)
 Returns f's flags.
FSL_EXPORT int fsl_cx_format (fsl_cx *f, fsl_output_f out, void *outState, char const *zFmt,...)
 The elipsis counterpart of fsl_cx_formatv().
FSL_EXPORT int fsl_cx_format_buffer (fsl_cx *f, fsl_buffer *tgt, char const *zFmt,...)
 Convenience formof fsl_cx_format() which appends the formatted output to tgt.
FSL_EXPORT int fsl_cx_format_FILE (fsl_cx *f, FILE *tgt, char const *zFmt,...)
 Convenience formof fsl_cx_format() which appends the formatted output to tgt.
FSL_EXPORT int fsl_cx_formatv (fsl_cx *f, fsl_output_f out, void *outState, char const *zFmt, va_list args)
 A proxy for fsl_appendfv() which pre-processes the format-specifier string (zFmt) to replace certain placeholders with information about the fsl_cx object.
FSL_EXPORT int fsl_cx_getcwd (fsl_cx *f, fsl_buffer *pOut)
 Works like fsl_getcwd() but updates f's error state on error and appends the current directory's name to the given buffer.
FSL_EXPORT int fsl_cx_glob_list (fsl_cx *f, fsl_glob_category_e gtype, fsl_list **tgt, bool forceReload)
 Fetches f's glob list of the given category.
FSL_EXPORT char const * fsl_cx_glob_matches (fsl_cx *f, int gtype, char const *str)
 Checks one or more of f's configurable glob lists to see if str matches one of them.
FSL_EXPORT bool fsl_cx_has_ckout (fsl_cx const *f)
 Returns true if the given context has a checkout opened, else false.
FSL_EXPORT int fsl_cx_hash_buffer (const fsl_cx *f, bool useAlternate, fsl_buffer const *pIn, fsl_buffer *pOut)
 Hashes all of pIn, appending the hash to pOut.
FSL_EXPORT int fsl_cx_hash_filename (fsl_cx *f, bool useAlternate, const char *zFilename, fsl_buffer *pOut)
 The file counterpart of fsl_cx_hash_buffer(), behaving exactly the same except that its data source is a file and it may return various error codes from fsl_buffer_fill_from_filename().
FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_get (fsl_cx const *f)
 Returns f's current hash policy.
FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_set (fsl_cx *f, fsl_hashpolicy_e p)
 Sets f's hash policy and returns the previous value.
FSL_EXPORT int fsl_cx_init (fsl_cx **tgt, fsl_cx_config const *param)
 Initializes a fsl_cx instance.
FSL_EXPORT int fsl_cx_interrupt (fsl_cx *f, int code, const char *fmt,...)
 Sets f's is-interrupted flag and, if the 3rd argument is not NULL, its error state.
FSL_EXPORT int fsl_cx_interrupted (fsl_cx const *f)
 If f's is-interrupted flag is set, this function returns its value.
FSL_EXPORT int fsl_cx_interruptv (fsl_cx *f, int code, char const *fmt, va_list args)
 The va_list counterpart of fsl_cx_interrupt().
FSL_EXPORT bool fsl_cx_is_case_sensitive (fsl_cx *const f, bool forceRecheck)
 Returns true if f is set for case-sensitive filename handling, else false.
FSL_EXPORT fsl_id_t fsl_cx_last_insert_id (fsl_cx *f)
 Wrapper around fsl_db_last_insert_id() which uses f's main database.
FSL_EXPORT int fsl_cx_last_sync_url (fsl_cx *f, fsl_buffer *tgt)
 Extracts the "last-sync-url" entry from f's repository configuration and appends it to tgt.
void fsl_cx_listener_replace (fsl_cx *f, fsl_msg_listener const *pNew, fsl_msg_listener *pOld)
 Replace's f's current fsl_msg listener with a bitwise copy of pNew.
FSL_EXPORT fsl_cx * fsl_cx_malloc (void)
 Allocates a new fsl_cx instance, which must eventually be passed to fsl_cx_finalize() to clean it up.
FSL_EXPORT int fsl_cx_prepare (fsl_cx *f, fsl_stmt *tgt, char const *sql,...)
 Convenience form of fsl_db_prepare() which uses f's main db.
FSL_EXPORT int fsl_cx_prepare_cached (fsl_cx *f, fsl_stmt **tgt, char const *sql,...)
 Convenience form of fsl_db_prepare_cached() which uses f's main db.
FSL_EXPORT int fsl_cx_preparev (fsl_cx *f, fsl_stmt *tgt, char const *sql, va_list args)
 va_list counterpart of fsl_cx_prepare().
FSL_EXPORT int fsl_cx_preparev_cached (fsl_cx *f, fsl_stmt **tgt, char const *sql, va_list args)
 va_list counterpart of fsl_cx_prepare_cached().
FSL_EXPORT int fsl_cx_stat (fsl_cx *f, bool relativeToCwd, char const *zName, fsl_fstat *tgt)
 Works similarly to fsl_stat(), except that zName must refer to a path under f's current checkout directory.
FSL_EXPORT int fsl_cx_stat2 (fsl_cx *f, bool relativeToCwd, char const *zName, fsl_fstat *tgt, fsl_buffer *nameOut, bool fullPath)
 This works identically to fsl_cx_stat(), but provides more information about the file being stat'd.
FSL_EXPORT int fsl_cx_txn_begin (fsl_cx *f)
 Returns the same as passing fsl_cx_db() to fsl_db_txn_begin().
FSL_EXPORT int fsl_cx_txn_end_v2 (fsl_cx *f, bool keepSavepoint, bool bubbleRollback)
 Returns the same as passing fsl_cx_db() to fsl_db_txn_end().
FSL_EXPORT int fsl_cx_txn_level (fsl_cx *f)
 Returns the same as passing fsl_cx_db() to fsl_db_txn_level(), or 0 if f has no db opened.
FSL_EXPORT int fsl_cx_uplift_db_error (fsl_cx *f, fsl_db *db)
 Unconditionally Moves db->error's state into f (without requiring any allocation).
FSL_EXPORT int fsl_cx_uplift_db_error2 (fsl_cx *f, fsl_db *db, int rc)
 If rc is not 0 and f has no error state but db does, this calls fsl_cx_uplift_db_error() and returns its result, else returns rc.
FSL_EXPORT char const * fsl_cx_user_get (fsl_cx const *f)
 Returns the name set by fsl_cx_user_set(), or NULL if f has no default user name set.
FSL_EXPORT char const * fsl_cx_user_guess (fsl_cx *f)
 If f has a user name set (via fsl_cx_user_set()) then this function returns that value.
FSL_EXPORT int fsl_cx_user_set (fsl_cx *f, char const *userName)
 Sets or clears (if userName is NULL or empty) the default repository user name for operations which require one.
FSL_EXPORT int fsl_flush (fsl_cx *f)
 Flushes f's output channel.
FSL_EXPORT fsl_glob_category_e fsl_glob_name_to_category (char const *str)
 Converts a well-known fossil glob list configuration key to a fsl_glob_category_e value:
FSL_EXPORT char const * fsl_hash_policy_name (fsl_hashpolicy_e p)
 Returns a human-friendly name for the given policy, or NULL for an invalid policy value.
FSL_EXPORT char const * fsl_library_version (void)
 Returns the value of FSL_LIBRARY_VERSION used to compile the library.
FSL_EXPORT bool fsl_library_version_matches (char const *yourLibVersion)
 Returns true (non-0) if yourLibVersion compares lexically equal to FSL_LIBRARY_VERSION, else it returns false (0).
FSL_EXPORT char const * fsl_library_version_scm (void)
 Returns the SCM-specific version info for libfossil (the hash and timestamp of it's own source's version).
FSL_EXPORT int fsl_msg_emit (fsl_msg const *msg, fsl_msg_listener const *where)
 If both where and where->callback are not NULL, msg is passed to where->callback and its result is returned, else this is a no-op and 0 is returned.
char const * fsl_msg_type_cstr (fsl_msg_e e)
 Returns the C-string form of the given sync message type, or NULL if e is invalid.
FSL_EXPORT fsl_db * fsl_needs_ckout (fsl_cx *f)
 The checkout-db counterpart of fsl_needs_repo().
FSL_EXPORT fsl_db * fsl_needs_repo (fsl_cx *f)
 A helper which fetches f's repository db.
FSL_EXPORT int fsl_output (fsl_cx *f, void const *src, fsl_size_t n)
 Outputs the first n bytes of src to f's configured output channel.
FSL_EXPORT int fsl_outputf (fsl_cx *f, char const *fmt,...)
 Uses fsl_appendf() to append formatted output to the channel configured for use with fsl_output().
FSL_EXPORT int fsl_outputfv (fsl_cx *f, char const *fmt, va_list args)
 va_list counterpart to fsl_outputf().
FSL_EXPORT char const * fsl_rc_cstr (int rc)
 Returns a "standard" string form for a fsl_rc_e code.
FSL_EXPORT char const * fsl_satype_cstr (fsl_satype_e t)
 Returns some arbitrary but distinct string for the given fsl_satype_e.
FSL_EXPORT char const * fsl_satype_event_cstr (fsl_satype_e t)
 For a given artifact type, it returns the key string used in the event.type db table.

Variables

FSL_EXPORT const fsl_cx_config fsl_cx_config_empty
 fsl_cx_config instance initialized with defaults, intended for non-const copy initialization.
FSL_EXPORT fsl_lib_configurable_t fsl_lib_configurable
const fsl_msg fsl_msg_empty
 fsl_msg instance intended for non-const copy initialization.
const fsl_msg_listener fsl_msg_listener_empty

Detailed Description

This file declares the core SCM-related public APIs.

Definition in file core.h.

Macro Definition Documentation

◆ E [1/3]

#define E ( N,
V )
Value:
N = V,

Definition at line 497 of file core.h.

◆ E [2/3]

#define E ( N,
V,
H )
Value:
N = V,

Definition at line 497 of file core.h.

Referenced by fsl__cx_caches_reset().

◆ E [3/3]

#define E ( NAME,
VAL,
IGNORED )
Value:
FSL_MSG_ ## NAME = VAL,

Definition at line 497 of file core.h.

◆ FSL__WARN_OOM

#define FSL__WARN_OOM   fsl_report_oom_impl

Definition at line 66 of file core.h.

◆ fsl_cx_config_empty_m

#define fsl_cx_config_empty_m
Value:
{ \
.traceSql = 0, \
.sqlPrint = 0, \
.hashPolicy = FSL_HPOLICY_SHA3, \
.listener = fsl_msg_listener_empty_m, \
.output = {.out=NULL, .state=NULL}, \
.see = {.getSEEKey = NULL, .pState = NULL} \
}
@ FSL_HPOLICY_SHA3
Use SHA3 hashes.
Definition core.h:310
#define fsl_msg_listener_empty_m
Definition core.h:810

fsl_cx_config instance initialized with defaults, intended for const-copy initialization.

Definition at line 885 of file core.h.

◆ fsl_cx_txn_end

#define fsl_cx_txn_end ( F,
RollbackMode )
Value:
fsl_cx_txn_end_v2((F), !(RollbackMode), false)
FSL_EXPORT int fsl_cx_txn_end_v2(fsl_cx *f, bool keepSavepoint, bool bubbleRollback)
Returns the same as passing fsl_cx_db() to fsl_db_txn_end().

Definition at line 1938 of file core.h.

◆ fsl_msg_empty_m

#define fsl_msg_empty_m
Value:
{ \
.type = FSL_MSG_INVALID, .payload = NULL, \
.f = NULL \
}

fsl_msg instance intended for const-copy initialization.

Definition at line 759 of file core.h.

◆ fsl_msg_listener_empty_m

#define fsl_msg_listener_empty_m   { .callback=0, .state=0 }

Definition at line 810 of file core.h.

◆ fsl_msg_map

#define fsl_msg_map ( E)
Value:
E(INVALID, 0, "Sentinel value") \
E(mask_type, 0x7F000000, "Data type mask") \
E(mask_reserved, 0x00FFFF00, "Reserved") \
E(mask_purpose, 0x000000FF, "Message purpose ID") \
E(type_null, 0x01000000, "NULL") \
E(type_string, 0x02000000, "(char const *)") \
E(type_buffer, 0x03000000, "(fsl_buffer const *)") \
E(type_size, 0x04000000, "(fsl_size_t const *)") \
E(type_blob, 0x06000000, "(fsl_msg_blob const *)" ) \
E(type_rebuild_step, 0x07000000, "(fsl_rebuild_step const *)" ) \
E(ERROR, 0x01 | FSL_MSG_type_string, "Error string") \
E(INFO, 0x02 | FSL_MSG_type_string, "Info string") \
E(DEBUG, 0x03 | FSL_MSG_type_string, "Debugging string") \
E(TMPFILE, 0x04 | FSL_MSG_type_string, "value=name of temp file left over") \
E(CONNECT, 0x05 | FSL_MSG_type_size, "value=trip number") \
E(RCV_BLOB, 0x06 | FSL_MSG_type_blob, "Blob received") \
E(RCV_MESSAGE, 0x07 | FSL_MSG_type_string, "\"message\" card from remote") \
E(RCV_CONFIG, 0x08 | FSL_MSG_type_string, "Config group name") \
E(REBUILD_STEP, 0x09 | FSL_MSG_type_rebuild_step, "") \
E(REBUILD_DONE, 0x0A | FSL_MSG_type_rebuild_step, "") \
E(TXN_BEGIN, 0x0B | FSL_MSG_type_size, "value=transaction level") \
E(TXN_COMMIT, 0x0C | FSL_MSG_type_size, "value=transaction level") \
E(TXN_ROLLBACK, 0x0D | FSL_MSG_type_size, "value=transaction level")
#define E(N, V, H)
Definition core.h:497

Expands to a mapping of all fsl_msg types by invoking E(NAME,VALUE,PayloadDescription) for each one.

NAME is the suffix part of the name, e.g. mask_type instead of FSL_MSG_mask_type. VALUE is its integer value. PayloadDescription is a human-legible string typically noting the data type of the payload.

Each entry encodes the data type corresponding to the associated fsl_msg object's payload member: mask the message type value against FSL_MSG_mask_type to get the payload's type.

This mechanism was added for the sync subsystem and the goal is now to replace some of the library's disparate callbacks with this mechanism.

Definition at line 676 of file core.h.

◆ fsl_rc_e_map

#define fsl_rc_e_map ( E)

A macro which invokes its argument (a macro name) to expand to all possible values of fsl_rc_e entries.

The macro name passed to it is invoked once for each entry and passed 3 arguments: the enum entry's full name (FSL_RC_...), its integer value, and a help-text string.

Definition at line 328 of file core.h.

◆ fsl_report_oom

#define fsl_report_oom   fsl_report_oom_impl

Definition at line 67 of file core.h.

◆ fsl_report_oom_impl

#define fsl_report_oom_impl   fprintf(stderr,"OOM @ %s:%d\n", __FILE__, __LINE__)

An internal helper macro to help localize OOM error reports (which are most often side effects of other issues, rather than being real OOM cases).

It's intended to be used like:

void * someAllocedMemory = fsl_malloc(...); // any allocating routine
if(!someAllocedMemory){
rc = FSL_RC_OOM;
goto end;
}
#define fsl_report_oom
Definition core.h:67
FSL_EXPORT void * fsl_malloc(fsl_size_t n)
Semantically behaves like malloc(3), but may introduce instrumentation, error checking,...

or:

if(FSL_RC_OOM==fs){ fsl_report_oom; }

Note that this macro may expand to encompass multiple commands so must never be used as the RHS of an if without squiggly braces surrounding it (as in the above example).

This macro is not invoked in every possible OOM case, so cannot simply be replaced with abort() to kill the app on OOM. For that, apply a custom allocator via fsl_lib_configurable.

Definition at line 61 of file core.h.

◆ fsl_satype_e_map

#define fsl_satype_e_map ( E)
Value:
E(FSL_SATYPE_INVALID, -1/** Sentinel value used for some error
reporting.*/) \
E(FSL_SATYPE_ANY, 0/** Sentinel value used to mark a deck as being
"any" type. This is a placeholder on a deck's
way to completion. */) \
E(FSL_SATYPE_CHECKIN, 1/** Indicates a "manifest" artifact (a checkin
record). */) \
E(FSL_SATYPE_CLUSTER, 2/** Indicates a "cluster" artifact. These
are used during synchronization. */) \
E(FSL_SATYPE_CONTROL, 3/** Indicates a "control" artifact (a tag
change).*/) \
E(FSL_SATYPE_WIKI, 4/** Indicates a "wiki" artifact. */) \
E(FSL_SATYPE_TICKET, 5/** Indicates a "ticket" artifact. */) \
E(FSL_SATYPE_ATTACHMENT, 6/** Indicates an "attachment" artifact
(used in the ticketing subsystem). */) \
E(FSL_SATYPE_TECHNOTE, 7/** Indicates a technote (formerly
"event") artifact (kind of like a blog
entry). */) \
E(FSL_SATYPE_FORUMPOST, 8/** Indicates a forum post artifact (a
close relative of wiki pages).*/)

Invokes macro E with 2 arguments one time for each of the core fsl_satype_e entries.

Argument 1 is the entry's name (identifier) and argument 2 is its value (integer).

Definition at line 1657 of file core.h.

Typedef Documentation

◆ fsl_configset_e

Definition at line 223 of file core.h.

◆ fsl_cx

typedef struct fsl_cx fsl_cx

Definition at line 98 of file core.h.

◆ fsl_cx_config

typedef struct fsl_cx_config fsl_cx_config

Definition at line 93 of file core.h.

◆ fsl_cx_flags_e

Definition at line 292 of file core.h.

◆ fsl_cx_init_opt

Definition at line 95 of file core.h.

◆ fsl_db

typedef struct fsl_db fsl_db

Definition at line 94 of file core.h.

◆ fsl_dbrole_e

typedef enum fsl_dbrole_e fsl_dbrole_e

Definition at line 186 of file core.h.

◆ fsl_fileperm_e

Definition at line 524 of file core.h.

◆ fsl_glob_category_e

Definition at line 1782 of file core.h.

◆ fsl_hashpolicy_e

Definition at line 318 of file core.h.

◆ fsl_lib_configurable_t

typedef struct fsl_lib_configurable_t fsl_lib_configurable_t

Definition at line 586 of file core.h.

◆ fsl_msg

typedef struct fsl_msg fsl_msg

Definition at line 756 of file core.h.

◆ fsl_msg_blob

typedef struct fsl_msg_blob fsl_msg_blob

Definition at line 720 of file core.h.

◆ fsl_msg_e

typedef enum fsl_msg_e fsl_msg_e

Definition at line 711 of file core.h.

◆ fsl_msg_f

typedef int(* fsl_msg_f) (fsl_msg const *msg, void *state)

A callback for use with the library's message-passing subsystem, to provide feedback during potentially long-running work, in particular synchronization with a remote.

Implementations are passed the a message object and any state associated with the callback.

If the function returns non-0, the operation is aborted and that result is propagated back up through the API. On error, this callback is expected to call either of fsl_cx_err_set() or the fsl_xfer_error() family of functions and return that code.

Messages are synchronous - the library must wait on a response from this function before continuing. Ergo, clients should not perform long work in the status callback (or should do so in a separate thread which does_not use msg->f (which is not thread-safe)).

This method is intended primarily for logging or non-interactive feedback, with the exception of the ability to return non-0 to interrupt the sync. e.g. an implementation could return FSL_RC_BREAK in response to an application-side cancel/interrupt button being triggered.

When triggered via a sync operation, the library guarantees that a db transaction will be in place when it calls this, a further incentive to keep implementations short and fast because the db is necessarily locked during that time.

Definition at line 797 of file core.h.

◆ fsl_msg_listener

typedef struct fsl_msg_listener fsl_msg_listener

Definition at line 809 of file core.h.

◆ fsl_rc_e

typedef enum fsl_rc_e fsl_rc_e

Definition at line 502 of file core.h.

◆ fsl_satype_e

typedef enum fsl_satype_e fsl_satype_e

Definition at line 1707 of file core.h.

◆ fsl_see_key_f

typedef int(* fsl_see_key_f) (void *pState, const char *zDbFile, fsl_buffer *pOut, int *keyType)

EXPERIMENTAL and subject to change.

But it seems to do its job reasonably well.

A callback type for fetching an encryption key for use with the SQLite Encryption Extension API. This is only for use in SEE-capable builds.

pState is the pointer provided by the client for use here (typically via fsl_cx_config::see::pState). It is opaque to the library, intended solely for the SEE client's use.

zDbFile is the NUL-terminated name of the db for which the key is being requested.

If a key is available, it must be appended to pOut using fsl_buffer_append() (or equivalent).

On success, it must return 0. Any non-0 result value is treated by the library as failure to open the db, with one exception: FSL_RC_UNSUPPORTED indicates that decryption is not supported but opening of a database will not fail fatally for this result. Instead, if the db really is encrypted, it will fail later when the db is first used.

If it populates pOut then it must set *keyType to one of the entries from the fsl_see_keytype_e enum, indicating the type of the key.

If the implementation has no key to provide for the db, but does not know that to be an error, it should simply return 0 and not add any bytes to pOut. It need not set *keyType in this case, as the library guarantees that it will initially have the value FSL_SEE_KEYTYPE_NONE.

The library does not cache the results of these calls and may need to call this multiple times for the same database during the life of a single context. (Ordinarily, though, the SCM databases are opened a single time and left that way.)

A recommended convention, derived from fossil(1), is to name encrypted repositories with a suffix of ".efossil". Implementations of this callback could use such a convention to determine whether or not a key is necessary for the db (something this library cannot do on its own).

Definition at line 657 of file core.h.

◆ fsl_see_keytype_e

Definition at line 609 of file core.h.

◆ fsl_stmt

typedef struct fsl_stmt fsl_stmt

Definition at line 96 of file core.h.

◆ fsl_xfer

typedef struct fsl__xfer fsl_xfer

A "transfer context" type used by many of the sync transfer APIs.

This type is opaque to client code.

Definition at line 732 of file core.h.

Enumeration Type Documentation

◆ fsl_buildinfo_e

Flags for use with fsl_buildinfo().

Enumerator
FSL_BUILDINFO_VERSION 
FSL_BUILDINFO_VERSION_HASH 
FSL_BUILDINFO_VERSION_TIMESTAMP 
FSL_BUILDINFO_CONFIG_TIMESTAMP 

Definition at line 2112 of file core.h.

◆ fsl_configset_e

Bitmask values specifying "configuration sets".

The values in this enum come directly from fossil(1), but they are not part of the db structure, so may be changed over time.

It seems very unlikely that these will ever be used at the level of this library. They are a "porting artifact" and retained for the time being, but will very likely be removed.

Enumerator
FSL_CONFSET_NONE 

Sentinel value.

FSL_CONFIGSET_CSS 

Style sheet only.

FSL_CONFIGSET_SKIN 

WWW interface appearance.

FSL_CONFIGSET_TKT 

Ticket configuration.

FSL_CONFIGSET_PROJ 

Project name.

FSL_CONFIGSET_SHUN 

Shun settings.

FSL_CONFIGSET_USER 

The USER table.

FSL_CONFIGSET_ADDR 

The CONCEALED table.

FSL_CONFIGSET_XFER 

Transfer configuration.

FSL_CONFIGSET_ALL 

Everything.

FSL_CONFIGSET_OVERWRITE 

Causes overwrite instead of merge.

FSL_CONFIGSET_OLDFORMAT 

Use the legacy format.

Definition at line 197 of file core.h.

◆ fsl_cx_flags_e

Runtime-configurable flags for a fsl_cx instance.

See also
fsl_cx_flag_set()
fsl_cx_flags_get()
Enumerator
FSL_CX_F_NONE 

The "no flags" value.

Guaranteed to be 0 and this is the only entry in this enum which is guaranteed to have a stable value.

FSL_CX_F_CALC_R_CARD 

Tells us whether or not we want to calculate R-cards by default.

Historically they were initially required but eventually made optional due largely to their memory costs.

FSL_CX_F_SKIP_UNKNOWN_CROSSLINKS 

When encounting artifact types in the crosslinking phase which the library does not currently support crosslinking for, skip over them instead of generating an error.

For day-to-day use this is, perhaps counter-intuitively, generally desirable.

As of 2021-12-04, crosslinking of all core fossil artifact types is supported, so this flag is effectively a no-op until/unless a new artifact type is added to fossil.

FSL_CX_F_ALLOW_WINDOWS_RESERVED_NAMES 

By default, fsl_reserved_fn_check() will fail if the given filename is reserved on Windows platforms because such filenames cannot be checked out on Windows.

This flag removes that limitation. It should only be used, if at all, for repositories which will never be used on Windows.

FSL_CX_F_MANIFEST_CACHE 

If on (the default) then an internal cache will be used for artifact loading to speed up operations which do lots of that.

Disabling this will save memory but may hurt performance for certain operations.

FSL_CX_F_BLOB_CACHE 

If on (the default) then fsl_content_get() will use an internal cache to speed up loading of repeatedly-fetched artifacts.

Disabling this can be costly.

FSL_CX_F_IS_OPENING_CKOUT 

Internal use only to prevent duplicate initialization of some bits.

FSL_CX_F_DEFAULTS 

Default flags for all fsl_cx instances.

Definition at line 231 of file core.h.

◆ fsl_dbrole_e

This enum defines type ID tags with which the API tags fsl_db instances so that the library can figure out which DB is which.

This is primarily important for certain queries, which need to know whether they are accessing the repo or config db, for example.

As of 2021-10, the fossil context db model has long been, and is very, very likely to remain:

  • When a context starts up, it creates a temporary db for use as its main db.
  • When a repo or checkout db are opened, they are ATTACHed to the main db with the names repo resp. ckout. (Note that those differ from the names fossil(1) uses: repository and localdb.)

A large amount of the library code is written as if the library (roughly) followed fossil's model of using separate sqlite3 objects, even though it does not do so. The reason is historical: when starting the libfossil port, it was clear that fossil's internal connection juggling was going to be painful for the library, so the internal API was shaped to permit two separate approaches:

Approach 1: the first db which gets opened (repo, checkout, or config) becomes the main db and all others get attached using their API-standard alias. That is mostly what fossil does, but it leads to fossil sometimes having to "swap" connections by closing the db and re-opening it so that the db names are in a state which fits the current use. That model led to the creation of this enum. However, it also leads to unpredictable database names for purposes of queries, as we're never sure (at the client level or higher library-level APIs) which db is main and which has an alias.

Approach 2: open a temp (or in-memory) db and attach all of the others to that using well-defined names.

The latter has proven to work well enough that returning to the first approach seems extremely unlikely at this point. Thus some newer library-level code behaves as if the latter model is in effect (which it is).

The long and the short of the above diversion is that APIs like fsl_cx_db_repo() and fsl_cx_db_ckout() will always return the same database handle, but they can tell whether a given role has been attached or not and will fail in their documented ways when the role's corresponding database has not yet been attached. e.g. fsl_cx_db_repo() will return NULL if a repo database is not attached.

See also
fsl_db_role_name()
fsl_cx_db_file_for_role()
Enumerator
FSL_DBROLE_NONE 

Sentinel "no role" value.

FSL_DBROLE_CONFIG 

The global (per user) config db.

Analog to fossil's "configdb".

FSL_DBROLE_REPO 

The repository db.

Analog to fossil's "repository".

FSL_DBROLE_CKOUT 

The checkout db.

Analog to fossil's "localdb".

FSL_DBROLE_MAIN 

Analog to fossil's "main", which is an alias for the first db opened.

In this API a fsl_cx instance has a temporary/transient main db opened even if it does not have a repository, checkout, or config db opened.

FSL_DBROLE_TEMP 

Refers to the "temp" database.

This is only used by a very few APIs and is outright invalid for most.

Definition at line 156 of file core.h.

◆ fsl_fileperm_e

File permissions flags supported by fossil manifests.

Their numeric values are a hard-coded part of the Fossil architecture and must not be changed. Note that these refer to manifest-level permissions and not filesystem-level permissions (though they translate to/from filesystem-level meanings at some point).

Enumerator
FSL_FILE_PERM_REGULAR 

Indicates a regular, writable file.

FSL_FILE_PERM_EXE 

Indicates a regular file with the executable bit set.

FSL_FILE_PERM_LINK 

Indicates a symlink.

Note that symlinks do not have the executable bit set separately on Unix systems. Also note that libfossil does NOT YET IMPLEMENT symlink support like fossil(1) does - it currently treats symlinks (mostly) as Unix treats symlinks.

Definition at line 511 of file core.h.

◆ fsl_glob_category_e

A collection of bitmaskable values indicating categories of fossil-standard glob sets.

These correspond to the following configurable settings:

ignore-glob, crnl-glob, binary-glob

Enumerator
FSL_GLOBS_INVALID 

Sentinel entry.

FSL_GLOBS_IGNORE 

Corresponds to the ignore-glob config setting.

FSL_GLOBS_CRNL 

Corresponds to the crnl-glob config setting.

FSL_GLOBS_BINARY 

Corresponds to the binary-glob config setting.

FSL_GLOBS_ANY 

A superset of all config-level glob categories.

Definition at line 1763 of file core.h.

◆ fsl_hashpolicy_e

List of hash policy values.

New repositories should generally use only SHA3 hashes, but older repos may contain SHA1 hashes (perhaps only SHA1), so we have to support those. Repositories may contain a mix of hash types.

Maintenance ACHTUNG: this enum's values must align with those from fossil(1) because their integer values are used in the repo.config table.

Enumerator
FSL_HPOLICY_SHA1 

Use only SHA1 hashes.

FSL_HPOLICY_AUTO 

Accept SHA1 hashes but auto-promote to SHA3.

FSL_HPOLICY_SHA3 

Use SHA3 hashes.

FSL_HPOLICY_SHA3_ONLY 

Use SHA3 hashes exclusively.

FSL_HPOLICY_SHUN_SHA1 

With this policy, fsl_uuid_is_shunned() will always return true for SHA1 hashes, making it "impossible" to get SHA1-hashed content into the repository (for a given value of "impossible").

Definition at line 304 of file core.h.

◆ fsl_msg_e

enum fsl_msg_e

Message type flags Indicators for use with fsl_sc::status, fsl_xfer_emit(), and friends.

Enumerator
fsl_msg_map 

Definition at line 705 of file core.h.

◆ fsl_rc_e

enum fsl_rc_e

Most functions in this library which return an int return result codes from the fsl_rc_e enum.

None of these entries are guaranteed to have a specific value across library versions except for FSL_RC_OK, which is guaranteed to always be 0 (and the API guarantees that no other code shall have a value of zero).

The only reasons numbers are hard-coded to the values is to simplify debugging during development. Clients may use fsl_rc_cstr() to get some human-readable (or programmer-readable) form for any given value in this enum.

Enumerator
fsl_rc_e_map 

Definition at line 495 of file core.h.

◆ fsl_satype_e

An enumeration of the types of structural artifacts used by Fossil.

The numeric values of all entries before FSL_SATYPE_count, with the exception of FSL_SATYPE_INVALID, are a hard-coded part of the Fossil db architecture and must never be changed. Any after FSL_SATYPE_count are libfossil extensions.

Enumerator
fsl_satype_e_map 
FSL_SATYPE_EVENT 
Deprecated
Historical (deprecated) name for FSL_SATYPE_TECHNOTE.
FSL_SATYPE_BRANCH_START 

A pseudo-type for use with fsl_sym_to_rid() which changes the behavior of checkin lookups to return the RID of the start of the branch rather than the tip, with the caveat that the results are unspecified if the given symbolic name refers to multiple branches.

fsl_satype_event_cstr() returns the same as FSL_SATYPE_CHECKIN for this entry.

This entry IS NOT VALID for most APIs which require a fsl_satype_e value.

Definition at line 1676 of file core.h.

◆ fsl_see_keytype_e

SQLite Encryption Extension (SEE) key types for use with fsl_see_key_f().

Each of these options corresponds to one of the key-entry modes supported by SEE via pragmas, e.g. PRAGMA key, PRAGMA textkey, and PRAGMA hexkey.

Enumerator
FSL_SEE_KEYTYPE_NONE 

Sentinel value indicating "not an SEE key".

FSL_SEE_KEYTYPE_PLAIN 

Corresponses to (PRAGMA key).

FSL_SEE_KEYTYPE_BINARY 

Corresponses to (PRAGMA hexkey).

Binary data to be hex-encoded by the library.

FSL_SEE_KEYTYPE_HEXKEY 

Corresponses to (PRAGMA hexkey).

Encoded by the client as a series of hex digits.

FSL_SEE_KEYTYPE_TEXTKEY 

Corresponses to (PRAGMA textkey).

Definition at line 595 of file core.h.

Function Documentation

◆ fsl_buildinfo()

FSL_EXPORT char const * fsl_buildinfo ( enum fsl_buildinfo_e what)

Fetches the piece of library-level build information specified by its argument.

If no such info is available, NULL is returned.

References FSL_BUILDINFO_CONFIG_TIMESTAMP, FSL_BUILDINFO_VERSION, FSL_BUILDINFO_VERSION_HASH, and FSL_BUILDINFO_VERSION_TIMESTAMP.

◆ fsl_close_dbs()

FSL_EXPORT int fsl_close_dbs ( fsl_cx * f)

Shorthand for calling both fsl_close_scm_dbs() and, if it succeeds, fsl_config_close().

Returns the result of the former if it fails, else returns the result of the latter.

References FSL_EXPORT.

◆ fsl_close_scm_dbs()

FSL_EXPORT int fsl_close_scm_dbs ( fsl_cx * f)

Closes any opened repository and/or checkout database(s) opened by f, freeing any associated resources and clearing out f's current user name.

Returns 0 on success or if no dbs are opened (noting that this does NOT close the separate global configuration db: see fsl_config_close()). Returns FSL_RC_MISUSE if the opened SCM db(s) have an opened transaction, but that behaviour may change in the future to force a rollback and close the database(s).

◆ fsl_config_close()

FSL_EXPORT int fsl_config_close ( fsl_cx * f)

Closes/detaches the database connection opened by fsl_config_open().

If the config db is not opened, this is a harmless no-op. Note that it does not propagate db-closing errors because there is no sensible recovery strategy from such cases.

This operation only fails if the config db is opened and has an active transaction, in which case f's error state is updated to reflect that cause of the error.

ACHTUNG: it is imperative that any prepared statements compiled against the config db be finalized before closing the db. Any statements prepared using fsl_db_prepare_cached() against the config db will be automatically finalized by the closing process.

Potential TODO: if a transaction is pending, force a rollback and close the db anyway. If we do that, this function will change to return void.

See also
fsl_cx_db_config()
fsl_config_open()

References FSL_EXPORT.

◆ fsl_config_open()

FSL_EXPORT int fsl_config_open ( fsl_cx * f,
char const * dbName )

Opens the given database file as f's configuration database.

If f already has a config database opened then:

1) If passed a NULL dbName or dbName is an empty string then this function returns 0 without side-effects.

2) If passed a non-NULL/non-empty dbName, any existing config db is closed before opening the named one. The database is created and populated with an initial schema if needed.

If dbName is NULL or empty then it uses a default db name, "probably" under the user's home directory (see fsl_config_global_preferred_name()). To get the name of the database after it has been opened/attached, use fsl_cx_db_file_config().

Results are undefined if f is NULL or not properly initialized.

See also
fsl_cx_db_config()
fsl_config_close()
fsl_config_global_preferred_name()

References FSL_EXPORT.

◆ fsl_cx_allows_symlinks()

FSL_EXPORT bool fsl_cx_allows_symlinks ( fsl_cx * f,
bool forceRecheck )

Returns true if f has the "allow-symlinks" repo-level configuration option set to a truthy value, else returns false.

That setting is cached to avoid performing a db lookup on each call, but passing true for the second argument causes the repository to be re-checked.

References FSL_EXPORT.

◆ fsl_cx_case_sensitive_set()

FSL_EXPORT void fsl_cx_case_sensitive_set ( fsl_cx * f,
bool caseSensitive )

Sets the case-sensitivity flag for f to the given value.

This flag alters how some filename-search/comparison operations operate. This option is only intended to have an effect on plaforms with case-insensitive filesystems.

Note that this does not save the option in the config database (repo-level "case-sensitive" boolean config option). It arguably should, and this behavior may change in the future.

See also
fsl_cx_is_case_sensitive()

References FSL_EXPORT.

◆ fsl_cx_ckout_dir_name()

FSL_EXPORT char const * fsl_cx_ckout_dir_name ( fsl_cx const * f,
fsl_size_t * len )

If f has an opened checkout db (from fsl_ckout_open_dir()) then this function returns the directory part of the path for the checkout, including (for historical and internal convenience reasons) a trailing slash.

The returned bytes are valid until that db connection is closed. If len is not NULL then *len is (on success) assigned to the length of the returned string, in bytes. The string is NUL-terminated, so fetching the length by passing a non-NULL 2nd parameter is optional.

Returns NULL if !f or f has no checkout opened.

See also
fsl_ckout_open_dir()
fsl_ckout_db_file()

References FSL_EXPORT.

◆ fsl_cx_confirm()

FSL_EXPORT int fsl_cx_confirm ( fsl_cx * f,
fsl_confirm_detail const * detail,
fsl_confirm_response * outAnswer )

If fsl_cx_confirmer() was used to install a confirmer callback in f then this routine calls that confirmer and returns its result code and its answer via *outAnswer.

If no confirmer is currently installed, it responds with default answers, depending on the eventId:

  • FSL_CEVENT_OVERWRITE_MOD_FILE: FSL_CRESPONSE_NEVER
  • FSL_CEVENT_OVERWRITE_UNMGD_FILE: FSL_CRESPONSE_NEVER
  • FSL_CEVENT_RM_MOD_UNMGD_FILE: FSL_CRESPONSE_NEVER
  • FSL_CEVENT_MULTIPLE_VERSIONS: FSL_CRESPONSE_CANCEL

Those are not 100% set in stone and are up for reconsideration.

If a confirmer has been installed, this function does not modify outAnswer->response if the installed confirmer does not. Thus routines should set it to some acceptable default/sentinel value before calling this, to account for callbacks which ignore the given detail->eventId.

If a confirmer callback responds with FSL_CRESPONSE_ALWAYS or FSL_CRESPONSE_NEVER, the code which is requesting confirmation must honor that by NOT calling the callback again for the current processing step of that eventId. e.g. if a loop asks for confirmation of FSL_CEVENT_RM_MOD_FILE and any response is one of the above, that one loop must not ask for confirmation again, and must instead accept that response for future queries within the same logical library operation (e.g. one checkout-update cycle). This is particularly important for applications which interactively present the question to the user for confirmation so that users have a way to not get spammed with a confirmation message showing up for each and every one of an arbitrary number of confirmations.

See also
fsl_confirm_callback_f
fsl_cx_confirmer()

References FSL_EXPORT.

◆ fsl_cx_confirmer()

FSL_EXPORT void fsl_cx_confirmer ( fsl_cx * f,
fsl_confirmer const * newConfirmer,
fsl_confirmer * prevConfirmer )

Installs or (if f is NULL) uninstalls a confirmation callback for use by operations on f which require user confirmation.

The exact implications of not installing a confirmer depend on the operation in question: see fsl_cx_confirm().

The 2nd argument bitwise copied into f's internal confirmer object. If the 2nd argument is NULL, f's confirmer is cleared, which will cause fsl_cx_confirm() to use certain default responses (see that function for details).

If the final argument is not NULL then the previous confirmer is bitwise copied to it.

See also
fsl_confirm_callback_f
fsl_cx_confirm()
fsl_cx_confirmer_get()

◆ fsl_cx_confirmer_get()

FSL_EXPORT void fsl_cx_confirmer_get ( fsl_cx const * f,
fsl_confirmer * dest )

Stores a bitwise copy of f's current confirmer object into *dest.

Can be used to save the confirmer before temporarily swapping it out.

See also
fsl_cx_confirmer()

References FSL_EXPORT.

◆ fsl_cx_db()

FSL_EXPORT fsl_db * fsl_cx_db ( fsl_cx * f)

Returns a handle to f's main db (which may or may not have any relationship to the repo/checkout/config databases - that's unspecified!), or NULL if f has no opened repo or checkout db.

The returned object is owned by f and the client MUST NOT do any of the following:

  • Close the db handle.
  • Use transactions without using fsl_db_txn_begin() and friends.
  • Fiddle with the handle's internals. Doing so might confuse its owning context.

Clients MAY add new user-defined functions, use the handle with fsl_db_prepare(), and other "mundane" db-related tasks.

Note that the global config db uses a separate db handle accessible via fsl_cx_db_config().

See also
fsl_cx_db_repo()
fsl_cx_db_ckout()
fsl_cx_db_config()

References FSL_EXPORT.

◆ fsl_cx_db_ckout()

FSL_EXPORT fsl_db * fsl_cx_db_ckout ( fsl_cx * f)

If f is not NULL and has had a checkout opened via fsl_ckout_open_dir() or similar, this returns a pointer to that database, else it returns NULL.

See also
fsl_cx_db()

References FSL_EXPORT.

◆ fsl_cx_db_config()

FSL_EXPORT fsl_db * fsl_cx_db_config ( fsl_cx * f)

If f has an opened configuration db then its handle is returned, else 0 is returned.

For API consistency's sake, the db handle's "MAIN" name is aliased to fsl_db_role_name(FSL_DBROLE_CONFIG).

See also
fsl_config_open()
fsl_config_close()

References FSL_EXPORT.

◆ fsl_cx_db_file_ckout()

FSL_EXPORT char const * fsl_cx_db_file_ckout ( fsl_cx const * f,
fsl_size_t * len )

If f is not NULL and has a checkout db opened then this function returns its name.

The bytes are valid until that checkout db connection is closed. If len is not NULL then *len is (on success) assigned to the length of the returned string, in bytes. The string is NUL-terminated, so fetching the length (by passing a non-NULL 2nd parameter) is optional.

Returns NULL if !f or f has no checkout opened.

See also
fsl_ckout_open_dir()
fsl_cx_ckout_dir_name()
fsl_cx_db_file_config()
fsl_cx_db_file_repo()

References FSL_EXPORT.

◆ fsl_cx_db_file_config()

FSL_EXPORT char const * fsl_cx_db_file_config ( fsl_cx const * f,
fsl_size_t * len )

Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened config db, if any.

See also
fsl_cx_db_file_ckout()
fsl_cx_db_file_repo()

References FSL_EXPORT.

◆ fsl_cx_db_file_for_role()

FSL_EXPORT char const * fsl_cx_db_file_for_role ( fsl_cx const * f,
fsl_dbrole_e r,
fsl_size_t * len )

Similar to fsl_cx_db_file_ckout() and friends except that it applies to db file implied by the specified role (2nd parameter).

If no such role is opened, or the role is invalid, NULL is returned.

Note that the role of FSL_DBROLE_TEMP is invalid here.

References FSL_EXPORT.

◆ fsl_cx_db_file_repo()

FSL_EXPORT char const * fsl_cx_db_file_repo ( fsl_cx const * f,
fsl_size_t * len )

Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened repository db, if any.

See also
fsl_cx_db_file_ckout()
fsl_cx_db_file_config()

References FSL_EXPORT.

◆ fsl_cx_db_repo()

FSL_EXPORT fsl_db * fsl_cx_db_repo ( fsl_cx * f)

If f is not NULL and has had its repo opened via fsl_repo_open(), fsl_ckout_open_dir(), or similar, this returns a pointer to that database, else it returns NULL.

See also
fsl_cx_db()

References FSL_EXPORT.

◆ fsl_cx_emit()

FSL_EXPORT int fsl_cx_emit ( fsl_cx *const f,
fsl_msg_e type,
void const * p )

If f has a fsl_msg listener, a fsl_msg composed from the given type and payload is passed to the the listener and its result is returned, else this is a no-op and 0 is returned.

References FSL_EXPORT.

◆ fsl_cx_emitf()

int fsl_cx_emitf ( fsl_cx * f,
fsl_msg_e type,
char const * zFmt,
... )

Elipsis counterpart of fsl_cx_emitfv().

◆ fsl_cx_emitfv()

int fsl_cx_emitfv ( fsl_cx * f,
fsl_msg_e type,
char const * zFmt,
va_list args )

va_list counterpart of fsl_cx_emit() which emits a fsl_appendf()-formatted message as a string or a buffer, depending on the message type.

It may (and does) fatally fail if passed a message type for which (type & FSL_MSG_mask_type) is not one of FSL_MSG_type_string or FSL_MSG_type_buffer.

◆ fsl_cx_err_e()

FSL_EXPORT fsl_error * fsl_cx_err_e ( fsl_cx * f)

Non-const counterpart of fsl_cx_err_ec().

References FSL_EXPORT.

◆ fsl_cx_err_ec()

FSL_EXPORT fsl_error const * fsl_cx_err_ec ( fsl_cx const * f)

Returns f's error object.

It is owned by f, and its address is stable as long as f is valid. It's provided as a semi-formal way for not-quite-core code to get access to f->error without having to reach into f directly. It should only be preferred over fsl_cx_err_set()/get() when an arbitrary fsl_error object is needed for an API (like fsl_buffer_escape_arg()) and we know we'd like to unconditionally propagate that error via f's error state. In such cases, using this object can avoid a second allocation to copy the error message.

References FSL_EXPORT.

◆ fsl_cx_err_get()

FSL_EXPORT int fsl_cx_err_get ( fsl_cx * f,
char const ** str,
fsl_size_t * len )

Fetches the error state from f.

See fsl_error_get() for the semantics of the parameters and return value.

References FSL_EXPORT.

◆ fsl_cx_err_report()

FSL_EXPORT int fsl_cx_err_report ( fsl_cx * f,
bool addNewline )

If f has error state then it outputs its error state to its output channel and returns the result of fsl_output().

Returns 0 if f has no error state our output of the state succeeds. If addNewline is true then it adds a trailing newline to the output, else it does not.

This is intended for testing and debugging only, and not as an error reporting mechanism for a full-fledged application.

References FSL_EXPORT.

◆ fsl_cx_err_reset()

FSL_EXPORT void fsl_cx_err_reset ( fsl_cx * f)

Resets's f's error state, basically equivalent to fsl_cx_err_set(f,0,NULL).

This may be necessary for apps if they rely on looking at fsl_cx_err_get() at the end of their app/routine, because error state survives until it is cleared, even if the error held there was caught and recovered. This function might keep error string memory around for re-use later on.

This does NOT reset the fsl_cx_interrupted() flag!

References FSL_EXPORT.

◆ fsl_cx_err_set()

FSL_EXPORT int fsl_cx_err_set ( fsl_cx * f,
int code,
char const * fmt,
... )

Sets the Fossil error state to the given error code and fsl_appendf()-style format string/arguments.

On success it returns the code parameter. It does not return 0 unless code is 0, and if it returns a value other than code then something went seriously wrong (e.g. allocation error: FSL_RC_OOM) or the arguments were invalid: !f results in FSL_RC_MISUSE.

If !fmt then fsl_rc_cstr(code) is used to create the error string.

As a special case, if code is FSL_RC_OOM, no error string is allocated (because it would likely fail, assuming the OOM is real).

As a special case, if code is 0 (the non-error value) then fmt is ignored and any error state is cleared.

References FSL_EXPORT.

◆ fsl_cx_err_set_e()

FSL_EXPORT int fsl_cx_err_set_e ( fsl_cx * f,
fsl_error * err )

Replaces f's error state with the contents of err, taking over any memory owned by err (but not err itself).

Returns the new error state code (the value of err->code before this call) on success. The only error case is if !f (FSL_RC_MISUSE). If err is NULL then f's error state is cleared and 0 is returned. err's error state is cleared by this call.

References FSL_EXPORT.

◆ fsl_cx_err_setv()

FSL_EXPORT int fsl_cx_err_setv ( fsl_cx * f,
int code,
char const * fmt,
va_list args )

va_list counterpart to fsl_cx_err_set().

References FSL_EXPORT.

◆ fsl_cx_exec()

FSL_EXPORT int fsl_cx_exec ( fsl_cx * f,
char const * sql,
... )

Convenience form of fsl_db_exec() which uses f's main db handle.

Returns 0 on success. On statement preparation or execution error, the db's error state is uplifted into f and that result is returned. Results are undefined if f or sql are NULL or otherwise invalid.

References FSL_EXPORT.

◆ fsl_cx_exec_multi()

FSL_EXPORT int fsl_cx_exec_multi ( fsl_cx * f,
char const * sql,
... )

The fsl_db_exec_multi() counterpart of fsl_cx_exec().

Results are undefined if f or sql are NULL or otherwise invalid.

References FSL_EXPORT.

◆ fsl_cx_exec_multiv()

FSL_EXPORT int fsl_cx_exec_multiv ( fsl_cx * f,
char const * sql,
va_list args )

va_list counterpart of fsl_cx_exec_multi().

References FSL_EXPORT.

◆ fsl_cx_execv()

FSL_EXPORT int fsl_cx_execv ( fsl_cx * f,
char const * sql,
va_list args )

va_list counterpart of fsl_cx_exec().

References FSL_EXPORT.

◆ fsl_cx_filename_cmp()

FSL_EXPORT int fsl_cx_filename_cmp ( fsl_cx * f,
char const * z1,
char const * z2 )

Compares two strings, represumably filenames, using either fsl_strcmp() or fsl_stricmp(), depending on f's filename case-sensitivity setting.

References FSL_EXPORT.

◆ fsl_cx_filename_collation()

FSL_EXPORT char const * fsl_cx_filename_collation ( fsl_cx const * f)

If f is set to use case-sensitive filename handling, returns a pointer to an empty string, otherwise a pointer to the string "COLLATE nocase" is returned.

Results are undefined if f is NULL. The returned bytes are static.

See also
fsl_cx_case_sensitive_set()
fsl_cx_is_case_sensitive()

References FSL_EXPORT.

◆ fsl_cx_finalize()

FSL_EXPORT void fsl_cx_finalize ( fsl_cx * f)

Frees all memory associated with f, which must have been allocated/initialized using fsl_cx_malloc(), fsl_cx_init(), or equivalent, or created on the stack and properly initialized (via fsl_cx_init() or copy-constructed from fsl_cx_empty).

If it was allocated using fsl_cx_malloc(), this function frees f, else the memory is owned by someone else and it is not freed.

This function triggers any finializers set for f's client state or output channel.

This is a no-op if !f and is effectively a no-op if f has no state to destruct.

References FSL_EXPORT.

◆ fsl_cx_flag_set()

FSL_EXPORT fsl_flag32_t fsl_cx_flag_set ( fsl_cx * f,
fsl_flag32_t flags,
bool enable )

Sets or unsets one or more option flags on the given fossil context.

flags is the flag or a bitmask of flags to set (from the fsl_cx_flags_e enum). If enable is true the flag(s) is (are) set, else it (they) is (are) unset. Returns the previous set of flags (that is, the state they were in before this call was made).

See also
fsl_cx_flags_get()

References FSL_EXPORT.

◆ fsl_cx_flags_get()

FSL_EXPORT fsl_flag32_t fsl_cx_flags_get ( fsl_cx const * f)

Returns f's flags.

See also
fsl_cx_flag_set()

References FSL_EXPORT.

◆ fsl_cx_format()

FSL_EXPORT int fsl_cx_format ( fsl_cx * f,
fsl_output_f out,
void * outState,
char const * zFmt,
... )

The elipsis counterpart of fsl_cx_formatv().

References FSL_EXPORT.

◆ fsl_cx_format_buffer()

FSL_EXPORT int fsl_cx_format_buffer ( fsl_cx * f,
fsl_buffer * tgt,
char const * zFmt,
... )

Convenience formof fsl_cx_format() which appends the formatted output to tgt.

References FSL_EXPORT.

◆ fsl_cx_format_FILE()

FSL_EXPORT int fsl_cx_format_FILE ( fsl_cx * f,
FILE * tgt,
char const * zFmt,
... )

Convenience formof fsl_cx_format() which appends the formatted output to tgt.

References FSL_EXPORT.

◆ fsl_cx_formatv()

FSL_EXPORT int fsl_cx_formatv ( fsl_cx * f,
fsl_output_f out,
void * outState,
char const * zFmt,
va_list args )

A proxy for fsl_appendfv() which pre-processes the format-specifier string (zFmt) to replace certain placeholders with information about the fsl_cx object.

After doing so, it passes on the adjusted zFmt to fsl_appendfv().

Placeholders are in the form {{X}}, where X is one of the words listed below. Any unknown X will cause the whole {{X}} to be emitted as-is.

Known X values (with quotes for clarity, but the quotes are not part of X):

  • "chkout.dir": gets replaced with the path to the current checkout directory, without a trailing slash.
  • "chkout.dir/": as for ckout-dir but with a trailing slash.
  • "repo.db": gets replaced with the path to the current repository database.
  • "user.name": gets replaced with fsl_cx_user_guess().

File and directory names which are empty are emitted as such.

The parser is not robust enough to attempt to recover from failures related to the "{{" and "}}" parts, and malformed tags may cause it to skip expansion on the remaining parts of the input (it will be passed on as-is, warts and all).

Returns 0 on success. Returns FSL_RC_OOM if allocation of the formatting buffer fails. Else returns the value of the fsl_appendfv() call.

References FSL_EXPORT.

◆ fsl_cx_getcwd()

FSL_EXPORT int fsl_cx_getcwd ( fsl_cx * f,
fsl_buffer * pOut )

Works like fsl_getcwd() but updates f's error state on error and appends the current directory's name to the given buffer.

Returns 0 on success.

References FSL_EXPORT.

◆ fsl_cx_glob_list()

FSL_EXPORT int fsl_cx_glob_list ( fsl_cx * f,
fsl_glob_category_e gtype,
fsl_list ** tgt,
bool forceReload )

Fetches f's glob list of the given category.

If forceReload is true then the context will check whether the list has had any content added to its source since it was initially loaded.

On success, returns 0 and assigns *tgt to the list (noting that it may be empty). On error *tgt is not modified.

Returns FSL_RC_RANGE if gtype is not one of FSL_GLOBS_IGNORE, FSL_GLOBS_CRNL, or FSL_GLOBS_BINARY. Returns FSL_RC_OOM if there is an allocation error during list reloading. May return lower-level result codes from the filesystem or db layer if loading a given list fails.

References FSL_EXPORT.

◆ fsl_cx_glob_matches()

FSL_EXPORT char const * fsl_cx_glob_matches ( fsl_cx * f,
int gtype,
char const * str )

Checks one or more of f's configurable glob lists to see if str matches one of them.

If it finds a match, it returns a pointer to the matching glob (as per fsl_glob_list_matches()), the bytes of which are owned by f and may be invalidated via modification or reloading of the underlying glob list. In generally the return value can be used as a boolean - clients generally do not need to know exactly which glob matched.

gtype specifies the glob list(s) to check in the form of a bitmask of fsl_glob_category_e values. Note that the order of the lists is unspecified, so if that is important for you then be sure that gtype only specifies one glob list (e.g. FSL_GLOBS_IGNORE) and call it again (e.g. passing FSL_GLOBS_BINARY) if you need to distinguish between those two cases.

str must be a non-NULL, non-empty empty string.

Returns NULL !str, !*str, gtype does not specify any known glob list(s), or no glob match is found.

Performance is, abstractly speaking, horrible, because we're comparing arbitrarily long lists of glob patterns against an arbitrary string. That said, it's fast enough for our purposes.

References FSL_EXPORT.

◆ fsl_cx_has_ckout()

FSL_EXPORT bool fsl_cx_has_ckout ( fsl_cx const * f)

Returns true if the given context has a checkout opened, else false.

See also
fsl_needs_ckout()

References FSL_EXPORT.

◆ fsl_cx_hash_buffer()

FSL_EXPORT int fsl_cx_hash_buffer ( const fsl_cx * f,
bool useAlternate,
fsl_buffer const * pIn,
fsl_buffer * pOut )

Hashes all of pIn, appending the hash to pOut.

Returns 0 on succes, FSL_RC_OOM if allocation of space in pOut fails. The hash algorithm used depends on the given fossil context's current hash policy and the value of the 2nd argument.

If the 2nd argument is false, the hash is performed per the first argument's current hash policy. If the 2nd argument is true, the hash policy is effectively inverted. e.g. if the context prefers SHA3 hashes, the alternate form will use SHA1.

Returns FSL_RC_UNSUPPORTED, without updating f's error state, if the hash is not possible due to conflicting values for the policy and its alternate. e.g. a context with policy FSL_HPOLICY_SHA3_ONLY will refuse to apply an SHA1 hash. Whether or not this result can be ignored is context-dependent, but it normally can be. This result is only possible when the 2nd argument is true.

Returns 0 on success.

◆ fsl_cx_hash_filename()

FSL_EXPORT int fsl_cx_hash_filename ( fsl_cx * f,
bool useAlternate,
const char * zFilename,
fsl_buffer * pOut )

The file counterpart of fsl_cx_hash_buffer(), behaving exactly the same except that its data source is a file and it may return various error codes from fsl_buffer_fill_from_filename().

Note that the contents of the file, not its name, are hashed.

References FSL_EXPORT.

◆ fsl_cx_hash_policy_get()

FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_get ( fsl_cx const * f)

Returns f's current hash policy.

References FSL_EXPORT.

◆ fsl_cx_hash_policy_set()

FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_set ( fsl_cx * f,
fsl_hashpolicy_e p )

Sets f's hash policy and returns the previous value.

If f has a repository db open then the setting is stored there and any error in setting it is placed into f's error state but otherwise ignored for purposes of this call.

If p is FSL_HPOLICY_AUTO and the current repository contains any SHA3-format hashes, the policy is interpreted as FSL_HPOLICY_SHA3.

This value is a suggestion, and may be trumped by various conditions, in particular in repositories containing older (SHA1) hashes.

◆ fsl_cx_init()

FSL_EXPORT int fsl_cx_init ( fsl_cx ** tgt,
fsl_cx_config const * param )

Initializes a fsl_cx instance.

tgt must be a pointer to NULL, e.g.:

fsl_cxt * f = NULL; // NULL is important - see below
int rc = fsl_cx_init( &f, NULL );
FSL_EXPORT int fsl_cx_init(fsl_cx **tgt, fsl_cx_config const *param)
Initializes a fsl_cx instance.

It is very important that f be initialized to NULL or to an instance which has been properly allocated and empty-initialized (e.g. via fsl_cx_malloc()). If *tgt is NULL, this routine allocates the context, else it assumes the caller did. If f points to unitialized memory then results are undefined.

If the second parameter is NULL then default implementations are used for the context's output routine and other options. If it is not NULL then param->allocator and param->output must be initialized properly before calling this function. The contents of param are bitwise copied by this function and ownership of the returned value is transfered to *tgt in all cases except one:

If passed a pointer to a NULL context and this function cannot allocate it, it returns FSL_RC_OOM and does not modify *tgt. In this one case, ownership of the context is not changed (as there's nothing to change!). On any other result (including errors), ownership of param's contents are transfered to *tgt and the client is responsible for passing *tgt ot fsl_cxt_finalize() when he is done with it. Note that (like in sqlite3), *tgt may be valid memory even if this function fails, and the caller must pass it to fsl_cx_finalize() whether or not this function succeeds unless it fails at the initial OOM (which the client can check by seeing if (*tgt) is NULL, but only if he set it to NULL before calling this).

Returns 0 on success, FSL_RC_OOM on an allocation error, FSL_RC_MISUSE if (!tgt). If this function fails, it is illegal to use the context object except to pass it to fsl_cx_finalize(), as explained above.

See also
fsl_cx_finalize()

References FSL_EXPORT.

◆ fsl_cx_interrupt()

FSL_EXPORT int fsl_cx_interrupt ( fsl_cx * f,
int code,
const char * fmt,
... )

Sets f's is-interrupted flag and, if the 3rd argument is not NULL, its error state.

The is-interrupted flag is separate from f's normal error state and is not cleared by fsl_cx_err_reset(). To clear the interrupted flag, call this function with values of 0 and NULL for the 2nd and 3rd arguments, respectively. This flag is not fetched by fsl_cx_err_get() but:

1) If this function is passed a non-NULL 3rd argument, then the normal error state, as well as the is-interrupted flag, is updated and can be fetched normally via fsl_cx_err_get(). However...

2) It is possible for any error message provided via this routine to be overwritten or reset by another routine before the interrupted flag can be acted upon, whereas the interrupted flag itself can only be modified by this routine.

Returns its 2nd argument on success or FSL_RC_OOM if given a formatted string and allocation of it fails. In either case, the interrupted flag, as returned by fsl_cx_interrupted(), is always assigned to the passed-in code.

If passed a code of 0, the is-interrupted flag is reset but the general error state is not modified.

Results are undefined if this function is called twice concurrently with the same fsl_cx object. i.e. all calls for a given fsl_cx must come from a single thread. Results are also undefined if it is called while f is in its finalization phase (typically during application shutdown).

ACHTUNG: this is new as of 2021-11-18 and is not yet widely honored within the API.

Library maintenance notes:

  • Long-running actions which honor this flag should, if it is set, clear it before returning its error code. Also, they should prefer to pass on non-interruption errors if one has been set set, in addition to clearing the interruption flag. Only routines which honor this flag, or top-most routines in the application, should ever clear this flag.
See also
fsl_cx_interrupted()
fsl_cx_interruptv()

◆ fsl_cx_interrupted()

FSL_EXPORT int fsl_cx_interrupted ( fsl_cx const * f)

If f's is-interrupted flag is set, this function returns its value.

Note that there is inherently a race condition when calling fsl_cx_interrupt() (to set the flag) from another thread (e.g. a UI thread while showing a progress indicator).

References FSL_EXPORT.

◆ fsl_cx_interruptv()

FSL_EXPORT int fsl_cx_interruptv ( fsl_cx * f,
int code,
char const * fmt,
va_list args )

The va_list counterpart of fsl_cx_interrupt().

References FSL_EXPORT.

◆ fsl_cx_is_case_sensitive()

FSL_EXPORT bool fsl_cx_is_case_sensitive ( fsl_cx *const f,
bool forceRecheck )

Returns true if f is set for case-sensitive filename handling, else false.

This setting is cached when a repository is opened, but passing true for the second argument forces the config option to be re-loaded from the repository db. Results are undefined if !f.

See also
fsl_cx_case_sensitive_set()

References FSL_EXPORT.

◆ fsl_cx_last_insert_id()

FSL_EXPORT fsl_id_t fsl_cx_last_insert_id ( fsl_cx * f)

Wrapper around fsl_db_last_insert_id() which uses f's main database.

Returns -1 if !f or f has no opened db.

See also
fsl_cx_db()

References FSL_EXPORT.

◆ fsl_cx_last_sync_url()

FSL_EXPORT int fsl_cx_last_sync_url ( fsl_cx * f,
fsl_buffer * tgt )

Extracts the "last-sync-url" entry from f's repository configuration and appends it to tgt.

On success, returns 0, else returns the result of fsl_config_get_buffer().

References FSL_EXPORT.

◆ fsl_cx_listener_replace()

void fsl_cx_listener_replace ( fsl_cx * f,
fsl_msg_listener const * pNew,
fsl_msg_listener * pOld )

Replace's f's current fsl_msg listener with a bitwise copy of pNew.

If pOld is not NULL then a bitwise copy of the previous listener is written there.

References FSL_EXPORT.

◆ fsl_cx_malloc()

FSL_EXPORT fsl_cx * fsl_cx_malloc ( void )

Allocates a new fsl_cx instance, which must eventually be passed to fsl_cx_finalize() to clean it up.

Normally clients do not need this - they can simply pass a pointer to NULL as the first argument to fsl_cx_init() to let it allocate an instance for them.

References FSL_EXPORT.

◆ fsl_cx_prepare()

FSL_EXPORT int fsl_cx_prepare ( fsl_cx * f,
fsl_stmt * tgt,
char const * sql,
... )

Convenience form of fsl_db_prepare() which uses f's main db.

Returns 0 on success. On preparation error, any db error state is uplifted from the db object to the fsl_cx object. Returns FSL_RC_RANGE if !*sql.

Results are undefined if f or sql are NULL or otherwise invalid.

References FSL_EXPORT.

◆ fsl_cx_prepare_cached()

FSL_EXPORT int fsl_cx_prepare_cached ( fsl_cx * f,
fsl_stmt ** tgt,
char const * sql,
... )

Convenience form of fsl_db_prepare_cached() which uses f's main db.

Returns 0 on success. On preparation error, any db error state is uplifted from the db object to the fsl_cx object. Returns FSL_RC_RANGE if !*sql.

Results are undefined if f or sql are NULL or otherwise invalid.

References FSL_EXPORT.

◆ fsl_cx_preparev()

FSL_EXPORT int fsl_cx_preparev ( fsl_cx * f,
fsl_stmt * tgt,
char const * sql,
va_list args )

va_list counterpart of fsl_cx_prepare().

References FSL_EXPORT.

◆ fsl_cx_preparev_cached()

FSL_EXPORT int fsl_cx_preparev_cached ( fsl_cx * f,
fsl_stmt ** tgt,
char const * sql,
va_list args )

va_list counterpart of fsl_cx_prepare_cached().

References FSL_EXPORT.

◆ fsl_cx_stat()

FSL_EXPORT int fsl_cx_stat ( fsl_cx * f,
bool relativeToCwd,
char const * zName,
fsl_fstat * tgt )

Works similarly to fsl_stat(), except that zName must refer to a path under f's current checkout directory.

Note that this stats local files, not repository-level content.

If relativeToCwd is true then the filename is resolved/canonicalized based on the current working directory (see fsl_getcwd()), otherwise f's current checkout directory is used as the virtual root. This makes a subtle yet important difference in how the name is resolved. Applications taking input from users (e.g. CLI apps) will normally want to resolve from the current working dir (assuming the filenames were passed in from the CLI). In a GUI environment, where the current directory is likely not the checkout root, resolving based on the checkout root (i.e. relativeToCwd=false) is probably saner.

Returns 0 on success. Errors include, but are not limited to:

  • FSL_RC_MISUSE if !zName.
  • FSL_RC_NOT_A_CKOUT if f has no opened checkout.
  • If fsl_is_simple_pathname(zName) returns false then fsl_ckout_filename_check() is used to normalize the name. If that fails, its failure code is returned.
  • As for fsl_stat().

See fsl_stat() for more details regarding the tgt parameter.

TODO: fossil-specific symlink support. Currently it does not distinguish between symlinks and non-links.

See also
fsl_cx_stat2()

References FSL_EXPORT.

◆ fsl_cx_stat2()

FSL_EXPORT int fsl_cx_stat2 ( fsl_cx * f,
bool relativeToCwd,
char const * zName,
fsl_fstat * tgt,
fsl_buffer * nameOut,
bool fullPath )

This works identically to fsl_cx_stat(), but provides more information about the file being stat'd.

If nameOut is not NULL then the resolved/normalized path to to that file is appended to nameOut. If fullPath is true then an absolute path is written to nameOut, otherwise a checkout-relative path is written.

Returns 0 on success. On stat() error, nameOut is not updated, but after stat()'ing, allocation of memory for nameOut's buffer may fail.

If zName ends with a trailing slash, that slash is retained in nameOut.

This function DOES NOT resolve symlinks, stat()ing the link instead of what it points to.

See also
fsl_cx_stat()

References FSL_EXPORT.

◆ fsl_cx_txn_begin()

FSL_EXPORT int fsl_cx_txn_begin ( fsl_cx * f)

Returns the same as passing fsl_cx_db() to fsl_db_txn_begin().

◆ fsl_cx_txn_end_v2()

FSL_EXPORT int fsl_cx_txn_end_v2 ( fsl_cx * f,
bool keepSavepoint,
bool bubbleRollback )

Returns the same as passing fsl_cx_db() to fsl_db_txn_end().

References FSL_EXPORT.

◆ fsl_cx_txn_level()

FSL_EXPORT int fsl_cx_txn_level ( fsl_cx * f)

Returns the same as passing fsl_cx_db() to fsl_db_txn_level(), or 0 if f has no db opened.

See also
fsl_cx_db()

References FSL_EXPORT.

◆ fsl_cx_uplift_db_error()

FSL_EXPORT int fsl_cx_uplift_db_error ( fsl_cx * f,
fsl_db * db )

Unconditionally Moves db->error's state into f (without requiring any allocation).

If db is NULL then f's primary db connection is used. Returns FSL_RC_MISUSE if (!db && f-is-not-opened), with the caveat f always has a db connection under the current connection architecture. On success it returns f's new error code (which may be 0).

The main purpose of this function is to propagate db-level errors up to higher-level code which deals directly with the f object but not the underlying db(s).

See also
fsl_cx_uplift_db_error2()

References FSL_EXPORT.

◆ fsl_cx_uplift_db_error2()

FSL_EXPORT int fsl_cx_uplift_db_error2 ( fsl_cx * f,
fsl_db * db,
int rc )

If rc is not 0 and f has no error state but db does, this calls fsl_cx_uplift_db_error() and returns its result, else returns rc.

If db is NULL, f's main db connection is used. It is intended to be called immediately after calling a db operation which might have failed, and passed that operation's result.

As a special case, if rc is FSL_RC_OOM, this function has no side effects and returns rc. The intention of that is to keep a propagated db-level error (which may perhaps be stale by the time this is called) from hiding an OOM error.

Results are undefined if db is NULL and f has no main db connection.

References FSL_EXPORT.

◆ fsl_cx_user_get()

FSL_EXPORT char const * fsl_cx_user_get ( fsl_cx const * f)

Returns the name set by fsl_cx_user_set(), or NULL if f has no default user name set.

The returned bytes are owned by f and will be invalidated by any future calls to fsl_cx_user_set().

See also
fsl_cx_user_guess()

References FSL_EXPORT.

◆ fsl_cx_user_guess()

FSL_EXPORT char const * fsl_cx_user_guess ( fsl_cx * f)

If f has a user name set (via fsl_cx_user_set()) then this function returns that value.

If none has been set, this tries to guess one, using the first of:

  • The "default-user" value from the checkout db's vvar table.
  • The user entry from the repo db's user table with id 1.
  • fsl_user_name_guess()

and then assigns it as f's current user name. Returns NULL only on allocation error or if an environment setup error prevents detection of the user name. Not having a user name is not normally a problem, but trying to create new artifacts will fail if they have no user name to apply to their U-cards.

The returned bytes are owned by f and will be invalidated by any future calls to fsl_cx_user_set().

Note that the user name is, by default, determined automatically when a repo or a checkout/repo combination is opened, so client code does not normally need to call this.

References FSL_EXPORT.

◆ fsl_cx_user_set()

FSL_EXPORT int fsl_cx_user_set ( fsl_cx * f,
char const * userName )

Sets or clears (if userName is NULL or empty) the default repository user name for operations which require one.

Returns 0 on success, FSL_RC_MISUSE if f is NULL, FSL_RC_OOM if copying of the userName fails.

Example usage:

char * u = fsl_user_name_guess();
int rc = fsl_cx_user_set(f, u);
FSL_EXPORT int fsl_cx_user_set(fsl_cx *f, char const *userName)
Sets or clears (if userName is NULL or empty) the default repository user name for operations which r...
FSL_EXPORT void fsl_free(void *mem)
Semantically behaves like free(3), but may introduce instrumentation, error checking,...
FSL_EXPORT char * fsl_user_name_guess(void)
Uses fsl_getenv() to look for the environment variables (FOSSIL_USER, (Windows: USERNAME),...

(Sorry about the extra string copy there, but adding a function which passes ownership of the name string seems like overkill.)

See also
fsl_cx_user_guess()

References FSL_EXPORT.

◆ fsl_flush()

FSL_EXPORT int fsl_flush ( fsl_cx * f)

Flushes f's output channel.

Returns 0 on success. If the flush routine is NULL then this is a harmless no-op. Results are undefined if f is NULL.

See also
fsl_outputf()
fsl_output()

References FSL_EXPORT.

◆ fsl_glob_name_to_category()

FSL_EXPORT fsl_glob_category_e fsl_glob_name_to_category ( char const * str)

Converts a well-known fossil glob list configuration key to a fsl_glob_category_e value:

  • "ignore-glob" = FSL_GLOBS_IGNORE
  • "binary-glob" = FSL_GLOBS_BINARY
  • "crnl-glob" = FSL_GLOBS_CRNL
  • Anything else = FSL_GLOBS_INVALID

To simplify this function's use via an SQL-accessible UDF, the *-glob names may be passed in without their -glob suffix, e.g. "ignore" instead of "ignore-glob".

References FSL_EXPORT.

◆ fsl_hash_policy_name()

FSL_EXPORT char const * fsl_hash_policy_name ( fsl_hashpolicy_e p)

Returns a human-friendly name for the given policy, or NULL for an invalid policy value.

The returned strings are the same ones used by fossil's hash-policy command.

References FSL_EXPORT.

◆ fsl_library_version()

FSL_EXPORT char const * fsl_library_version ( void )

Returns the value of FSL_LIBRARY_VERSION used to compile the library.

If this value differs from the value the caller was compiled with, Chaos might ensue.

The API does not yet have any mechanism for determining compatibility between library versions and it also currently does no explicit checking to disallow incompatible versions.

References FSL_EXPORT.

◆ fsl_library_version_matches()

FSL_EXPORT bool fsl_library_version_matches ( char const * yourLibVersion)

Returns true (non-0) if yourLibVersion compares lexically equal to FSL_LIBRARY_VERSION, else it returns false (0).

It is intended to be passed the FSL_LIBRARY_VERSION string the client code was built with.

References FSL_EXPORT.

◆ fsl_library_version_scm()

FSL_EXPORT char const * fsl_library_version_scm ( void )

Returns the SCM-specific version info for libfossil (the hash and timestamp of it's own source's version).

References FSL_EXPORT.

◆ fsl_msg_emit()

FSL_EXPORT int fsl_msg_emit ( fsl_msg const * msg,
fsl_msg_listener const * where )

If both where and where->callback are not NULL, msg is passed to where->callback and its result is returned, else this is a no-op and 0 is returned.

Results are undefined if msg is NULL or either argument is improperly populated.

References FSL_EXPORT.

◆ fsl_msg_type_cstr()

char const * fsl_msg_type_cstr ( fsl_msg_e e)

Returns the C-string form of the given sync message type, or NULL if e is invalid.

◆ fsl_needs_ckout()

FSL_EXPORT fsl_db * fsl_needs_ckout ( fsl_cx * f)

The checkout-db counterpart of fsl_needs_repo().

If no checkout is opened, f's error state is updated with a FSL_RC_NOT_A_CKOUT code and description of the problem.

See also
fsl_cx_db()
fsl_needs_repo()
fsl_cx_db_ckout()
fsl_cx_has_ckout()

References FSL_EXPORT.

◆ fsl_needs_repo()

FSL_EXPORT fsl_db * fsl_needs_repo ( fsl_cx * f)

A helper which fetches f's repository db.

If f has no repo db then it sets f's error state to FSL_RC_NOT_A_REPO with a message describing the requirement, then returns NULL. Returns NULL if !f.

See also
fsl_cx_db()
fsl_cx_db_repo()
fsl_needs_ckout()
fsl_cx_has_ckout()

References FSL_EXPORT.

◆ fsl_output()

FSL_EXPORT int fsl_output ( fsl_cx * f,
void const * src,
fsl_size_t n )

Outputs the first n bytes of src to f's configured output channel.

Returns 0 on success, 0 (without side effects) if !n, else it returns the result of the underlying output call. This is a harmless no-op if f is configured with no output channel.

Results are undefined if f or src are NULL.

See also
fsl_outputf()
fsl_flush()

References FSL_EXPORT.

◆ fsl_outputf()

FSL_EXPORT int fsl_outputf ( fsl_cx * f,
char const * fmt,
... )

Uses fsl_appendf() to append formatted output to the channel configured for use with fsl_output().

Returns 0 on success, and will otherwise return the result of the underlying fsl_cx_format() call. (Prior to 2025-08-11, it used fsl_appendf() instead.)

Results are undefined if f or fmt are NULL or otherwise malformed.

See also
fsl_output()
fsl_flush()

References FSL_EXPORT.

◆ fsl_outputfv()

FSL_EXPORT int fsl_outputfv ( fsl_cx * f,
char const * fmt,
va_list args )

va_list counterpart to fsl_outputf().

References FSL_EXPORT.

◆ fsl_rc_cstr()

FSL_EXPORT char const * fsl_rc_cstr ( int rc)

Returns a "standard" string form for a fsl_rc_e code.

The string is primarily intended for debugging purposes. The returned bytes are guaranteed to be static and NUL-terminated. They are not guaranteed to contain anything useful for any purposes other than debugging and tracking down problems. If passed a code which is not in the fsl_rc_e enum, it returns NULL.

References FSL_EXPORT.

◆ fsl_satype_cstr()

FSL_EXPORT char const * fsl_satype_cstr ( fsl_satype_e t)

Returns some arbitrary but distinct string for the given fsl_satype_e.

The returned bytes are static and NUL-terminated. Intended primarily for debugging and informative purposes, not actual user output.

References FSL_SATYPE_BRANCH_START.

◆ fsl_satype_event_cstr()

FSL_EXPORT char const * fsl_satype_event_cstr ( fsl_satype_e t)

For a given artifact type, it returns the key string used in the event.type db table.

Returns NULL if passed an unknown value or a type which is not used in the event table, otherwise the returned bytes are static and NUL-terminated.

The returned strings for a given type are as follows:

  • FSL_SATYPE_ANY returns "*"
  • FSL_SATYPE_CHECKIN and FSL_SATYPE_BRANCH_START return "ci"
  • FSL_SATYPE_WIKI returns "w"
  • FSL_SATYPE_TAG returns "g"
  • FSL_SATYPE_TICKET returns "t"
  • FSL_SATYPE_EVENT returns "e"

The other control artifact types do not have representations in the event table, and NULL is returned for them.

All of the returned values can be used in comparison clauses in queries on the event table's 'type' field (but use GLOB instead of '=' so that the "*" returned by FSL_ATYPE_ANY can match). For example, to get the comments from the most recent 5 commits:

SELECT
datetime(mtime),
coalesce(ecomment,comment),
user
FROM event WHERE type='ci'
ORDER BY mtime DESC LIMIT 5;

Where 'ci' in the SQL is the non-NULL return value from this function. When escaping this value via fsl_buffer_appendf() (or anything functionally similar), use the %q/%Q format specifiers to escape it.

Variable Documentation

◆ fsl_cx_config_empty

FSL_EXPORT const fsl_cx_config fsl_cx_config_empty

fsl_cx_config instance initialized with defaults, intended for non-const copy initialization.

Definition at line 898 of file core.h.

◆ fsl_lib_configurable

FSL_EXPORT fsl_lib_configurable_t fsl_lib_configurable

Definition at line 587 of file core.h.

◆ fsl_msg_empty

const fsl_msg fsl_msg_empty
extern

fsl_msg instance intended for non-const copy initialization.

◆ fsl_msg_listener_empty

const fsl_msg_listener fsl_msg_listener_empty
extern