libfossil
fossil-internal.h File Reference

Go to the source code of this file.

Data Structures

struct  fsl_acache
 
struct  fsl_acache_line
 
struct  fsl_cx
 The main Fossil "context" type. More...
 
struct  fsl_pq
 
struct  fsl_pq_e
 
struct  fsl_xlinker
 
struct  fsl_xlinker_list
 

Macros

#define fsl_acache_empty_m
 
#define fsl_acache_line_empty_m   { 0,0,fsl_buffer_empty_m }
 
#define fsl_cx_empty_m
 
#define fsl_pq_e_empty_m   {0,NULL,0.0}
 
#define fsl_pq_empty_m   {0,0,NULL}
 
#define fsl_xlinker_empty_m   {NULL,NULL,NULL}
 Empty-initialized fsl_xlinker struct, intended for const-copy intialization. More...
 
#define fsl_xlinker_list_empty_m   {0,0,NULL}
 Empty-initializes fsl_xlinker_list struct, intended for const-copy intialization. More...
 

Typedefs

typedef struct fsl_acache fsl_acache
 
typedef struct fsl_acache_line fsl_acache_line
 
typedef enum fsl_phantom_t fsl_phantom_t
 
typedef struct fsl_pq fsl_pq
 
typedef struct fsl_pq_e fsl_pq_e
 
typedef struct fsl_xlinker fsl_xlinker
 
typedef struct fsl_xlinker_list fsl_xlinker_list
 

Enumerations

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
}
 
enum  fsl_ckout_sig_t {
  FSL_VFILE_CKSIG_NONE = 0,
  FSL_VFILE_CKSIG_ENOTFILE = 0x001,
  FSL_VFILE_CKSIG_SHA1 = 0x002,
  FSL_VFILE_CKSIG_SETMTIME = 0x004,
  FSL_VFILE_CKSIG_CLEAR_VFILE = 0x008
}
 
enum  fsl_phantom_t {
  FSL_PHANTOM_NONE = 0,
  FSL_PHANTOM_PUBLIC = 1,
  FSL_PHANTOM_PRIVATE = 2
}
 
enum  fsl_vfile_change_t {
  FSL_VFILE_CHANGE_NONE = 0,
  FSL_VFILE_CHANGE_MOD = 1,
  FSL_VFILE_CHANGE_MERGE_MOD = 2,
  FSL_VFILE_CHANGE_MERGE_ADD = 3,
  FSL_VFILE_CHANGE_INTEGRATE_MOD = 4,
  FSL_VFILE_CHANGE_INTEGRATE_ADD = 5
}
 Hard-coded range of values of the vfile.chnged db field. More...
 

Functions

int fsl_acache_check_available (fsl_cx *f, fsl_id_t rid)
 
void fsl_acache_clear (fsl_acache *c)
 
char fsl_acache_expire_oldest (fsl_acache *c)
 
int fsl_acache_insert (fsl_acache *c, fsl_id_t rid, fsl_buffer *pBlob)
 
void fsl_card_J_list_free (fsl_list *li, char alsoListMem)
 
FSL_EXPORT int fsl_checkout_filename_vfile_id (fsl_cx *f, char const *fn, fsl_id_t vid, fsl_id_t *rv)
 
char * fsl_config_inop_rhs (int iMask)
 
int fsl_content_deltify (fsl_cx *f, fsl_id_t rid, fsl_id_t srcid, char force)
 
int fsl_content_new (fsl_cx *f, fsl_uuid_cstr uuid, char isPrivate, fsl_id_t *newId)
 
int fsl_content_put (fsl_cx *f, fsl_buffer const *pBlob, fsl_id_t *newRid)
 
FSL_EXPORT int fsl_content_put_ex (fsl_cx *f, fsl_buffer const *pBlob, fsl_uuid_cstr zUuid, fsl_id_t srcId, fsl_size_t uncompSize, char isPrivate, fsl_id_t *outRid)
 
int fsl_content_undeltify (fsl_cx *f, fsl_id_t rid)
 
void fsl_cx_clear_mf_seen (fsl_cx *f)
 
int fsl_cx_ticket_create_table (fsl_cx *f)
 
FSL_EXPORT int fsl_cx_ticket_load_fields (fsl_cx *f, char forceReload)
 
int fsl_cx_update_checkout_uuid (fsl_cx *f)
 
void fsl_cx_yield_file_buffer (fsl_cx *f)
 
void fsl_db_clear_strings (fsl_db *db, char alsoErrorState)
 
int fsl_db_repo_verify_schema (fsl_db *db)
 
char * fsl_db_setting_inop_rhs ()
 
fsl_card_Ffsl_deck_F_seek (fsl_deck *const d, const char *zName)
 
int fsl_deck_parse2 (fsl_deck *d, fsl_buffer *src, fsl_id_t rid)
 
FSL_EXPORT void fsl_fatal (int code, char const *fmt,...)
 
char * fsl_file_without_drive_letter (char *zFile)
 
int fsl_filename_to_vfile_id (fsl_cx *f, char const *zName, fsl_id_t *vfid)
 
int fsl_filename_to_vfile_ids (fsl_cx *f, fsl_id_t vid, fsl_id_bag *dest, char const *zName)
 
int fsl_mf_crosslink_begin (fsl_cx *f)
 
int fsl_mf_crosslink_end (fsl_cx *f)
 
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, fsl_double_t v, void *pData)
 
int fsl_qsort_cmp_J_cards (void const *lhs, void const *rhs)
 
void fsl_remove_pgp_signature (unsigned char const **pz, fsl_size_t *pn)
 
FSL_EXPORT int fsl_repo_filename_fnid2 (fsl_cx *f, char const *filename, fsl_id_t *rv, char createNew)
 
int fsl_repo_leaf_check (fsl_cx *f, fsl_id_t pid)
 
int fsl_repo_leaf_do_pending_checks (fsl_cx *f)
 
int fsl_repo_leaf_eventually_check (fsl_cx *f, fsl_id_t rid)
 
FSL_EXPORT int fsl_repo_leaves_rebuild (fsl_cx *f)
 
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)
 
FSL_EXPORT fsl_id_t fsl_tag_id (fsl_cx *f, char const *tag, char create)
 
int fsl_tag_insert (fsl_cx *f, fsl_tag_type tagtype, char const *zTag, char const *zValue, fsl_id_t srcId, fsl_double_t mtime, fsl_id_t rid, fsl_id_t *outRid)
 
int fsl_tag_propagate (fsl_cx *f, fsl_tag_type tagType, fsl_id_t pid, fsl_id_t tagid, fsl_id_t origId, const char *zValue, fsl_double_t mtime)
 
int fsl_tag_propagate_all (fsl_cx *f, fsl_id_t pid)
 
fsl_id_t fsl_uuid_to_rid2 (fsl_cx *f, fsl_uuid_cstr uuid, fsl_phantom_t mode)
 
FSL_EXPORT int fsl_vfile_changes_scan (fsl_cx *f, fsl_id_t vid, int cksigFlags)
 
int fsl_vfile_load_from_rid (fsl_cx *f, fsl_id_t manifestRid, char clearOthers)
 
fsl_xlinkerfsl_xlinker_by_name (fsl_cx *f, char const *name)
 

Variables

const fsl_acache fsl_acache_empty
 
const fsl_cx fsl_cx_empty
 
const fsl_pq fsl_pq_empty
 
const fsl_xlinker fsl_xlinker_empty
 Empty-initialized fsl_xlinker struct, intended for copy intialization. More...
 
const fsl_xlinker_list fsl_xlinker_list_empty
 Empty-initializes fsl_xlinker_list struct, intended for copy intialization. More...
 

Macro Definition Documentation

#define fsl_acache_empty_m
Value:
{ \
0/*szTotal*/,0/*used*/,0/*capacity*/, \
0/*nextAge*/,NULL/*list*/, \
fsl_id_bag_empty_m/*available*/ \
}
#define fsl_id_bag_empty_m
Initialized-with-defaults fsl_id_bag structure, intended for in-struct initialization.
Definition: fossil-util.h:4019

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

Definition at line 183 of file fossil-internal.h.

#define fsl_acache_line_empty_m   { 0,0,fsl_buffer_empty_m }

Empty-initialized fsl_acache_line structure.

Definition at line 126 of file fossil-internal.h.

#define fsl_cx_empty_m

Initialized-with-defaults fsl_cx struct.

Definition at line 628 of file fossil-internal.h.

#define fsl_pq_e_empty_m   {0,NULL,0.0}

Empty-initialized fsl_pq_e structure.

Definition at line 53 of file fossil-internal.h.

#define fsl_pq_empty_m   {0,0,NULL}

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

Definition at line 73 of file fossil-internal.h.

#define fsl_xlinker_empty_m   {NULL,NULL,NULL}

Empty-initialized fsl_xlinker struct, intended for const-copy intialization.

Definition at line 214 of file fossil-internal.h.

#define fsl_xlinker_list_empty_m   {0,0,NULL}

Empty-initializes fsl_xlinker_list struct, intended for const-copy intialization.

Definition at line 235 of file fossil-internal.h.

Typedef Documentation

typedef struct fsl_acache fsl_acache

Definition at line 33 of file fossil-internal.h.

Definition at line 34 of file fossil-internal.h.

Definition at line 1167 of file fossil-internal.h.

typedef struct fsl_pq fsl_pq

Definition at line 35 of file fossil-internal.h.

typedef struct fsl_pq_e fsl_pq_e

Definition at line 36 of file fossil-internal.h.

typedef struct fsl_xlinker fsl_xlinker

Definition at line 210 of file fossil-internal.h.

Definition at line 231 of file fossil-internal.h.

Enumeration Type Documentation

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 1377 of file fossil-internal.h.

A bitmask of flags for fsl_vfile_changes_scan().

Enumerator
FSL_VFILE_CKSIG_NONE 

The empty flags set.

FSL_VFILE_CKSIG_ENOTFILE 

Non-file FS objects throw an error.

Not yet implemented.

FSL_VFILE_CKSIG_SHA1 

Verify file content using sha1sum, regardless of whether or not file timestamps differ.

FSL_VFILE_CKSIG_SETMTIME 

For unchanged or changed-by-merge files, set the mtime to last check-out time, as determined by fsl_mtime_of_manifest_file().

FSL_VFILE_CKSIG_CLEAR_VFILE 

Indicates that when populating the vfile table, it should be cleared of entries for other checkins.

This is primarily for compatibility with fossil(1), which generally assumes only a single checkin's worth of state is in vfile and can get confused if that is not the case.

Definition at line 1304 of file fossil-internal.h.

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.

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 1150 of file fossil-internal.h.

Hard-coded range of values of the vfile.chnged db field.

Enumerator
FSL_VFILE_CHANGE_NONE 
FSL_VFILE_CHANGE_MOD 
FSL_VFILE_CHANGE_MERGE_MOD 
FSL_VFILE_CHANGE_MERGE_ADD 
FSL_VFILE_CHANGE_INTEGRATE_MOD 
FSL_VFILE_CHANGE_INTEGRATE_ADD 

Definition at line 1268 of file fossil-internal.h.

Function Documentation

int fsl_acache_check_available ( fsl_cx f,
fsl_id_t  rid 
)

Checks f->cache.arty 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.

void fsl_acache_clear ( fsl_acache c)

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

char fsl_acache_expire_oldest ( fsl_acache c)

Expires the single oldest entry in c. Returns true (non-0) if it removes an item, else 0.

int fsl_acache_insert ( fsl_acache 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 memory when it has finished with it.

Returns 0 on success, FSL_RC_OOM on allocation error. Has undefined behaviour if !c, rid is not semantically valid, !pBlob (or pBlob has no content???).

void fsl_card_J_list_free ( fsl_list li,
char  alsoListMem 
)

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_EXPORT int fsl_checkout_filename_vfile_id ( fsl_cx f,
char const *  fn,
fsl_id_t  vid,
fsl_id_t rv 
)

Functionally similar to fsl_repo_filename_fnid2(), but fetches a vfile.id value. vid is the vfile.vid to filter on. If vid is <=0 then f->ckout.rid is used. It only matches on vfile.pathname, not vfile.origname, and requires an exact match because it is expected that the input filename will typically come from fsl_card_F entries.

On success returns 0 and sets *rv to the vfile.id or to 0 if no entry is found. On error, returns non-0 and it should be taken seriously.

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

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_t values). Ownership of the returned string is passed to the caller, who must eventually pass it to fsl_free(). Returns NULL on allocation error.

int fsl_content_deltify ( fsl_cx f,
fsl_id_t  rid,
fsl_id_t  srcid,
char  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.

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.

See also
fsl_content_undeltify()
int fsl_content_new ( fsl_cx f,
fsl_uuid_cstr  uuid,
char  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, FSL_RC_MISUSE if !f or !uuid, FSL_RC_RANGE if fsl_is_uuid(uuid) returns false, FSL_RC_NOT_A_REPO if f has no repository opened, FSL_RC_ACCESS if the given uuid has been shunned, and about 20 other potential error codes from the underlying db calls. 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()).

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,0,newRid).

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

See also
fsl_content_put_ex()
FSL_EXPORT int fsl_content_put_ex ( fsl_cx f,
fsl_buffer const *  pBlob,
fsl_uuid_cstr  zUuid,
fsl_id_t  srcId,
fsl_size_t  uncompSize,
char  isPrivate,
fsl_id_t outRid 
)

This is THE ONLY routine which adds content to the blob table.

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 SHA1 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: 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, 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.

Potential TODO: we don't really need the uncompSize param - we can deduce it, if needed, based on pBlob's content. We cannot, however, know the UUID of the decompressed content unless the client passes it in to us.

See also
fsl_content_put()
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_MISUSE if !f, 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()
void fsl_cx_clear_mf_seen ( fsl_cx f)

Clears the "seen" cache used by manifest parsing. Should be called by routines which initialize parsing, but not until their work has finished all parsing (so that recursive parsing can use it).

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

Returns 0 on success.

FSL_EXPORT int fsl_cx_ticket_load_fields ( fsl_cx f,
char  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
int fsl_cx_update_checkout_uuid ( 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, the f->ckout state is left in a potentially inconsistent state, and it should not be relied upon until/unless the error is resolved.

void fsl_cx_yield_file_buffer ( fsl_cx f)

Part of the fsl_cx::fileContent optimization. This sets f->fileContent.used to 0 and if its capacity is over a certain (unspecified, unconfigurable) size then it is trimmed to that size.

void fsl_db_clear_strings ( fsl_db db,
char  alsoErrorState 
)

Clears all fsl_buffer members of db but leaves the rest intact. If alsoErrorState is true then the error state is also cleared, else it is kept as well.

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.

char* fsl_db_setting_inop_rhs ( )

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.

fsl_card_F* fsl_deck_F_seek ( fsl_deck *const  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_mf_card 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_CATYPE_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.

int fsl_deck_parse2 ( fsl_deck d,
fsl_buffer src,
fsl_id_t  rid 
)

The internal version of fsl_deck_parse(). See that function for details regarding everything but the 3rd argument.

If you happen to know the _correct_ RID for the deck being parsed, pass it as the rid argument, else pass 0. A negative value will result in a FSL_RC_RANGE error. This value is (or will be) only used as an optimization in other places and only if d->f is not NULL. Passing a positive value has no effect on how the content is parsed or on the result - it only affects internal details/optimizations.

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

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.

int fsl_filename_to_vfile_id ( fsl_cx f,
char const *  zName,
fsl_id_t vfid 
)

Expects f to have an opened checkout and zName to be the name of an entry in the vfile table. This function does not do any path resolution on zName. On success it returns 0 and assigned *vfid to the vfile.id value of the matching file. If no match is found, 0 is returned and *vfile is set to 0.

This search honors the context-level case-insensitivity setting (see fsl_cx_case_sensitive_set()).

int fsl_filename_to_vfile_ids ( fsl_cx f,
fsl_id_t  vid,
fsl_id_bag dest,
char const *  zName 
)

Searches the vfile table where vfile.vid=vid for a name which matches zName or a subdirectory named zName. For each entry it finds, it adds the vfile.id to dest. If zName is NULL or empty then all files in vfile with the given vid are selected.

This search honors the context-level case-insensitivity setting (see fsl_cx_case_sensitive_set()).

Returns 0 on success. Not finding anything is not treated as an error, though we could arguably return FSL_RC_NOT_FOUND for the cases which use this function.

int fsl_mf_crosslink_begin ( fsl_cx f)

UNTESTED - the bits which use this are not yet ported.

This initializes some temporary db state for the crosslinking of tickets.

Returns 0 on success. If it returns 0, the caller must eventually call fsl_mf_crosslink_end(), otherwise he must not call fsl_mf_crosslink_end().

This function starts a db transaction if one is not already active. fsl_mf_crosslink_end() will end it.

int fsl_mf_crosslink_end ( fsl_cx f)

UNTESTED - the bits which use this are not yet ported.

Must not be called unless fsl_mf_crosslink_begin() has been called.

Returns 0 on success. On error it initiates (or propagates) a rollback for the current transaction.

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_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 the 'p' member of the extracted element.

int fsl_pq_insert ( fsl_pq p,
fsl_id_t  e,
fsl_double_t  v,
void *  pData 
)

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

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.

void fsl_remove_pgp_signature ( unsigned char const **  pz,
fsl_size_t pn 
)

Remove the PGP signature from a raw artifact, if there is one.

Expects *pz to point to *pn bytes of string memory which might or might not be prefixed by a PGP signature. If the string is enveloped in a signature, then upon returning *pz will point to the first byte after the end of the PGP header and *pn will contain the length of the content up to, but not including, the PGP footer.

If *pz does not look like a PGP header then this is a no-op.

Neither pointer may be NULL and *pz must point to *pn bytes of valid memory.

FSL_EXPORT int fsl_repo_filename_fnid2 ( fsl_cx f,
char const *  filename,
fsl_id_t rv,
char  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.

int fsl_repo_leaf_check ( fsl_cx f,
fsl_id_t  pid 
)

Check to see if checkin "rid" is a leaf and either add it to the LEAF table if it is, or remove it if it is not.

Returns 0 on success, FSL_RC_MISUSE if !f or f has no repo db opened, FSL_RC_RANGE if pid is <=0. Other errors (e.g. FSL_RC_DB) may indicate that db is not a repo. On error db's error state may be updated.

int fsl_repo_leaf_do_pending_checks ( fsl_cx f)

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

int fsl_repo_leaf_eventually_check ( fsl_cx f,
fsl_id_t  rid 
)

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

FSL_EXPORT int fsl_repo_leaves_rebuild ( fsl_cx f)

Recompute/rebuild the entire repo.leaf table.

This can be expensive (in time) for a really large repository. So it is only done for things like a full rebuild.

Returns 0 on success. Error may indicate that f is not a repo. On error f's error state may be updated.

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.

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 contant which depend on to-be-shunned content are replaced with their undeltad forms.

Returns 0 on success.

int fsl_repo_verify_at_commit ( fsl_cx f)

Processes all pending verify-at-commit entries 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_transaction_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 a checksum does not match then this routine fails and returns non-0. Any error f's error state will be updated.

See also
fsl_repo_verify_cancel()
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 at the next commit. 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()
void fsl_repo_verify_cancel ( fsl_cx f)

Clears f's verify-at-commit list of RIDs.

See also
fsl_repo_verify_at_commit()
fsl_repo_verify_before_commit()
FSL_EXPORT fsl_id_t fsl_tag_id ( fsl_cx f,
char const *  tag,
char  create 
)

Searches for a repo.tag entry given name in the given context's repository db. If found, it returns the record's id. If no record is found and create is true (non-0) then a tag is created and its entry id is returned. Returns 0 if it finds no entry, a negative value on error. On db-level error, f's error state is updated.

int fsl_tag_insert ( fsl_cx f,
fsl_tag_type  tagtype,
char const *  zTag,
char const *  zValue,
fsl_id_t  srcId,
fsl_double_t  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_add_artifact() 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.

int fsl_tag_propagate ( fsl_cx f,
fsl_tag_type  tagType,
fsl_id_t  pid,
fsl_id_t  tagid,
fsl_id_t  origId,
const char *  zValue,
fsl_double_t  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.

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.

int fsl_tag_propagate_all ( fsl_cx f,
fsl_id_t  pid 
)

Propagate all propagatable tags in pid to the children of pid.

fsl_id_t fsl_uuid_to_rid2 ( fsl_cx f,
fsl_uuid_cstr  uuid,
fsl_phantom_t  mode 
)

Works like fsl_uuid_to_rid(), with these differences:

  • uuid is expected 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, and 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.

FSL_EXPORT int fsl_vfile_changes_scan ( fsl_cx f,
fsl_id_t  vid,
int  cksigFlags 
)

This function populates (if needed) the vfile table of f's checkout db for the given checkin version ID then compares files listed in it against files in the checkout directory, updating vfile's status for the current checkout version id as its goes. If vid is negative then the current checkout's RID is used in its place (note that 0 is the RID of an initial empty repository!). cksigFlags must be a bitmask of fsl_ckout_sig_t values.

Returns 0 on success, non-0 on error.

BUG: this does not properly catch one particular corner-case change, where a file has been replaced by a same-named non-file.

int fsl_vfile_load_from_rid ( fsl_cx f,
fsl_id_t  manifestRid,
char  clearOthers 
)

Populates f's checkout vfile table with all files from the given Manifest RID. If vfile already contains entries for that manifest, it assumes they are loaded and does not insert them (returning 0 unless cleanup (see below) fails). If manifestRid is 0 or less then the current checkout's RID is used.

The clearOthers flag is a compatibility flag for fossil(1). The vfile model allows an arbitrary number of checkin versions to be installed in it at once, but several of fossil(1)'s commands do not account for that, and assume only one version is loaded at a time.

Returns 0 on success, any number of codes on any number of errors.

f must not be NULL and must have opened checkout and repository databases. In debug builds it will assert that that is so.

fsl_xlinker* fsl_xlinker_by_name ( fsl_cx f,
char const *  name 
)

Searches f's crosslink callbacks for an entry with the given name and returns that entry, or NULL if no match is found. The returned object is owned by f.

Variable Documentation

const fsl_acache fsl_acache_empty

Empty-initialized fsl_acache structure, intended for copy initialization.

const fsl_cx fsl_cx_empty

Initialized-with-defaults fsl_cx instance.

const fsl_pq fsl_pq_empty

Empty-initialized fsl_pq struct, intended for copy initialization.

const fsl_xlinker fsl_xlinker_empty

Empty-initialized fsl_xlinker struct, intended for copy intialization.

const fsl_xlinker_list fsl_xlinker_list_empty

Empty-initializes fsl_xlinker_list struct, intended for copy intialization.