libfossil
internal.h File Reference
#include "fossil-scm/repo.h"
#include "fossil-scm/sync.h"
Include dependency graph for internal.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  fsl__bccache
struct  fsl__bccache_line
struct  fsl__diff_cx
struct  fsl__mcache
struct  fsl__pq
struct  fsl__pq_entry
struct  fsl__ptl
 This object manages a stack of fsl__ptl_line objects for a fsl_cx. More...
struct  fsl__ptl_line
 A cache of fsl_cx state which applies per transaction level. More...
struct  fsl__tokenizer
struct  fsl__xfer
struct  fsl_cx
 The main Fossil "context" type. More...
struct  fsl_xfcard

Macros

#define E(NAME, IGNORED)
#define E(X)
#define E(X)
#define fsl__bccache_empty_m
#define fsl__bccache_line_empty_m   { 0,0,fsl_buffer_empty_m }
#define fsl__buffer_err(B)
#define fsl__cx_cache_stmt_map(E)
#define fsl__cx_ptl_has(F, W, R)
#define fsl__cx_ptl_insert(F, W, R)
#define fsl__cx_txn(FslCx, RcVar, RollbackTopOnError, KeepSPOnSuccess, BODY)
 An experiment.
#define fsl__cx_txn_global(FslCx, RcVar, KeepSPOnSuccess, BODY)
 fsl__cx_txn() proxy for use with local savepoints which should trigger a global savepoint rollback on error.
#define fsl__cx_txn_local(FslCx, RcVar, KeepSPOnSuccess, BODY)
 fsl__cx_txn() proxy for use with local savepoints which should not trigger a global savepoint rollback on error.
#define fsl__diff_cx_empty_m
#define FSL__LINE_LENGTH_MASK   ((1<<FSL__LINE_LENGTH_MASK_SZ)-1)
#define FSL__LINE_LENGTH_MASK_SZ   15
#define fsl__mcache_empty_m
#define fsl__pq_empty_m   {0,0,NULL}
#define fsl__pq_entry_empty_m   {0,NULL,0.0}
#define fsl__ptl_empty_m
 Empty-initialized fsl__ptl struct.
#define fsl__ptl_line_map(E)
 Expands to a list of the names of all fsl_id_bag members of the fsl__ptl_line struct by invoking macro E(NAME) once for each name.
#define fsl__tokenizer_empty_m   {NULL,NULL,false}
#define fsl__xfcard_searchNU(WORD)
 Non-unsigned-qualified C-string convenience form of fsl__xfcard_search().
#define FSL_ENABLE_MUTEX   0
 Determine whether fsl__mutex_enter() and friends are no-ops.
#define fsl_xfcard_hash_1(W)
#define fsl_xfcard_hash_10(W)
#define fsl_xfcard_hash_11(W)
#define fsl_xfcard_hash_2(W)
#define fsl_xfcard_hash_3(W)
#define fsl_xfcard_hash_4(W)
#define fsl_xfcard_hash_5(W)
#define fsl_xfcard_hash_6(W)
#define fsl_xfcard_hash_7(W)
#define fsl_xfcard_hash_8(W)
#define fsl_xfcard_hash_9(W)
#define fsl_xfcard_hash_N(N, W)
#define fsl_xfcard_hash_step(H, I, WORD)
#define fsl_xfcard_hash_step_ch(H, I, CHAR)
#define fsl_xfcard_hashS(WORD)
 Non-unsigned-qualified C-string convenience form of fsl_xfcard_hash().
#define fsl_xfcard_LowestIdChar   '$'
 Lowest-valued legal identifier character in a sync card name.
#define fsl_xfcard_MaxCardNameLen   11 /*==strlen("clone_seqno")*/
#define STMT(MEMBER, IGNORED)

Typedefs

typedef struct fsl__bccache fsl__bccache
typedef struct fsl__bccache_line fsl__bccache_line
typedef int fsl__cx_StaticAssertScratchpadSizes[((sizeof(fsl__cx_empty.scratchpads.buf)/sizeof(fsl__cx_empty.scratchpads.buf[0]))==(sizeof(fsl__cx_empty.scratchpads.used)/sizeof(fsl__cx_empty.scratchpads.used[0]))) ? 1 :-1]
 Ensure that fsl_cx::scratchpads::buf/used have the same array size.
typedef struct fsl__diff_cx fsl__diff_cx
typedef enum fsl__localmod_e fsl__localmod_e
typedef struct fsl__mcache fsl__mcache
typedef int fsl__mcache_StaticAssertArraySizes[((sizeof(fsl__mcache_empty.aAge)/sizeof(fsl__mcache_empty.aAge[0]))==(sizeof(fsl__mcache_empty.decks)/sizeof(fsl__mcache_empty.decks[0]))) ? 1 :-1]
 This will fail to compile if the arrays fsl__mcache::aAge and fsl__mcache::decks have different sizes.
typedef enum fsl__phantom_e fsl__phantom_e
typedef struct fsl__pq fsl__pq
typedef struct fsl__pq_entry fsl__pq_entry
typedef struct fsl__ptl fsl__ptl
typedef enum fsl__ptl_e fsl__ptl_e
typedef struct fsl__ptl_line fsl__ptl_line
typedef struct fsl__tokenizer fsl__tokenizer
typedef struct fsl__xfer fsl__xfer
typedef struct fsl_xfcard fsl_xfcard
typedef uint32_t fsl_xfcard_hash_t

Enumerations

enum  { fsl__xfer_max_tokens = 6 }
enum  fsl__cx_stmt_e { fsl__cx_cache_stmt_map =(E) }
enum  fsl__localmod_e {
  FSL__LOCALMOD_NONE = 0 ,
  FSL__LOCALMOD_PERM = 0x01 ,
  FSL__LOCALMOD_CONTENT = 0x02 ,
  FSL__LOCALMOD_LINK = 0x04 ,
  FSL__LOCALMOD_NOTFOUND = 0x10
}
enum  fsl__phantom_e {
  FSL_PHANTOM_NONE = 0 ,
  FSL_PHANTOM_PUBLIC = 1 ,
  FSL_PHANTOM_PRIVATE = 2
}
enum  fsl__ptl_e {
  fsl__ptl_e_dummy = 0 ,
  fsl__ptl_line_map =(E)
}
 Enum entries corresponding to fsl__ptl_line members. More...
enum  fsl_card_J_flags {
  FSL_CARD_J_INVALID = 0 ,
  FSL_CARD_J_TICKET = 0x01 ,
  FSL_CARD_J_CHNG = 0x02 ,
  FSL_CARD_J_BOTH = FSL_CARD_J_TICKET | FSL_CARD_J_CHNG
}

Functions

int fsl__bccache_check_available (fsl_cx *f, fsl_id_t rid)
void fsl__bccache_clear (fsl__bccache *c)
bool fsl__bccache_expire_oldest (fsl__bccache *c)
int fsl__bccache_insert (fsl__bccache *c, fsl_id_t rid, fsl_buffer *pBlob)
void fsl__bccache_reuse (fsl__bccache *c)
void fsl__bprc (int rc)
 A place to put a breakpoint to help trace down errors.
int fsl__call_xlink_listeners (fsl_deck *d)
void fsl__card_J_list_free (fsl_list *li, bool alsoListMem)
int fsl__ckout_clear_merge_state (fsl_cx *f, bool fullWipe)
int fsl__ckout_install_schema (fsl_cx *f, bool dropIfExists)
int fsl__ckout_rid (fsl_cx *f, fsl_id_t *rid)
 Sets *rid to f->db.ckout.rid, fetching the latter if needed.
unsigned int fsl__ckout_rm_empty_dirs (fsl_cx *f, fsl_buffer const *tgtDir)
int fsl__ckout_rm_empty_dirs_for_file (fsl_cx *f, char const *zAbsPath)
int fsl__ckout_safe_file_check (fsl_cx *f, char const *zFilename)
int fsl__ckout_symlink_create (fsl_cx *f, char const *zTgtFile, char const *zLinkFile)
int fsl__ckout_version_fetch (fsl_cx *f)
int fsl__ckout_version_write (fsl_cx *f, fsl_id_t vid, fsl_uuid_cstr uuid)
char * fsl__config_inop_rhs (int iMask)
int fsl__content_deltify (fsl_cx *f, fsl_id_t rid, fsl_id_t srcid, bool force)
int fsl__content_put (fsl_cx *f, fsl_buffer const *pBlob, fsl_id_t *newRid)
int fsl__content_put_ex (fsl_cx *f, fsl_buffer const *pBlob, fsl_uuid_cstr zUuid, fsl_id_t srcId, fsl_size_t uncompSize, bool isPrivate, fsl_id_t *outRid)
int fsl__content_undeltify (fsl_cx *f, fsl_id_t rid)
int fsl__crosslink_begin (fsl_cx *f)
int fsl__crosslink_end (fsl_cx *f, int resultCode)
int fsl__cx_attach_role (fsl_cx *f, const char *zDbName, fsl_dbrole_e r, bool createIfNotExists)
void fsl__cx_caches_reset (fsl_cx *f, bool isTxnCommit)
 Clears various internal caches and resets various internally-cached values related to repository and checkout dbs.
void fsl__cx_ckout_clear (fsl_cx *f)
fsl_buffer * fsl__cx_content_buffer (fsl_cx *f)
void fsl__cx_content_buffer_yield (fsl_cx *f)
void fsl__cx_content_caches_clear (fsl_cx *f)
 Clears only caches which are relevant to content lookup.
fsl_db * fsl__cx_db_for_role (fsl_cx *f, fsl_dbrole_e r)
int fsl__cx_init_db (fsl_cx *f, fsl_db *db)
void fsl__cx_mcache_clear (fsl_cx *f)
 Clears the contents of f->cache.mcache.
fsl_id_bag * fsl__cx_ptl_bag (fsl_cx *f, fsl__ptl_e which)
 Returns the given bag for the current transaction level.
int fsl__cx_ptl_pop (fsl_cx *f, bool isCommit)
 Can fail with OOM if isCommit and f->cache.ptl.level>0.
int fsl__cx_ptl_push (fsl_cx *f)
bool fsl__cx_ptl_remove (fsl_cx *f, fsl__ptl_e where, fsl_id_t rid)
 Removes rid from the given PTL list.
void fsl__cx_reset_for_txn (fsl_cx *f, bool isCommit)
 May clear or reset cached data.
fsl_buffer * fsl__cx_scratchpad (fsl_cx *f)
void fsl__cx_scratchpad_yield (fsl_cx *f, fsl_buffer *b)
int fsl__cx_see_key (fsl_cx *f, const char *zDbFile, fsl_buffer *pOut, int *keyType)
fsl_stmt * fsl__cx_stmt (fsl_cx *f, enum fsl__cx_stmt_e which)
 Returns the given cached statement object, preparing it if needed.
void fsl__cx_stmt_yield (fsl_cx *f, fsl_stmt *q)
 Must be passed all statement pointers obtained via fsl__cx_stmt().
int fsl__cx_ticket_create_table (fsl_cx *f)
int fsl__cx_ticket_load_fields (fsl_cx *f, bool forceReload)
int fsl__cx_update_seen_delta_deck (fsl_cx *f)
int fsl__db_cached_clear_role (fsl_db *db, fsl_flag32_t role)
void fsl__db_clear_strings (fsl_db *db, bool alsoBuffers)
int fsl__db_errcode (fsl_db *db, int sqliteCode)
int fsl__db_repo_verify_schema (fsl_db *db)
char * fsl__db_setting_inop_rhs (void)
void fsl__deck_clean_cards (fsl_deck *d, char const *letters)
int fsl__deck_crosslink (fsl_deck *d)
int fsl__deck_crosslink_one (fsl_deck *d)
int fsl__deck_deltify_parent (fsl_deck *d)
 If d->P.used then this makes d->P.list[0] a delta from d->rid, else this is a no-op.
fsl_card_F * fsl__deck_F_seek (fsl_deck *d, const char *zName)
int fsl__delta_delete (fsl_cx *f, fsl_id_t rid)
 Replaces the repo.delta entry with the given rid.
int fsl__delta_replace (fsl_cx *f, fsl_id_t rid, fsl_id_t srcid)
 Replaces the repo.delta entry with the given rid.
int fsl__diff_all (fsl__diff_cx *p)
void fsl__diff_cx_clean (fsl__diff_cx *cx)
void fsl__diff_optimize (fsl__diff_cx *p)
void fsl__dump_triples (fsl__diff_cx const *p, char const *zFile, int ln)
void fsl__fatal (int code, char const *fmt,...)
int fsl__fdgets (int fdIn, unsigned char *pOut, fsl_size_t nOut, char **ppOut, fsl_size_t *pnOut)
char * fsl__file_without_drive_letter (char *zFile)
int fsl__find_bin (char const *zPath, char const *zBinName, char **zOut)
int fsl__find_filename_changes (fsl_cx *f, fsl_id_t iFrom, fsl_id_t iTo, bool revOK, uint32_t *pnChng, fsl_id_t **aiChng)
int fsl__foci_register (fsl_cx *f, fsl_db *db)
void fsl__id_bag_dump (fsl_id_bag const *src, FILE *to, char const *zHeader)
int fsl__is_locally_modified (fsl_cx *f, const char *zFilename, fsl_size_t fileSize, const char *zOrigHash, fsl_int_t zOrigHashLen, fsl_fileperm_e origPerm, int *isModified)
bool fsl__is_reserved_fn_windows (const char *zPath, fsl_int_t nameLen)
int fsl__leaf_do_pending_checks (fsl_cx *f)
int fsl__leaf_eventually_check (fsl_cx *f, fsl_id_t rid)
void fsl__mutex_enter (void)
bool fsl__mutex_held (void)
void fsl__mutex_leave (void)
int fsl__pclose2 (int fdIn, FILE *pOut, int childPid)
int fsl__phantom_new (fsl_cx *f, fsl_uuid_cstr uuid, bool isPrivate, fsl_id_t *newId)
int fsl__phantom_rid_add (fsl_cx *f, fsl_id_t rid)
 Inserts the given rid into the repo.phantom table.
int fsl__popen2 (const char *zCmd, int *pfdIn, FILE **ppOut, int *pChildPid)
void fsl__pq_clear (fsl__pq *p)
fsl_id_t fsl__pq_extract (fsl__pq *p, void **pp)
int fsl__pq_insert (fsl__pq *p, fsl_id_t e, double v, void *pData)
int fsl__private_rid_add (fsl_cx *f, fsl_id_t rid)
 Inserts the given rid into the repo.private table.
int fsl__private_rid_delete (fsl_cx *f, fsl_id_t rid)
 Deletes the given rid from the repo.private table.
void fsl__ptl_clear (fsl__ptl *c)
bool fsl__ptl_has (fsl__ptl const *c, fsl__ptl_e where, fsl_id_t rid)
int fsl__ptl_init (fsl__ptl *c, uint16_t prealloc)
int fsl__ptl_insert (fsl__ptl *c, fsl__ptl_e where, fsl_id_t rid)
bool fsl__ptl_remove (fsl__ptl const *c, fsl__ptl_e where, fsl_id_t rid)
int fsl__qsort_cmp_J_cards (void const *lhs, void const *rhs)
int fsl__repo_filename_fnid2 (fsl_cx *f, char const *filename, fsl_id_t *rv, bool createNew)
int fsl__repo_fingerprint_search (fsl_cx *f, fsl_id_t rcvid, char **zOut)
int fsl__repo_import_blob (fsl_cx *f, fsl_input_f inFunc, void *inState, fsl_id_t *rid, fsl_uuid_str *uuid)
 Imports content to f's opened repository's BLOB table using a client-provided input source.
int fsl__repo_import_buffer (fsl_cx *f, fsl_buffer const *bIn, fsl_id_t *rid, fsl_uuid_str *uuid)
 A convenience form of fsl__repo_import_blob(), equivalent to:
int fsl__repo_record_filename (fsl_cx *f)
int fsl__repo_shun_artifacts (fsl_cx *f)
int fsl__repo_verify_at_commit (fsl_cx *f)
int fsl__repo_verify_before_commit (fsl_cx *f, fsl_id_t rid)
void fsl__repo_verify_cancel (fsl_cx *f)
int fsl__rid_delete (fsl_cx *f, fsl_dbrole_e dbRole, char const *zTable, fsl_id_t rid)
 Expects zTable to name a table with an rid field.
int fsl__search_doc_touch (fsl_cx *f, fsl_satype_e saType, fsl_id_t rid, const char *docName)
int fsl__shunned_remove (fsl_cx *f)
int fsl__symlink_copy (char const *zFrom, char const *zTo, bool realLink)
int fsl__tag_insert (fsl_cx *f, fsl_tagtype_e tagtype, char const *zTag, char const *zValue, fsl_id_t srcId, double mtime, fsl_id_t rid, fsl_id_t *outRid)
int fsl__tag_propagate (fsl_cx *f, fsl_tagtype_e tagType, fsl_id_t pid, fsl_id_t tagid, fsl_id_t origId, const char *zValue, double mtime)
int fsl__tag_propagate_all (fsl_cx *f, fsl_id_t pid)
int fsl__ticket_rebuild (fsl_cx *f, char const *zTktId)
int fsl__tmpchmod (char const *z)
 If FSL_PLATFORM_IS_UNIX then this returns the result of chmod(2) for the given file name, converted from errno using fsl_errno_to_rc().
int fsl__tmpfile (fsl_buffer *tgt, char const *zBaseName)
unsigned char * fsl__tokenizer_next (fsl__tokenizer *pIn, fsl_size_t *pLen)
int fsl__unclustered_rid_add (fsl_cx *f, fsl_id_t rid)
 Inserts the given rid into the repo.unclustered table.
int fsl__unsent_rid_add (fsl_cx *f, fsl_id_t rid)
 Inserts the given rid into the repo.unsent table.
fsl_id_t fsl__uuid_to_rid2 (fsl_cx *f, fsl_uuid_cstr uuid, fsl__phantom_e mode)
int fsl__vfile_to_ckout (fsl_cx *f, fsl_id_t vfileId, int *wasWritten)
fsl_xfcard const * fsl__xfcard_search (unsigned char const *z)
fsl_xfcard_hash_t fsl_xfcard_hash (unsigned const char *word)

Variables

const fsl_cx fsl__cx_empty
const fsl__diff_cx fsl__diff_cx_empty
const fsl__mcache fsl__mcache_empty
const fsl__pq fsl__pq_empty
const fsl__tokenizer fsl__tokenizer_empty
const fsl__xfer fsl__xfer_empty
 Empty-initialized fsl__xfer instance, intended for copy initialization.

Macro Definition Documentation

◆ E [1/3]

#define E ( NAME,
IGNORED )
Value:
fsl__cx_stmt_e_ ## NAME,

Definition at line 318 of file internal.h.

◆ E [2/3]

#define E ( X)
Value:
fsl__ptl_e_ ## X,

Definition at line 318 of file internal.h.

◆ E [3/3]

#define E ( X)
Value:
A container type for lists of db record IDs.
Definition util.h:5694

Definition at line 318 of file internal.h.

Referenced by fsl__ptl_line::fsl__ptl_line_map().

◆ fsl__bccache_empty_m

#define fsl__bccache_empty_m
Value:
{ \
.szTotal = 0U, \
.szLimit = 20000000U/*Historical fossil value=50M*/, \
.used = 0U, .usedLimit = 400U/*Historical fossil value=500*/,\
.capacity = 0, \
.nextAge = 0, \
.changeMarker = 0, \
.list = NULL, \
.inCache = fsl_id_bag_empty_m, \
.metrics = {.hits = 0U, .misses = 0U} \
}
#define fsl_id_bag_empty_m
Initialized-with-defaults fsl_id_bag structure, intended for in-struct initialization.
Definition util.h:5727

Empty-initialized fsl__bccache structure, intended for const-copy initialization.

Definition at line 220 of file internal.h.

◆ fsl__bccache_line_empty_m

#define fsl__bccache_line_empty_m   { 0,0,fsl_buffer_empty_m }

Empty-initialized fsl__bccache_line structure.

Definition at line 135 of file internal.h.

◆ fsl__buffer_err

#define fsl__buffer_err ( B)
Value:
(B)->errCode

Internal impl of fsl_buffer_err(), implemented as a macro for efficiency's sake.

Definition at line 2622 of file internal.h.

◆ fsl__cx_cache_stmt_map

#define fsl__cx_cache_stmt_map ( E)

Definition at line 894 of file internal.h.

Referenced by fsl__cx_caches_reset().

◆ fsl__cx_ptl_has

#define fsl__cx_ptl_has ( F,
W,
R )
Value:
fsl__ptl_has(&(F)->cache.ptl, W, R)
bool fsl__ptl_has(fsl__ptl const *c, fsl__ptl_e where, fsl_id_t rid)

Definition at line 3333 of file internal.h.

◆ fsl__cx_ptl_insert

#define fsl__cx_ptl_insert ( F,
W,
R )
Value:
fsl__ptl_insert(&(F)->cache.ptl, W, R)
int fsl__ptl_insert(fsl__ptl *c, fsl__ptl_e where, fsl_id_t rid)

Definition at line 3334 of file internal.h.

◆ fsl__cx_txn

#define fsl__cx_txn ( FslCx,
RcVar,
RollbackTopOnError,
KeepSPOnSuccess,
BODY )
Value:
{ \
RcVar = fsl_cx_txn_begin(FslCx); \
if( 0==RcVar ){ \
BODY \
} \
int const RcVar ## __ = \
fsl_cx_txn_end_v2((FslCx), (0==RcVar) && (KeepSPOnSuccess), \
((RollbackTopOnError) && (0!=RcVar))); \
if( !RcVar ) RcVar = RcVar ## __; \
}
FSL_EXPORT int fsl_cx_txn_begin(fsl_cx *f)
Returns the same as passing fsl_cx_db() to fsl_db_txn_begin().

An experiment.

Runs BODY ( a {...} block) in the context of a fsl_cx savepoint. The body is expected to assign int-type RcVar to 0 on success and false on error. If RcVar is 0 when this is invoked, BODY is not run. If BODY succeeds, the savepoint is saved if KeepSPOnSuccess is true, else it is silently discarded. If RollbackTopOnError is true then any outer savepoint is put into a persistent rollback state, else any outer savepoint is unaffected. If BODY succeeds but the commit/rollback fails, RcVar is set to that failure code.

Definition at line 3283 of file internal.h.

◆ fsl__cx_txn_global

#define fsl__cx_txn_global ( FslCx,
RcVar,
KeepSPOnSuccess,
BODY )
Value:
fsl__cx_txn(FslCx, RcVar, 1, KeepSPOnSuccess, BODY)
#define fsl__cx_txn(FslCx, RcVar, RollbackTopOnError, KeepSPOnSuccess, BODY)
An experiment.
Definition internal.h:3283

fsl__cx_txn() proxy for use with local savepoints which should trigger a global savepoint rollback on error.

Definition at line 3305 of file internal.h.

◆ fsl__cx_txn_local

#define fsl__cx_txn_local ( FslCx,
RcVar,
KeepSPOnSuccess,
BODY )
Value:
fsl__cx_txn(FslCx, RcVar, 0, KeepSPOnSuccess, BODY)

fsl__cx_txn() proxy for use with local savepoints which should not trigger a global savepoint rollback on error.

Definition at line 3298 of file internal.h.

◆ fsl__diff_cx_empty_m

#define fsl__diff_cx_empty_m
Value:
{\
NULL,0,0,NULL,0,NULL,0,fsl_dline_cmp \
}
FSL_EXPORT int fsl_dline_cmp(const fsl_dline *pA, const fsl_dline *pB)
Compares two fsl_dline instances using memcmp() semantics, returning 0 if they are equivalent.

Initialized-with-defaults fsl__diff_cx structure, intended for const-copy initialization.

Definition at line 2368 of file internal.h.

◆ FSL__LINE_LENGTH_MASK

#define FSL__LINE_LENGTH_MASK   ((1<<FSL__LINE_LENGTH_MASK_SZ)-1)

Bitmask which, when AND-ed with a number, will result in the bottom FSL__LINE_LENGTH_MASK_SZ bits of that number.

Definition at line 2615 of file internal.h.

◆ FSL__LINE_LENGTH_MASK_SZ

#define FSL__LINE_LENGTH_MASK_SZ   15

Maximum length of a line in a text file, in bytes. (2**15 = 32k)

Definition at line 2608 of file internal.h.

◆ fsl__mcache_empty_m

#define fsl__mcache_empty_m
Value:
{ \
.nextAge=0, .hits=0, .misses=0, \
.aAge = {0,0,0,0}, \
}
#define fsl_deck_empty_m
Initialized-with-defaults fsl_deck structure, intended for in-struct and const copy initialization.
Definition repo.h:536

Initialized-with-defaults fsl__mcache structure, intended for const-copy initialization.

Definition at line 277 of file internal.h.

◆ fsl__pq_empty_m

#define fsl__pq_empty_m   {0,0,NULL}

Empty-initialized fsl__pq struct, intended for const-copy initialization.

Definition at line 82 of file internal.h.

◆ fsl__pq_entry_empty_m

#define fsl__pq_entry_empty_m   {0,NULL,0.0}

Empty-initialized fsl__pq_entry structure.

Definition at line 62 of file internal.h.

◆ fsl__ptl_empty_m

#define fsl__ptl_empty_m
Value:
{ \
.rc = 0, .allocated = 0, .level = 0, \
.validateRidLevel = -1, \
.stack = NULL, .line = NULL, \
}
#define fsl_buffer_empty_m
Empty-initialized fsl_buffer instance, intended for const-copy initialization.
Definition util.h:764

Empty-initialized fsl__ptl struct.

Definition at line 382 of file internal.h.

◆ fsl__ptl_line_map

#define fsl__ptl_line_map ( E)
Value:
E(toVerify/*RIDs of blobs added at this level*/) \
E(leafCheck/*Used during the processing of manifests to keep track
of "leaf checks" which need to be done downstream.*/) \
E(available/*RIDs of known-available content*/) \
E(missing/*RIDs of known-missing content*/) \
E(dephantomize/*An experiment in queueing up dephantomization work*/)
#define E(N, V, H)
Definition core.h:497

Expands to a list of the names of all fsl_id_bag members of the fsl__ptl_line struct by invoking macro E(NAME) once for each name.

Definition at line 306 of file internal.h.

◆ fsl__tokenizer_empty_m

#define fsl__tokenizer_empty_m   {NULL,NULL,false}

Definition at line 2679 of file internal.h.

◆ fsl__xfcard_searchNU

#define fsl__xfcard_searchNU ( WORD)
Value:
fsl__xfcard_search((unsigned const char *)(WORD))
fsl_xfcard const * fsl__xfcard_search(unsigned char const *z)

Non-unsigned-qualified C-string convenience form of fsl__xfcard_search().

Definition at line 3062 of file internal.h.

◆ FSL_ENABLE_MUTEX

#define FSL_ENABLE_MUTEX   0

Determine whether fsl__mutex_enter() and friends are no-ops.

If we'd require C11 then we could use C11's mutexes instead of sqlite3's, but we have those handy so we might as well use them.

Definition at line 31 of file internal.h.

◆ fsl_xfcard_hash_1

#define fsl_xfcard_hash_1 ( W)
Value:
#define fsl_xfcard_hash_step(H, I, WORD)
Definition internal.h:2990

Compile-time hashers for words of length 1..11.

Definition at line 3020 of file internal.h.

◆ fsl_xfcard_hash_10

#define fsl_xfcard_hash_10 ( W)
Value:
#define fsl_xfcard_hash_9(W)
Definition internal.h:3028

Definition at line 3029 of file internal.h.

◆ fsl_xfcard_hash_11

#define fsl_xfcard_hash_11 ( W)
Value:
#define fsl_xfcard_hash_10(W)
Definition internal.h:3029

Definition at line 3030 of file internal.h.

◆ fsl_xfcard_hash_2

#define fsl_xfcard_hash_2 ( W)
Value:
#define fsl_xfcard_hash_1(W)
Definition internal.h:3020

Definition at line 3021 of file internal.h.

◆ fsl_xfcard_hash_3

#define fsl_xfcard_hash_3 ( W)
Value:
#define fsl_xfcard_hash_2(W)
Definition internal.h:3021

Definition at line 3022 of file internal.h.

◆ fsl_xfcard_hash_4

#define fsl_xfcard_hash_4 ( W)
Value:
#define fsl_xfcard_hash_3(W)
Definition internal.h:3022

Definition at line 3023 of file internal.h.

◆ fsl_xfcard_hash_5

#define fsl_xfcard_hash_5 ( W)
Value:
#define fsl_xfcard_hash_4(W)
Definition internal.h:3023

Definition at line 3024 of file internal.h.

◆ fsl_xfcard_hash_6

#define fsl_xfcard_hash_6 ( W)
Value:
#define fsl_xfcard_hash_5(W)
Definition internal.h:3024

Definition at line 3025 of file internal.h.

◆ fsl_xfcard_hash_7

#define fsl_xfcard_hash_7 ( W)
Value:
#define fsl_xfcard_hash_6(W)
Definition internal.h:3025

Definition at line 3026 of file internal.h.

◆ fsl_xfcard_hash_8

#define fsl_xfcard_hash_8 ( W)
Value:
#define fsl_xfcard_hash_7(W)
Definition internal.h:3026

Definition at line 3027 of file internal.h.

◆ fsl_xfcard_hash_9

#define fsl_xfcard_hash_9 ( W)
Value:
#define fsl_xfcard_hash_8(W)
Definition internal.h:3027

Definition at line 3028 of file internal.h.

◆ fsl_xfcard_hash_N

#define fsl_xfcard_hash_N ( N,
W )
Value:
fsl_xfcard_hash_ ## N(W)

Definition at line 3031 of file internal.h.

◆ fsl_xfcard_hash_step

#define fsl_xfcard_hash_step ( H,
I,
WORD )
Value:
fsl_xfcard_hash_step_ch(H,I,(#WORD[I]))
#define fsl_xfcard_hash_step_ch(H, I, CHAR)
Definition internal.h:2971

Slightly-convenience form of fsl_xfcard_hash_step_ch() which takes its 3rd argument as an unquoted word.

The first invocation for a given WORD must pass 0 for H and I. Each subsequent call must pass the result the previous call as its H, an incremented-by-1 I value, and the same WORD.

Definition at line 2990 of file internal.h.

◆ fsl_xfcard_hash_step_ch

#define fsl_xfcard_hash_step_ch ( H,
I,
CHAR )
Value:
(((((fsl_xfcard_hash_t)H << 1) + (I+1)) * (CHAR - fsl_xfcard_LowestIdChar-1)) ^ CHAR)
#define fsl_xfcard_LowestIdChar
Lowest-valued legal identifier character in a sync card name.
Definition internal.h:2953
uint32_t fsl_xfcard_hash_t
Definition internal.h:2947

Internal impl for one hash step of fsl_xfcard_hash() and the HASH#() family of macros (for compile-time hashes). Arguments:

  • H is the current hash value (starting at 0)
  • I is the char index into the word we're hashing.
  • CHAR is the character at index I of the word.

Reminder to self:

collision with "else" and "eval": h = (h << 1) + (++i) * (CHAR - 35)

Definition at line 2971 of file internal.h.

◆ fsl_xfcard_hashS

#define fsl_xfcard_hashS ( WORD)
Value:
fsl_xfcard_hash((unsigned const char *)WORD)
fsl_xfcard_hash_t fsl_xfcard_hash(unsigned const char *word)

Non-unsigned-qualified C-string convenience form of fsl_xfcard_hash().

Definition at line 3014 of file internal.h.

◆ fsl_xfcard_LowestIdChar

#define fsl_xfcard_LowestIdChar   '$'

Lowest-valued legal identifier character in a sync card name.

This plays a role in the hash.

Definition at line 2953 of file internal.h.

◆ fsl_xfcard_MaxCardNameLen

#define fsl_xfcard_MaxCardNameLen   11 /*==strlen("clone_seqno")*/

Definition at line 2954 of file internal.h.

◆ STMT

#define STMT ( MEMBER,
IGNORED )
Value:
fsl_stmt MEMBER;
Represents a prepared statement handle.
Definition db.h:555

Definition at line 946 of file internal.h.

Typedef Documentation

◆ fsl__bccache

typedef struct fsl__bccache fsl__bccache

Definition at line 39 of file internal.h.

◆ fsl__bccache_line

typedef struct fsl__bccache_line fsl__bccache_line

Definition at line 40 of file internal.h.

◆ fsl__cx_StaticAssertScratchpadSizes

typedef int fsl__cx_StaticAssertScratchpadSizes[((sizeof(fsl__cx_empty.scratchpads.buf)/sizeof(fsl__cx_empty.scratchpads.buf[0]))==(sizeof(fsl__cx_empty.scratchpads.used)/sizeof(fsl__cx_empty.scratchpads.used[0]))) ? 1 :-1]

Ensure that fsl_cx::scratchpads::buf/used have the same array size.

Definition at line 1052 of file internal.h.

◆ fsl__diff_cx

typedef struct fsl__diff_cx fsl__diff_cx

Convenience typeef.

Definition at line 2364 of file internal.h.

◆ fsl__localmod_e

Definition at line 2150 of file internal.h.

◆ fsl__mcache

typedef struct fsl__mcache fsl__mcache

Convenience typedef.

Definition at line 272 of file internal.h.

◆ fsl__mcache_StaticAssertArraySizes

typedef int fsl__mcache_StaticAssertArraySizes[((sizeof(fsl__mcache_empty.aAge)/sizeof(fsl__mcache_empty.aAge[0]))==(sizeof(fsl__mcache_empty.decks)/sizeof(fsl__mcache_empty.decks[0]))) ? 1 :-1]

This will fail to compile if the arrays fsl__mcache::aAge and fsl__mcache::decks have different sizes.

They must have the same size.

Definition at line 294 of file internal.h.

◆ fsl__phantom_e

Definition at line 1471 of file internal.h.

◆ fsl__pq

typedef struct fsl__pq fsl__pq

Definition at line 41 of file internal.h.

◆ fsl__pq_entry

typedef struct fsl__pq_entry fsl__pq_entry

Definition at line 42 of file internal.h.

◆ fsl__ptl

typedef struct fsl__ptl fsl__ptl

Definition at line 379 of file internal.h.

◆ fsl__ptl_e

typedef enum fsl__ptl_e fsl__ptl_e

Definition at line 351 of file internal.h.

◆ fsl__ptl_line

typedef struct fsl__ptl_line fsl__ptl_line

Definition at line 339 of file internal.h.

◆ fsl__tokenizer

typedef struct fsl__tokenizer fsl__tokenizer

Definition at line 2678 of file internal.h.

◆ fsl__xfer

typedef struct fsl__xfer fsl__xfer

Definition at line 2896 of file internal.h.

◆ fsl_xfcard

typedef struct fsl_xfcard fsl_xfcard

Definition at line 3046 of file internal.h.

◆ fsl_xfcard_hash_t

typedef uint32_t fsl_xfcard_hash_t

Hash value for fsl_xfcard card name hashing.

This algo historically uses 32-bit hashes because the values (generated at build-time) were used in switch/case contexts, where 64-bit values are not portable.

Definition at line 2947 of file internal.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
fsl__xfer_max_tokens 

Max number of expected tokens in fsl__xfer::line.

This number is inherited from fossil(1).

Definition at line 2699 of file internal.h.

◆ fsl__cx_stmt_e

Enumerator
fsl__cx_cache_stmt_map 

Definition at line 3217 of file internal.h.

◆ fsl__localmod_e

Bitmask of file change types for use with fsl__is_locally_modified().

Enumerator
FSL__LOCALMOD_NONE 

Sentinel value.

FSL__LOCALMOD_PERM 

Permissions changed.

FSL__LOCALMOD_CONTENT 

File size or hash (i.e.

content) differ.

FSL__LOCALMOD_LINK 

The file type was switched between symlink and normal file.

In this case, no check for content change, beyond the file size change, is performed.

FSL__LOCALMOD_NOTFOUND 

File was not found in the local checkout.

Definition at line 2128 of file internal.h.

◆ fsl__phantom_e

Flags for APIs which add phantom blobs to the repository. The values in this enum derive from fossil(1) code and should not be changed without careful forethought and (afterwards) testing. A phantom blob is a blob about whose existence we know but for which we have no content. This normally happens during sync or rebuild operations, but can also happen when artifacts are stored directly as files in a repo (like this project's repository does, storing artifacts from other projects for testing purposes).

Enumerator
FSL_PHANTOM_NONE 

Indicates to fsl__uuid_to_rid2() that no phantom artifact should be created.

FSL_PHANTOM_PUBLIC 

Indicates to fsl__uuid_to_rid2() that a public phantom artifact should be created if no artifact is found.

FSL_PHANTOM_PRIVATE 

Indicates to fsl__uuid_to_rid2() that a private phantom artifact should be created if no artifact is found.

Definition at line 1454 of file internal.h.

◆ fsl__ptl_e

enum fsl__ptl_e

Enum entries corresponding to fsl__ptl_line members.

Enumerator
fsl__ptl_e_dummy 

Sentinel value needed in slot 0.

fsl__ptl_line_map 

Definition at line 344 of file internal.h.

◆ fsl_card_J_flags

Values for fsl_card_J::flags.

Enumerator
FSL_CARD_J_INVALID 

Sentinel value.

FSL_CARD_J_TICKET 

Indicates that the field is used by the ticket table.

FSL_CARD_J_CHNG 

Indicates that the field is used by the ticketchng table.

FSL_CARD_J_BOTH 

Indicates that the field is used by both the ticket and ticketchng tables.

Definition at line 1606 of file internal.h.

Function Documentation

◆ fsl__bccache_check_available()

int fsl__bccache_check_available ( fsl_cx * f,
fsl_id_t rid )

Checks f->cache.blobContent to see if rid is available in the repository opened by f.

Returns 0 if the content for the given rid is available in the repo or the cache. Returns FSL_RC_NOT_FOUND if it is not in the repo nor the cache. Returns some other non-0 code for "real errors," e.g. FSL_RC_OOM if a cache allocation fails. This operation may update the cache's contents.

If this function detects a loop in artifact lineage, it fails an assert() in debug builds and returns FSL_RC_CONSISTENCY in non-debug builds. That doesn't happen in real life, though.

Reminder to self: it should arguably return FSL_RC_PHANTOM if it's a phantom but the next call for that same rid would pull from f->cache.blobContent.missing and lose the distinction between "wasn't found" and "is a phantom", so would have to return FSL_RC_NOT_FOUND. If we ever need another fsl_id_bag for tracking phantoms, we can adjust this to return FSL_RC_PHANTOM by checking that bag for the RID.

◆ fsl__bccache_clear()

void fsl__bccache_clear ( fsl__bccache * c)

Frees all memory held by c, and clears out c's state, but does not free c. Results are undefined if !c.

◆ fsl__bccache_expire_oldest()

bool fsl__bccache_expire_oldest ( fsl__bccache * c)

Expires the single oldest entry in c. Returns true if it removes an item, else false.

◆ fsl__bccache_insert()

int fsl__bccache_insert ( fsl__bccache * c,
fsl_id_t rid,
fsl_buffer * pBlob )

Add an entry to the content cache.

This routines transfers the contents of pBlob over to c, regardless of success or failure. The cache will deallocate the memory when it has finished with it.

If the cache cannot add the entry due to cache-internal constraints, as opposed to allocation errors, it clears the buffer (for consistency's sake) and returns 0.

Returns 0 on success, FSL_RC_OOM on allocation error. Has undefined behaviour if !c, rid is not semantically valid, !pBlob. An empty blob is normally semantically illegal but is not strictly illegal for this cache's purposes.

◆ fsl__bccache_reuse()

void fsl__bccache_reuse ( fsl__bccache * c)

Resets all bags associated with the given cache and frees all cached buffer memory, but keeps any fsl_id_bag memory intact for re-use. This does not reset the hit/miss metrics.

◆ fsl__bprc()

void fsl__bprc ( int rc)

A place to put a breakpoint to help trace down errors.

Pass it the rc of a just-failed operation and set a breakpoint in the if(rc) block of this function in fsl.c.

◆ fsl__call_xlink_listeners()

int fsl__call_xlink_listeners ( fsl_deck * d)

Calls all registered crosslink link listeners, passing each the given deck. Returns 0 if there are no listeners or if all return 0, else it propagates an error from a failed listener.

This must only be called while crosslinking is underway.

See also
fsl_xlink_listener()

◆ fsl__card_J_list_free()

void fsl__card_J_list_free ( fsl_list * li,
bool alsoListMem )

Frees all J-card entries in the given list.

li is assumed to be empty or contain (fsl_card_J*) instances. If alsoListMem is true then any memory owned by li is also freed. li itself is not freed.

Results are undefined if li is NULL.

◆ fsl__ckout_clear_merge_state()

int fsl__ckout_clear_merge_state ( fsl_cx * f,
bool fullWipe )

Clears any pending merge state from the f's checkout db's vmerge table. Returns 0 on success, non-0 on db error.

If fullWipe is true, it clears all vfile contents uncondtionally, else it clears only entries for which the corresponding vfile entries are marked as unchanged and then cleans up remaining merge state if no file-level merge changes are pending.

◆ fsl__ckout_install_schema()

int fsl__ckout_install_schema ( fsl_cx * f,
bool dropIfExists )

Installs or reinstalls the checkout database schema into f's open checkout db. Returns 0 on success, FSL_RC_NOT_A_CKOUT if f has no opened checkout, or an code if a lower-level operation fails.

If dropIfExists is true then all affected tables are dropped beforehand if they exist. "It's the only way to be sure."

If dropIfExists is false and the schema appears to already exists (without actually validating its validity), 0 is returned.

◆ fsl__ckout_rid()

int fsl__ckout_rid ( fsl_cx * f,
fsl_id_t * rid )

Sets *rid to f->db.ckout.rid, fetching the latter if needed.

Returns non-0 if fetching fails.

◆ fsl__ckout_rm_empty_dirs()

unsigned int fsl__ckout_rm_empty_dirs ( fsl_cx * f,
fsl_buffer const * tgtDir )

Attempts to remove empty directories from under a checkout, starting with tgtDir and working upwards until it either cannot remove one or it reaches the top of the checkout dir.

The second argument must be the canonicalized absolute path to some directory under the checkout root. The contents of the buffer may, for efficiency's sake, be modified by this routine as it traverses the directory tree. It will never grow the buffer but may mutate its memory's contents.

Returns the number of directories it is able to remove.

Results are undefined if tgtDir is not an absolute path rooted in f's current checkout.

There are any number of valid reasons removal of a directory might fail, and this routine stops at the first one which does.

◆ fsl__ckout_rm_empty_dirs_for_file()

int fsl__ckout_rm_empty_dirs_for_file ( fsl_cx * f,
char const * zAbsPath )

This is intended to be passed the name of a file which was just deleted and "might" have left behind an empty directory. The name must an absolute path based in f's current checkout. This routine uses fsl_file_dirpart() to strip path components from the string and remove directories until either removing one fails or the top of the checkout is reached. Since removal of a directory can fail for any given reason, this routine ignores such errors. It returns 0 on success, FSL_RC_OOM if allocation of the working buffer for the filename hackery fails, and FSL_RC_MISUSE if zFilename is not rooted in the checkout (in which case it may assert(), so don't do that).

See also
fsl_is_rooted_in_ckout()
fsl_rm_empty_dirs()

◆ fsl__ckout_safe_file_check()

int fsl__ckout_safe_file_check ( fsl_cx * f,
char const * zFilename )

Checks whether the given filename is "safe" for writing to within f's current checkout.

zFilename must be in canonical form: only '/' directory separators. If zFilename is not absolute, it is assumed to be relative to the top of the current checkout, else it must point to a file under the current checkout.

Checks made on the filename include:

  • It must refer to a file under the current checkout.
  • Ensure that each directory listed in the file's path is actually a directory, and fail if any part other than the final one is a non-directory.

If the name refers to something not (yet) in the filesystem, that is not considered an error.

Returns 0 on success. On error f's error state is updated with information about the problem.

◆ fsl__ckout_symlink_create()

int fsl__ckout_symlink_create ( fsl_cx * f,
char const * zTgtFile,
char const * zLinkFile )

UNTESTED!

Creates a file named zLinkFile and populates its contents with a single line: zTgtFile. This behaviour corresponds to how fossil manages SCM'd symlink entries on Windows and on other platforms when the 'allow-symlinks' repo-level config setting is disabled. (In late 2020 fossil defaulted that setting to disabled and made it non-versionable.)

zLinkFile may be an absolute path rooted at f's current checkout or may be a checkout-relative path.

Returns 0 on success, non-0 on error:

  • FSL_RC_NOT_A_CKOUT if f has no opened checkout.
  • FSL_RC_MISUSE if zLinkFile refers to a path outside of the current checkout.

Potential TODO (maybe!): handle symlinks as described above or "properly" on systems which natively support them iff f's 'allow-symlinks' repo-level config setting is true. That said: the addition of symlinks support into fossil was, IMHO, a poor decision for $REASONS. That might (might) be reflected long-term in this API by only supporting them in the way fossil does for platforms which do not support symlinks.

◆ fsl__ckout_version_fetch()

int fsl__ckout_version_fetch ( fsl_cx * f)

Updates f->ckout.uuid and f->ckout.rid to reflect the current checkout state. If no checkout is opened, the uuid is freed/NULLed and the rid is set to 0. Returns 0 on success. If it returns an error (OOM or db-related), the f->ckout state is left in a potentially inconsistent state, and it should not be relied upon until/unless the error is resolved.

This is done when a checkout db is opened, when performing a checkin, and otherwise as needed, and so calling it from other code is normally not necessary.

See also
fsl__ckout_version_write()

◆ fsl__ckout_version_write()

int fsl__ckout_version_write ( fsl_cx * f,
fsl_id_t vid,
fsl_uuid_cstr uuid )

Updates f->ckout's state to reflect the given version info and writes the 'checkout' and 'checkout-hash' properties to the currently-opened checkout db. Returns 0 on success, FSL_RC_NOT_A_CKOUT if no checkout is opened (may assert() in that case!), or some other code if writing to the db fails.

If vid is 0 then the version info is null'd out. Else if uuid is NULL then fsl_rid_to_uuid() is used to fetch the UUID for vid.

If the RID differs from f->ckout.rid then f->ckout's version state is updated to the new values.

This routine also updates or removes the checkout's manifest files, as per fsl_ckout_manifest_write(). If vid is 0 then it removes any such files which themselves are not part of the current checkout.

See also
fsl__ckout_version_fetch()
fsl_cx_ckout_version_set()

◆ fsl__config_inop_rhs()

char * fsl__config_inop_rhs ( int iMask)

.

Return a pointer to a string that contains the RHS of an SQL IN operator which will select config.name values that are part of the configuration that matches iMatch (a bitmask of fsl_configset_e values). Ownership of the returned string is passed to the caller, who must eventually pass it to fsl_free(). Returns NULL on allocation error.

Reminder to self: this is part of the infrastructure for copying config state from an existing repo when creating new repo.

◆ fsl__content_deltify()

int fsl__content_deltify ( fsl_cx * f,
fsl_id_t rid,
fsl_id_t srcid,
bool force )

The converse of fsl__content_undeltify(), this replaces the storage of the given blob record so that it is a delta of srcid.

If rid is already a delta from some other place then no conversion occurs and this is a no-op unless force is true, which case the content is undeltified and re-delta'd against srcid.

If rid's contents are not available because the the rid is a phantom or depends to one, no delta is generated and 0 is returned.

It never generates a delta that carries a private artifact into a public artifact. Otherwise, when we go to send the public artifact on a sync operation, the other end of the sync will never be able to receive the source of the delta. It is OK to delta private->private, public->private, and public->public. Just no private->public delta. For such cases this function returns 0, as opposed to FSL_RC_ACCESS or some similar code, and leaves the content untouched.

If srcid is a delta that depends on rid, then srcid is converted to undelta'd text.

If either rid or srcid contain less than some "small, unspecified number" of bytes (currently 50), or if the resulting delta does not achieve a compression of at least 25%, the rid is left untouched.

Returns 0 if a delta is successfully made or none needs to be made, non-0 on error.

Requires that fsl_cx_txn_level() be greater than 0.

See also
fsl__content_undeltify()

◆ fsl__content_put()

int fsl__content_put ( fsl_cx * f,
fsl_buffer const * pBlob,
fsl_id_t * newRid )

Equivalent to fsl__content_put_ex(f,pBlob,NULL,0,0,false,newRid).

This must only be used for saving raw (non-delta) content.

See also
fsl__content_put_ex()

◆ fsl__content_put_ex()

int fsl__content_put_ex ( fsl_cx * f,
fsl_buffer const * pBlob,
fsl_uuid_cstr zUuid,
fsl_id_t srcId,
fsl_size_t uncompSize,
bool isPrivate,
fsl_id_t * outRid )

This is THE ONLY ROUTINE IN THE LIBRARY which is permitted to add content to the blob table. Only one other routine (fsl__phantom_new()) adds new blob entries, but that one does not add blobs with content.

This writes the given buffer content into the repository database's blob tabe. It Returns the record ID via outRid (if it is not NULL). If the content is already in the database (as determined by a lookup of its hash against blob.uuid), this routine fetches the RID (via *outRid) but has no side effects in the repo.

If srcId is >0 then pBlob must contain delta content from the srcId record. srcId might be a phantom.

pBlob is normally uncompressed text, but if uncompSize>0 then the pBlob value is assumed to be compressed (via fsl_buffer_compress() or equivalent) and uncompSize is its uncompressed size. If uncompSize>0 then zUuid must be valid and refer to the hash of the uncompressed data (which is why this routine does not calculate it for the client).

Sidebar 2025-08-04: it is legal for the uncompressed size to be 0 when the content is compressed (and larger). That case can't be represented with the above semantics. Do we actually handle the empty-file case properly?

Sidebar: we "could" use fsl_buffer_is_compressed() and friends to determine if pBlob is compressed and get its decompressed size, then remove the uncompSize parameter, but that would require that this function decompress the content to calculate the hash. Since the caller likely just compressed it, that seems like a huge waste.

zUuid is the UUID of the artifact, if it is not NULL. When srcId is specified then zUuid must always be specified. If srcId is zero, and zUuid is zero then the correct zUuid is computed from pBlob. If zUuid is not NULL then this function asserts (in debug builds) that fsl_is_uuid() returns true for zUuid.

If isPrivate is true or if f->cache.markPrivate is true, the blob is created as a private record.

If the record already exists but is a phantom, the pBlob content is inserted and the phatom becomes a real record.

The original content of pBlob is not disturbed. The caller continues to be responsible for pBlob. This routine does not take over responsibility for freeing pBlob.

If outRid is not NULL then on success *outRid is assigned to the RID of the underlying blob record.

Returns 0 on success and there are too many potential error cases to name - this function is a massive beast.

On success, the new blob's RID is queued up for pre-commit content validation. If this is the first call to this function in the current transaction stack, the RID is queued in the COMMIT handler for the parent transaction. Subsequent calls will cause the RID to be queued in that same transaction level. We cannot validate in this function because the validation would trigger at the end of the transaction level which this function installs. Content validation has to be delayed until we believe we have all content which will be injected in the current transaction stack.

See also
fsl__content_put()

◆ fsl__content_undeltify()

int fsl__content_undeltify ( fsl_cx * f,
fsl_id_t rid )

If the given blob ID refers to deltified repo content, this routine undeltifies it and replaces its content with its expanded form.

Returns 0 on success, FSL_RC_NOT_A_REPO if f has no opened repository, FSL_RC_RANGE if rid is not positive, and any number of other potential errors during the db and content operations. This function treats already unexpanded content as success.

See also
fsl__content_deltify()

◆ fsl__crosslink_begin()

int fsl__crosslink_begin ( fsl_cx * f)

This starts a transaction (possibly nested) on the repository db and initializes some temporary db state needed for the crosslinking certain artifact types. It "should" (see below) be called at the start of the crosslinking process. Crosslinking can* work without this but certain steps for certain (subject to change) artifact types will be skipped, possibly leading to unexpected timeline data or similar funkiness. No permanent SCM-relevant state will be missing, but the timeline might not be updated and tickets might not be fully processed. This should be used before crosslinking any artifact types, but will only have significant side effects for certain (subject to change) types.

Returns 0 on success.

If it returns 0 then the caller is OBLIGATED to either 1) call fsl__crosslink_end() or 2) call fsl_db_txn_rollback() and set f->cache.isCrosslinking to false. This process may install temporary tables and/or triggers, so failing to call one or the other of those will result in misbehavior.

See also
fsl__deck_crosslink()

◆ fsl__crosslink_end()

int fsl__crosslink_end ( fsl_cx * f,
int resultCode )

Must not be called unless fsl__crosslink_begin() has succeeded. This performs crosslink post-processing on certain artifact types and cleans up any temporary db state initialized by fsl__crosslink_begin().

If the 2nd argument is not 0 then this routine triggers a rollback of the transaction started by fsl__crosslink_begin() and propagates any pending error code from f or (if f has no error code) from f's db handle.

The second argument is intended to be the value of any pending result code (0 or otherwise) from any work done after fsl__crosslink_begin() succeeded. If passed 0, it assumes that there is no propagating error state and will attempt to complete the crosslinking process. If passed non-0, it triggers a rollback and unsets the f->cache.isCrosslinking flag, but does no additional work, then returns resultCode.

Returns 0 on success. On error it initiates (or propagates) a rollback for the current transaction. If called when a rollback is pending, it unsets the crosslink-is-running flag and returns the propagating result code.

◆ fsl__cx_attach_role()

int fsl__cx_attach_role ( fsl_cx * f,
const char * zDbName,
fsl_dbrole_e r,
bool createIfNotExists )

Attaches the given db file to f with the given role. This function "should" be static but we need it in repo.c when creating a new repository.

This function has tightly-controlled preconditions which will assert if not met. r must be one of FSL_DBROLE_CKOUT or FSL_DBROLE_REPO.

If createIfNotExists is true and zDbName does not exist in the filesystem, it is created before/as part of the OPEN or ATTACH. This is almost never desired, but is required for operations which create a repo (e.g. the aptly-named fsl_repo_create()) or a checkout db (e.g. fsl_repo_open_ckout()).

◆ fsl__cx_caches_reset()

void fsl__cx_caches_reset ( fsl_cx * f,
bool isTxnCommit )

Clears various internal caches and resets various internally-cached values related to repository and checkout dbs.

Its argument must be true if we're clearing caches as a result of a transaction commit, else false.

References E, and fsl__cx_cache_stmt_map.

◆ fsl__cx_ckout_clear()

void fsl__cx_ckout_clear ( fsl_cx * f)

Frees/clears the non-db state of f->ckout.

◆ fsl__cx_content_buffer()

fsl_buffer * fsl__cx_content_buffer ( fsl_cx * f)

Ensures that f's single file content buffer is available for use and returns it to the caller. If it appears to already be in use, this function fails fatally via fsl__fatal(), indicating a serious misuse of the internal API.

Calling this obligates the caller to call fsl__cx_content_buffer_yield() as soon as they are done with the buffer.

◆ fsl__cx_content_buffer_yield()

void fsl__cx_content_buffer_yield ( fsl_cx * f)

Part of the fsl_cx::cache::fileContent optimization. Passes f->cache.fileContent to fsl_buffer_reuse() and if its capacity is over a certain (unspecified, unconfigurable) size then it is trimmed to that size. It also updates some of f's metrics.

◆ fsl__cx_content_caches_clear()

void fsl__cx_content_caches_clear ( fsl_cx * f)

Clears only caches which are relevant to content lookup.

◆ fsl__cx_db_for_role()

fsl_db * fsl__cx_db_for_role ( fsl_cx * f,
fsl_dbrole_e r )

Returns one of f->{repo,ckout}.db or NULL.

ACHTUNG and REMINDER TO SELF: the current (2021-03) design means that none of these handles except for FSL_DBROLE_MAIN actually has an sqlite3 db handle assigned to it. This returns a handle to the "level of abstraction" we need to keep track of each db's name and db-specific other state.

e.g. passing a role of FSL_DBROLE_CKOUT this does NOT return the same thing as fsl_cx_db_ckout().

◆ fsl__cx_init_db()

int fsl__cx_init_db ( fsl_cx * f,
fsl_db * db )

Plug in fsl_cx-specific db functionality into the given db handle. This must only be passed the MAIN db handle for the context, immediately after opening that handle, before f->dbMain is assigned.

This function has very limited applicability and various preconditions which are assert()ed.

◆ fsl__cx_mcache_clear()

void fsl__cx_mcache_clear ( fsl_cx * f)

Clears the contents of f->cache.mcache.

◆ fsl__cx_ptl_bag()

fsl_id_bag * fsl__cx_ptl_bag ( fsl_cx * f,
fsl__ptl_e which )

Returns the given bag for the current transaction level.

Never returns NULL unless "which" is invalid, in which case it prefers to fail fatally.

◆ fsl__cx_ptl_pop()

int fsl__cx_ptl_pop ( fsl_cx * f,
bool isCommit )

Can fail with OOM if isCommit and f->cache.ptl.level>0.

◆ fsl__cx_ptl_push()

int fsl__cx_ptl_push ( fsl_cx * f)

◆ fsl__cx_ptl_remove()

bool fsl__cx_ptl_remove ( fsl_cx * f,
fsl__ptl_e where,
fsl_id_t rid )

Removes rid from the given PTL list.

◆ fsl__cx_reset_for_txn()

void fsl__cx_reset_for_txn ( fsl_cx * f,
bool isCommit )

May clear or reset cached data.

This is intended to be called as part of a transaction commit/rollback hook and be passed true for a commit and false for a rollback.

◆ fsl__cx_scratchpad()

fsl_buffer * fsl__cx_scratchpad ( fsl_cx * f)

Very, VERY internal.

Returns the next available buffer from f->scratchpads. Fatally aborts if there are no free buffers because "that should not happen." Calling this obligates the caller to eventually pass its result to fsl__cx_scratchpad_yield().

This function guarantees the returned buffer's 'used' member will be set to 0.

Maintenance note: the number of buffers is hard-coded in the fsl_cx::scratchpads anonymous struct.

◆ fsl__cx_scratchpad_yield()

void fsl__cx_scratchpad_yield ( fsl_cx * f,
fsl_buffer * b )

Very, VERY internal.

"Yields" a buffer which was returned from fsl__cx_scratchpad(), making it available for re-use. The caller must treat the buffer as if this routine frees it: using the buffer after having passed it to this function will internally be flagged as explicit misuse and will lead to a fatal crash the next time that buffer is fetched via fsl__cx_scratchpad(). So don't do that.

◆ fsl__cx_see_key()

int fsl__cx_see_key ( fsl_cx * f,
const char * zDbFile,
fsl_buffer * pOut,
int * keyType )

If f has an SEE key-fetching function installed, it is called, its result is returned (but see below), and it is responsible for populating the final two arguments. If no such function is installed, or the function returns FSL_RC_UNSUPPORTED, the 3rd argument is unmodified, *keyType is set to 0, and 0 is returned. See fsl_cx_config::see and fsl_see_key_f() for details.

If a non-0 value other than FSL_RC_UNSUPPORTED or FSL_RC_OOM are returned, f's error state will be updated with a generic message about SEE key init failure.

◆ fsl__cx_stmt()

fsl_stmt * fsl__cx_stmt ( fsl_cx * f,
enum fsl__cx_stmt_e which )

Returns the given cached statement object, preparing it if needed.

If preparation fails then NULL is returned and f->error will hold the details.

If this returns non-NULL then the caller is obligated to pass the same q object to fsl__cx_stmt_yield().

◆ fsl__cx_stmt_yield()

void fsl__cx_stmt_yield ( fsl_cx * f,
fsl_stmt * q )

Must be passed all statement pointers obtained via fsl__cx_stmt().

It MUST NOT be passed any statement from elsewhere except that q==NULL is permitted to simplify its usage. This resets the statement and clears any bindings.

Callers must treat q as if this function finalizes it, i.e. they must not derefence any members or pass it to another API after this. It can only be legally used again after fetching it from fsl__cx_stmt().

◆ fsl__cx_ticket_create_table()

int fsl__cx_ticket_create_table ( fsl_cx * f)

Creates the ticket and ticketchng tables in f's repository db, DROPPING them if they already exist. The schema comes from fsl_schema_ticket().

TODO? Add a flag specifying whether to drop or keep existing copies.

Returns 0 on success.

◆ fsl__cx_ticket_load_fields()

int fsl__cx_ticket_load_fields ( fsl_cx * f,
bool forceReload )

Loads all custom/customizable ticket fields from f's repo's ticket table info f. If f has already loaded the list and forceReload is false, this is a no-op.

Returns 0 on success.

See also
fsl_cx::ticket::customFields

References FSL_CARD_J_INVALID.

◆ fsl__cx_update_seen_delta_deck()

int fsl__cx_update_seen_delta_deck ( fsl_cx * f)

If f->cache.seenDeltaManifest<=0 then this routine sets it to 1 and sets the 'seen-delta-manifest' repository config setting to 1, else this has no side effects. Returns 0 on success, non-0 if there is an error while writing to the repository config.

◆ fsl__db_cached_clear_role()

int fsl__db_cached_clear_role ( fsl_db * db,
fsl_flag32_t role )

This is a fossil-specific internal detail not needed by the more generic parts of the fsl_db API. It loops through all "cached" prepared statements for which stmt->role has been assigned a value which bitmasks as true against the given role and finalizes them. If such a statement is currently held by a call to/via fsl_db_prepare_cachedv() then this will NOT finalize that statement, will update db's error state, and return FSL_RC_MISUSE.

Returns 0 on success.

As a special case, if role==0 then ALL cached statements are closed, with the caveat that the process will still fail if any statement is currently flagged as active.

◆ fsl__db_clear_strings()

void fsl__db_clear_strings ( fsl_db * db,
bool alsoBuffers )

Clears and frees all (char*) members of db but leaves the rest intact. If alsoBuffers is true then the error state and prep buffer are also freed, else they are kept as well.

◆ fsl__db_errcode()

int fsl__db_errcode ( fsl_db * db,
int sqliteCode )

Translates sqliteCode (or, if it's 0, sqlite3_errcode()) to an approximate FSL_RC_xxx match but treats SQLITE_ROW and SQLITE_DONE as non-errors (result code 0). If non-0 is returned db's error state is updated with the current sqlite3_errmsg() string.

◆ fsl__db_repo_verify_schema()

int fsl__db_repo_verify_schema ( fsl_db * db)

Returns 0 if db appears to have a current repository schema, 1 if it appears to have an out of date schema, and -1 if it appears to not be a repository. Results are undefined if db is NULL or not opened.

◆ fsl__db_setting_inop_rhs()

char * fsl__db_setting_inop_rhs ( void )

Return a pointer to a string that contains the RHS of an IN operator that will select config.name values that are in the list of control settings. Ownership of the returned string is passed to the caller, who must eventually pass it to fsl_free(). Returns NULL on allocation error.

Reminder to self: this is part of the infrastructure for copying config state from an existing repo when creating new repo.

◆ fsl__deck_clean_cards()

void fsl__deck_clean_cards ( fsl_deck * d,
char const * letters )

This routine cleans up the state of selected cards in the given deck. The 2nd argument is an list of upper-case letters representing the cards which should be cleaned up, e.g. "ADG". If it is NULL, all cards are cleaned up but d has non-card state which is not cleaned up by this routine. Unknown letters are simply ignored.

◆ fsl__deck_crosslink()

int fsl__deck_crosslink ( fsl_deck * d)

Run automatically by fsl_deck_save(), so it needn't normally be run aside from that, at least not from average client code.

Runs postprocessing on the Structural Artifact represented by d. d->f must be set, d->rid must be set and valid and d's contents must accurately represent the stored manifest for the given rid. This is normally run just after the insertion of a new manifest, but is sometimes also run after reading a deck from the database (in order to rebuild all db relations and add/update the timeline entry).

Returns 0 on succes, FSL_RC_MISUSE !d->f, FSL_RC_RANGE if d->rid<=0, FSL_RC_MISUSE (with more error info in f) if d does not contain all required cards for its d->type value. It may return various other codes from the many routines it delegates work to.

Crosslinking of ticket artifacts is currently (2021-11) missing.

Design note: d "really should" be const here but some internals (d->F.cursor and delayed baseline loading) prohibit it.

See also
fsl__deck_crosslink_one()

◆ fsl__deck_crosslink_one()

int fsl__deck_crosslink_one ( fsl_deck * d)

Run automatically by fsl_deck_save(), so it needn't normally be run aside from that, at least not from average client code.

This is a convience form of crosslinking which must only be used when a single deck (and only a single deck) is to be crosslinked. This function wraps the crosslinking in fsl_crosslink_begin() and fsl__crosslink_end(), but otherwise behaves the same as fsl__deck_crosslink(). If crosslinking fails, any in-progress transaction will be flagged as failed.

Returns 0 on success.

◆ fsl__deck_deltify_parent()

int fsl__deck_deltify_parent ( fsl_deck * d)

If d->P.used then this makes d->P.list[0] a delta from d->rid, else this is a no-op.

Returns non-0 if fetching the parent RID or deltification fail. Returns 0 if there's nothing to do or if what needs doing gets done.

◆ fsl__deck_F_seek()

fsl_card_F * fsl__deck_F_seek ( fsl_deck * d,
const char * zName )

This is identical to the public-API member fsl_deck_F_search(), except that it returns a non-const F-card.

Locate a file named zName in d->F.list. Return a pointer to the appropriate fsl_card_F object. Return NULL if not found.

If d->f is set (as it is when loading decks via fsl_deck_load_rid() and friends), this routine works even if p is a delta-manifest. The pointer returned might be to the baseline and d->B.baseline is loaded on demand if needed.

If the returned card's uuid member is NULL, it means that the file was removed in the checkin represented by d.

If !d, zName is NULL or empty, or FSL_SATYPE_CHECKIN!=d->type, it asserts in debug builds and returns NULL in non-debug builds.

We assume that filenames are in sorted order and use a binary search. As an optimization, to support the most common use case, searches through a deck update d->F.cursor to the last position a search was found. Because searches are normally done in lexical order (because of architectural reasons), this is normally an O(1) operation. It degrades to O(N) if out-of-lexical-order searches are performed.

◆ fsl__delta_delete()

int fsl__delta_delete ( fsl_cx * f,
fsl_id_t rid )

Replaces the repo.delta entry with the given rid.

This does not manipulate the related blobs in any way.

◆ fsl__delta_replace()

int fsl__delta_replace ( fsl_cx * f,
fsl_id_t rid,
fsl_id_t srcid )

Replaces the repo.delta entry with the given rid.

This does not manipulate the related blobs in any way.

◆ fsl__diff_all()

int fsl__diff_all ( fsl__diff_cx * p)

Compute the differences between two files already loaded into the fsl__diff_cx structure.

A divide and conquer technique is used. We look for a large block of common text that is in the middle of both files. Then compute the difference on those parts of the file before and after the common block. This technique is fast, but it does not necessarily generate the minimum difference set. On the other hand, we do not need a minimum difference set, only one that makes sense to human readers, which this algorithm does.

Any common text at the beginning and end of the two files is removed before starting the divide-and-conquer algorithm.

Returns 0 on succes, FSL_RC_OOM on an allocation error.

◆ fsl__diff_cx_clean()

void fsl__diff_cx_clean ( fsl__diff_cx * cx)

◆ fsl__diff_optimize()

void fsl__diff_optimize ( fsl__diff_cx * p)

This function is, as of this writing, only exposed via a header file for the sake of fnc, which still relies on it after we moved the "v1" diff code out of this library and into fnc.

Attempt to shift insertion or deletion blocks so that they begin and end on lines that are pure whitespace. In other words, try to transform this:

int func1(int x){
return x*10;
+}
+
+int func2(int x){
+ return x*20;
}
int func3(int x){
return x/5;
}

Into one of these:

int func1(int x){ int func1(int x){
return x*10; return x*10;
} }
+
+int func2(int x){ +int func2(int x){
+ return x*20; + return x*20;
+} +}
+
int func3(int x){ int func3(int x){
return x/5; return x/5;
} }

◆ fsl__dump_triples()

void fsl__dump_triples ( fsl__diff_cx const * p,
char const * zFile,
int ln )

Undocumented. For internal debugging only. The 2nd argument is intended to be FILE and the 3rd is intended to be LINE.

References fsl__diff_cx_empty.

◆ fsl__fatal()

void fsl__fatal ( int code,
char const * fmt,
... )

Generates an fsl_appendf()-formatted message to stderr and fatally aborts the application by calling exit(). This is only (ONLY!) intended for us as a placeholder for certain test cases and is neither thread-safe nor reantrant.

fmt may be empty or NULL, in which case only the code and its fsl_rc_cstr() representation are output.

This function does not return.

◆ fsl__fdgets()

int fsl__fdgets ( int fdIn,
unsigned char * pOut,
fsl_size_t nOut,
char ** ppOut,
fsl_size_t * pnOut )

An fgets() workalike which uses an unbuffered file descriptor for reading.

Scans the input 1 byte at a time for a '
', appending each read character to pOut, including the '
' and a trailing NUL, up to a maximum of nOut-1 (to account for the NUL). If it hits EOF before finding a
, that is not treated as an error, and downstream code may need to special-case that.

On success it returns 0, sets *ppOut to pOut, and *pnOut to the number of bytes filled out in pOut. On error, returns FSL_RC_IO on read error or FSL_RC_RANGE if no newline is found before nOut bytes are read.

If called when fdIn is at EOF, it will return 0 but set *pnOut to 0.

On error it will return either FSL_RC_RANGE (if it finds now newline before nOut bytes) or propagate an error from the read() call, in the form of another non-0 fsl_rc_e value.

◆ fsl__file_without_drive_letter()

char * fsl__file_without_drive_letter ( char * zFile)

On Windows platforms (only), if fsl_isalpha(*zFile) and ':' == zFile[1] then this returns zFile+2, otherwise it returns zFile.

◆ fsl__find_bin()

int fsl__find_bin ( char const * zPath,
char const * zBinName,
char ** zOut )

Searches the OS path zPath for a binary named zBinName. If found, it puts a library-allocated copy of the resolved name to *zOut (which the caller must eventually pass to fsl_free()) then returns 0.

If zPath is NULL, getenv("PATH") is used.

On error, *zOut is not modified and non-0 is returned:

  • FSL_RC_NOT_FOUND if no match is found. This will also be returned if both zPath and $PATH are NULL.
  • FSL_RC_OOM on allocation error.

On Windows platforms it will extend the search to include a ".exe" extension.

◆ fsl__find_filename_changes()

int fsl__find_filename_changes ( fsl_cx * f,
fsl_id_t iFrom,
fsl_id_t iTo,
bool revOK,
uint32_t * pnChng,
fsl_id_t ** aiChng )

Compute all file name changes that occur going from check-in iFrom to check-in iTo. Requires an opened repository.

If revOK is true, the algorithm is free to move backwards in the chain. This is the opposite of the oneWayOnly parameter for fsl_vpath_shortest().

On success, the number of name changes is written into *pnChng. For each name change, two integers are allocated for *piChng. The first is the filename.fnid for the original name as seen in check-in iFrom and the second is for new name as it is used in check-in iTo. If *pnChng is 0 then *aiChng will be NULL.

On error returns non-0, pnChng and aiChng are not modified, and f's error state might (depending on the error) contain a description of the problem.

Space to hold *aiChng is obtained from fsl_malloc() and must be released by the caller.

◆ fsl__foci_register()

int fsl__foci_register ( fsl_cx * f,
fsl_db * db )

Register the "files of checkin" (fsl_foci) SQLite3 virtual table.

◆ fsl__id_bag_dump()

void fsl__id_bag_dump ( fsl_id_bag const * src,
FILE * to,
char const * zHeader )

◆ fsl__is_locally_modified()

int fsl__is_locally_modified ( fsl_cx * f,
const char * zFilename,
fsl_size_t fileSize,
const char * zOrigHash,
fsl_int_t zOrigHashLen,
fsl_fileperm_e origPerm,
int * isModified )

Checks whether the given file has been locally modified compared to a known size, hash value, and permissions. Requires that f has an opened checkout.

If zFilename is not an absolute path, it is assumed to be relative to the checkout root (as opposed to the current directory) and is canonicalized into an absolute path for purposes of this function.

fileSize is the "original" version's file size. zOrigHash is the initial hash of the file to use as a basis for comparison. zOrigHashLen is the length of zOrigHash, or a negative value if this function should use fsl_is_uuid() to determine the length. If the hash length is not that of one of the supported hash types, FSL_RC_RANGE is returned and f's error state is updated. This length is used to determine which hash to use for the comparison.

If the file's current size differs from the given size, it is quickly considered modified, otherwise the file's contents get hashed and compared to zOrigHash.

Because this is used for comparing local files to their state from the fossil database, where files have no timestamps, the local file's timestamp is never considered for purposes of modification checking.

If isModified is not NULL then on success it is set to a bitmask of values from the fsl__localmod_e enum specifying the type(s) of change(s) detected:

  • FSL__LOCALMOD_PERM = permissions changed.
  • FSL__LOCALMOD_CONTENT = file size or hash (i.e. content) differ.
  • FSL__LOCALMOD_LINK = the file type was switched between symlink and normal file. In this case, no check for content change, beyond the file size change, is performed.
  • FSL__LOCALMOD_NOFOUND = file was not found in the local checkout.

Noting that:

  • Combined values of (FSL__LOCALMOD_PERM | FSL__LOCALMOD_CONTENT) are possible, but FSL__LOCALMOD_NOTFOUND will never be combined with one of the other values.

If stat() fails for any reason other than file-not-found (e.g. permissions), an error is triggered.

Returns 0 on success. On error, returns non-0 and f's error state will be updated and isModified... isNotModified. Errors include, but are not limited to:

  • Invalid hash length: FSL_RC_RANGE
  • f has no opened checkout: FSL_RC_NOT_A_CKOUT
  • Cannot find the file: FSL_RC_NOT_FOUND
  • Error accessing the file: FSL_RC_ACCESS
  • Allocation error: FSL_RC_OOM
  • I/O error during hashing: FSL_RC_IO

And potentially other errors, roughly translated from errno values, for corner cases such as passing a directory name instead of a file.

Results are undefined if any pointer argument is NULL or invalid.

This function currently does NOT follow symlinks for purposes of resolving zFilename, but that behavior may change in the future or may become dependent on the repository's 'allow-symlinks' setting.

Internal detail, not relevant for clients: this updates f's cache stat entry.

◆ fsl__is_reserved_fn_windows()

bool fsl__is_reserved_fn_windows ( const char * zPath,
fsl_int_t nameLen )

Returns true if the given file name is a reserved filename (case-insensitive) on Windows platforms, else returns false.

zPath must be a canonical path with forward-slash directory separators. nameLen is the length of zPath. If negative, fsl_strlen() is used to determine its length.

◆ fsl__leaf_do_pending_checks()

int fsl__leaf_do_pending_checks ( fsl_cx * f)

Perform all pending leaf checks. Returns 0 on success or if it has nothing to do.

◆ fsl__leaf_eventually_check()

int fsl__leaf_eventually_check ( fsl_cx * f,
fsl_id_t rid )

Schedules a leaf check for "rid" and its parents. Returns 0 on success.

◆ fsl__mutex_enter()

void fsl__mutex_enter ( void )

If the lib is built with FSL_ENABLE_MUTEX, locks the library's global non-recursive mutex, which only guards a small amount of state. If the lib is not built with FSL_ENABLE_MUTEX, this is a no-op.

◆ fsl__mutex_held()

bool fsl__mutex_held ( void )

Returns true if fsl__mutex_enter() is active, else false. Always returns true(!) in-single-threaded builds because that's how SQLite does it. This is only intended for use in assert() and the like - it must not be used for flow control.

May assert() that fsl__mutex_enter() has been called.

◆ fsl__mutex_leave()

void fsl__mutex_leave ( void )

If the lib is built with FSL_ENABLE_MUTEX, unlocks the library's global non-recursive mutex, else it's a no-op.

May assert() that fsl__mutex_enter() has been called.

◆ fsl__pclose2()

int fsl__pclose2 ( int fdIn,
FILE * pOut,
int childPid )

Close the connection to a child process previously created using fsl__popen2(). All 3 arguments are assumed to values returned via fsl__popen2()'s output parameters: the input file descriptor, output FILE handle, and child process PID.

Return the waitpid()-derived exit code of the child process.

On Windows platforms, killing of the child process is not implemented. (Patches are welcomed.)

References fsl__xfer_empty.

◆ fsl__phantom_new()

int fsl__phantom_new ( fsl_cx * f,
fsl_uuid_cstr uuid,
bool isPrivate,
fsl_id_t * newId )

Creates a new phantom blob with the given UUID and return its artifact ID via *newId. Returns 0 on success, any of many codes on error. If isPrivate is true or f has been flagged as being in "private mode" then the new content is flagged as private. newId may be NULL, but if it is then the caller will have to find the record id himself by using the UUID (see fsl_uuid_to_rid()).

◆ fsl__phantom_rid_add()

int fsl__phantom_rid_add ( fsl_cx * f,
fsl_id_t rid )

Inserts the given rid into the repo.phantom table.

◆ fsl__popen2()

int fsl__popen2 ( const char * zCmd,
int * pfdIn,
FILE ** ppOut,
int * pChildPid )

Create a child process running shell command "zCmd". *pfdIn gets assigned to the stdout from the child process. (The caller reads from *pfdIn in order to receive input from the child.) *ppOut gets assigned to a FILE that becomes the standard input of the child process. (The caller writes to *ppOut in order to send text to the child.) Note that *pfdIn is an unbuffered file descriptor, not a FILE. The process ID of the child is written into *pChildPid.

On success the values returned via *pfdIn, *ppOut, and *pChildPid must be passed to fsl_pclose2() to properly clean up.

Return 0 on success, non-0 on error.

◆ fsl__pq_clear()

void fsl__pq_clear ( fsl__pq * p)

Clears the contents of p, freeing any memory it owns, but not freeing p. Results are undefined if !p.

◆ fsl__pq_extract()

fsl_id_t fsl__pq_extract ( fsl__pq * p,
void ** pp )

Extracts (removes) the first element from the queue (the element with the smallest value) and return its ID. Return 0 if the queue is empty. If pp is not NULL then *pp is (on success) assigned to opaquedata pointer mapped to the entry.

◆ fsl__pq_insert()

int fsl__pq_insert ( fsl__pq * p,
fsl_id_t e,
double v,
void * pData )

Insert element e into the queue. Returns 0 on success, FSL_RC_OOM on error. Results are undefined if !p. pData may be NULL.

◆ fsl__private_rid_add()

int fsl__private_rid_add ( fsl_cx * f,
fsl_id_t rid )

Inserts the given rid into the repo.private table.

◆ fsl__private_rid_delete()

int fsl__private_rid_delete ( fsl_cx * f,
fsl_id_t rid )

Deletes the given rid from the repo.private table.

◆ fsl__ptl_clear()

void fsl__ptl_clear ( fsl__ptl * c)

◆ fsl__ptl_has()

bool fsl__ptl_has ( fsl__ptl const * c,
fsl__ptl_e where,
fsl_id_t rid )

◆ fsl__ptl_init()

int fsl__ptl_init ( fsl__ptl * c,
uint16_t prealloc )

◆ fsl__ptl_insert()

int fsl__ptl_insert ( fsl__ptl * c,
fsl__ptl_e where,
fsl_id_t rid )

◆ fsl__ptl_remove()

bool fsl__ptl_remove ( fsl__ptl const * c,
fsl__ptl_e where,
fsl_id_t rid )

◆ fsl__qsort_cmp_J_cards()

int fsl__qsort_cmp_J_cards ( void const * lhs,
void const * rhs )

A comparison routine for qsort(3) which compares fsl_card_J instances in a lexical manner based on their names. The order is important for card ordering in generated manifests.

This routine expects to get passed (fsl_card_J**) (namely from fsl_list entries), and will not work on an array of J-cards.

References FSL_CARD_J_BOTH, FSL_CARD_J_CHNG, and FSL_CARD_J_TICKET.

◆ fsl__repo_filename_fnid2()

int fsl__repo_filename_fnid2 ( fsl_cx * f,
char const * filename,
fsl_id_t * rv,
bool createNew )

Translate a normalized, repo-relative filename into a filename-id (fnid). Create a new fnid if none previously exists and createNew is true. On success returns 0 and sets *rv to the filename.fnid record value. If createNew is false and no match is found, 0 is returned but *rv will be set to 0. Returns non-0 on error. Results are undefined if any parameter is NULL.

In debug builds, this function asserts that no pointer arguments are NULL and that f has an opened repository.

◆ fsl__repo_fingerprint_search()

int fsl__repo_fingerprint_search ( fsl_cx * f,
fsl_id_t rcvid,
char ** zOut )

Searches the current repository database for a fingerprint and returns it as a string in *zOut.

If rcvid<=0 then the fingerprint matches the last entry in the [rcvfrom] table, where "last" means highest-numbered rcvid (as opposed to most recent mtime, for whatever reason). If rcvid>0 then it searches for an exact match.

Returns 0 on non-error. Finding no matching rcvid results in FSL_RC_NOT_FOUND. If 0 is returned then *zOut will be non-NULL and ownership of that value is transferred to the caller, who must eventually pass it to fsl_free(). On error, *zOut is not modified.

Returns FSL_RC_NOT_A_REPO if f has no opened repository, FSL_RC_OOM on allocation error, or any number of potential db-related codes if something goes wrong at the db level.

This API internally first checks for "version 1" fossil fingerprints and falls back to "version 0" fingerprint if a v1 fingerprint is not found. Version 0 was very short-lived and is not expected to be in many repositories which are accessed via this library. Practice has, however, revealed some.

See also
fsl_ckout_fingerprint_check()

◆ fsl__repo_import_blob()

int fsl__repo_import_blob ( fsl_cx * f,
fsl_input_f inFunc,
void * inState,
fsl_id_t * rid,
fsl_uuid_str * uuid )

Imports content to f's opened repository's BLOB table using a client-provided input source.

f must have an opened repository db. inFunc is the source of the data and inState is the first argument passed to inFunc(). If inFunc() succeeds in fetching all data (i.e. if it always returns 0 when called by this function) then that data is inserted into the blob table if no existing record with the same hash is already in the table. If such a record exists, it is assumed that the content is identical and this function has no side-effects vis-a-vis the db in that case.

If rid is not NULL then the BLOB.RID record value (possibly of an older record!) is stored in *rid. If uuid is not NULL then the BLOB.UUID record value is stored in *uuid and the caller takes ownership of those bytes, which must eventually be passed to fsl_free() to release them.

rid and uuid are only modified on success and only if they are not NULL.

Returns 0 on success, non-0 on error. For errors other than basic argument validation and OOM conditions, f's error state is updated with a description of the problem. Returns FSL_RC_MISUSE if either f or inFunc are NULL. Whether or not inState may be NULL depends on inFunc's concrete implementation.

Be aware that BLOB.RID values can (but do not necessarily) change in the life of a repod db (via a reconstruct, a full re-clone, or similar, or simply when referring to different clones of the same repo). Thus clients should always store the full UUID, as opposed to the RID, for later reference. RIDs should, in general, be treated as session-transient values. That said, for purposes of linking tables in the db, the RID is used exclusively (clients are free to link their own extension tables using UUIDs, but doing so has a performance penalty comared to RIDs). For long-term storage of external links, and to guaranty that the data be usable with other copies of the same repo, the UUID is required.

Note that Fossil may deltify, compress, or otherwise modify content on its way into the blob table, and it may even modify content long after its insertion (e.g. to make it a delta against a newer version). Thus clients should normally never try to read back the blob directly from the database, but should instead read it using fsl_content_get().

That said: this routine has no way of associating and older version (if any) of the same content with this newly-imported version, and therefore cannot delta-compress the older version.

Maintenance reminder: this is basically just a glorified form of the internal fsl__content_put(). Interestingly, fsl__content_put() always sets content to public (by default - the f object may override that later). It is not yet clear whether this routine needs to have a flag to set the blob private or not. Generally speaking, privacy is applied to fossil artifacts, as opposed to content blobs.

See also
fsl__repo_import_buffer()

◆ fsl__repo_import_buffer()

int fsl__repo_import_buffer ( fsl_cx * f,
fsl_buffer const * bIn,
fsl_id_t * rid,
fsl_uuid_str * uuid )

A convenience form of fsl__repo_import_blob(), equivalent to:

int fsl__repo_import_blob(fsl_cx *f, fsl_input_f inFunc, void *inState, fsl_id_t *rid, fsl_uuid_str *uuid)
Imports content to f's opened repository's BLOB table using a client-provided input source.
FSL_EXPORT int fsl_input_f_buffer(void *state, void *dest, fsl_size_t *n)
A fsl_input_f() implementation which requires that state be a readable (fsl_buffer*) handle.

except that (A) bIn is const in this call and non-const in the other form (due to cursor traversal requirements) and (B) it returns FSL_RC_MISUSE if bIn is NULL.

◆ fsl__repo_record_filename()

int fsl__repo_record_filename ( fsl_cx * f)

This function updates the repo and/or global config databases with links between the dbs intended for various fossil-level bookkeeping and housecleaning. These links are not essential to fossil's functionality but assist in certain "global" operations.

If no checkout is opened but a repo is, the global config (if opened) is updated to know about the opened repo db.

If a checkout is opened, global config (if opened) and the repo are updated to point to the checked-out db.

◆ fsl__repo_shun_artifacts()

int fsl__repo_shun_artifacts ( fsl_cx * f)

Removes all entries from the repo's blob table which are listed in the shun table. Returns 0 on success. This operation is wrapped in a transaction. Delta content which depend on to-be-shunned content are replaced with their undeltad forms.

Returns 0 on success. On error, its transaction is aborted or a pseudo-nested transaction is set into a rollback state.

◆ fsl__repo_verify_at_commit()

int fsl__repo_verify_at_commit ( fsl_cx * f)

Processes all pending verify-at-commit entries for the current transaction level and clears the to-verify list. Returns 0 on success. On error f's error state will likely be updated.

ONLY call this from fsl_db_txn_end() or its delegate (if refactored).

Verification calls fsl_content_get() to "unpack" content added in the current transaction. If fetching the content (which applies any deltas it may need to) fails or its hash does not match its blob.uuid value then this routine fails and returns non-0.

See also
fsl_repo_verify_cancel()
fsl__repo_verify_before_commit()

◆ fsl__repo_verify_before_commit()

int fsl__repo_verify_before_commit ( fsl_cx * f,
fsl_id_t rid )

Schedules the given rid to be verified before it is commited, but whether the validation will be done at the commit of the current transaction level or a higher-up one is as-yet unspecified . This is used by routines which add artifact records to the blob table.

The only error case, assuming the arguments are valid, is an allocation error while appending rid to the internal to-verify queue.

See also
fsl__repo_verify_at_commit()
fsl_repo_verify_cancel()

◆ fsl__repo_verify_cancel()

void fsl__repo_verify_cancel ( fsl_cx * f)

Clears the current transaction level's verify-at-commit list of RIDs.

See also
fsl__repo_verify_at_commit()
fsl__repo_verify_before_commit()

◆ fsl__rid_delete()

int fsl__rid_delete ( fsl_cx * f,
fsl_dbrole_e dbRole,
char const * zTable,
fsl_id_t rid )

Expects zTable to name a table with an rid field.

That record is deleted.

◆ fsl__search_doc_touch()

int fsl__search_doc_touch ( fsl_cx * f,
fsl_satype_e saType,
fsl_id_t rid,
const char * docName )

Currently disabled (always returns 0) pending resolution of a "wha???" result from one of the underlying queries.

Queues up the given artifact for a search index update. This is only intended to be called from crosslinking steps and similar content updates. Returns 0 on success.

The final argument is intended only for wiki titles (the L-card of a wiki post).

If the repository database has no search index or the given content is marked as private, this function returns 0 and makes no changes to the db.

◆ fsl__shunned_remove()

int fsl__shunned_remove ( fsl_cx * f)

Removes from the BLOB table all artifacts that are in the SHUN table. Returns 0 on success. Requires (asserts) that a repo is opened. Note that this is not a simple DELETE operation, as it requires ensuring that all removed blobs have been undeltified first so that no stale delta records are left behind.

◆ fsl__symlink_copy()

int fsl__symlink_copy ( char const * zFrom,
char const * zTo,
bool realLink )

Copies symlink zFrom to a new symlink or pseudo-symlink named zTo.

If realLink is true and this is a non-Windows platform, symlink zFrom is copied to zTo.

If realLink is false or this is a Windows platform them...

  • On Windows this has currently undesired, or at least, highly arguable, behavior (historical, inherited from fossil(1)), in that an empty file named zTo will be created. In fossil(1) this function's counterpart is (apparently) never called on Windows, so that behavior seems to be moot. It is, however, important that this library never call it on Windows.
  • On non-Windows, a pseudo-symlink will be created: the string zFrom will be written to a regular file named zTo. That is, the file zTo will hold, as its contents, what it would point to if it were a symlink.

◆ fsl__tag_insert()

int fsl__tag_insert ( fsl_cx * f,
fsl_tagtype_e tagtype,
char const * zTag,
char const * zValue,
fsl_id_t srcId,
double mtime,
fsl_id_t rid,
fsl_id_t * outRid )

Inserts a tag into f's repo db. It does not create the related control artifact - use fsl_tag_an_rid() for that.

rid is the artifact to which the tag is being applied.

srcId is the artifact that contains the tag. It is often, but not always, the same as rid. This is often the RID of the manifest containing tags added as part of the commit, in which case rid==srcId. A Control Artifact which tags a different artifact will have rid!=srcId.

mtime is the Julian timestamp for the tag. Defaults to the current time if mtime <= 0.0.

If outRid is not NULL then on success *outRid is assigned the record ID of the generated tag (the tag.tagid db field).

If a more recent (compared to mtime) entry already exists for this tag/rid combination then its tag.tagid is returned via outRid (if outRid is not NULL) and no new entry is created.

Returns 0 on success, and has a huge number of potential error codes.

◆ fsl__tag_propagate()

int fsl__tag_propagate ( fsl_cx * f,
fsl_tagtype_e tagType,
fsl_id_t pid,
fsl_id_t tagid,
fsl_id_t origId,
const char * zValue,
double mtime )

Propagates a tag through the various internal pipelines.

pid is the artifact id to whose children the tag should be propagated.

tagid is the id of the tag to propagate (the tag.tagid db value).

tagType is the type of tag to propagate. Must be either FSL_TAGTYPE_CANCEL or FSL_TAGTYPE_PROPAGATING. Note that FSL_TAGTYPE_ADD is not permitted. The tag-handling internals (other than this function) translate ADD to CANCEL for propagation purposes. A CANCEL tag is used to stop propagation. (That's a historical behaviour inherited from fossil(1).) A potential TODO is for this function to simply treat ADD as CANCEL, without requiring that the caller be sure to never pass an ADD tag.

origId is the artifact id of the origin tag if tagType == FSL_TAGTYPE_PROPAGATING, otherwise it is ignored.

zValue is the optional value for the tag. May be NULL.

mtime is the Julian timestamp for the tag. Must be a valid time (no defaults here).

This function is unforgiving of invalid values/ranges, and may assert in debug mode if passed invalid ids (values<=0), a NULL f, or if f has no opened repo.

◆ fsl__tag_propagate_all()

int fsl__tag_propagate_all ( fsl_cx * f,
fsl_id_t pid )

Propagate all propagatable tags in artifact pid to the children of pid. Returns 0 on... non-error. Returns FSL_RC_RANGE if pid<=0.

◆ fsl__ticket_rebuild()

int fsl__ticket_rebuild ( fsl_cx * f,
char const * zTktId )

Part of the crosslinking bits: rebuilds the entry for the ticket with the given K-card value.

◆ fsl__tmpchmod()

int fsl__tmpchmod ( char const * z)

If FSL_PLATFORM_IS_UNIX then this returns the result of chmod(2) for the given file name, converted from errno using fsl_errno_to_rc().

It uses permissions 0600.

On other platforms this is a no-op and returns 0.

◆ fsl__tmpfile()

int fsl__tmpfile ( fsl_buffer * tgt,
char const * zBaseName )

fsl_file_tempname() proxy which uses fsl_temp_dirs_get() to get the target dir. zBaseName may be NULL but library routines are strongly enouraged to use a of "libfossil-PURPOSE", where PURPOSE is a descrtive identifier, e.g. "PopenRequest" or "popen-request".

◆ fsl__tokenizer_next()

unsigned char * fsl__tokenizer_next ( fsl__tokenizer * pIn,
fsl_size_t * pLen )

Returns a pointer to the next space-separated token in pIn. The token is zero-terminated. Return NULL if there are no more tokens on the current line, but the call after that will return non-NULL unless we have reached the end of the input. If this function returns non-NULL then *pLen (which must not be NULL) is set to the byte length of the new token. Once the end of the input is reached, this function always returns NULL.

A token is defined as a sequence of a non-whitespace (0x20), non-newline (0x0A) bytes. The input is modified, replacing spaces and newlines with a NUL.

References fsl__tokenizer::z.

◆ fsl__unclustered_rid_add()

int fsl__unclustered_rid_add ( fsl_cx * f,
fsl_id_t rid )

Inserts the given rid into the repo.unclustered table.

◆ fsl__unsent_rid_add()

int fsl__unsent_rid_add ( fsl_cx * f,
fsl_id_t rid )

Inserts the given rid into the repo.unsent table.

◆ fsl__uuid_to_rid2()

fsl_id_t fsl__uuid_to_rid2 ( fsl_cx * f,
fsl_uuid_cstr uuid,
fsl__phantom_e mode )

Works like fsl_uuid_to_rid(), with these differences:

  • uuid is required to be a complete UUID, not a prefix.
  • If it finds no entry and the mode argument specifies so then it will add either a public or private phantom entry and return its new rid. If mode is FSL_PHANTOM_NONE then this this behaves just like fsl_uuid_to_rid().

Returns a positive value on success, 0 if it finds no entry and mode==FSL_PHANTOM_NONE, and1 a negative value on error (e.g. if fsl_is_uuid(uuid) returns false). Errors which happen after argument validation will "most likely" update f's error state with details.

References FSL_PHANTOM_NONE, FSL_PHANTOM_PRIVATE, and FSL_PHANTOM_PUBLIC.

◆ fsl__vfile_to_ckout()

int fsl__vfile_to_ckout ( fsl_cx * f,
fsl_id_t vfileId,
int * wasWritten )

Exports the file with the given [vfile].[id] to the checkout, overwriting (if possible) anything which gets in its way. If the file is determined to have not been modified, it is unchanged.

If the final argument is not NULL then it is set to 0 if the file was not modified, 1 if only its permissions were modified, and 2 if its contents were updated (which also requires resetting its permissions to match their repo-side state).

Returns 0 on success, any number of potential non-0 codes on error, including, but not limited to:

  • FSL_RC_NOT_A_CKOUT - no opened checkout.
  • FSL_RC_NOT_FOUND - no matching vfile entry.
  • FSL_RC_OOM - we cannot escape this eventuality.

Trivia:

  • fossil(1)'s vfile_to_disk() is how it exports a whole vfile, or a single vfile entry, to disk. e.g. it performs a checkout that way, whereas we currently perform a checkout using the "repo extraction" API. The checkout mechanism was probably the first major core fossil feature which was structured radically differently in libfossil, compared to the feature's fossil counterpart, when it was ported over.
  • This routine always writes to the vfile.pathname entry, as opposed to vfile.origname.

Maintenance reminders: internally this code supports handling multiple files at once, but (A) that's not part of the interface and may change and (B) the 3rd parameter makes little sense in that case unless maybe we change it to a callback, which seems like overkill for our use cases.

BUGS:

  • When doing a fsl_ckout_revert(), this function does not recognize a file which has been modified (only) via a merge as modified, so does not set *wasWritten. Whether that bug is in this function or fsl__is_locally_modified() is not yet clear. fsl_ckout_revert() works around that so that the client can be notified of reverted files, but that's only hiding the underlying discrepancy.

◆ fsl__xfcard_search()

fsl_xfcard const * fsl__xfcard_search ( unsigned char const * z)

Searches for a sync card with the given name. Returns a static/const instance of one on success, else NULL. This is a binary search ordered on the card names' hashes, so is fairly fast: hash z, binary search on that hash, and one fsl_strcmp() on a match. The hash algo bails early if z is not shaped like a card name.

Design note: this takes an unsigned string because its argument is invariably from fsl__xfer::line::aToken.

◆ fsl_xfcard_hash()

fsl_xfcard_hash_t fsl_xfcard_hash ( unsigned const char * word)

Very simple hash which has proven to be collision-free for several dozen keywords in a live scripting engine.

This hash is used to generate ids for limited keyword lists such that we can verify, via assert(), that the hash iscollision-free for the full input set.

Aside from the current implementation, these variations of fsl_xfcard_hash_step have worked out in prior testing:

  • ((H << 1) + 100*I + I*CHAR - I* (fsl_xfcard_LowestIdChar - 1))
  • ((H << 1) + 45*I + CHAR - fsl_xfcard_LowestIdChar - 1)

Design note: this takes an unsigned string because its argument is invariably from fsl__xfer::line::aToken.

Variable Documentation

◆ fsl__cx_empty

const fsl_cx fsl__cx_empty
extern

Initialized-with-defaults fsl_cx instance.

◆ fsl__diff_cx_empty

const fsl__diff_cx fsl__diff_cx_empty
extern

Initialized-with-defaults fsl__diff_cx structure, intended for non-const copy initialization.

Referenced by fsl__dump_triples().

◆ fsl__mcache_empty

const fsl__mcache fsl__mcache_empty
extern

Initialized-with-defaults fsl__mcache structure, intended for non-const copy initialization.

◆ fsl__pq_empty

const fsl__pq fsl__pq_empty
extern

Empty-initialized fsl__pq struct, intended for copy initialization.

◆ fsl__tokenizer_empty

const fsl__tokenizer fsl__tokenizer_empty
extern

◆ fsl__xfer_empty

const fsl__xfer fsl__xfer_empty
extern

Empty-initialized fsl__xfer instance, intended for copy initialization.

Referenced by fsl__pclose2().