libfossil
fossil-core.h File Reference
#include "fossil-scm/fossil-util.h"
#include <time.h>

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_cx_init_opt
 Parameters for fsl_cx_init(). 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_repo_create_opt
 Configuration parameters for fsl_repo_create(). More...
 

Namespaces

 fsl
 License as yet undecided!
 

Macros

#define fsl_cx_config_empty_m
 fsl_cx_config instance initialized with defaults, intended for in-struct initialization. More...
 
#define fsl_cx_init_opt_default_m   {fsl_outputer_FILE_m, fsl_cx_config_empty_m}
 fsl_cx_init_opt instance initialized to use stdout for output and the standard system memory allocator. More...
 
#define fsl_cx_init_opt_empty_m   {fsl_outputer_empty_m, fsl_cx_config_empty_m}
 Empty-initialized fsl_cx_init_opt instance. More...
 
#define fsl_repo_create_opt_empty_m
 Initialized-with-defaults fsl_repo_create_opt struct, intended for in-struct initialization. More...
 

Typedefs

typedef enum fsl_catype_t fsl_catype_t
 
typedef enum fsl_configset_t fsl_configset_t
 
typedef struct fsl_cx fsl_cx
 
typedef struct fsl_cx_config fsl_cx_config
 
typedef enum fsl_cx_flag_t fsl_cx_flag_t
 
typedef struct fsl_cx_init_opt fsl_cx_init_opt
 
typedef struct fsl_db fsl_db
 
typedef enum fsl_db_role_t fsl_db_role_t
 
typedef enum fsl_file_perm_t fsl_file_perm_t
 
typedef enum fsl_glob_category_t fsl_glob_category_t
 
typedef struct fsl_lib_configurable_t fsl_lib_configurable_t
 
typedef enum fsl_rc_t fsl_rc_t
 
typedef struct fsl_repo_create_opt fsl_repo_create_opt
 
typedef struct fsl_stmt fsl_stmt
 
typedef enum fsl_user_role_t fsl_user_role_t
 

Enumerations

enum  fsl_catype_t {
  FSL_CATYPE_INVALID = -1,
  FSL_CATYPE_ANY = 0,
  FSL_CATYPE_CHECKIN = 1,
  FSL_CATYPE_CLUSTER = 2,
  FSL_CATYPE_CONTROL = 3,
  FSL_CATYPE_WIKI = 4,
  FSL_CATYPE_TICKET = 5,
  FSL_CATYPE_ATTACHMENT = 6,
  FSL_CATYPE_EVENT = 7
}
 An enumeration of the types of control artifacts used by Fossil. More...
 
enum  fsl_configset_t {
  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." 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. More...
 
enum  fsl_cx_flag_t {
  FSL_CX_F_NONE = 0,
  FSL_CX_F_CALC_R_CARD = 0x01,
  FSL_CX_F_IS_OPENING_CKOUT = 0x02,
  FSL_CX_F_DEFAULTS = FSL_CX_F_NONE
}
 Runtime-configurable flags for a fsl_cx instance. More...
 
enum  fsl_db_role_t {
  FSL_DB_ROLE_NONE = 0,
  FSL_DB_ROLE_CONFIG = 0x01,
  FSL_DB_ROLE_REPO = 0x02,
  FSL_DB_ROLE_CHECKOUT = 0x04,
  FSL_DB_ROLE_MAIN = 0x08
}
 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_file_perm_t {
  FSL_FILE_PERM_REGULAR = 0,
  FSL_FILE_PERM_EXE = 0x1,
  FSL_FILE_PERM_LINK = 0x2
}
 Filesystem-level permissions flags supported by fossil Manifests. More...
 
enum  fsl_glob_category_t {
  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_rc_t {
  FSL_RC_OK = 0,
  FSL_RC_ERROR = 100,
  FSL_RC_NYI = 101,
  FSL_RC_OOM = 102,
  FSL_RC_MISUSE = 103,
  FSL_RC_RANGE = 104,
  FSL_RC_ACCESS = 105,
  FSL_RC_IO = 106,
  FSL_RC_NOT_FOUND = 107,
  FSL_RC_ALREADY_EXISTS = 108,
  FSL_RC_CONSISTENCY = 109,
  FSL_RC_REPO_NEEDS_REBUILD = 110,
  FSL_RC_NOT_A_REPO = 111,
  FSL_RC_REPO_VERSION = 112,
  FSL_RC_DB = 113,
  FSL_RC_BREAK = 114,
  FSL_RC_STEP_ROW = 115,
  FSL_RC_STEP_DONE = 116,
  FSL_RC_STEP_ERROR = 117,
  FSL_RC_TYPE = 118,
  FSL_RC_NOT_A_CHECKOUT = 119,
  FSL_RC_REPO_MISMATCH = 120,
  FSL_RC_CHECKSUM_MISMATCH = 121,
  FSL_RC_UNKNOWN_RESOURCE,
  FSL_RC_SIZE_MISMATCH,
  FSL_RC_DELTA_INVALID_SEPARATOR,
  FSL_RC_DELTA_INVALID_SIZE,
  FSL_RC_DELTA_INVALID_OPERATOR,
  FSL_RC_DELTA_INVALID_TERMINATOR,
  FSL_RC_CA_SYNTAX,
  FSL_RC_AMBIGUOUS
}
 Most functions in this API which return an int type return error codes from the fsl_rc_t enum. More...
 
enum  fsl_user_role_t {
  FSL_UROLE_DEFAULT = 0,
  FSL_UROLE_GUEST = FSL_UROLE_DEFAULT,
  FSL_UROLE_ANONYMOUS = 1,
  FSL_UROLE_ADMIN = 1 << 1,
  FSL_UROLE_SETUP = 1 << 2,
  FSL_UROLE_READ = 1 << 3,
  FSL_UROLE_COMMIT = 1 << 4,
  FSL_UROLE_DELETE = 1 << 5,
  FSL_UROLE_PASSWORD = 1 << 6,
  FSL_UROLE_QUERY = 1 << 7,
  FSL_UROLE_WRITE = 1 << 8,
  FSL_UROLE_HYPERLINK = 1 << 9,
  FSL_UROLE_CLONE = 1 << 10,
  FSL_UROLE_WIKI_READ = 1 << 11,
  FSL_UROLE_WIKI_CREATE = 1 << 12,
  FSL_UROLE_WIKI_APPEND = 1 << 13,
  FSL_UROLE_WIKI_EDIT = 1 << 14,
  FSL_UROLE_WIKI_MODERATE = 1 << 15,
  FSL_UROLE_TKT_READ = 1 << 16,
  FSL_UROLE_TKT_NEW = 1 << 17,
  FSL_UROLE_TKT_APPEND = 1 << 18,
  FSL_UROLE_TKT_WRITE = 1 << 19,
  FSL_UROLE_TKT_MODERATE = 1 << 20,
  FSL_UROLE_TKT_RPT_FORMAT = 1 << 21,
  FSL_UROLE_ATTACH = 1 << 22,
  FSL_UROLE_READ_ADDR = 1 << 23,
  FSL_UROLE_ZIP = 1 << 24,
  FSL_UROLE_PRIVATE = 1 << 25,
  FSL_UROLE_ALL = 0x7FFFFFFF
}
 Roles equate to permissions in Fossil v1. More...
 

Functions

FSL_EXPORT char const * fsl_catype_cstr (fsl_catype_t t)
 Returns some arbitrary but distinct string for the given fsl_catype_t. More...
 
FSL_EXPORT char const * fsl_catype_event_cstr (fsl_catype_t t)
 For a given artifact type, it returns the key string used in the event.type db table. More...
 
FSL_EXPORT int fsl_checkout_close (fsl_cx *f)
 If fsl_checkout_open_dir() has been used to open a checkout db, this call closes that db and returns 0. More...
 
FSL_EXPORT int fsl_checkout_db_search (char const *dirName, fsl_int_t dirNameLen, char checkParentDirs, fsl_buffer *pOut)
 Searches the given directory (or the current directory if dirName is 0) for a fossil checkout database file named one of (_FOSSIL_, .fslckout). More...
 
FSL_EXPORT int fsl_checkout_open_dir (fsl_cx *f, char const *dirName, fsl_int_t dirNameLen, char checkParentDirs)
 Tries to open a checked-out fossil repository db in the given directory. More...
 
FSL_EXPORT void fsl_checkout_version_info (fsl_cx *f, fsl_id_t *rid, fsl_uuid_cstr *uuid)
 Returs version information for the current checkout. More...
 
FSL_EXPORT int fsl_config_close (fsl_cx *f)
 Closes/detaches the database connection opened by fsl_config_open(). More...
 
FSL_EXPORT int fsl_config_open (fsl_cx *f, char const *dbName)
 Opens the given database file as f's configuration database. More...
 
FSL_EXPORT void fsl_cx_case_sensitive_set (fsl_cx *f, char caseSensitive)
 Sets the case-sensitivity flag for f to the given value. More...
 
FSL_EXPORT char const * fsl_cx_checkout_dir_name (fsl_cx const *f, fsl_size_t *len)
 If f has an opened checkout db (from fsl_checkout_open_dir()) then this function returns the directory part of the path for the checkout. More...
 
FSL_EXPORT void fsl_cx_close_dbs (fsl_cx *f)
 Closes any opened databases (repo/checkout/config). More...
 
FSL_EXPORT fsl_dbfsl_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. More...
 
FSL_EXPORT fsl_dbfsl_cx_db_checkout (fsl_cx *f)
 If f is not NULL and has had a checkout opened via fsl_checkout_open_dir() or similar, this returns a pointer to that database, else it returns NULL. More...
 
FSL_EXPORT fsl_dbfsl_cx_db_config (fsl_cx *f)
 If f has an opened/attached configuration db then its handle is returned, else 0 is returned. More...
 
FSL_EXPORT char const * fsl_cx_db_file_checkout (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. More...
 
FSL_EXPORT char const * fsl_cx_db_file_config (fsl_cx const *f, fsl_size_t *len)
 Equivalent to fsl_checkout_db_file() except that it applies to the name of the opened config db, if any. More...
 
FSL_EXPORT char const * fsl_cx_db_file_for_role (fsl_cx const *f, fsl_db_role_t r, fsl_size_t *len)
 Similar to fsl_cx_db_file_checkout() and friends except that it applies to db file implied by the specified role (2nd parameter). More...
 
FSL_EXPORT char const * fsl_cx_db_file_repo (fsl_cx const *f, fsl_size_t *len)
 Equivalent to fsl_checkout_db_file() except that it applies to the name of the opened repository db, if any. More...
 
FSL_EXPORT fsl_dbfsl_cx_db_metadata (fsl_cx *f)
 Returns the db handle associated with the configuration settings virtual db table. More...
 
FSL_EXPORT char const * fsl_cx_db_name_for_role (fsl_cx const *f, fsl_db_role_t r, fsl_size_t *len)
 Similar to fsl_cx_db_file_checkout() and friends except that it applies to db name implied by the specified role (2nd parameter). More...
 
FSL_EXPORT fsl_dbfsl_cx_db_repo (fsl_cx *f)
 If f is not NULL and has had its repo opened via fsl_repo_open(), fsl_checkout_open_dir(), or similar, this returns a pointer to that database, else it returns NULL. More...
 
FSL_EXPORT fsl_dbfsl_cx_db_versioned (fsl_cx *f)
 The versioned settings counterpart of fsl_cx_db_checkout(). More...
 
FSL_EXPORT int fsl_cx_err_get (fsl_cx *f, char const **str, fsl_size_t *len)
 Fetches the error state from f. More...
 
FSL_EXPORT fsl_error const * fsl_cx_err_get_e (fsl_cx const *f)
 Returns f's error state object. More...
 
FSL_EXPORT int fsl_cx_err_report (fsl_cx *f, char addNewline)
 If f has error state then it outputs its error state to its output channel and returns the result of fsl_output(). More...
 
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). More...
 
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. More...
 
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). More...
 
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(). More...
 
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. More...
 
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). More...
 
FSL_EXPORT int fsl_cx_flag_set (fsl_cx *f, int flags, char enable)
 Sets or unsets one or more option flags on the given fossil context. More...
 
FSL_EXPORT int fsl_cx_flags_get (fsl_cx *f)
 Returns f's flags, or -1 if !f. More...
 
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. More...
 
FSL_EXPORT int fsl_cx_init (fsl_cx **tgt, fsl_cx_init_opt const *param)
 Initializes a fsl_cx instance. More...
 
FSL_EXPORT char fsl_cx_is_case_sensitive (fsl_cx const *f)
 Returns true (non-0) if f is set for case-sensitive filename handling, else 0. More...
 
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. More...
 
FSL_EXPORT fsl_cxfsl_cx_malloc ()
 Allocates a new fsl_cx instance, which must eventually be passed to fsl_cx_finalize() to clean it up. More...
 
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. More...
 
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(). More...
 
FSL_EXPORT void fsl_cx_reset (fsl_cx *f, char closeDatabases)
 Clears (most) dynamic state in f, but does not free f and does not free "static" state (that set up by the init process). More...
 
FSL_EXPORT int fsl_cx_schema_ticket (fsl_cx *f, fsl_buffer *pOut)
 If f's opened repository has a config non-empty entry named 'ticket-table', this returns its text via appending it to pOut. More...
 
FSL_EXPORT int fsl_cx_stat (fsl_cx *f, char 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. More...
 
FSL_EXPORT int fsl_cx_stat2 (fsl_cx *f, char relativeToCwd, char const *zName, fsl_fstat *tgt, fsl_buffer *nameOut, char fullPath)
 This works identically to fsl_cx_stat(), but provides more information about the file being stat'd. More...
 
FSL_EXPORT int fsl_cx_uplift_db_error (fsl_cx *f, fsl_db *db)
 Moves db->error's state into f. More...
 
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. More...
 
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. More...
 
FSL_EXPORT int fsl_flush (fsl_cx *f)
 Flushes f's output channel. More...
 
FSL_EXPORT char const * fsl_library_version ()
 Returns the value of FSL_LIBRARY_VERSION used to compile the library. More...
 
FSL_EXPORT char 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). More...
 
FSL_EXPORT fsl_dbfsl_needs_checkout (fsl_cx *f)
 The checkout-db counterpart of fsl_needs_repo(). More...
 
FSL_EXPORT fsl_dbfsl_needs_repo (fsl_cx *f)
 A helper which fetches f's repository db. More...
 
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. More...
 
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(). More...
 
FSL_EXPORT int fsl_outputfv (fsl_cx *f, char const *fmt, va_list args)
 va_list counterpart to fsl_outputf(). More...
 
FSL_EXPORT char const * fsl_rc_cstr (int)
 Returns a "standard" string form for a fsl_rc_t code. More...
 
FSL_EXPORT int fsl_repo_close (fsl_cx *f)
 If fsl_repo_open_xxx() or fsl_checkout_open_dir() has been used to open a respository db, this call closes that db and returns 0. More...
 
FSL_EXPORT int fsl_repo_create (fsl_cx *f, fsl_repo_create_opt const *opt)
 Creates a new repository database using the options provided in the second argument. More...
 
FSL_EXPORT char fsl_repo_is_readonly (fsl_cx const *f)
 UNTESTED. More...
 
FSL_EXPORT int fsl_repo_open (fsl_cx *f, char const *repoDbFile)
 Opens the given db file name as f's repository. More...
 
FSL_EXPORT fsl_uuid_str fsl_rid_to_artifact_uuid (fsl_cx *f, fsl_id_t rid, fsl_catype_t type)
 This works identically to fsl_uuid_to_rid() except that it will only resolve to a UUID if an artifact matching the given type has that UUID. More...
 
FSL_EXPORT fsl_uuid_str fsl_rid_to_uuid (fsl_cx *f, fsl_id_t rid)
 The opposite of fsl_uuid_to_rid(), this returns the UUID string of the given blob record ID. More...
 
FSL_EXPORT char const * fsl_schema_checkout ()
 Returns the raw SQL code for a Fossil checkout database. More...
 
FSL_EXPORT char const * fsl_schema_config ()
 Returns the raw SQL code for a Fossil global config database. More...
 
FSL_EXPORT char const * fsl_schema_repo1 ()
 Returns the raw SQL code for the "static" parts of a Fossil repository database. More...
 
FSL_EXPORT char const * fsl_schema_repo2 ()
 Returns the raw SQL code for the "transient" parts of a Fossil repository database - any parts which can be calculated via data held in the primary "static" schemas. More...
 
FSL_EXPORT char const * fsl_schema_ticket ()
 Returns the raw SQL code for a Fossil checkout db's _default_ core ticket-related tables. More...
 
FSL_EXPORT char const * fsl_schema_ticket_reports ()
 Returns the raw SQL code for Fossil ticket reports schemas. More...
 
FSL_EXPORT int fsl_sym_to_rid (fsl_cx *f, char const *sym, fsl_catype_t type, fsl_id_t *rv)
 Resolves client-provided symbol as an artifact's db record ID. More...
 
FSL_EXPORT int fsl_sym_to_uuid (fsl_cx *f, char const *sym, fsl_catype_t type, fsl_uuid_str *rv, fsl_id_t *rid)
 Similar to fsl_sym_to_rid() but on success if returns a UUID string by assigning it to *rv. More...
 
FSL_EXPORT fsl_id_t fsl_uuid_to_rid (fsl_cx *f, char const *uuid)
 Searches f's repo database for the a blob with the given uuid (any unique UUID prefix). More...
 

Variables

FSL_EXPORT const fsl_cx_config fsl_cx_config_empty
 fsl_cx_config instance initialized with defaults, intended for copy-initialization. More...
 
FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_default
 fsl_cx_init_opt instance initialized to use stdout for output and the standard system memory allocator. More...
 
FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_empty
 Empty-initialized fsl_cx_init_opt instance. More...
 
FSL_EXPORT fsl_lib_configurable_t fsl_lib_configurable
 
FSL_EXPORT const fsl_repo_create_opt fsl_repo_create_opt_empty
 Initialized-with-defaults fsl_repo_create_opt struct, intended for copy-initialization. More...
 

Macro Definition Documentation

#define fsl_cx_config_empty_m
Value:
{ \
0/*traceSql*/, \
0/*sqlPrint*/ \
}

fsl_cx_config instance initialized with defaults, intended for in-struct initialization.

Definition at line 523 of file fossil-core.h.

#define fsl_cx_init_opt_default_m   {fsl_outputer_FILE_m, fsl_cx_config_empty_m}

fsl_cx_init_opt instance initialized to use stdout for output and the standard system memory allocator.

Definition at line 555 of file fossil-core.h.

#define fsl_cx_init_opt_empty_m   {fsl_outputer_empty_m, fsl_cx_config_empty_m}

Empty-initialized fsl_cx_init_opt instance.

Definition at line 550 of file fossil-core.h.

#define fsl_repo_create_opt_empty_m
Value:
{ \
NULL/*filename*/, \
NULL/*username*/, \
"egg"/*commitMessage*/, \
NULL/*configRepo*/, \
0/*allowOverwrite*/ \
}

Initialized-with-defaults fsl_repo_create_opt struct, intended for in-struct initialization.

Definition at line 948 of file fossil-core.h.

Typedef Documentation

typedef enum fsl_catype_t fsl_catype_t

Definition at line 1588 of file fossil-core.h.

Definition at line 186 of file fossil-core.h.

typedef struct fsl_cx fsl_cx

Definition at line 66 of file fossil-core.h.

typedef struct fsl_cx_config fsl_cx_config

Definition at line 67 of file fossil-core.h.

Definition at line 211 of file fossil-core.h.

Definition at line 69 of file fossil-core.h.

typedef struct fsl_db fsl_db

Definition at line 68 of file fossil-core.h.

Definition at line 106 of file fossil-core.h.

Definition at line 444 of file fossil-core.h.

Definition at line 1752 of file fossil-core.h.

Definition at line 499 of file fossil-core.h.

typedef enum fsl_rc_t fsl_rc_t

Definition at line 421 of file fossil-core.h.

Definition at line 944 of file fossil-core.h.

typedef struct fsl_stmt fsl_stmt

Definition at line 70 of file fossil-core.h.

Definition at line 151 of file fossil-core.h.

Enumeration Type Documentation

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

Their numeric values (with the exception of FSL_TYPE_CATYPE_INVALID) are a hard-coded part of the Fossil db architecture and must never be changed.

Enumerator
FSL_CATYPE_INVALID 

Sentinel value used for some error reporting.

FSL_CATYPE_ANY 

Sentinel value used to mark a deck as being "any" type.

This is a placeholder on a deck's way to completion.

FSL_CATYPE_CHECKIN 

Indicates a "manifest" artifact (a checkin record).

FSL_CATYPE_CLUSTER 

Indicates a "cluster" artifact.

These are used during synchronization.

FSL_CATYPE_CONTROL 

Indicates a "control" artifact (a tag change).

FSL_CATYPE_WIKI 

Indicates a "wiki" artifact.

FSL_CATYPE_TICKET 

Indicates a "ticket" artifact.

FSL_CATYPE_ATTACHMENT 

Indicates an "attachment" artifact (used in the ticketing subsystem).

FSL_CATYPE_EVENT 

Indicates an "event" artifact (kind of like a blog entry).

Definition at line 1548 of file fossil-core.h.

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.

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 160 of file fossil-core.h.

Runtime-configurable flags for a fsl_cx instance.

Enumerator
FSL_CX_F_NONE 
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_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 191 of file fossil-core.h.

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.

All that said, i'm not yet fully convinced that a straight port of the v1 model is the best option for how we internally manage DBs, so this is subject to eventual change or removal.

Enumerator
FSL_DB_ROLE_NONE 

Sentinel "no role" value.

FSL_DB_ROLE_CONFIG 

Analog to v1's "configdb".

FSL_DB_ROLE_REPO 

Analog to v1's "repository".

FSL_DB_ROLE_CHECKOUT 

Analog to v1's "localdb".

FSL_DB_ROLE_MAIN 

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

Definition at line 83 of file fossil-core.h.

Filesystem-level 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 as Unix treats symlinks.

Definition at line 431 of file fossil-core.h.

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_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 1742 of file fossil-core.h.

enum fsl_rc_t

Most functions in this API which return an int type return error codes from the fsl_rc_t enum.

None of these entries are (currently) guaranteed to have a specific value across Fossil 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 (or some of them) 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.

Maintenance reminder: as entries are added/changed, update fsl_rc_cstr().

Enumerator
FSL_RC_OK 

The quintessential not-an-error value.

FSL_RC_ERROR 

Generic/unknown error.

FSL_RC_NYI 

A placeholder return value for "not yet implemented" functions.

FSL_RC_OOM 

Out of memory.

Indicates that a resource allocation request failed.

FSL_RC_MISUSE 
FSL_RC_RANGE 

Some range was violated (function argument, UTF character, etc.).

FSL_RC_ACCESS 

Indicates that access to or locking of a resource was denied by some security mechanism or other.

FSL_RC_IO 

Indicates an I/O error.

Whether it was reading or writing is context-dependent.

FSL_RC_NOT_FOUND 

requested resource not found

FSL_RC_ALREADY_EXISTS 

Indicates that a to-be-created resource already exists.

FSL_RC_CONSISTENCY 

Data consistency problem.

FSL_RC_REPO_NEEDS_REBUILD 

Indicates that the requested repo needs to be rebuilt.

FSL_RC_NOT_A_REPO 

Indicates that the requested repo is not, in fact, a repo.

Also used by some APIs to indicate that they require a repository db but none has been opened.

FSL_RC_REPO_VERSION 

Indicates an attempt to open a too-old or too-new repository db.

FSL_RC_DB 

Indicates db-level error (e.g.

statement prep failed). In such cases, the error state of the related db handle (fsl_db) or Fossilc context (fsl_cx) will be updated to contain more information directly from the db driver.

FSL_RC_BREAK 

Used by some iteration routines to indicate that iteration should stop prematurely without an error.

FSL_RC_STEP_ROW 

Indicates that fsl_stmt_step() has fetched a row and the cursor may be used to access the current row state (e.g.

using fsl_stmt_get_int32() and friends). It is strictly illegal to use the fsl_stmt_get_xxx() APIs unless fsl_stmt_step() has returned this code.

FSL_RC_STEP_DONE 

Indicates that fsl_stmt_step() has reached the end of the result set and that there is no row data to process.

This is also the result for non-fetching queries (INSERT and friends). It is strictly illegal to use the fsl_stmt_get_xxx() APIs after fsl_stmt_step() has returned this code.

FSL_RC_STEP_ERROR 

Indicates that a db-level error occurred during a fsl_stmt_step() iteration.

FSL_RC_TYPE 

Indicates that some data type or logical type is incorrect (e.g.

an invalid card type in conjunction with a given fsl_deck).

FSL_RC_NOT_A_CHECKOUT 

Indicates that an operation which requires a checkout does not have a checkout to work on.

FSL_RC_REPO_MISMATCH 

Not yet used.

Indicates that a repo and checkout do not belong together. The public API currently does not allow that to happen.

FSL_RC_CHECKSUM_MISMATCH 

Indicates that a checksum comparison failed, possibly indicating that corrupted or unexpected data was just read.

FSL_RC_UNKNOWN_RESOURCE 

This is a special case of FSL_RC_NOT_FOUND, intended specifically to differentiate from "file not found in filesystem" (FSL_RC_NOT_FOUND) and "fossil does not know about this file" in routines for which both might be an error case.

An example is a an operation which wants to update a repo file with contents from the filesystem - the file might not exist or it might not be in the current repo db.

That said, this can also be used for APIs which search for other resources (UUIDs, tickets, etc.), but FSL_RC_NOT_FOUND is already fairly well entrenched in those cases and is unambiguous, so this code is only needed by APIs for which both cases described above might happen.

FSL_RC_SIZE_MISMATCH 

Indicates that a size comparison check failed.

TODO: remove this if it is not used.

FSL_RC_DELTA_INVALID_SEPARATOR 

Indicates that an invalid separator was encountered while parsing a delta.

FSL_RC_DELTA_INVALID_SIZE 

Indicates that an invalid size value was encountered while parsing a delta.

FSL_RC_DELTA_INVALID_OPERATOR 

Indicates that an invalid operator was encountered while parsing a delta.

FSL_RC_DELTA_INVALID_TERMINATOR 

Indicates that an invalid terminator was encountered while parsing a delta.

FSL_RC_CA_SYNTAX 

Indicates a generic syntax error in a control artifact.

Some types of manifest-releated errors are reported with more specific error codes, e.g. FSL_RC_RANGE if a given Card type appears too often.

FSL_RC_AMBIGUOUS 

Indicates that some value or expression is ambiguous.

Typically caused by trying to resolve ambiguous symbolic names or partial UUIDs to their full UUIDs.

Definition at line 229 of file fossil-core.h.

Roles equate to permissions in Fossil v1.

Here we implement them as a bitmask and hope we never need more than 31 of them.

Actually... all of this app-level stuff. The library doesn't really care about users (and therefore access rights) at all. Nonetheless, the library should provide some base functionality for it, based on the v1 model. Clients are of course not prohibited from adding their own security models/policies.

Enumerator
FSL_UROLE_DEFAULT 
FSL_UROLE_GUEST 
FSL_UROLE_ANONYMOUS 
FSL_UROLE_ADMIN 
FSL_UROLE_SETUP 
FSL_UROLE_READ 
FSL_UROLE_COMMIT 
FSL_UROLE_DELETE 
FSL_UROLE_PASSWORD 
FSL_UROLE_QUERY 
FSL_UROLE_WRITE 
FSL_UROLE_HYPERLINK 
FSL_UROLE_CLONE 
FSL_UROLE_WIKI_READ 
FSL_UROLE_WIKI_CREATE 
FSL_UROLE_WIKI_APPEND 
FSL_UROLE_WIKI_EDIT 
FSL_UROLE_WIKI_MODERATE 
FSL_UROLE_TKT_READ 
FSL_UROLE_TKT_NEW 
FSL_UROLE_TKT_APPEND 
FSL_UROLE_TKT_WRITE 
FSL_UROLE_TKT_MODERATE 
FSL_UROLE_TKT_RPT_FORMAT 
FSL_UROLE_ATTACH 
FSL_UROLE_READ_ADDR 
FSL_UROLE_ZIP 
FSL_UROLE_PRIVATE 
FSL_UROLE_ALL 

Definition at line 118 of file fossil-core.h.

Function Documentation

FSL_EXPORT char const* fsl_catype_cstr ( fsl_catype_t  t)

Returns some arbitrary but distinct string for the given fsl_catype_t.

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

FSL_EXPORT char const* fsl_catype_event_cstr ( fsl_catype_t  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_CATYPE_ANY returns "*"
  • FSL_CATYPE_CHECKIN returns "ci"
  • FSL_CATYPE_WIKI returns "w"
  • FSL_CATYPE_TAG returns "g"
  • FSL_CATYPE_TICKET returns "t"
  • FSL_CATYPE_EVENT returns "e"

The other control artifact types to 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:

1 SELECT
2 datetime(mtime),
3 coalesce(ecomment,comment),
4 user
5 FROM event WHERE type='ci'
6 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.

FSL_EXPORT int fsl_checkout_close ( fsl_cx f)

If fsl_checkout_open_dir() has been used to open a checkout db, this call closes that db and returns 0.

Returns FSL_RC_MISUSE if !f, FSL_RC_NOT_FOUND if f has not opened a checkout (which can safely be ignored and does not update f's error state).

This also closes the repository implicitly opened for the checkout.

If the checkout is the "main" db, this also closes any associated config db.

FSL_EXPORT int fsl_checkout_db_search ( char const *  dirName,
fsl_int_t  dirNameLen,
char  checkParentDirs,
fsl_buffer pOut 
)

Searches the given directory (or the current directory if dirName is 0) for a fossil checkout database file named one of (_FOSSIL_, .fslckout).

If it finds one, it returns 0 and appends the file's path to pOut if pOut is not 0. If neither is found AND if checkParentDirs is true (non-0) an then it moves up the path one directory and tries again, until it hits the root of the dirPath (see below for a note/caveat).

If dirName is NULL then it behaves as if it had been passed the absolute path of the current directory (as determined by fsl_getcwd()).

If dirName is not NULL and dirNameLen is <0 then fsl_strlen() is used to calculate dirName's len. If dirName is NULL then dirNameLen is ignored.

This function does no normalization of dirName. Because of that...

Achtung: if dirName is relative, this routine might not find a checkout where it would find one if given an absolute path (because it traverses the path string given it instead of its canonical form). Wether this is a bug or a feature is not yet clear. When in doubt, use fsl_file_canonical_name() to normalize the directory name before passing it in here. If it turns out that we always want that behaviour, this routine will be modified to canonicalize the name.

This routine can return at least the following error codes:

  • FSL_RC_NOT_FOUND: either no checkout db was found or the given directory was not found.
  • FSL_RC_RANGE if dirName is an empty string. (We could arguably interpret this as a NULL string, i.e. the current directory.)
  • FSL_RC_OOM if allocation of a filename buffer fails.
FSL_EXPORT int fsl_checkout_open_dir ( fsl_cx f,
char const *  dirName,
fsl_int_t  dirNameLen,
char  checkParentDirs 
)

Tries to open a checked-out fossil repository db in the given directory.

The (dirName, dirNameLen, checkParentDirs) parameters are passed on as-is to fsl_checkout_db_search() to find a checkout db, so see that routine for how it searches.

If this routine finds/opens a checkout, it also tries to open the repository database from which the checkout derives (and fails if it cannot).

Returns 0 on success. If there is an error opening or validating the checkout or its repository db, f's error state will be updated. Error codes/conditions include:

  • FSL_RC_MISUSE if f is NULL.
  • FSL_RC_ACCESS if f already has and opened checkout.
  • FSL_RC_OOM if an allocation fails.
  • FSL_RC_NOT_FOUND if no checkout is foud or if a checkout's repository is not found.
  • FSL_RC_RANGE if dirname is not NULL but has a length of 0, either because 0 was passed in for dirNameLen or because dirNameLen was negative and *dirName is a NUL byte.
  • Various codes from fsl_getcwd() (if dirName is NULL).
  • Various codes if opening the associated repository DB fails.

TODO: there's really nothing in the architecture which restricts a checkout db to being in the same directory as the checkout, except for some historical bits which "could" be refactored. It "might be interesting" to eventually provide a variant which opens a checkout db file directly. We have the infrastructure, just need some refactoring. We would need to add the working directory path to the checkout db's config, but should otherwise require no trickery or incompatibilities with fossil(1).

FSL_EXPORT void fsl_checkout_version_info ( fsl_cx f,
fsl_id_t rid,
fsl_uuid_cstr uuid 
)

Returs version information for the current checkout.

If f is not NULL and has an opened checkout then...

If uuid is not NULL then *uuid is set to the UUID of the opened checkout. If rid is not NULL, *rid is set to the record ID of that checkout. The returned uuid bytes and rid are valid until the library closes the checkout db or updates its state to a newer checkout version. When in doubt about lifetime issues, copy the UUID immediately after calling this if they will be needed later.

Corner case: a new repo with no checkins has an RID of 0 and a UUID of NULL.

If f is NULL or has no checkout then *uuid will be set to NULL and *rid will be set to 0.

FSL_EXPORT int fsl_config_close ( fsl_cx f)

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

Returns 0 on succes, FSL_RC_MISUSE if !f, FSL_RC_NOT_FOUND if no config db connection is opened/attached.

See also
fsl_cx_db_config()
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, it is closed before opening the new 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. To get the name of the database after it has been opened/attached, use fsl_cx_db_file_config().

TODO: strongly consider supporting non-attached use of the config db. Comments in v1 suggest that it is possible to lock the config db for other apps when it is attached to a long-running op by a fossil process.

See also
fsl_cx_db_config()
fsl_config_close()
FSL_EXPORT void fsl_cx_case_sensitive_set ( fsl_cx f,
char  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.

See also
fsl_cx_is_case_sensitive()
FSL_EXPORT char const* fsl_cx_checkout_dir_name ( fsl_cx const *  f,
fsl_size_t len 
)

If f has an opened checkout db (from fsl_checkout_open_dir()) then this function returns the directory part of the path for the checkout.

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_checkout_open_dir()
fsl_checkout_db_file()
FSL_EXPORT void fsl_cx_close_dbs ( fsl_cx f)

Closes any opened databases (repo/checkout/config).

Any errors triggered by (e.g.) trying to close an unopened db are suppressed.

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.

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_transaction_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.

Design notes:

The current architecture designates the first db opened for a context as its "main" db, and the other databases (if opened) get attached to that one. As long as there are no table name collisions across databases, this does not affect how queries are formulated. It does, however, pose problems when constructing full-qualified db table names.

See also
fsl_cx_db_repo()
fsl_cx_db_checkout()
FSL_EXPORT fsl_db* fsl_cx_db_checkout ( fsl_cx f)

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

See also
fsl_cx_db()
FSL_EXPORT fsl_db* fsl_cx_db_config ( fsl_cx f)

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

See also
fsl_config_open()
fsl_config_close()
FSL_EXPORT char const* fsl_cx_db_file_checkout ( 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_checkout_open_dir()
fsl_cx_checkout_dir_name()
fsl_cx_db_file_config()
fsl_cx_db_file_repo()
FSL_EXPORT char const* fsl_cx_db_file_config ( fsl_cx const *  f,
fsl_size_t len 
)

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

See also
fsl_cx_db_file_checkout()
fsl_cx_db_file_repo()
FSL_EXPORT char const* fsl_cx_db_file_for_role ( fsl_cx const *  f,
fsl_db_role_t  r,
fsl_size_t len 
)

Similar to fsl_cx_db_file_checkout() 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.

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

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

See also
fsl_cx_db_file_checkout()
fsl_cx_db_file_config()
FSL_EXPORT fsl_db* fsl_cx_db_metadata ( fsl_cx f)

Returns the db handle associated with the configuration settings virtual db table.

It only returns a handle once one of f's databases has been opened, and it will return a handle to the "main" database. If no db is opened, or f is 0, it returns 0.

The settings metadata virtual able contains read-only descriptions of fossil(1) and libfossil configuration settings.

See also
fsl_cx_db()
fsl_cx_db_repo()
fsl_cx_db_checkout()
FSL_EXPORT char const* fsl_cx_db_name_for_role ( fsl_cx const *  f,
fsl_db_role_t  r,
fsl_size_t len 
)

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

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

This is the "easiest" way to figure out the DB name of the given role, independent of what order f's databases were opened (because the first-opened db is always called 'main').

The Fossil-standard names of its primary databases are: "ckout", "repo", and "cfg" (global config db). When opening its main DB, fsl_cx also ATTACHes the db to its well-known name for the given role, making this function essentially obsolete.

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_checkout_open_dir(), or similar, this returns a pointer to that database, else it returns NULL.

See also
fsl_cx_db()
FSL_EXPORT fsl_db* fsl_cx_db_versioned ( fsl_cx f)

The versioned settings counterpart of fsl_cx_db_checkout().

This will only return a handle if f's checkout db is opened, else it returns 0.

See also
fsl_cx_db()
fsl_cx_db_repo()
fsl_cx_db_checkout()
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.

FSL_EXPORT fsl_error const* fsl_cx_err_get_e ( fsl_cx const *  f)

Returns f's error state object.

This pointer is guaranteed by the API to be stable until f is finalized, but its contents are modified my routines as part of the error reporting process.

Returns NULL if !f.

FSL_EXPORT int fsl_cx_err_report ( fsl_cx f,
char  addNewline 
)

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

Returns FSL_RC_MISUSE if !f, 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.

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).

Is a no-op if f is 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.

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.

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.

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 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()
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).

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.

FSL_EXPORT int fsl_cx_flag_set ( fsl_cx f,
int  flags,
char  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_flag_t enum). If enable is true the flag(s) is (are) set, else it (they) is (are) unset. Returns the new set of flags, or -1 if !f.

FSL_EXPORT int fsl_cx_flags_get ( fsl_cx f)

Returns f's flags, or -1 if !f.

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_t 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 if !f, !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.

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

Initializes a fsl_cx instance.

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

1 fsl_cxt * f = NULL; // NULL is important - see below
2 int rc = fsl_cx_init( &f, NULL );

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 this function cannot allocate a new instance it returns FSL_RC_OOM and does not modify *tgt. In this case, ownership of param's contents is not changed. On any other error, 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).

See also
fsl_cx_finalize()
fsl_cx_reset()
FSL_EXPORT char fsl_cx_is_case_sensitive ( fsl_cx const *  f)

Returns true (non-0) if f is set for case-sensitive filename handling, else 0.

Returns 0 if !f.

See also
fsl_cx_case_sensitive_set()
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()
FSL_EXPORT fsl_cx* fsl_cx_malloc ( )

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.

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, FSL_RC_MISUSE if !f or !sql, FSL_RC_RANGE if !*sql.

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 void fsl_cx_reset ( fsl_cx f,
char  closeDatabases 
)

Clears (most) dynamic state in f, but does not free f and does not free "static" state (that set up by the init process).

If closeDatabases is true then any databases managed by f are closed, else they are kept open.

Client code will not normally need this - it is intended for a particular potential memory optimization case. If (and only if) closeDatabases is true then after calling this, f may be legally re-used as a target for fsl_cx_init().

This function does not trigger any finializers set for f's client state or output channel. It _does_ clear any user name set fsl_cx_user_set().

This is a no-op if !f.

FSL_EXPORT int fsl_cx_schema_ticket ( fsl_cx f,
fsl_buffer pOut 
)

If f's opened repository has a config non-empty entry named 'ticket-table', this returns its text via appending it to pOut.

If no entry is found, fsl_schema_ticket() is appended to pOut.

Returns 0 on success. On error the contents of pOut must not be considered valid but pOut might be partially populated.

FSL_EXPORT int fsl_cx_stat ( fsl_cx f,
char  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 (non-0) 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=0) is probably saner.

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

  • FSL_RC_MISUSE if !f or !zName.
  • FSL_RC_NOT_A_CHECKOUT if f has no opened checkout.
  • If fsl_is_simple_pathname(zName) returns false then fsl_checkout_filename_check() is used o normalize the name. If that fails, its failure core 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()
FSL_EXPORT int fsl_cx_stat2 ( fsl_cx f,
char  relativeToCwd,
char const *  zName,
fsl_fstat tgt,
fsl_buffer nameOut,
char  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.

See also
fsl_cx_stat()
FSL_EXPORT int fsl_cx_uplift_db_error ( fsl_cx f,
fsl_db db 
)

Moves db->error's state into f.

If db is NULL then f's primary db connection is used. Returns FSL_RC_MISUSE if !f or (!db && f-is-not-opened). On success it returns f's new error code.

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).

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 may be invalidated by any call to 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:

1 char * u = fsl_guess_user_name();
2 int rc = fsl_cx_user_set(f, u);
3 fsl_free(u);

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

FSL_EXPORT int fsl_flush ( fsl_cx f)

Flushes f's output channel.

Returns 0 on success, FSL_RC_MISUSE if !f. If the flush routine is NULL then this is a harmless no-op.

See also
fsl_outputf()
fsl_output()
FSL_EXPORT char const* fsl_library_version ( )

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 repository versions and it also currently does no explicit checking to disallow incompatible versions.

FSL_EXPORT char 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 fsl_db* fsl_needs_checkout ( fsl_cx f)

The checkout-db counterpart of fsl_needs_repo().

See also
fsl_cx_db()
fsl_needs_repo()
fsl_cx_db_checkout()
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_checkout()
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, FSL_RC_MISUSE if (!f || !src), 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.

See also
fsl_outputf()
fsl_flush()
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, FSL_RC_MISUSE if !f or !fmt, FSL_RC_RANGE if !*fmt, and FSL_RC_IO if the underlying fsl_appendf() operation fails.

Note, however, that due to the printf()-style return semantics of fsl_appendf(), it is not generically possible to distinguish a partially-successful (i.e. failed in the middle) write from success. e.g. if fmt contains a format specifier which performs memory allocation and that allocation fails, it is unlikely that this function will be able to be aware of that error. The only way to fix that is to change the return semantics of fsl_appendf() (and adjust any existing code which relies on them).

See also
fsl_output()
fsl_flush()
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  )

Returns a "standard" string form for a fsl_rc_t 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.

Referenced by fsl::Stmt::eachRow().

FSL_EXPORT int fsl_repo_close ( fsl_cx f)

If fsl_repo_open_xxx() or fsl_checkout_open_dir() has been used to open a respository db, this call closes that db and returns 0.

Returns FSL_RC_MISUSE if !f. FSL_RC_NOT_FOUND if f has not opened a repository.

If the repo is the "main" db, this also closes any associated checkout and config dbs.

If a repository is opened "indirectly" via fsl_checkout_open_dir() then clients must not close it using this function; they should allow it to be closed implicitly when the checkout db is closed.

See also
fsl_repo_open()
fsl_repo_create()
FSL_EXPORT int fsl_repo_create ( fsl_cx f,
fsl_repo_create_opt const *  opt 
)

Creates a new repository database using the options provided in the second argument.

If f is not NULL, it must be a valid context instance, though it need not have an opened checkout/repository (if it does, it/they will be closed by this operation). If f is NULL, a temporary context is used for creating the repository, in which case the caller will not have access to detailed error information (only the result code) if this operation fails. The opt argument may not be NULL.

If opt->allowOverwrite is false (0) and the file exists, it fails with FSL_RC_ALREADY_EXISTS, otherwise is creates/overwrites the file. This is a destructive operation if opt->allowOverwrite is true (non-0), so be careful.

This operation installs the various "static" repository schemas into the db, sets up some default settings, and installs a default user.

This operation always closes any repository/checkout opened by f because setting up the new db requires wiring it to f to set up some of the db-side infrastructure. The one exception is if argument validation fails, in which case f's repo/checkout-related state are not modified.

See the fsl_repo_create_opt docs for more details regarding the creation options.

On success, 0 is returned and f (if not NULL) is left with the new repository opened and ready for use. On error, f's error state is updated and any number of the FSL_RC_xxx codes may be returned - there are no less than 30 different _potential_ error conditions on the way to creating a new repository.

Example usage:

1 fsl_repo_create_opt opt = fsl_repo_create_opt_empty;
2 int rc;
3 opt.filename = "my.fossil";
4 // ... any other opt.xxx you want to set, e.g.:
5 // opt.user = "fred";
6 // Assume fsl is a valid fsl_cx instance:
7 rc = fsl_repo_create(fsl, &opt );
8 if(rc) { ...error... }
9 else {
10 fsl_db * db = fsl_cx_db_repo(f);
11 assert(db); // == the new repo db
12 ...
13 }
See also
fsl_repo_open()
fsl_repo_close()
FSL_EXPORT char fsl_repo_is_readonly ( fsl_cx const *  f)

UNTESTED.

Returns true if f has an opened repository database which is opened in read-only mode, else returns false.

FSL_EXPORT int fsl_repo_open ( fsl_cx f,
char const *  repoDbFile 
)

Opens the given db file name as f's repository.

Returns 0 on success. On error it sets f's error state and returns that code unless the error was FSL_RC_MISUSE (which indicates invalid arguments and it does not set the error state).

Fails with FSL_RC_MISUSE if !f, !repoDbFile, !*repoDbFile. Returns FSL_RC_ACCESS if f already has an opened repo db.

Returns FSL_RC_NOT_FOUND if repoDbFile is not found, as this routine cannot create a new repository db.

When a repository is opened, the fossil-level user name associated with f (if any) is overwritten with the default user from the repo's login table (the one with uid=1). Thus fsl_cx_user_get() may return a value even if the client has not called fsl_cx_user_set().

It would be nice to have a parameter specifying that the repo should be opened read-only. That's not as straightforward as it sounds because of how the various dbs are internally managed (via one db handle). Until then, the permissions of the underlying repo file will determine how it is opened. i.e. a read-only repo will be opened read-only.

Potentially interesting side-effects:

  • On success this re-sets the "allow-symlinks" option on f to match that of the opened repo, keeping its current setting if the repo specifies no value for that option.
See also
fsl_repo_create()
fsl_repo_close()
FSL_EXPORT fsl_uuid_str fsl_rid_to_artifact_uuid ( fsl_cx f,
fsl_id_t  rid,
fsl_catype_t  type 
)

This works identically to fsl_uuid_to_rid() except that it will only resolve to a UUID if an artifact matching the given type has that UUID.

If no entry is found, f's error state gets updated with a description of the problem.

This can be used to distinguish artifact UUIDs from file blob content UUIDs by passing the type FSL_CATYPE_ANY. A non-artifact blob will return NULL in that, but any artifact type will match (assuming rid is valid).

FSL_EXPORT fsl_uuid_str fsl_rid_to_uuid ( fsl_cx f,
fsl_id_t  rid 
)

The opposite of fsl_uuid_to_rid(), this returns the UUID string of the given blob record ID.

Ownership of the string is passed to the caller and it must eventually be freed using fsl_free(). Returns NULL on error (invalid arguments or f has no repo opened) or if no blob record is found. If no record is found, f's error state is updated with an explanation of the problem.

FSL_EXPORT char const* fsl_schema_checkout ( )

Returns the raw SQL code for a Fossil checkout database.

FSL_EXPORT char const* fsl_schema_config ( )

Returns the raw SQL code for a Fossil global config database.

FSL_EXPORT char const* fsl_schema_repo1 ( )

Returns the raw SQL code for the "static" parts of a Fossil repository database.

These are the parts which are immutable (for the most part) between Fossil versions. They change _very_ rarely.

FSL_EXPORT char const* fsl_schema_repo2 ( )

Returns the raw SQL code for the "transient" parts of a Fossil repository database - any parts which can be calculated via data held in the primary "static" schemas.

These parts are occassionally recreated, e.g. via a 'rebuild' of a repository.

FSL_EXPORT char const* fsl_schema_ticket ( )

Returns the raw SQL code for a Fossil checkout db's _default_ core ticket-related tables.

See also
fsl_cx_schema_ticket()
FSL_EXPORT char const* fsl_schema_ticket_reports ( )

Returns the raw SQL code for Fossil ticket reports schemas.

This gets installed as needed into repository databases.

FSL_EXPORT int fsl_sym_to_rid ( fsl_cx f,
char const *  sym,
fsl_catype_t  type,
fsl_id_t rv 
)

Resolves client-provided symbol as an artifact's db record ID.

f must have an opened repository db, and some symbols can only be looked up if it has an opened checkout (see the list below).

Returns 0 and sets *rv to the id if it finds an unambiguous match.

Returns FSL_RC_MISUSE if !f, !sym, !*sym, or !rv.

Returns FSL_RC_NOT_A_REPO if f has no opened repository.

Returns FSL_RC_AMBIGUOUS if sym is a partial UUID which matches multiple full UUIDs.

Returns FSL_RC_NOT_FOUND if it cannot find anything.

Symbols supported by this function:

  • SHA1 hash
  • SHA1 hash prefix of at least 4 characters
  • Symbolic Name
  • "tag:" + symbolic name
  • Date or date-time
  • "date:" + Date or date-time
  • symbolic-name ":" date-time
  • "tip"
  • "root:" resolves to the root manifest of the given checkin. In the trunk this will always resolve to the first "empty checkin" manifest.

The following additional forms are available in local checkouts:

  • "current"
  • "prev" or "previous"
  • "next"

If type is not FSL_CATYPE_ANY then it will only match artifacts of the specified type. In order to resolve arbitrary UUIDs, e.g. those of arbitrary blob content, type needs to be FSL_CATYPE_ANY.

FSL_EXPORT int fsl_sym_to_uuid ( fsl_cx f,
char const *  sym,
fsl_catype_t  type,
fsl_uuid_str rv,
fsl_id_t rid 
)

Similar to fsl_sym_to_rid() but on success if returns a UUID string by assigning it to *rv.

If rid is not NULL then on success the db record ID corresponding to the returned UUID is assigned to *rid. The caller must eventually free the returned string memory by passing it to fsl_free().

FSL_EXPORT fsl_id_t fsl_uuid_to_rid ( fsl_cx f,
char const *  uuid 
)

Searches f's repo database for the a blob with the given uuid (any unique UUID prefix).

On success a positive record ID is returned. On error one of several unspecified negative values is returned. If no uuid match is found 0 is returned.

Error cases include: either argument is NULL, uuid does not appear to be a full or partial UUID (or is too long), uuid is ambiguous (try providing a longer one)

This implementation is more efficient when given a full, valid UUID (one for which fsl_is_uuid() returns true).

Variable Documentation

FSL_EXPORT const fsl_cx_config fsl_cx_config_empty

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

Definition at line 532 of file fossil-core.h.

FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_default

fsl_cx_init_opt instance initialized to use stdout for output and the standard system memory allocator.

Used as the default when fsl_cx_init() is passed a NULL value for this parameter.

Definition at line 565 of file fossil-core.h.

FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_empty

Empty-initialized fsl_cx_init_opt instance.

Definition at line 558 of file fossil-core.h.

FSL_EXPORT fsl_lib_configurable_t fsl_lib_configurable

Definition at line 500 of file fossil-core.h.

FSL_EXPORT const fsl_repo_create_opt fsl_repo_create_opt_empty

Initialized-with-defaults fsl_repo_create_opt struct, intended for copy-initialization.

Definition at line 958 of file fossil-core.h.