libfossil
core.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_CORE_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_CORE_H_INCLUDED
5/*
6 Copyright 2013-2025 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13*/
14
15#include <stdbool.h>
16
17/** @file core.h
18
19 This file declares the core SCM-related public APIs.
20*/
21
22#include "fossil-scm/util.h" /* MUST come first b/c of config macros */
23#include <time.h> /* struct tm, time_t */
24#if defined(__cplusplus)
25/**
26 The fsl namespace is reserved for an eventual C++ wrapper for the API.
27*/
28namespace fsl {}
29extern "C" {
30#endif
31
32/**
33 An internal helper macro to help localize OOM error reports (which
34 are most often side effects of other issues, rather than being
35 real OOM cases). It's intended to be used like:
36
37 ```
38 void * someAllocedMemory = fsl_malloc(...); // any allocating routine
39 if(!someAllocedMemory){
40 fsl_report_oom;
41 rc = FSL_RC_OOM;
42 goto end;
43 }
44 ```
45
46 or:
47
48 ```
49 if(FSL_RC_OOM==fs){ fsl_report_oom; }
50 ```
51
52 Note that this macro _may_ expand to encompass multiple commands
53 so must never be used as the RHS of an `if` without squiggly
54 braces surrounding it (as in the above example).
55
56 This macro is _not_ invoked in _every_ possible OOM case, so
57 cannot simply be replaced with abort() to kill the app on OOM.
58 For that, apply a custom allocator via fsl_lib_configurable.
59*/
60#if !defined(fsl_report_oom_impl)
61#define fsl_report_oom_impl \
62 fprintf(stderr,"OOM @ %s:%d\n", __FILE__, __LINE__)
63#endif
64
65/* older name fos fsl_report_oom */
66#define FSL__WARN_OOM fsl_report_oom_impl
67#define fsl_report_oom fsl_report_oom_impl
68
69/**
70 @struct fsl_cx
71
72 The main Fossil "context" type. This is the first argument to
73 many Fossil library API routines, and holds all state related
74 to a checkout and/or repository and/or global fossil configuration
75 database(s).
76
77 An instance's lifetime looks something like this:
78
79 ```
80 int rc;
81 fsl_cx * f = NULL; // ALWAYS initialize to NULL or results are undefined
82 rc = fsl_cx_init( &f, NULL );
83 assert(!rc);
84 rc = fsl_repo_open( f, "myrepo.fsl" );
85 ...use the context, and clean up when done...
86 fsl_cx_finalize(f);
87 ```
88
89 The contents of an fsl_cx instance are strictly private, for use
90 only by APIs in this library. Any client-side dependencies on
91 them will lead to undefined behaviour at some point.
92*/
94typedef struct fsl_db fsl_db;
96typedef struct fsl_stmt fsl_stmt;
97//typedef struct fsl__cx fsl_cx;
98typedef struct fsl_cx fsl_cx;
99
100/**
101 This enum defines type ID tags with which the API tags fsl_db
102 instances so that the library can figure out which DB is
103 which. This is primarily important for certain queries, which
104 need to know whether they are accessing the repo or config db,
105 for example.
106
107 As of 2021-10, the fossil context db model has long been, and is
108 very, very likely to remain:
109
110 - When a context starts up, it creates a temporary db for use
111 as its `main` db.
112
113 - When a repo or checkout db are opened, they are `ATTACH`ed to the
114 main db with the names `repo` resp. `ckout`. (Note that those
115 differ from the names fossil(1) uses: `repository` and
116 `localdb`.)
117
118 A large amount of the library code is written _as if_ the library
119 (roughly) followed fossil's model of using separate sqlite3
120 objects, even though it does not do so. The reason is historical:
121 when starting the libfossil port, it was clear that fossil's
122 internal connection juggling was going to be painful for the
123 library, so the internal API was shaped to permit two separate
124 approaches:
125
126 Approach 1: the first db which gets opened (repo, checkout, or
127 config) becomes the `main` db and all others get attached using
128 their API-standard alias. That is _mostly_ what fossil does, but it
129 leads to fossil sometimes having to "swap" connections by closing
130 the db and re-opening it so that the db names are in a state which
131 fits the current use. That model led to the creation of this
132 enum. However, it also leads to unpredictable database names for
133 purposes of queries, as we're never sure (at the client level or
134 higher library-level APIs) which db is `main` and which has an
135 alias.
136
137 Approach 2: open a temp (or in-memory) db and attach all of the
138 others to that using well-defined names.
139
140 The latter has proven to work well enough that returning to the
141 first approach seems _extremely_ unlikely at this point. Thus some
142 newer library-level code behaves as if the latter model is in effect
143 (which it is).
144
145 The long and the short of the above diversion is that APIs like
146 fsl_cx_db_repo() and fsl_cx_db_ckout() will always return the same
147 database handle, but they can tell whether a given role has been
148 attached or not and will fail in their documented ways when the
149 role's corresponding database has not yet been attached. e.g.
150 `fsl_cx_db_repo()` will return `NULL` if a repo database is not
151 attached.
152
153 @see fsl_db_role_name()
154 @see fsl_cx_db_file_for_role()
155*/
157/**
158 Sentinel "no role" value.
159*/
161/**
162 The global (per user) config db. Analog to fossil's "configdb".
163*/
165/**
166 The repository db. Analog to fossil's "repository".
167*/
169/**
170 The checkout db. Analog to fossil's "localdb".
171*/
173/**
174 Analog to fossil's "main", which is an alias for the first db
175 opened. In this API a fsl_cx instance has a temporary/transient
176 main db opened even if it does not have a repository, checkout, or
177 config db opened.
178*/
180/**
181 Refers to the "temp" database. This is only used by a very few APIs
182 and is outright invalid for most.
183*/
185};
187
188/**
189 Bitmask values specifying "configuration sets". The values in
190 this enum come directly from fossil(1), but they are not part of
191 the db structure, so may be changed over time.
192
193 It seems very unlikely that these will ever be used at the level of
194 this library. They are a "porting artifact" and retained for the
195 time being, but will very likely be removed.
196*/
198/** Sentinel value. */
200/** Style sheet only */
202/** WWW interface appearance */
204/** Ticket configuration */
206/** Project name */
208/** Shun settings */
210/** The USER table */
212/** The CONCEALED table */
214/** Transfer configuration */
216/** Everything */
218/** Causes overwrite instead of merge */
220/** Use the legacy format */
222};
224
225/**
226 Runtime-configurable flags for a fsl_cx instance.
227
228 @see fsl_cx_flag_set()
229 @see fsl_cx_flags_get()
230*/
232/**
233 The "no flags" value. Guaranteed to be 0 and this is the only entry
234 in this enum which is guaranteed to have a stable value.
235*/
237/**
238 Tells us whether or not we want to calculate R-cards by default.
239 Historically they were initially required but eventually made
240 optional due largely to their memory costs.
241*/
243
244/**
245 When encounting artifact types in the crosslinking phase which
246 the library does not currently support crosslinking for, skip over
247 them instead of generating an error. For day-to-day use this is,
248 perhaps counter-intuitively, generally desirable.
249
250 As of 2021-12-04, crosslinking of all core fossil artifact types is
251 supported, so this flag is effectively a no-op until/unless a new
252 artifact type is added to fossil.
253*/
255
256/**
257 By default, fsl_reserved_fn_check() will fail if the given filename
258 is reserved on Windows platforms because such filenames cannot be
259 checked out on Windows. This flag removes that limitation. It
260 should only be used, if at all, for repositories which will _never_
261 be used on Windows.
262*/
264
265/**
266 If on (the default) then an internal cache will be used for
267 artifact loading to speed up operations which do lots of that.
268 Disabling this will save memory but may hurt performance for
269 certain operations.
270*/
272
273/**
274 If on (the default) then fsl_content_get() will use an internal
275 cache to speed up loading of repeatedly-fetched artifacts.
276 Disabling this can be costly.
277*/
279
280/**
281 Internal use only to prevent duplicate initialization of some
282 bits.
283*/
285
286/**
287 Default flags for all fsl_cx instances.
288*/
290
291};
293
294/**
295 List of hash policy values. New repositories should generally use
296 only SHA3 hashes, but older repos may contain SHA1 hashes (perhaps
297 only SHA1), so we have to support those. Repositories may contain
298 a mix of hash types.
299
300 Maintenance ACHTUNG: this enum's values must align with those from
301 fossil(1) because their integer values are used in the
302 `repo.config` table.
303*/
305/** Use only SHA1 hashes. */
307/** Accept SHA1 hashes but auto-promote to SHA3. */
309/** Use SHA3 hashes. */
311/** Use SHA3 hashes exclusively. */
313/** With this policy, fsl_uuid_is_shunned() will always return true
314 for SHA1 hashes, making it "impossible" to get SHA1-hashed content
315 into the repository (for a given value of "impossible"). */
317};
319
320
321/**
322 A macro which invokes its argument (a macro name) to expand to all
323 possible values of fsl_rc_e entries. The macro name passed to it is
324 invoked once for each entry and passed 3 arguments: the enum
325 entry's full name (FSL_RC_...), its integer value, and a help-text
326 string.
327*/
328#define fsl_rc_e_map(E) \
329 E(FSL_RC_OK, 0, \
330 "The quintessential not-an-error value.") \
331 E(FSL_RC_ERROR, 100, \
332 "Generic/unknown error.") \
333 E(FSL_RC_NYI, 101, \
334 "A placeholder return value for not yet implemented functions.") \
335 E(FSL_RC_OOM, 102, \
336 "Out of memory. Indicates that a resource allocation request failed.") \
337 E(FSL_RC_MISUSE, 103, \
338 "API misuse (invalid args).") \
339 E(FSL_RC_RANGE, 104, \
340 "Some range was violated (function argument, UTF character, etc.).") \
341 E(FSL_RC_ACCESS, 105, \
342 "Indicates that access to or locking of a resource was denied " \
343 "by some security mechanism or other.") \
344 E(FSL_RC_IO, 106, \
345 "Indicates an I/O error. Whether it was reading or " \
346 "writing is context-dependent.") \
347 E(FSL_RC_NOT_FOUND, 107, \
348 "Requested resource not found") \
349 E(FSL_RC_ALREADY_EXISTS, 108, \
350 "Indicates that a to-be-created resource already exists.") \
351 E(FSL_RC_CONSISTENCY, 109, \
352 "Data consistency problem") \
353 E(FSL_RC_REPO_NEEDS_REBUILD, 110, \
354 "Indicates that the requested repo needs to be rebuilt.") \
355 E(FSL_RC_NOT_A_REPO, 111, \
356 "Indicates that the requested repo is not, in fact, a repo. " \
357 "Also used by some APIs to indicate that they require a " \
358 "repository db but none has been opened.") \
359 E(FSL_RC_REPO_VERSION, 112, \
360 "Indicates an attempt to open a too-old or too-new repository db.") \
361 E(FSL_RC_DB, 113, \
362 "Indicates db-level error (e.g. statement prep failed). In such " \
363 "cases, the error state of the related db handle (fsl_db) or " \
364 "Fossil context (fsl_cx) will be updated to contain more " \
365 "information directly from the db driver.") \
366 E(FSL_RC_BREAK, 114, \
367 "Used by some iteration routines to indicate that " \
368 "iteration should stop prematurely without an error.") \
369 E(FSL_RC_STEP_ROW, 115, \
370 "Indicates that fsl_stmt_step() has fetched a row and " \
371 "the cursor may be used to access the current row state (e.g. using " \
372 "fsl_stmt_get_int32() and friends). It is strictly illegal to use " \
373 "the fsl_stmt_get_xxx() APIs unless fsl_stmt_step() has returned " \
374 "this code.") \
375 E(FSL_RC_STEP_DONE, 116, \
376 "Indicates that fsl_stmt_step() has reached the end of " \
377 "the result set and that there is no row data to process. This is also the " \
378 "result for non-fetching queries (INSERT and friends). It is strictly " \
379 "illegal to use the fsl_stmt_get_xxx() APIs after fsl_stmt_step() has " \
380 "returned this code.") \
381 E(FSL_RC_STEP_ERROR, 117, \
382 "Indicates that a db-level error occurred " \
383 "during a fsl_stmt_step() iteration.") \
384 E(FSL_RC_TYPE, 118, \
385 "Indicates that some data type or logical type is incorrect " \
386 "(e.g. an invalid card type in conjunction with a given fsl_deck).") \
387 E(FSL_RC_NOT_A_CKOUT, 119, \
388 "Indicates that an operation which requires a checkout does not " \
389 "have a checkout to work on.") \
390 E(FSL_RC_REPO_MISMATCH, 120, \
391 "Indicates that a repo and checkout do not belong together.") \
392 E(FSL_RC_CHECKSUM_MISMATCH, 121, \
393 "Indicates that a checksum comparison failed, possibly indicating " \
394 "that corrupted or unexpected data was just read.") \
395 E(FSL_RC_LOCKED, 122, \
396 "Indicates a resource-locking error of some sort, normally a db lock.") \
397 E(FSL_RC_CONFLICT, 123, \
398 "Indicates that a merge conflict, or some other context-dependent " \
399 "type of conflict, was detected.") \
400 E(FSL_RC_UNKNOWN_RESOURCE, 124, \
401 "This is a special case of FSL_RC_NOT_FOUND, intended specifically " \
402 "to differentiate from \"file not found in filesystem\" " \
403 "(FSL_RC_NOT_FOUND) and \"fossil does not know about this file\" in " \
404 "routines for which both might be an error case. An example is a " \
405 "an operation which wants to update a repo file with contents " \
406 "from the filesystem - the file might not exist or it might not be " \
407 "in the current repo db. " \
408 "That said, this can also be used for APIs which search for other " \
409 "resources (UUIDs, tickets, etc.), but FSL_RC_NOT_FOUND is already " \
410 "fairly well entrenched in those cases and is unambiguous, so this " \
411 "code is only needed by APIs for which both cases described above " \
412 "might happen." ) \
413 E(FSL_RC_SIZE_MISMATCH, 125, \
414 "Indicates that a size comparison check failed. " \
415 "TODO: remove this if it is not used." ) \
416 E(FSL_RC_DELTA_INVALID_SEPARATOR, 126, \
417 "Indicates that an invalid separator was encountered while " \
418 "parsing a delta." ) \
419 E(FSL_RC_DELTA_INVALID_SIZE, 127, \
420 "Indicates that an invalid size value was encountered while " \
421 "parsing a delta." ) \
422 E(FSL_RC_DELTA_INVALID_OPERATOR, 128, \
423 "Indicates that an invalid operator was encountered while parsing " \
424 "a delta.") \
425 E(FSL_RC_DELTA_INVALID_TERMINATOR, 129, \
426 "Indicates that an invalid terminator was encountered while " \
427 "parsing a delta.") \
428 E(FSL_RC_SYNTAX, 130, \
429 "Indicates a generic syntax error in a structural artifact. Some " \
430 "types of manifest-releated errors are reported with more specific " \
431 "error codes, e.g. FSL_RC_RANGE if a given card type appears too " \
432 "often.") \
433 E(FSL_RC_AMBIGUOUS, 131, \
434 "Indicates that some value or expression is ambiguous. Typically " \
435 "caused by trying to resolve ambiguous symbolic names or hash " \
436 "prefixes to their full hashes.") \
437 E(FSL_RC_NOOP, 132, \
438 "Used by fsl_checkin_commit(), and similar operations, to indicate " \
439 "that they're failing because they would be no-ops. That would " \
440 "normally indicate a \"non-error\", but a condition the caller " \
441 "certainly needs to know about.") \
442 E(FSL_RC_PHANTOM, 133, \
443 "A special case of FSL_RC_NOT_FOUND which indicates that the " \
444 "requested repository blob could not be loaded because it is a " \
445 "phantom. That is, the record is found but its contents are not " \
446 "available. Phantoms are blobs which fossil knows should exist, " \
447 "because it's seen references to their hashes, but for which it does " \
448 "not yet have any content.") \
449 E(FSL_RC_UNSUPPORTED, 134, \
450 "Indicates that the requested operation is unsupported.") \
451 E(FSL_RC_MISSING_INFO, 135, \
452 "Indicates that the requested operation is missing certain required " \
453 "information.") \
454 E(FSL_RC_DIFF_BINARY, 136, \
455 "Special case of FSL_RC_TYPE triggered in some diff APIs, indicating " \
456 "that the API cannot diff what appears to be binary data.") \
457 E(FSL_RC_DIFF_WS_ONLY, 137, \
458 "Triggered by some diff APIs to indicate that only whitespace " \
459 "changes we found and the diff was requested to ignore whitespace.") \
460 E(FSL_RC_INTERRUPTED, 138, \
461 "Intended to be used with fsl_cx_interrupt() by signal handlers " \
462 "and UI threads.") \
463 E(FSL_RC_WOULD_FORK, 139, \
464 "Intended to be used by operations which would cause what is " \
465 "presumably an unintended fork. Fossil does not have any issues with " \
466 "forking, but practice suggests that most forks (that is, checking " \
467 "in to a non-leaf version) are unintentional.") \
468 E(FSL_RC_CANNOT_HAPPEN, 140, \
469 "This is intended only for internal use with fsl__fatal(), to " \
470 "report conditions which \"cannot possibly happen\".") \
471 E(FSL_RC_TIMEOUT, 141, \
472 "Indicates that a context-specific timeout was triggered.") \
473 E(FSL_RC_REMOTE, 142, \
474 "Indicates that an error was received from a remote during " \
475 "syncing.") \
476 E(FSL_RC_SHUNNED, 143, \
477 "Indicates that a given blob is in the SHUNNED list.") \
478 E(FSL_RC_end,999, \
479 "Must be the final entry in the enum. Used for creating client-side " \
480 "result codes which are guaranteed to live outside of this one's " \
481 "range.")
482
483/**
484 Most functions in this library which return an int return result
485 codes from the fsl_rc_e enum. None of these entries are guaranteed
486 to have a specific value across library versions except for
487 FSL_RC_OK, which is guaranteed to always be 0 (and the API
488 guarantees that no other code shall have a value of zero).
489
490 The only reasons numbers are hard-coded to the values is to
491 simplify debugging during development. Clients may use
492 fsl_rc_cstr() to get some human-readable (or programmer-readable)
493 form for any given value in this enum.
494*/
496
497#define E(N,V,H) N = V,
499#undef E
500
501};
502typedef enum fsl_rc_e fsl_rc_e;
503
504/**
505 File permissions flags supported by fossil manifests. Their numeric
506 values are a hard-coded part of the Fossil architecture and must
507 not be changed. Note that these refer to manifest-level permissions
508 and not filesystem-level permissions (though they translate to/from
509 filesystem-level meanings at some point).
510*/
512/** Indicates a regular, writable file. */
514/** Indicates a regular file with the executable bit set. */
516/**
517 Indicates a symlink. Note that symlinks do not have the executable
518 bit set separately on Unix systems. Also note that libfossil does
519 NOT YET IMPLEMENT symlink support like fossil(1) does - it
520 currently treats symlinks (mostly) as Unix treats symlinks.
521*/
523};
525
526/**
527 Returns a "standard" string form for a fsl_rc_e code. The string
528 is primarily intended for debugging purposes. The returned bytes
529 are guaranteed to be static and NUL-terminated. They are not
530 guaranteed to contain anything useful for any purposes other than
531 debugging and tracking down problems. If passed a code which is
532 not in the fsl_rc_e enum, it returns NULL.
533*/
534FSL_EXPORT char const * fsl_rc_cstr(int rc);
535
536/**
537 Returns the value of FSL_LIBRARY_VERSION used to compile the
538 library. If this value differs from the value the caller was
539 compiled with, Chaos might ensue.
540
541 The API does not yet have any mechanism for determining
542 compatibility between library versions and it also currently does
543 no explicit checking to disallow incompatible versions.
544*/
546
547/**
548 Returns the SCM-specific version info for libfossil (the hash and
549 timestamp of it's own source's version).
550*/
552
553/**
554 Returns true (non-0) if yourLibVersion compares lexically equal to
555 FSL_LIBRARY_VERSION, else it returns false (0). It is intended to
556 be passed the FSL_LIBRARY_VERSION string the client code was built
557 with.
558*/
559FSL_EXPORT bool fsl_library_version_matches(char const * yourLibVersion);
560
561/**
562 This type, accessible to clients via the ::fsl_lib_configurable
563 global, contains configuration-related data for the library
564 which can be swapped out by clients.
565*/
567 /**
568 Library-wide allocator. It may be replaced by the client IFF it
569 is replaced before the library allocates any memory. The default
570 implementation uses the C-standard de/re/allocators. Modifying
571 this member while any memory allocated through it is still "live"
572 leads to undefined results. There is an exception: a "read-only"
573 middleman proxy which does not change how the memory is allocated
574 or intepreted can safely be swapped in or out at any time
575 provided the underlying allocator stays the same and the client
576 can ensure that there are no thread-related race
577 conditions. e.g. it is legal to swap this out with a proxy which
578 logs allocation requests and then forwards the call on to the
579 original implementation, and it is legal to do so at essentially
580 any time. The important thing this that all of the
581 library-allocated memory goes through a single underlying
582 (de)allocator for the lifetime of the application.
583 */
585};
588
589/**
590 SQLite Encryption Extension (SEE) key types for use with
591 fsl_see_key_f(). Each of these options corresponds to one
592 of the key-entry modes supported by SEE via pragmas,
593 e.g. PRAGMA key, PRAGMA textkey, and PRAGMA hexkey.
594*/
596 /** Sentinel value indicating "not an SEE key". */
598 /** Corresponses to (PRAGMA key). */
600 /** Corresponses to (PRAGMA hexkey). Binary data to be hex-encoded
601 by the library. */
603 /** Corresponses to (PRAGMA hexkey). Encoded by the client as a
604 series of hex digits. */
606 /** Corresponses to (PRAGMA textkey). */
608};
610
611/**
612 EXPERIMENTAL and subject to change. But it seems to do its job
613 reasonably well.
614
615 A callback type for fetching an encryption key for use with the
616 SQLite Encryption Extension API. This is only for use in
617 SEE-capable builds.
618
619 `pState` is the pointer provided by the client for use here
620 (typically via fsl_cx_config::see::pState). It is opaque to the
621 library, intended solely for the SEE client's use.
622
623 `zDbFile` is the NUL-terminated name of the db for which the key is
624 being requested.
625
626 If a key is available, it must be appended to pOut using
627 fsl_buffer_append() (or equivalent).
628
629 On success, it must return 0. Any non-0 result value is treated by
630 the library as failure to open the db, with one exception:
631 FSL_RC_UNSUPPORTED indicates that decryption is not supported but
632 opening of a database will not fail fatally for this result.
633 Instead, if the db really is encrypted, it will fail later when the
634 db is first used.
635
636 If it populates pOut then it must set `*keyType` to one of the
637 entries from the fsl_see_keytype_e enum, indicating the type of the
638 key.
639
640 If the implementation has no key to provide for the db, but does
641 not know that to be an error, it should simply return 0 and not add
642 any bytes to pOut. It need not set `*keyType` in this case, as the
643 library guarantees that it will initially have the value
644 FSL_SEE_KEYTYPE_NONE.
645
646 The library does not cache the results of these calls and may need
647 to call this multiple times for the same database during the life
648 of a single context. (Ordinarily, though, the SCM databases are
649 opened a single time and left that way.)
650
651 A recommended convention, derived from fossil(1), is to name
652 encrypted repositories with a suffix of ".efossil". Implementations
653 of this callback could use such a convention to determine whether
654 or not a key is necessary for the db (something this library cannot
655 do on its own).
656*/
657typedef int (*fsl_see_key_f)(void * pState, const char *zDbFile,
658 fsl_buffer * pOut, int *keyType);
659
660/**
661 Expands to a mapping of all fsl_msg types by invoking
662 E(NAME,VALUE,PayloadDescription) for each one. NAME is the suffix
663 part of the name, e.g. mask_type instead of
664 FSL_MSG_mask_type. VALUE is its integer
665 value. PayloadDescription is a human-legible string typically
666 noting the data type of the payload.
667
668 Each entry encodes the data type corresponding to the associated
669 fsl_msg object's payload member: mask the message type value
670 against FSL_MSG_mask_type to get the payload's type.
671
672 This mechanism was added for the sync subsystem and the goal is now
673 to replace some of the library's disparate callbacks with this
674 mechanism.
675*/
676#define fsl_msg_map(E) \
677 E(INVALID, 0, "Sentinel value") \
678 E(mask_type, 0x7F000000, "Data type mask") \
679 E(mask_reserved, 0x00FFFF00, "Reserved") \
680 E(mask_purpose, 0x000000FF, "Message purpose ID") \
681 E(type_null, 0x01000000, "NULL") \
682 E(type_string, 0x02000000, "(char const *)") \
683 E(type_buffer, 0x03000000, "(fsl_buffer const *)") \
684 E(type_size, 0x04000000, "(fsl_size_t const *)") \
685 E(type_blob, 0x06000000, "(fsl_msg_blob const *)" ) \
686 E(type_rebuild_step, 0x07000000, "(fsl_rebuild_step const *)" ) \
687 E(ERROR, 0x01 | FSL_MSG_type_string, "Error string") \
688 E(INFO, 0x02 | FSL_MSG_type_string, "Info string") \
689 E(DEBUG, 0x03 | FSL_MSG_type_string, "Debugging string") \
690 E(TMPFILE, 0x04 | FSL_MSG_type_string, "value=name of temp file left over") \
691 E(CONNECT, 0x05 | FSL_MSG_type_size, "value=trip number") \
692 E(RCV_BLOB, 0x06 | FSL_MSG_type_blob, "Blob received") \
693 E(RCV_MESSAGE, 0x07 | FSL_MSG_type_string, "\"message\" card from remote") \
694 E(RCV_CONFIG, 0x08 | FSL_MSG_type_string, "Config group name") \
695 E(REBUILD_STEP, 0x09 | FSL_MSG_type_rebuild_step, "") \
696 E(REBUILD_DONE, 0x0A | FSL_MSG_type_rebuild_step, "") \
697 E(TXN_BEGIN, 0x0B | FSL_MSG_type_size, "value=transaction level") \
698 E(TXN_COMMIT, 0x0C | FSL_MSG_type_size, "value=transaction level") \
699 E(TXN_ROLLBACK, 0x0D | FSL_MSG_type_size, "value=transaction level")
700
701/**
702 Message type flags Indicators for use with fsl_sc::status,
703 fsl_xfer_emit(), and friends.
704*/
706#define E(NAME,VAL,IGNORED) FSL_MSG_ ## NAME = VAL,
708#undef E
709};
710
711typedef enum fsl_msg_e fsl_msg_e;
712
713/**
714 Message payload type for FSL_MSG_type_blob.
715*/
717 char const * hash;
718 fsl_int_t size /* negative for phantom blobs */;
719};
721
722/**
723 Returns the C-string form of the given sync message type, or NULL
724 if e is invalid.
725*/
727
728/**
729 A "transfer context" type used by many of the sync transfer
730 APIs. This type is opaque to client code.
731*/
732typedef struct fsl__xfer fsl_xfer;
733
734/**
735 A message object type for use with fsl_sc::status().
736*/
737struct fsl_msg {
738 /** The type of status message. */
740
741 /**
742 An optional bit of informative text. If set, the bytes are owned
743 by the library and may be (and likely are) invalidated as soon as
744 the message callback returns. The data type depends on this->type
745 and it can be interpreted by deciphering fsl_msg_e.
746 */
747 void const * payload;
748
749 /**
750 This message's fsl_cx context, providing the callback with access
751 to the associated SCM state.
752 */
754};
755
756typedef struct fsl_msg fsl_msg;
757
758/** fsl_msg instance intended for const-copy initialization. */
759#define fsl_msg_empty_m { \
760 .type = FSL_MSG_INVALID, .payload = NULL, \
761 .f = NULL \
762 }
763
764/** fsl_msg instance intended for non-const copy initialization. */
765extern const fsl_msg fsl_msg_empty;
766
767/**
768 A callback for use with the library's message-passing subsystem, to
769 provide feedback during potentially long-running work, in
770 particular synchronization with a remote.
771
772 Implementations are passed the a message object and any state
773 associated with the callback.
774
775 If the function returns non-0, the operation is aborted and that
776 result is propagated back up through the API. On error, this
777 callback is expected to call either of fsl_cx_err_set() or the
778 fsl_xfer_error() family of functions and return that code.
779
780 Messages are synchronous - the library must wait on a response from
781 this function before continuing. Ergo, clients should not perform
782 long work in the status callback (or should do so in a separate
783 thread which _does_not_ use msg->f (which is not
784 thread-safe)).
785
786 This method is intended primarily for logging or non-interactive
787 feedback, with the exception of the ability to return non-0 to
788 interrupt the sync. e.g. an implementation could return
789 FSL_RC_BREAK in response to an application-side cancel/interrupt
790 button being triggered.
791
792 When triggered via a sync operation, the library guarantees that a
793 db transaction will be in place when it calls this, a further
794 incentive to keep implementations short and fast because the db is
795 necessarily locked during that time.
796*/
797typedef int (*fsl_msg_f)(fsl_msg const * msg, void *state);
798
799/**
800 Client callback info for receiving various events during
801 fossil sync processing.
802*/
804 /** Callback function. */
806 /** State for the final argument to this->callback(). */
807 void * state;
808};
810#define fsl_msg_listener_empty_m { .callback=0, .state=0 }
812
813
814/**
815 A part of the configuration used by fsl_cx_init() and friends.
816*/
818 /**
819 If true, all SQL which goes through the fossil engine will be
820 traced to stdout. This is, of course, only intended for use in
821 debugging.
822
823 TODO: replace this with a fsl_outputer.
824 */
826 /**
827 If true, the fsl_print() SQL function will output its output to the
828 fsl_output()-configured channel, else it is a no-op.
829 */
831
832 /**
833 Specifies the default hash policy.
834 */
836
837 /**
838 Listener for fsl_msg-type events. This is how the library
839 provides status updates for potentially long-running operations
840 like synchronization.
841 */
843
844 /**
845 The output channel for the Fossil instance.
846
847 Reminder to self: if this is not used at the library level then
848 consider removing it. This addition may have been a piece of
849 unnecessary overengineering. To the best of my recollection, the
850 library internals do not use this, but the fcli API does. If that
851 is indeed the case, we can move it into that API.
852 */
854
855 /**
856 Config state for use with the SQLite3 Encryption Extension (SEE).
857 This state is only useful together with encrypted databases.
858 */
859 struct {
860 /**
861 If this is non NULL, it is called when the library needs to
862 fetch the encryption key to use for a db. Its first
863 argument will be the pState member of this struct.
864
865 Note that the library does not actually know whether it is built
866 with SEE support or not.
867 */
869 /**
870 Optional state for use as the first argument to getSEEKey. This
871 may be NULL, so long as the getSEEKey argument accepts
872 NULL. Ownership of this pointer is the client's
873 responsibility. It must survive as as long as any fsl_cx which
874 it is assigned to, but the library cannot know when (or
875 whether) to clean it up.
876 */
877 void * pState;
879};
880
881/**
882 fsl_cx_config instance initialized with defaults, intended for
883 const-copy initialization.
884*/
885#define fsl_cx_config_empty_m { \
886 .traceSql = 0, \
887 .sqlPrint = 0, \
888 .hashPolicy = FSL_HPOLICY_SHA3, \
889 .listener = fsl_msg_listener_empty_m, \
890 .output = {.out=NULL, .state=NULL}, \
891 .see = {.getSEEKey = NULL, .pState = NULL} \
892}
893
894/**
895 fsl_cx_config instance initialized with defaults, intended for
896 non-const copy initialization.
897*/
899
900/**
901 Allocates a new fsl_cx instance, which must eventually
902 be passed to fsl_cx_finalize() to clean it up.
903 Normally clients do not need this - they can simply pass
904 a pointer to NULL as the first argument to fsl_cx_init()
905 to let it allocate an instance for them.
906*/
908
909/**
910 Initializes a fsl_cx instance. tgt must be a pointer to NULL,
911 e.g.:
912
913 ```
914 fsl_cxt * f = NULL; // NULL is important - see below
915 int rc = fsl_cx_init( &f, NULL );
916 ```
917
918 It is very important that f be initialized to NULL _or_ to an
919 instance which has been properly allocated and empty-initialized
920 (e.g. via fsl_cx_malloc()). If *tgt is NULL, this routine
921 allocates the context, else it assumes the caller did. If f
922 points to unitialized memory then results are undefined.
923
924 If the second parameter is NULL then default implementations are
925 used for the context's output routine and other options. If it
926 is not NULL then param->allocator and param->output must be
927 initialized properly before calling this function. The contents
928 of param are bitwise copied by this function and ownership of
929 the returned value is transfered to *tgt in all cases except
930 one:
931
932 If passed a pointer to a NULL context and this function cannot
933 allocate it, it returns FSL_RC_OOM and does not modify *tgt. In
934 this one case, ownership of the context is not changed (as there's
935 nothing to change!). On any other result (including errors),
936 ownership of param's contents are transfered to *tgt and the client
937 is responsible for passing *tgt ot fsl_cxt_finalize() when he is
938 done with it. Note that (like in sqlite3), *tgt may be valid memory
939 even if this function fails, and the caller must pass it to
940 fsl_cx_finalize() whether or not this function succeeds unless it
941 fails at the initial OOM (which the client can check by seeing if
942 (*tgt) is NULL, but only if he set it to NULL before calling this).
943
944 Returns 0 on success, FSL_RC_OOM on an allocation error,
945 FSL_RC_MISUSE if (!tgt). If this function fails, it is illegal to
946 use the context object except to pass it to fsl_cx_finalize(), as
947 explained above.
948
949 @see fsl_cx_finalize()
950*/
951FSL_EXPORT int fsl_cx_init( fsl_cx ** tgt, fsl_cx_config const * param );
952
953/**
954 Frees all memory associated with f, which must have been
955 allocated/initialized using fsl_cx_malloc(), fsl_cx_init(), or
956 equivalent, or created on the stack and properly initialized (via
957 fsl_cx_init() or copy-constructed from fsl_cx_empty). If it was
958 allocated using fsl_cx_malloc(), this function frees f, else the
959 memory is owned by someone else and it is not freed.
960
961 This function triggers any finializers set for f's client state
962 or output channel.
963
964 This is a no-op if !f and is effectively a no-op if f has no
965 state to destruct.
966*/
968
969
970/**
971 Sets or unsets one or more option flags on the given fossil
972 context. flags is the flag or a bitmask of flags to set (from the
973 fsl_cx_flags_e enum). If enable is true the flag(s) is (are) set,
974 else it (they) is (are) unset. Returns the _previous_ set of flags
975 (that is, the state they were in before this call was made).
976
977 @see fsl_cx_flags_get()
978*/
980 bool enable );
981
982/**
983 Returns f's flags.
984
985 @see fsl_cx_flag_set()
986*/
988
989/**
990 Sets the Fossil error state to the given error code and
991 fsl_appendf()-style format string/arguments. On success it
992 returns the code parameter. It does not return 0 unless code is
993 0, and if it returns a value other than code then something went
994 seriously wrong (e.g. allocation error: FSL_RC_OOM) or the
995 arguments were invalid: !f results in FSL_RC_MISUSE.
996
997 If !fmt then fsl_rc_cstr(code) is used to create the
998 error string.
999
1000 As a special case, if code is FSL_RC_OOM, no error string is
1001 allocated (because it would likely fail, assuming the OOM
1002 is real).
1003
1004 As a special case, if code is 0 (the non-error value) then fmt is
1005 ignored and any error state is cleared.
1006*/
1007FSL_EXPORT int fsl_cx_err_set( fsl_cx * f, int code, char const * fmt, ... );
1008
1009/**
1010 va_list counterpart to fsl_cx_err_set().
1011*/
1012FSL_EXPORT int fsl_cx_err_setv( fsl_cx * f, int code, char const * fmt,
1013 va_list args );
1014
1015/**
1016 Fetches the error state from f. See fsl_error_get() for the semantics
1017 of the parameters and return value.
1018*/
1019FSL_EXPORT int fsl_cx_err_get( fsl_cx * f, char const ** str, fsl_size_t * len );
1020
1021
1022/**
1023 Returns f's error object. It is owned by f, and its address is
1024 stable as long as f is valid. It's provided as a semi-formal way
1025 for not-quite-core code to get access to f->error without having to
1026 reach into f directly. It should only be preferred over
1027 fsl_cx_err_set()/get() when an arbitrary fsl_error object is needed
1028 for an API (like fsl_buffer_escape_arg()) and we know we'd like to
1029 unconditionally propagate that error via f's error state. In such
1030 cases, using this object can avoid a second allocation to copy the
1031 error message.
1032*/
1034
1035/** Non-const counterpart of fsl_cx_err_ec(). */
1037
1038/**
1039 Resets's f's error state, basically equivalent to
1040 fsl_cx_err_set(f,0,NULL). This may be necessary for apps if they
1041 rely on looking at fsl_cx_err_get() at the end of their
1042 app/routine, because error state survives until it is cleared, even
1043 if the error held there was caught and recovered. This function
1044 might keep error string memory around for re-use later on.
1045
1046 This does NOT reset the fsl_cx_interrupted() flag!
1047*/
1049
1050/**
1051 Replaces f's error state with the contents of err, taking over
1052 any memory owned by err (but not err itself). Returns the new
1053 error state code (the value of err->code before this call) on
1054 success. The only error case is if !f (FSL_RC_MISUSE). If err is
1055 NULL then f's error state is cleared and 0 is returned. err's
1056 error state is cleared by this call.
1057*/
1059
1060/**
1061 If f has error state then it outputs its error state to its output
1062 channel and returns the result of fsl_output(). Returns 0 if f has
1063 no error state our output of the state succeeds. If addNewline is
1064 true then it adds a trailing newline to the output, else it does
1065 not.
1066
1067 This is intended for testing and debugging only, and not as an
1068 error reporting mechanism for a full-fledged application.
1069*/
1070FSL_EXPORT int fsl_cx_err_report( fsl_cx * f, bool addNewline );
1071
1072/**
1073 Unconditionally Moves db->error's state into f (without requiring
1074 any allocation). If db is NULL then f's primary db connection is
1075 used. Returns FSL_RC_MISUSE if (!db && f-is-not-opened), with the
1076 caveat f _always_ has a db connection under the current connection
1077 architecture. On success it returns f's new error code (which may be
1078 0).
1079
1080 The main purpose of this function is to propagate db-level errors
1081 up to higher-level code which deals directly with the f object but
1082 not the underlying db(s).
1083
1084 @see fsl_cx_uplift_db_error2()
1085*/
1087
1088/**
1089 If rc is not 0 and f has no error state but db does, this calls
1090 fsl_cx_uplift_db_error() and returns its result, else returns
1091 rc. If db is NULL, f's main db connection is used. It is intended
1092 to be called immediately after calling a db operation which might
1093 have failed, and passed that operation's result.
1094
1095 As a special case, if rc is FSL_RC_OOM, this function has no side
1096 effects and returns rc. The intention of that is to keep a
1097 propagated db-level error (which may perhaps be stale by the time
1098 this is called) from hiding an OOM error.
1099
1100 Results are undefined if db is NULL and f has no main db
1101 connection.
1102*/
1104
1105/**
1106 Outputs the first n bytes of src to f's configured output
1107 channel. Returns 0 on success, 0 (without side effects) if !n, else
1108 it returns the result of the underlying output call. This is a
1109 harmless no-op if f is configured with no output channel.
1110
1111 Results are undefined if f or src are NULL.
1112
1113 @see fsl_outputf()
1114 @see fsl_flush()
1115*/
1116FSL_EXPORT int fsl_output( fsl_cx * f, void const * src,
1117 fsl_size_t n );
1118
1119/**
1120 Flushes f's output channel. Returns 0 on success. If the flush
1121 routine is NULL then this is a harmless no-op. Results are undefined
1122 if f is NULL.
1123
1124 @see fsl_outputf()
1125 @see fsl_output()
1126*/
1128
1129/**
1130 Uses fsl_appendf() to append formatted output to the channel
1131 configured for use with fsl_output(). Returns 0 on success, and
1132 will otherwise return the result of the underlying fsl_cx_format()
1133 call. (Prior to 2025-08-11, it used fsl_appendf() instead.)
1134
1135 Results are undefined if f or fmt are NULL or otherwise malformed.
1136
1137 @see fsl_output()
1138 @see fsl_flush()
1139*/
1140FSL_EXPORT int fsl_outputf( fsl_cx * f, char const * fmt, ... );
1141
1142/**
1143 va_list counterpart to fsl_outputf().
1144*/
1145FSL_EXPORT int fsl_outputfv( fsl_cx * f, char const * fmt, va_list args );
1146
1147
1148/**
1149 A proxy for fsl_appendfv() which pre-processes the format-specifier
1150 string (zFmt) to replace certain placeholders with information
1151 about the fsl_cx object. After doing so, it passes on the adjusted
1152 zFmt to fsl_appendfv().
1153
1154 Placeholders are in the form {{X}}, where X is one of the words
1155 listed below. Any unknown X will cause the whole {{X}} to be
1156 emitted as-is.
1157
1158 Known X values (with quotes for clarity, but the quotes are not
1159 part of X):
1160
1161 - "chkout.dir": gets replaced with the path to the current checkout
1162 directory, without a trailing slash.
1163
1164 - "chkout.dir/": as for ckout-dir but with a trailing slash.
1165
1166 - "repo.db": gets replaced with the path to the current repository
1167 database.
1168
1169 - "user.name": gets replaced with fsl_cx_user_guess().
1170
1171 File and directory names which are empty are emitted as such.
1172
1173 The parser is not robust enough to attempt to recover from failures
1174 related to the "{{" and "}}" parts, and malformed tags may cause it
1175 to skip expansion on the remaining parts of the input (it will be
1176 passed on as-is, warts and all).
1177
1178 Returns 0 on success. Returns FSL_RC_OOM if allocation of the
1179 formatting buffer fails. Else returns the value of the
1180 fsl_appendfv() call.
1181*/
1183 void * outState, char const *zFmt,
1184 va_list args );
1185
1186/**
1187 The elipsis counterpart of fsl_cx_formatv().
1188*/
1190 void * outState, char const *zFmt, ... );
1191
1192/**
1193 Convenience formof fsl_cx_format() which appends the formatted
1194 output to tgt.
1195*/
1197 char const *zFmt, ... );
1198
1199/**
1200 Convenience formof fsl_cx_format() which appends the formatted
1201 output to tgt.
1202*/
1204 char const *zFmt, ... );
1205
1206
1207/**
1208 Sets or clears (if userName is NULL or empty) the default
1209 repository user name for operations which require one.
1210
1211 Returns 0 on success, FSL_RC_MISUSE if f is NULL,
1212 FSL_RC_OOM if copying of the userName fails.
1213
1214 Example usage:
1215 ```
1216 char * u = fsl_user_name_guess();
1217 int rc = fsl_cx_user_set(f, u);
1218 fsl_free(u);
1219 ```
1220
1221 (Sorry about the extra string copy there, but adding a function
1222 which passes ownership of the name string seems like overkill.)
1223
1224 @see fsl_cx_user_guess()
1225*/
1226FSL_EXPORT int fsl_cx_user_set( fsl_cx * f, char const * userName );
1227
1228/**
1229 If f has a user name set (via fsl_cx_user_set()) then this function
1230 returns that value. If none has been set, this tries to guess one,
1231 using the first of:
1232
1233 - The "default-user" value from the checkout db's vvar table.
1234 - The user entry from the repo db's user table with id 1.
1235 - fsl_user_name_guess()
1236
1237 and then assigns it as f's current user name. Returns NULL only on
1238 allocation error or if an environment setup error prevents
1239 detection of the user name. Not having a user name is not normally
1240 a problem, but trying to create new artifacts will fail if they
1241 have no user name to apply to their U-cards.
1242
1243 The returned bytes are owned by f and will be invalidated by
1244 any future calls to fsl_cx_user_set().
1245
1246 Note that the user name is, by default, determined automatically
1247 when a repo or a checkout/repo combination is opened, so client
1248 code does not normally need to call this.
1249*/
1251
1252/**
1253 Returns the name set by fsl_cx_user_set(), or NULL if f has no
1254 default user name set. The returned bytes are owned by f and will
1255 be invalidated by any future calls to fsl_cx_user_set().
1256
1257 @see fsl_cx_user_guess()
1258*/
1259FSL_EXPORT char const * fsl_cx_user_get( fsl_cx const * f );
1260
1261/**
1262 If f is not NULL and has a checkout db opened then this function
1263 returns its name. The bytes are valid until that checkout db
1264 connection is closed. If len is not NULL then *len is (on
1265 success) assigned to the length of the returned string, in
1266 bytes. The string is NUL-terminated, so fetching the length (by
1267 passing a non-NULL 2nd parameter) is optional.
1268
1269 Returns NULL if !f or f has no checkout opened.
1270
1271 @see fsl_ckout_open_dir()
1272 @see fsl_cx_ckout_dir_name()
1273 @see fsl_cx_db_file_config()
1274 @see fsl_cx_db_file_repo()
1275*/
1277 fsl_size_t * len);
1278
1279/**
1280 Equivalent to fsl_ckout_db_file() except that
1281 it applies to the name of the opened repository db,
1282 if any.
1283
1284 @see fsl_cx_db_file_ckout()
1285 @see fsl_cx_db_file_config()
1286*/
1288 fsl_size_t * len);
1289
1290/**
1291 Equivalent to fsl_ckout_db_file() except that
1292 it applies to the name of the opened config db,
1293 if any.
1294
1295 @see fsl_cx_db_file_ckout()
1296 @see fsl_cx_db_file_repo()
1297*/
1299 fsl_size_t * len);
1300
1301/**
1302 Similar to fsl_cx_db_file_ckout() and friends except that it
1303 applies to db file implied by the specified role (2nd
1304 parameter). If no such role is opened, or the role is invalid,
1305 NULL is returned.
1306
1307 Note that the role of FSL_DBROLE_TEMP is invalid here.
1308*/
1310 fsl_dbrole_e r,
1311 fsl_size_t * len);
1312
1313/**
1314 If f has an opened checkout db (from fsl_ckout_open_dir()) then
1315 this function returns the directory part of the path for the
1316 checkout, including (for historical and internal convenience
1317 reasons) a trailing slash. The returned bytes are valid until that
1318 db connection is closed. If len is not NULL then *len is (on
1319 success) assigned to the length of the returned string, in bytes.
1320 The string is NUL-terminated, so fetching the length by passing a
1321 non-NULL 2nd parameter is optional.
1322
1323 Returns NULL if !f or f has no checkout opened.
1324
1325 @see fsl_ckout_open_dir()
1326 @see fsl_ckout_db_file()
1327*/
1329 fsl_size_t * len);
1330
1331/**
1332 Returns a handle to f's main db (which may or may not have any
1333 relationship to the repo/checkout/config databases - that's
1334 unspecified!), or NULL if f has no opened repo or checkout db. The
1335 returned object is owned by f and the client MUST NOT do any of the
1336 following:
1337
1338 - Close the db handle.
1339
1340 - Use transactions without using fsl_db_txn_begin()
1341 and friends.
1342
1343 - Fiddle with the handle's internals. Doing so might confuse its
1344 owning context.
1345
1346 Clients MAY add new user-defined functions, use the handle with
1347 fsl_db_prepare(), and other "mundane" db-related tasks.
1348
1349 Note that the global config db uses a separate db handle accessible
1350 via fsl_cx_db_config().
1351
1352 @see fsl_cx_db_repo()
1353 @see fsl_cx_db_ckout()
1354 @see fsl_cx_db_config()
1355*/
1357
1358/**
1359 If f is not NULL and has had its repo opened via
1360 fsl_repo_open(), fsl_ckout_open_dir(), or similar, this
1361 returns a pointer to that database, else it returns NULL.
1362
1363 @see fsl_cx_db()
1364*/
1366
1367/**
1368 If f is not NULL and has had a checkout opened via
1369 fsl_ckout_open_dir() or similar, this returns a pointer to that
1370 database, else it returns NULL.
1371
1372 @see fsl_cx_db()
1373*/
1375
1376/**
1377 A helper which fetches f's repository db. If f has no repo db
1378 then it sets f's error state to FSL_RC_NOT_A_REPO with a message
1379 describing the requirement, then returns NULL. Returns NULL if
1380 !f.
1381
1382 @see fsl_cx_db()
1383 @see fsl_cx_db_repo()
1384 @see fsl_needs_ckout()
1385 @see fsl_cx_has_ckout()
1386*/
1388
1389/**
1390 The checkout-db counterpart of fsl_needs_repo(). If no checkout is
1391 opened, f's error state is updated with a FSL_RC_NOT_A_CKOUT code
1392 and description of the problem.
1393
1394 @see fsl_cx_db()
1395 @see fsl_needs_repo()
1396 @see fsl_cx_db_ckout()
1397 @see fsl_cx_has_ckout()
1398*/
1400
1401/**
1402 Returns true if the given context has a checkout opened, else
1403 false.
1404
1405 @see fsl_needs_ckout()
1406*/
1408
1409/**
1410 Opens the given database file as f's configuration database.
1411
1412 If f already has a config database opened then:
1413
1414 1) If passed a NULL dbName or dbName is an empty string then this
1415 function returns 0 without side-effects.
1416
1417 2) If passed a non-NULL/non-empty dbName, any existing config db is
1418 closed before opening the named one. The database is created and
1419 populated with an initial schema if needed.
1420
1421 If dbName is NULL or empty then it uses a default db name,
1422 "probably" under the user's home directory (see
1423 fsl_config_global_preferred_name()). To get the name of the
1424 database after it has been opened/attached, use
1425 fsl_cx_db_file_config().
1426
1427 Results are undefined if f is NULL or not properly initialized.
1428
1429 @see fsl_cx_db_config()
1430 @see fsl_config_close()
1431 @see fsl_config_global_preferred_name()
1432*/
1433FSL_EXPORT int fsl_config_open( fsl_cx * f, char const * dbName );
1434
1435/**
1436 Closes/detaches the database connection opened by
1437 fsl_config_open(). If the config db is not opened, this
1438 is a harmless no-op. Note that it does not propagate db-closing
1439 errors because there is no sensible recovery strategy from
1440 such cases.
1441
1442 This operation only fails if the config db is opened and has
1443 an active transaction, in which case f's error state is updated
1444 to reflect that cause of the error.
1445
1446 ACHTUNG: it is imperative that any prepared statements compiled
1447 against the config db be finalized before closing the db. Any
1448 statements prepared using fsl_db_prepare_cached() against the
1449 config db will be automatically finalized by the closing process.
1450
1451 Potential TODO: if a transaction is pending, force a rollback and
1452 close the db anyway. If we do that, this function will change to
1453 return void.
1454
1455 @see fsl_cx_db_config()
1456 @see fsl_config_open()
1457*/
1459
1460/**
1461 If f has an opened configuration db then its handle is returned,
1462 else 0 is returned.
1463
1464 For API consistency's sake, the db handle's "MAIN" name is aliased
1465 to fsl_db_role_name(FSL_DBROLE_CONFIG).
1466
1467 @see fsl_config_open()
1468 @see fsl_config_close()
1469*/
1471
1472/**
1473 Convenience form of fsl_db_prepare() which uses f's main db.
1474 Returns 0 on success. On preparation error, any db error state is
1475 uplifted from the db object to the fsl_cx object. Returns
1476 FSL_RC_RANGE if !*sql.
1477
1478 Results are undefined if f or sql are NULL or otherwise
1479 invalid.
1480*/
1482 char const * sql, ... );
1483
1484/**
1485 va_list counterpart of fsl_cx_prepare().
1486*/
1488 char const * sql, va_list args );
1489
1490/**
1491 Convenience form of fsl_db_prepare_cached() which uses f's main db.
1492 Returns 0 on success. On preparation error, any db error state is
1493 uplifted from the db object to the fsl_cx object. Returns
1494 FSL_RC_RANGE if !*sql.
1495
1496 Results are undefined if f or sql are NULL or otherwise
1497 invalid.
1498*/
1500 char const * sql, ... );
1501
1502/**
1503 va_list counterpart of fsl_cx_prepare_cached().
1504*/
1506 char const * sql, va_list args );
1507
1508/**
1509 Convenience form of fsl_db_exec() which uses f's main db handle.
1510 Returns 0 on success. On statement preparation or execution error,
1511 the db's error state is uplifted into f and that result is
1512 returned. Results are undefined if f or sql are NULL or otherwise
1513 invalid.
1514*/
1515FSL_EXPORT int fsl_cx_exec( fsl_cx * f, char const * sql, ... );
1516
1517/**
1518 va_list counterpart of fsl_cx_exec().
1519*/
1520FSL_EXPORT int fsl_cx_execv( fsl_cx * f, char const * sql, va_list args );
1521
1522/**
1523 The fsl_db_exec_multi() counterpart of fsl_cx_exec(). Results are
1524 undefined if f or sql are NULL or otherwise invalid.
1525*/
1526FSL_EXPORT int fsl_cx_exec_multi( fsl_cx * f, char const * sql, ... );
1527
1528/**
1529 va_list counterpart of fsl_cx_exec_multi().
1530*/
1531FSL_EXPORT int fsl_cx_exec_multiv( fsl_cx * f, char const * sql,
1532 va_list args );
1533
1534/**
1535 Wrapper around fsl_db_last_insert_id() which uses f's main
1536 database. Returns -1 if !f or f has no opened db.
1537
1538 @see fsl_cx_db()
1539*/
1541
1542
1543/**
1544 Works similarly to fsl_stat(), except that zName must refer to a
1545 path under f's current checkout directory. Note that this stats
1546 local files, not repository-level content.
1547
1548 If relativeToCwd is true then the filename is
1549 resolved/canonicalized based on the current working directory (see
1550 fsl_getcwd()), otherwise f's current checkout directory is used as
1551 the virtual root. This makes a subtle yet important difference in
1552 how the name is resolved. Applications taking input from users
1553 (e.g. CLI apps) will normally want to resolve from the current
1554 working dir (assuming the filenames were passed in from the
1555 CLI). In a GUI environment, where the current directory is likely
1556 not the checkout root, resolving based on the checkout root
1557 (i.e. relativeToCwd=false) is probably saner.
1558
1559 Returns 0 on success. Errors include, but are not limited to:
1560
1561 - FSL_RC_MISUSE if !zName.
1562
1563 - FSL_RC_NOT_A_CKOUT if f has no opened checkout.
1564
1565 - If fsl_is_simple_pathname(zName) returns false then
1566 fsl_ckout_filename_check() is used to normalize the name. If
1567 that fails, its failure code is returned.
1568
1569 - As for fsl_stat().
1570
1571 See fsl_stat() for more details regarding the tgt parameter.
1572
1573 TODO: fossil-specific symlink support. Currently it does not
1574 distinguish between symlinks and non-links.
1575
1576 @see fsl_cx_stat2()
1577*/
1578FSL_EXPORT int fsl_cx_stat( fsl_cx * f, bool relativeToCwd,
1579 char const * zName, fsl_fstat * tgt );
1580
1581/**
1582 This works identically to fsl_cx_stat(), but provides more
1583 information about the file being stat'd.
1584
1585 If nameOut is not NULL then the resolved/normalized path to to
1586 that file is appended to nameOut. If fullPath is true then an
1587 absolute path is written to nameOut, otherwise a
1588 checkout-relative path is written.
1589
1590 Returns 0 on success. On stat() error, nameOut is not updated,
1591 but after stat()'ing, allocation of memory for nameOut's buffer
1592 may fail.
1593
1594 If zName ends with a trailing slash, that slash is retained in
1595 nameOut.
1596
1597 This function DOES NOT resolve symlinks, stat()ing the link instead
1598 of what it points to.
1599
1600 @see fsl_cx_stat()
1601*/
1602FSL_EXPORT int fsl_cx_stat2( fsl_cx * f, bool relativeToCwd,
1603 char const * zName,
1604 fsl_fstat * tgt,
1605 fsl_buffer * nameOut,
1606 bool fullPath);
1607
1608/**
1609 Sets the case-sensitivity flag for f to the given value. This flag
1610 alters how some filename-search/comparison operations operate. This
1611 option is only intended to have an effect on plaforms with
1612 case-insensitive filesystems.
1613
1614 Note that this does not save the option in the config database
1615 (repo-level "case-sensitive" boolean config option). It arguably
1616 should, and this behavior may change in the future.
1617
1618 @see fsl_cx_is_case_sensitive()
1619*/
1620FSL_EXPORT void fsl_cx_case_sensitive_set(fsl_cx * f, bool caseSensitive);
1621
1622/**
1623 Returns true if f is set for case-sensitive filename
1624 handling, else false. This setting is cached when a repository
1625 is opened, but passing true for the second argument forces the
1626 config option to be re-loaded from the repository db.
1627 Results are undefined if !f.
1628
1629 @see fsl_cx_case_sensitive_set()
1630*/
1631FSL_EXPORT bool fsl_cx_is_case_sensitive(fsl_cx * const f, bool forceRecheck);
1632
1633/**
1634 Compares two strings, represumably filenames, using either
1635 fsl_strcmp() or fsl_stricmp(), depending on f's filename
1636 case-sensitivity setting.
1637*/
1638FSL_EXPORT int fsl_cx_filename_cmp(fsl_cx * f, char const * z1, char const *z2);
1639
1640/**
1641 If f is set to use case-sensitive filename handling,
1642 returns a pointer to an empty string, otherwise a pointer
1643 to the string "COLLATE nocase" is returned.
1644 Results are undefined if f is NULL. The returned bytes
1645 are static.
1646
1647 @see fsl_cx_case_sensitive_set()
1648 @see fsl_cx_is_case_sensitive()
1649*/
1651
1652/**
1653 Invokes macro E with 2 arguments one time for each of the core
1654 fsl_satype_e entries. Argument 1 is the entry's name (identifier)
1655 and argument 2 is its value (integer).
1656*/
1657#define fsl_satype_e_map(E) \
1658 E(FSL_SATYPE_INVALID, -1/** Sentinel value used for some error
1659 reporting.*/) \
1660 E(FSL_SATYPE_ANY, 0/** Sentinel value used to mark a deck as being
1661 "any" type. This is a placeholder on a deck's
1662 way to completion. */) \
1663 E(FSL_SATYPE_CHECKIN, 1/** Indicates a "manifest" artifact (a checkin
1664 record). */) \
1665 E(FSL_SATYPE_CLUSTER, 2/** Indicates a "cluster" artifact. These
1666 are used during synchronization. */) \
1667 E(FSL_SATYPE_CONTROL, 3/** Indicates a "control" artifact (a tag
1668 change).*/) \
1669 E(FSL_SATYPE_WIKI, 4/** Indicates a "wiki" artifact. */) \
1670 E(FSL_SATYPE_TICKET, 5/** Indicates a "ticket" artifact. */) \
1671 E(FSL_SATYPE_ATTACHMENT, 6/** Indicates an "attachment" artifact
1672 (used in the ticketing subsystem). */) \
1673 E(FSL_SATYPE_TECHNOTE, 7/** Indicates a technote (formerly
1674 "event") artifact (kind of like a blog
1675 entry). */) \
1676 E(FSL_SATYPE_FORUMPOST, 8/** Indicates a forum post artifact (a
1677 close relative of wiki pages).*/)
1679/**
1680 An enumeration of the types of structural artifacts used by
1681 Fossil. The numeric values of all entries before FSL_SATYPE_count,
1682 with the exception of FSL_SATYPE_INVALID, are a hard-coded part of
1683 the Fossil db architecture and must never be changed. Any after
1684 FSL_SATYPE_count are libfossil extensions.
1685*/
1686enum fsl_satype_e {
1687#define E(N,V) N = V,
1689#undef E
1690 /**
1691 The number of non-pseudo artifact types in this enum. It is used
1692 to size arrays and must have a value of the last entry in
1693 fsl_satype_e_map() plus 1.
1694 */
1695 FSL_SATYPE_count,
1696
1697 /** @deprecated
1698 Historical (deprecated) name for FSL_SATYPE_TECHNOTE.
1699 */
1700 FSL_SATYPE_EVENT = FSL_SATYPE_TECHNOTE,
1701
1702 /**
1703 A pseudo-type for use with fsl_sym_to_rid() which changes the
1704 behavior of checkin lookups to return the RID of the start of the
1705 branch rather than the tip, with the caveat that the results are
1706 unspecified if the given symbolic name refers to multiple
1707 branches.
1708
1709 fsl_satype_event_cstr() returns the same as FSL_SATYPE_CHECKIN for
1710 this entry.
1711
1712 This entry IS NOT VALID for most APIs which require a fsl_satype_e
1713 value.
1714 */
1716};
1717typedef enum fsl_satype_e fsl_satype_e;
1718
1719/**
1720 Returns some arbitrary but distinct string for the given
1721 fsl_satype_e. The returned bytes are static and
1722 NUL-terminated. Intended primarily for debugging and informative
1723 purposes, not actual user output.
1724*/
1726
1727/**
1728 For a given artifact type, it returns the key string used in the
1729 event.type db table. Returns NULL if passed an unknown value or
1730 a type which is not used in the event table, otherwise the
1731 returned bytes are static and NUL-terminated.
1732
1733 The returned strings for a given type are as follows:
1734
1735 - FSL_SATYPE_ANY returns "*"
1736 - FSL_SATYPE_CHECKIN and FSL_SATYPE_BRANCH_START return "ci"
1737 - FSL_SATYPE_WIKI returns "w"
1738 - FSL_SATYPE_TAG returns "g"
1739 - FSL_SATYPE_TICKET returns "t"
1740 - FSL_SATYPE_EVENT returns "e"
1741
1742 The other control artifact types do not have representations
1743 in the event table, and NULL is returned for them.
1744
1745 All of the returned values can be used in comparison clauses in
1746 queries on the event table's 'type' field (but use GLOB instead
1747 of '=' so that the "*" returned by FSL_ATYPE_ANY can match).
1748 For example, to get the comments from the most recent 5 commits:
1749
1750 ```
1751 SELECT
1752 datetime(mtime),
1753 coalesce(ecomment,comment),
1754 user
1755 FROM event WHERE type='ci'
1756 ORDER BY mtime DESC LIMIT 5;
1757 ```
1758
1759 Where 'ci' in the SQL is the non-NULL return value from this
1760 function. When escaping this value via fsl_buffer_appendf() (or
1761 anything functionally similar), use the %%q/%%Q format
1762 specifiers to escape it.
1766/**
1767 A collection of bitmaskable values indicating categories
1768 of fossil-standard glob sets. These correspond to the following
1769 configurable settings:
1770
1771 ignore-glob, crnl-glob, binary-glob
1772*/
1774/** Sentinel entry. */
1776/** Corresponds to the ignore-glob config setting. */
1777FSL_GLOBS_IGNORE = 0x01,
1778/** Corresponds to the crnl-glob config setting. */
1779FSL_GLOBS_CRNL = 0x02,
1780/** Corresponds to the binary-glob config setting. */
1781FSL_GLOBS_BINARY = 0x04,
1782/** A superset of all config-level glob categories. */
1783FSL_GLOBS_ANY = 0xFF
1784/*
1785 Potential TODO: add FSL_GLOBS_CURRENT_OP for use with SQL UDFs. The
1786 idea would be that SCM operations which could make use of
1787 op-specific glob lists, e.g., checkin/add/merge, could set a custom
1788 glob set as the current one and then access it via their SQL using
1789 `fsl_glob('_', ...)` or some such.
1790*/
1791};
1793
1794/**
1795 Checks one or more of f's configurable glob lists to see if str
1796 matches one of them. If it finds a match, it returns a pointer to
1797 the matching glob (as per fsl_glob_list_matches()), the bytes
1798 of which are owned by f and may be invalidated via modification
1799 or reloading of the underlying glob list. In generally the return
1800 value can be used as a boolean - clients generally do not need
1801 to know exactly which glob matched.
1802
1803 gtype specifies the glob list(s) to check in the form of a
1804 bitmask of fsl_glob_category_e values. Note that the order of the
1805 lists is unspecified, so if that is important for you then be
1806 sure that gtype only specifies one glob list
1807 (e.g. FSL_GLOBS_IGNORE) and call it again (e.g. passing
1808 FSL_GLOBS_BINARY) if you need to distinguish between those two
1809 cases.
1811 str must be a non-NULL, non-empty empty string.
1812
1813 Returns NULL !str, !*str, gtype does not specify any known
1814 glob list(s), or no glob match is found.
1815
1816 Performance is, abstractly speaking, horrible, because we're
1817 comparing arbitrarily long lists of glob patterns against an
1818 arbitrary string. That said, it's fast enough for our purposes.
1819*/
1820FSL_EXPORT char const * fsl_cx_glob_matches( fsl_cx * f, int gtype,
1821 char const * str );
1822
1823/**
1824 Converts a well-known fossil glob list configuration key to
1825 a fsl_glob_category_e value:
1827 - "ignore-glob" = FSL_GLOBS_IGNORE
1828 - "binary-glob" = FSL_GLOBS_BINARY
1829 - "crnl-glob" = FSL_GLOBS_CRNL
1830 - Anything else = FSL_GLOBS_INVALID
1831
1832 To simplify this function's use via an SQL-accessible UDF, the
1833 `*-glob` names may be passed in without their `-glob` suffix,
1834 e.g. `"ignore"` instead of `"ignore-glob"`.
1835*/
1837
1838/**
1839 Fetches f's glob list of the given category. If forceReload is true
1840 then the context will check whether the list has had any content
1841 added to its source since it was initially loaded.
1843 On success, returns 0 and assigns `*tgt` to the list (noting that
1844 it may be empty). On error `*tgt` is not modified.
1845
1846 Returns FSL_RC_RANGE if gtype is not one of FSL_GLOBS_IGNORE,
1847 FSL_GLOBS_CRNL, or FSL_GLOBS_BINARY. Returns FSL_RC_OOM if there is
1848 an allocation error during list reloading. May return lower-level
1849 result codes from the filesystem or db layer if loading a given
1850 list fails.
1851*/
1853 fsl_glob_category_e gtype,
1854 fsl_list ** tgt,
1855 bool forceReload );
1856
1857/**
1858 Sets f's hash policy and returns the previous value. If f has a
1859 repository db open then the setting is stored there and any error
1860 in setting it is placed into f's error state but otherwise ignored
1861 for purposes of this call.
1862
1863 If p is FSL_HPOLICY_AUTO *and* the current repository contains any
1864 SHA3-format hashes, the policy is interpreted as FSL_HPOLICY_SHA3.
1866 This value is a *suggestion*, and may be trumped by various
1867 conditions, in particular in repositories containing older (SHA1)
1868 hashes.
1869*/
1871
1873 Returns f's current hash policy.
1874*/
1876
1877/**
1878 Returns a human-friendly name for the given policy, or NULL for an
1879 invalid policy value. The returned strings are the same ones used
1880 by fossil's hash-policy command.
1881*/
1883
1884/**
1885 Hashes all of pIn, appending the hash to pOut. Returns 0 on succes,
1886 FSL_RC_OOM if allocation of space in pOut fails. The hash algorithm
1887 used depends on the given fossil context's current hash policy and
1888 the value of the 2nd argument.
1889
1890 If the 2nd argument is false, the hash is performed per the first
1891 argument's current hash policy. If the 2nd argument is true, the
1892 hash policy is effectively inverted. e.g. if the context prefers
1893 SHA3 hashes, the alternate form will use SHA1.
1895 Returns FSL_RC_UNSUPPORTED, without updating f's error state, if
1896 the hash is not possible due to conflicting values for the policy
1897 and its alternate. e.g. a context with policy FSL_HPOLICY_SHA3_ONLY
1898 will refuse to apply an SHA1 hash. Whether or not this result can
1899 be ignored is context-dependent, but it normally can be. This
1900 result is only possible when the 2nd argument is true.
1901
1902 Returns 0 on success.
1904FSL_EXPORT int fsl_cx_hash_buffer( const fsl_cx * f, bool useAlternate,
1905 fsl_buffer const * pIn,
1906 fsl_buffer * pOut);
1907/**
1908 The file counterpart of fsl_cx_hash_buffer(), behaving exactly the
1909 same except that its data source is a file and it may return
1910 various error codes from fsl_buffer_fill_from_filename(). Note that
1911 the contents of the file, not its name, are hashed.
1912*/
1913FSL_EXPORT int fsl_cx_hash_filename( fsl_cx * f, bool useAlternate,
1914 const char * zFilename, fsl_buffer * pOut);
1915
1916/**
1917 Works like fsl_getcwd() but updates f's error state on error and
1918 appends the current directory's name to the given buffer. Returns 0
1919 on success.
1920*/
1921FSL_EXPORT int fsl_cx_getcwd(fsl_cx * f, fsl_buffer * pOut);
1922
1923/**
1924 Returns the same as passing fsl_cx_db() to
1925 fsl_db_txn_level(), or 0 if f has no db opened.
1926
1927 @see fsl_cx_db()
1930/**
1931 Returns the same as passing fsl_cx_db() to
1932 fsl_db_txn_begin().
1933*/
1935/**
1936 Returns the same as passing fsl_cx_db() to fsl_db_txn_end().
1937*/
1938FSL_EXPORT int fsl_cx_txn_end_v2(fsl_cx * f, bool keepSavepoint,
1939 bool bubbleRollback);
1940
1941#if 0
1942/* Legacy behavior. */
1943#define fsl_cx_txn_end(F, RollbackMode) \
1944 fsl_cx_txn_end_v2((F), !(RollbackMode), !!(RollbackMode))
1945#else
1946/* What we probably should have been doing instead but
1947 now breaks stuff. */
1948#define fsl_cx_txn_end(F, RollbackMode) \
1949 fsl_cx_txn_end_v2((F), !(RollbackMode), false)
1950#endif
1951/**
1952 Installs or (if f is NULL) uninstalls a confirmation callback for
1953 use by operations on f which require user confirmation. The exact
1954 implications of *not* installing a confirmer depend on the
1955 operation in question: see fsl_cx_confirm().
1956
1957 The 2nd argument bitwise copied into f's internal confirmer
1958 object. If the 2nd argument is NULL, f's confirmer is cleared,
1959 which will cause fsl_cx_confirm() to use certain default responses
1960 (see that function for details).
1961
1962 If the final argument is not NULL then the previous confirmer is
1963 bitwise copied to it.
1964
1965 @see fsl_confirm_callback_f
1966 @see fsl_cx_confirm()
1967 @see fsl_cx_confirmer_get()
1970 fsl_confirmer const * newConfirmer,
1971 fsl_confirmer * prevConfirmer);
1972/**
1973 Stores a bitwise copy of f's current confirmer object into *dest. Can
1974 be used to save the confirmer before temporarily swapping it out.
1975
1976 @see fsl_cx_confirmer()
1977*/
1978FSL_EXPORT void fsl_cx_confirmer_get(fsl_cx const * f, fsl_confirmer * dest);
1979
1980/**
1981 If fsl_cx_confirmer() was used to install a confirmer callback in f
1982 then this routine calls that confirmer and returns its result code
1983 and its answer via *outAnswer. If no confirmer is currently
1984 installed, it responds with default answers, depending on the
1985 eventId:
1986
1987 - FSL_CEVENT_OVERWRITE_MOD_FILE: FSL_CRESPONSE_NEVER
1988
1989 - FSL_CEVENT_OVERWRITE_UNMGD_FILE: FSL_CRESPONSE_NEVER
1990
1991 - FSL_CEVENT_RM_MOD_UNMGD_FILE: FSL_CRESPONSE_NEVER
1992
1993 - FSL_CEVENT_MULTIPLE_VERSIONS: FSL_CRESPONSE_CANCEL
1994
1995 Those are not 100% set in stone and are up for reconsideration.
1996
1997 If a confirmer has been installed, this function does not modify
1998 outAnswer->response if the installed confirmer does not. Thus
1999 routines should set it to some acceptable default/sentinel value
2000 before calling this, to account for callbacks which ignore the
2001 given detail->eventId.
2002
2003 If a confirmer callback responds with FSL_CRESPONSE_ALWAYS or
2004 FSL_CRESPONSE_NEVER, the code which is requesting confirmation must
2005 honor that by *NOT* calling the callback again for the current
2006 processing step of that eventId. e.g. if a loop asks for
2007 confirmation of FSL_CEVENT_RM_MOD_FILE and any response is one of
2008 the above, that one loop must not ask for confirmation again, and
2009 must instead accept that response for future queries within the
2010 same logical library operation (e.g. one checkout-update
2011 cycle). This is particularly important for applications which
2012 interactively present the question to the user for confirmation so
2013 that users have a way to *not* get spammed with a confirmation
2014 message showing up for each and every one of an arbitrary number of
2015 confirmations.
2016
2017 @see fsl_confirm_callback_f
2018 @see fsl_cx_confirmer()
2019*/
2020FSL_EXPORT int fsl_cx_confirm(fsl_cx * f, fsl_confirm_detail const * detail,
2021 fsl_confirm_response *outAnswer);
2022
2023/**
2024 Sets f's is-interrupted flag and, if the 3rd argument is not NULL,
2025 its error state. The is-interrupted flag is separate from f's
2026 normal error state and is _not_ cleared by fsl_cx_err_reset(). To
2027 clear the interrupted flag, call this function with values of 0 and
2028 NULL for the 2nd and 3rd arguments, respectively. This flag is
2029 _not_ fetched by fsl_cx_err_get() but:
2030
2031 1) If this function is passed a non-NULL 3rd argument, then the
2032 normal error state, as well as the is-interrupted flag, is updated
2033 and can be fetched normally via fsl_cx_err_get(). However...
2034
2035 2) It is possible for any error message provided via this routine
2036 to be overwritten or reset by another routine before the
2037 interrupted flag can be acted upon, whereas the interrupted flag
2038 itself can only be modified by this routine.
2039
2040 Returns its 2nd argument on success or FSL_RC_OOM if given a
2041 formatted string and allocation of it fails. In either case, the
2042 interrupted flag, as returned by fsl_cx_interrupted(), is _always_
2043 assigned to the passed-in code.
2044
2045 If passed a code of 0, the is-interrupted flag is reset but the
2046 general error state is not modified.
2047
2048 Results are undefined if this function is called twice concurrently
2049 with the same fsl_cx object. i.e. all calls for a given fsl_cx must
2050 come from a single thread. Results are also undefined if it is
2051 called while f is in its finalization phase (typically during
2052 application shutdown).
2053
2054 ACHTUNG: this is new as of 2021-11-18 and is not yet widely honored
2055 within the API.
2056
2057 Library maintenance notes:
2058
2059 - Long-running actions which honor this flag should, if it is set,
2060 clear it before returning its error code. Also, they should prefer
2061 to pass on non-interruption errors if one has been set set, in
2062 addition to clearing the interruption flag. Only routines which
2063 honor this flag, or top-most routines in the application, should
2064 ever clear this flag.
2066 @see fsl_cx_interrupted()
2067 @see fsl_cx_interruptv()
2068*/
2069FSL_EXPORT int fsl_cx_interrupt(fsl_cx * f, int code,
2070 const char * fmt, ...);
2071
2072/**
2073 The va_list counterpart of fsl_cx_interrupt().
2074*/
2075FSL_EXPORT int fsl_cx_interruptv(fsl_cx * f, int code, char const * fmt, va_list args);
2076
2077/**
2078 If f's is-interrupted flag is set, this function returns its
2079 value. Note that there is inherently a race condition when calling
2080 fsl_cx_interrupt() (to set the flag) from another thread (e.g. a
2081 UI thread while showing a progress indicator).
2083FSL_EXPORT int fsl_cx_interrupted(fsl_cx const * f);
2084
2085/**
2086 Returns true if f has the "allow-symlinks" repo-level configuration
2087 option set to a truthy value, else returns false. That setting is
2088 cached to avoid performing a db lookup on each call, but passing
2089 true for the second argument causes the repository to be
2090 re-checked.
2091*/
2092FSL_EXPORT bool fsl_cx_allows_symlinks(fsl_cx * f, bool forceRecheck);
2094/**
2095 Closes any opened repository and/or checkout database(s) opened by
2096 f, freeing any associated resources and clearing out f's current
2097 user name. Returns 0 on success or if no dbs are opened (noting
2098 that this does NOT close the separate global configuration db: see
2099 fsl_config_close()). Returns FSL_RC_MISUSE if the opened SCM db(s)
2100 have an opened transaction, but that behaviour may change in the
2101 future to force a rollback and close the database(s).
2102*/
2104
2105/**
2106 Shorthand for calling both fsl_close_scm_dbs() and, if it succeeds,
2107 fsl_config_close(). Returns the result of the former if it fails,
2108 else returns the result of the latter.
2109 */
2111
2113 Extracts the "last-sync-url" entry from f's repository
2114 configuration and appends it to tgt. On success, returns 0, else
2115 returns the result of fsl_config_get_buffer().
2118
2119/**
2120 Flags for use with fsl_buildinfo().
2121*/
2122enum fsl_buildinfo_e {
2127};
2128
2129/**
2130 Fetches the piece of library-level build information specified by
2131 its argument. If no such info is available, NULL is returned.
2132*/
2134
2135/**
2136 If both where and where->callback are not NULL, msg is passed to
2137 where->callback and its result is returned, else this is a no-op
2138 and 0 is returned.
2139
2140 Results are undefined if msg is NULL or either argument is
2141 improperly populated.
2142*/
2143FSL_EXPORT int fsl_msg_emit(fsl_msg const * msg,
2144 fsl_msg_listener const * where);
2145
2146/**
2147 If f has a fsl_msg listener, a fsl_msg composed from the given type
2148 and payload is passed to the the listener and its result is
2149 returned, else this is a no-op and 0 is returned.
2150*/
2151FSL_EXPORT int fsl_cx_emit(fsl_cx * const f, fsl_msg_e type, void const * p);
2153/**
2154 va_list counterpart of fsl_cx_emit() which emits a
2155 fsl_appendf()-formatted message as a string or a buffer, depending
2156 on the message type.
2157
2158 It may (and does) fatally fail if passed a message type for which
2159 (type & FSL_MSG_mask_type) is not one of FSL_MSG_type_string or
2160 FSL_MSG_type_buffer.
2161*/
2162int fsl_cx_emitfv(fsl_cx * f, fsl_msg_e type, char const * zFmt,
2163 va_list args);
2164
2165/** Elipsis counterpart of fsl_cx_emitfv(). */
2166int fsl_cx_emitf(fsl_cx *f, fsl_msg_e type, char const * zFmt, ...);
2167
2168/**
2169 Replace's f's current fsl_msg listener with a bitwise copy of
2170 pNew. If pOld is not NULL then a bitwise copy of the previous
2171 listener is written there.
2172*/
2173void fsl_cx_listener_replace(fsl_cx * f, fsl_msg_listener const *pNew,
2174 fsl_msg_listener * pOld);
2175
2176#if 0
2177/**
2178 DO NOT USE - not yet tested and ready.
2179
2180 Returns the result of either localtime(clock) or gmtime(clock),
2181 depending on f:
2182
2183 - If f is NULL, returns localtime(clock).
2184
2185 - If f has had its FSL_CX_F_LOCALTIME_GMT flag set (see
2186 fsl_cx_flag_set()) then returns gmtime(clock), else
2187 localtime(clock).
2188
2189 If clock is NULL, NULL is returned.
2190
2191 Note that fsl_cx instances default to using UTC for everything,
2192 which is the opposite of fossil(1).
2193*/
2194FSL_EXPORT struct tm * fsl_cx_localtime( fsl_cx const * f, const time_t * clock );
2195
2196/**
2197 Equivalent to fsl_cx_localtime(NULL, clock).
2198*/
2199FSL_EXPORT struct tm * fsl_localtime( const time_t * clock );
2200
2201/**
2202 DO NOT USE - not yet tested and ready.
2203
2204 This function passes (f, clock) to fsl_cx_localtime(),
2205 then returns the result of mktime(3) on it. So...
2206 it adjusts a UTC Unix timestamp to either the same UTC
2207 local timestamp or to the local time.
2208*/
2209FSL_EXPORT time_t fsl_cx_time_adj(fsl_cx const * f, time_t clock);
2210#endif
2211
2212#if defined(__cplusplus)
2213} /*extern "C"*/
2214#endif
2215#endif /* ORG_FOSSIL_SCM_FSL_CORE_H_INCLUDED */
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Definition config.h:192
uint32_t fsl_flag32_t
A 32-bit unsigned int type.
Definition config.h:154
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
FSL_EXPORT int fsl_cx_formatv(fsl_cx *f, fsl_output_f out, void *outState, char const *zFmt, va_list args)
A proxy for fsl_appendfv() which pre-processes the format-specifier string (zFmt) to replace certain ...
fsl_hashpolicy_e
List of hash policy values.
Definition core.h:304
@ FSL_HPOLICY_SHA3_ONLY
Use SHA3 hashes exclusively.
Definition core.h:312
@ FSL_HPOLICY_SHA3
Use SHA3 hashes.
Definition core.h:310
@ FSL_HPOLICY_SHA1
Use only SHA1 hashes.
Definition core.h:306
@ FSL_HPOLICY_SHUN_SHA1
With this policy, fsl_uuid_is_shunned() will always return true for SHA1 hashes, making it "impossibl...
Definition core.h:316
@ FSL_HPOLICY_AUTO
Accept SHA1 hashes but auto-promote to SHA3.
Definition core.h:308
#define fsl_rc_e_map(E)
A macro which invokes its argument (a macro name) to expand to all possible values of fsl_rc_e entrie...
Definition core.h:328
fsl_see_keytype_e
SQLite Encryption Extension (SEE) key types for use with fsl_see_key_f().
Definition core.h:595
@ FSL_SEE_KEYTYPE_PLAIN
Corresponses to (PRAGMA key).
Definition core.h:599
@ FSL_SEE_KEYTYPE_BINARY
Corresponses to (PRAGMA hexkey).
Definition core.h:602
@ FSL_SEE_KEYTYPE_TEXTKEY
Corresponses to (PRAGMA textkey).
Definition core.h:607
@ FSL_SEE_KEYTYPE_HEXKEY
Corresponses to (PRAGMA hexkey).
Definition core.h:605
@ FSL_SEE_KEYTYPE_NONE
Sentinel value indicating "not an SEE key".
Definition core.h:597
fsl_rc_e
Most functions in this library which return an int return result codes from the fsl_rc_e enum.
Definition core.h:495
FSL_EXPORT int fsl_cx_format(fsl_cx *f, fsl_output_f out, void *outState, char const *zFmt,...)
The elipsis counterpart of fsl_cx_formatv().
FSL_EXPORT int fsl_cx_interruptv(fsl_cx *f, int code, char const *fmt, va_list args)
The va_list counterpart of fsl_cx_interrupt().
FSL_EXPORT int fsl_config_close(fsl_cx *f)
Closes/detaches the database connection opened by fsl_config_open().
FSL_EXPORT void fsl_cx_confirmer_get(fsl_cx const *f, fsl_confirmer *dest)
Stores a bitwise copy of f's current confirmer object into *dest.
const fsl_msg_listener fsl_msg_listener_empty
FSL_EXPORT int fsl_cx_user_set(fsl_cx *f, char const *userName)
Sets or clears (if userName is NULL or empty) the default repository user name for operations which r...
FSL_EXPORT const fsl_cx_config fsl_cx_config_empty
fsl_cx_config instance initialized with defaults, intended for non-const copy initialization.
Definition core.h:898
FSL_EXPORT void fsl_cx_case_sensitive_set(fsl_cx *f, bool caseSensitive)
Sets the case-sensitivity flag for f to the given value.
FSL_EXPORT char const * fsl_cx_filename_collation(fsl_cx const *f)
If f is set to use case-sensitive filename handling, returns a pointer to an empty string,...
FSL_EXPORT char const * fsl_cx_db_file_repo(fsl_cx const *f, fsl_size_t *len)
Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened repository db,...
FSL_EXPORT fsl_id_t fsl_cx_last_insert_id(fsl_cx *f)
Wrapper around fsl_db_last_insert_id() which uses f's main database.
FSL_EXPORT int fsl_cx_hash_filename(fsl_cx *f, bool useAlternate, const char *zFilename, fsl_buffer *pOut)
The file counterpart of fsl_cx_hash_buffer(), behaving exactly the same except that its data source i...
const fsl_msg fsl_msg_empty
fsl_msg instance intended for non-const copy initialization.
FSL_EXPORT int fsl_cx_err_report(fsl_cx *f, bool addNewline)
If f has error state then it outputs its error state to its output channel and returns the result of ...
FSL_EXPORT int fsl_cx_preparev_cached(fsl_cx *f, fsl_stmt **tgt, char const *sql, va_list args)
va_list counterpart of fsl_cx_prepare_cached().
#define fsl_satype_e_map(E)
Invokes macro E with 2 arguments one time for each of the core fsl_satype_e entries.
Definition core.h:1657
FSL_EXPORT bool fsl_cx_allows_symlinks(fsl_cx *f, bool forceRecheck)
Returns true if f has the "allow-symlinks" repo-level configuration option set to a truthy value,...
FSL_EXPORT fsl_glob_category_e fsl_glob_name_to_category(char const *str)
Converts a well-known fossil glob list configuration key to a fsl_glob_category_e value:
FSL_EXPORT int fsl_msg_emit(fsl_msg const *msg, fsl_msg_listener const *where)
If both where and where->callback are not NULL, msg is passed to where->callback and its result is re...
fsl_dbrole_e
This enum defines type ID tags with which the API tags fsl_db instances so that the library can figur...
Definition core.h:156
@ FSL_DBROLE_NONE
Sentinel "no role" value.
Definition core.h:160
@ FSL_DBROLE_CKOUT
The checkout db.
Definition core.h:172
@ FSL_DBROLE_TEMP
Refers to the "temp" database.
Definition core.h:184
@ FSL_DBROLE_CONFIG
The global (per user) config db.
Definition core.h:164
@ FSL_DBROLE_MAIN
Analog to fossil's "main", which is an alias for the first db opened.
Definition core.h:179
@ FSL_DBROLE_REPO
The repository db.
Definition core.h:168
struct fsl_cx_init_opt fsl_cx_init_opt
Definition core.h:95
FSL_EXPORT char const * fsl_cx_db_file_config(fsl_cx const *f, fsl_size_t *len)
Equivalent to fsl_ckout_db_file() except that it applies to the name of the opened config db,...
FSL_EXPORT int fsl_cx_last_sync_url(fsl_cx *f, fsl_buffer *tgt)
Extracts the "last-sync-url" entry from f's repository configuration and appends it to tgt.
FSL_EXPORT int fsl_cx_hash_buffer(const fsl_cx *f, bool useAlternate, fsl_buffer const *pIn, fsl_buffer *pOut)
Hashes all of pIn, appending the hash to pOut.
fsl_cx_flags_e
Runtime-configurable flags for a fsl_cx instance.
Definition core.h:231
@ FSL_CX_F_NONE
The "no flags" value.
Definition core.h:236
@ FSL_CX_F_BLOB_CACHE
If on (the default) then fsl_content_get() will use an internal cache to speed up loading of repeated...
Definition core.h:278
@ FSL_CX_F_SKIP_UNKNOWN_CROSSLINKS
When encounting artifact types in the crosslinking phase which the library does not currently support...
Definition core.h:254
@ FSL_CX_F_MANIFEST_CACHE
If on (the default) then an internal cache will be used for artifact loading to speed up operations w...
Definition core.h:271
@ FSL_CX_F_ALLOW_WINDOWS_RESERVED_NAMES
By default, fsl_reserved_fn_check() will fail if the given filename is reserved on Windows platforms ...
Definition core.h:263
@ FSL_CX_F_IS_OPENING_CKOUT
Internal use only to prevent duplicate initialization of some bits.
Definition core.h:284
@ FSL_CX_F_DEFAULTS
Default flags for all fsl_cx instances.
Definition core.h:289
@ FSL_CX_F_CALC_R_CARD
Tells us whether or not we want to calculate R-cards by default.
Definition core.h:242
fsl_msg_e
Message type flags Indicators for use with fsl_sc::status, fsl_xfer_emit(), and friends.
Definition core.h:705
char const * fsl_msg_type_cstr(fsl_msg_e e)
Returns the C-string form of the given sync message type, or NULL if e is invalid.
FSL_EXPORT int fsl_cx_format_FILE(fsl_cx *f, FILE *tgt, char const *zFmt,...)
Convenience formof fsl_cx_format() which appends the formatted output to tgt.
FSL_EXPORT char const * fsl_cx_db_file_ckout(fsl_cx const *f, fsl_size_t *len)
If f is not NULL and has a checkout db opened then this function returns its name.
FSL_EXPORT int fsl_outputfv(fsl_cx *f, char const *fmt, va_list args)
va_list counterpart to fsl_outputf().
void fsl_cx_listener_replace(fsl_cx *f, fsl_msg_listener const *pNew, fsl_msg_listener *pOld)
Replace's f's current fsl_msg listener with a bitwise copy of pNew.
FSL_EXPORT int fsl_cx_interrupted(fsl_cx const *f)
If f's is-interrupted flag is set, this function returns its value.
FSL_EXPORT int fsl_flush(fsl_cx *f)
Flushes f's output channel.
FSL_EXPORT int fsl_cx_exec(fsl_cx *f, char const *sql,...)
Convenience form of fsl_db_exec() which uses f's main db handle.
FSL_EXPORT fsl_error const * fsl_cx_err_ec(fsl_cx const *f)
Returns f's error object.
int(* fsl_see_key_f)(void *pState, const char *zDbFile, fsl_buffer *pOut, int *keyType)
EXPERIMENTAL and subject to change.
Definition core.h:657
FSL_EXPORT int fsl_cx_txn_begin(fsl_cx *f)
Returns the same as passing fsl_cx_db() to fsl_db_txn_begin().
FSL_EXPORT int fsl_cx_err_set_e(fsl_cx *f, fsl_error *err)
Replaces f's error state with the contents of err, taking over any memory owned by err (but not err i...
FSL_EXPORT int fsl_cx_emit(fsl_cx *const f, fsl_msg_e type, void const *p)
If f has a fsl_msg listener, a fsl_msg composed from the given type and payload is passed to the the ...
FSL_EXPORT int fsl_cx_interrupt(fsl_cx *f, int code, const char *fmt,...)
Sets f's is-interrupted flag and, if the 3rd argument is not NULL, its error state.
FSL_EXPORT int fsl_cx_glob_list(fsl_cx *f, fsl_glob_category_e gtype, fsl_list **tgt, bool forceReload)
Fetches f's glob list of the given category.
FSL_EXPORT fsl_flag32_t fsl_cx_flag_set(fsl_cx *f, fsl_flag32_t flags, bool enable)
Sets or unsets one or more option flags on the given fossil context.
FSL_EXPORT char const * fsl_buildinfo(enum fsl_buildinfo_e what)
Fetches the piece of library-level build information specified by its argument.
FSL_EXPORT char const * fsl_cx_db_file_for_role(fsl_cx const *f, fsl_dbrole_e r, fsl_size_t *len)
Similar to fsl_cx_db_file_ckout() and friends except that it applies to db file implied by the specif...
FSL_EXPORT int fsl_cx_txn_level(fsl_cx *f)
Returns the same as passing fsl_cx_db() to fsl_db_txn_level(), or 0 if f has no db opened.
int(* fsl_msg_f)(fsl_msg const *msg, void *state)
A callback for use with the library's message-passing subsystem, to provide feedback during potential...
Definition core.h:797
FSL_EXPORT int fsl_cx_confirm(fsl_cx *f, fsl_confirm_detail const *detail, fsl_confirm_response *outAnswer)
If fsl_cx_confirmer() was used to install a confirmer callback in f then this routine calls that conf...
FSL_EXPORT int fsl_cx_prepare_cached(fsl_cx *f, fsl_stmt **tgt, char const *sql,...)
Convenience form of fsl_db_prepare_cached() which uses f's main db.
FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_get(fsl_cx const *f)
Returns f's current hash policy.
FSL_EXPORT void fsl_cx_finalize(fsl_cx *f)
Frees all memory associated with f, which must have been allocated/initialized using fsl_cx_malloc(),...
FSL_EXPORT char const * fsl_satype_event_cstr(fsl_satype_e t)
For a given artifact type, it returns the key string used in the event.type db table.
FSL_EXPORT char const * fsl_cx_glob_matches(fsl_cx *f, int gtype, char const *str)
Checks one or more of f's configurable glob lists to see if str matches one of them.
FSL_EXPORT int fsl_cx_uplift_db_error2(fsl_cx *f, fsl_db *db, int rc)
If rc is not 0 and f has no error state but db does, this calls fsl_cx_uplift_db_error() and returns ...
FSL_EXPORT bool fsl_cx_has_ckout(fsl_cx const *f)
Returns true if the given context has a checkout opened, else false.
FSL_EXPORT int fsl_cx_stat(fsl_cx *f, bool relativeToCwd, char const *zName, fsl_fstat *tgt)
Works similarly to fsl_stat(), except that zName must refer to a path under f's current checkout dire...
FSL_EXPORT int fsl_outputf(fsl_cx *f, char const *fmt,...)
Uses fsl_appendf() to append formatted output to the channel configured for use with fsl_output().
int fsl_cx_emitfv(fsl_cx *f, fsl_msg_e type, char const *zFmt, va_list args)
va_list counterpart of fsl_cx_emit() which emits a fsl_appendf()-formatted message as a string or a b...
FSL_EXPORT fsl_db * fsl_cx_db_config(fsl_cx *f)
If f has an opened configuration db then its handle is returned, else 0 is returned.
FSL_EXPORT char const * fsl_cx_user_guess(fsl_cx *f)
If f has a user name set (via fsl_cx_user_set()) then this function returns that value.
FSL_EXPORT bool fsl_cx_is_case_sensitive(fsl_cx *const f, bool forceRecheck)
Returns true if f is set for case-sensitive filename handling, else false.
fsl_fileperm_e
File permissions flags supported by fossil manifests.
Definition core.h:511
@ FSL_FILE_PERM_LINK
Indicates a symlink.
Definition core.h:522
@ FSL_FILE_PERM_EXE
Indicates a regular file with the executable bit set.
Definition core.h:515
@ FSL_FILE_PERM_REGULAR
Indicates a regular, writable file.
Definition core.h:513
FSL_EXPORT int fsl_close_dbs(fsl_cx *f)
Shorthand for calling both fsl_close_scm_dbs() and, if it succeeds, fsl_config_close().
FSL_EXPORT int fsl_cx_exec_multiv(fsl_cx *f, char const *sql, va_list args)
va_list counterpart of fsl_cx_exec_multi().
FSL_EXPORT fsl_db * fsl_needs_repo(fsl_cx *f)
A helper which fetches f's repository db.
FSL_EXPORT int fsl_output(fsl_cx *f, void const *src, fsl_size_t n)
Outputs the first n bytes of src to f's configured output channel.
FSL_EXPORT char const * fsl_cx_ckout_dir_name(fsl_cx const *f, fsl_size_t *len)
If f has an opened checkout db (from fsl_ckout_open_dir()) then this function returns the directory p...
FSL_EXPORT fsl_cx * fsl_cx_malloc(void)
Allocates a new fsl_cx instance, which must eventually be passed to fsl_cx_finalize() to clean it up.
FSL_EXPORT fsl_flag32_t fsl_cx_flags_get(fsl_cx const *f)
Returns f's flags.
FSL_EXPORT int fsl_cx_filename_cmp(fsl_cx *f, char const *z1, char const *z2)
Compares two strings, represumably filenames, using either fsl_strcmp() or fsl_stricmp(),...
#define E(N, V, H)
Definition core.h:497
fsl_configset_e
Bitmask values specifying "configuration sets".
Definition core.h:197
@ FSL_CONFIGSET_SHUN
Shun settings.
Definition core.h:209
@ FSL_CONFIGSET_ADDR
The CONCEALED table.
Definition core.h:213
@ FSL_CONFIGSET_PROJ
Project name.
Definition core.h:207
@ FSL_CONFIGSET_OLDFORMAT
Use the legacy format.
Definition core.h:221
@ FSL_CONFIGSET_CSS
Style sheet only.
Definition core.h:201
@ FSL_CONFIGSET_OVERWRITE
Causes overwrite instead of merge.
Definition core.h:219
@ FSL_CONFIGSET_XFER
Transfer configuration.
Definition core.h:215
@ FSL_CONFIGSET_TKT
Ticket configuration.
Definition core.h:205
@ FSL_CONFIGSET_USER
The USER table.
Definition core.h:211
@ FSL_CONFIGSET_ALL
Everything.
Definition core.h:217
@ FSL_CONFSET_NONE
Sentinel value.
Definition core.h:199
@ FSL_CONFIGSET_SKIN
WWW interface appearance.
Definition core.h:203
FSL_EXPORT int fsl_cx_err_get(fsl_cx *f, char const **str, fsl_size_t *len)
Fetches the error state from f.
FSL_EXPORT int fsl_cx_exec_multi(fsl_cx *f, char const *sql,...)
The fsl_db_exec_multi() counterpart of fsl_cx_exec().
FSL_EXPORT int fsl_config_open(fsl_cx *f, char const *dbName)
Opens the given database file as f's configuration database.
FSL_EXPORT char const * fsl_library_version(void)
Returns the value of FSL_LIBRARY_VERSION used to compile the library.
FSL_EXPORT char const * fsl_rc_cstr(int rc)
Returns a "standard" string form for a fsl_rc_e code.
FSL_EXPORT void fsl_cx_confirmer(fsl_cx *f, fsl_confirmer const *newConfirmer, fsl_confirmer *prevConfirmer)
Installs or (if f is NULL) uninstalls a confirmation callback for use by operations on f which requir...
struct fsl__xfer fsl_xfer
A "transfer context" type used by many of the sync transfer APIs.
Definition core.h:732
FSL_EXPORT char const * fsl_hash_policy_name(fsl_hashpolicy_e p)
Returns a human-friendly name for the given policy, or NULL for an invalid policy value.
#define fsl_msg_map(E)
Expands to a mapping of all fsl_msg types by invoking E(NAME,VALUE,PayloadDescription) for each one.
Definition core.h:676
FSL_EXPORT void fsl_cx_err_reset(fsl_cx *f)
Resets's f's error state, basically equivalent to fsl_cx_err_set(f,0,NULL).
FSL_EXPORT int fsl_cx_stat2(fsl_cx *f, bool relativeToCwd, char const *zName, fsl_fstat *tgt, fsl_buffer *nameOut, bool fullPath)
This works identically to fsl_cx_stat(), but provides more information about the file being stat'd.
FSL_EXPORT int fsl_cx_init(fsl_cx **tgt, fsl_cx_config const *param)
Initializes a fsl_cx instance.
FSL_EXPORT fsl_lib_configurable_t fsl_lib_configurable
Definition core.h:587
FSL_EXPORT char const * fsl_cx_user_get(fsl_cx const *f)
Returns the name set by fsl_cx_user_set(), or NULL if f has no default user name set.
FSL_EXPORT char const * fsl_satype_cstr(fsl_satype_e t)
Returns some arbitrary but distinct string for the given fsl_satype_e.
FSL_EXPORT int fsl_cx_txn_end_v2(fsl_cx *f, bool keepSavepoint, bool bubbleRollback)
Returns the same as passing fsl_cx_db() to fsl_db_txn_end().
FSL_EXPORT bool fsl_library_version_matches(char const *yourLibVersion)
Returns true (non-0) if yourLibVersion compares lexically equal to FSL_LIBRARY_VERSION,...
FSL_EXPORT int fsl_cx_execv(fsl_cx *f, char const *sql, va_list args)
va_list counterpart of fsl_cx_exec().
FSL_EXPORT int fsl_cx_uplift_db_error(fsl_cx *f, fsl_db *db)
Unconditionally Moves db->error's state into f (without requiring any allocation).
FSL_EXPORT char const * fsl_library_version_scm(void)
Returns the SCM-specific version info for libfossil (the hash and timestamp of it's own source's vers...
FSL_EXPORT int fsl_cx_err_setv(fsl_cx *f, int code, char const *fmt, va_list args)
va_list counterpart to fsl_cx_err_set().
fsl_buildinfo_e
Flags for use with fsl_buildinfo().
Definition core.h:2112
@ FSL_BUILDINFO_VERSION_TIMESTAMP
Definition core.h:2115
@ FSL_BUILDINFO_CONFIG_TIMESTAMP
Definition core.h:2116
@ FSL_BUILDINFO_VERSION_HASH
Definition core.h:2114
@ FSL_BUILDINFO_VERSION
Definition core.h:2113
fsl_satype_e
An enumeration of the types of structural artifacts used by Fossil.
Definition core.h:1676
@ FSL_SATYPE_BRANCH_START
A pseudo-type for use with fsl_sym_to_rid() which changes the behavior of checkin lookups to return t...
Definition core.h:1705
@ FSL_SATYPE_EVENT
Definition core.h:1690
FSL_EXPORT fsl_db * fsl_cx_db_repo(fsl_cx *f)
If f is not NULL and has had its repo opened via fsl_repo_open(), fsl_ckout_open_dir(),...
FSL_EXPORT int fsl_cx_getcwd(fsl_cx *f, fsl_buffer *pOut)
Works like fsl_getcwd() but updates f's error state on error and appends the current directory's name...
FSL_EXPORT int fsl_cx_preparev(fsl_cx *f, fsl_stmt *tgt, char const *sql, va_list args)
va_list counterpart of fsl_cx_prepare().
FSL_EXPORT fsl_error * fsl_cx_err_e(fsl_cx *f)
Non-const counterpart of fsl_cx_err_ec().
FSL_EXPORT int fsl_cx_prepare(fsl_cx *f, fsl_stmt *tgt, char const *sql,...)
Convenience form of fsl_db_prepare() which uses f's main db.
FSL_EXPORT int fsl_cx_err_set(fsl_cx *f, int code, char const *fmt,...)
Sets the Fossil error state to the given error code and fsl_appendf()-style format string/arguments.
FSL_EXPORT fsl_db * fsl_needs_ckout(fsl_cx *f)
The checkout-db counterpart of fsl_needs_repo().
FSL_EXPORT fsl_hashpolicy_e fsl_cx_hash_policy_set(fsl_cx *f, fsl_hashpolicy_e p)
Sets f's hash policy and returns the previous value.
fsl_glob_category_e
A collection of bitmaskable values indicating categories of fossil-standard glob sets.
Definition core.h:1763
@ FSL_GLOBS_ANY
A superset of all config-level glob categories.
Definition core.h:1773
@ FSL_GLOBS_CRNL
Corresponds to the crnl-glob config setting.
Definition core.h:1769
@ FSL_GLOBS_IGNORE
Corresponds to the ignore-glob config setting.
Definition core.h:1767
@ FSL_GLOBS_INVALID
Sentinel entry.
Definition core.h:1765
@ FSL_GLOBS_BINARY
Corresponds to the binary-glob config setting.
Definition core.h:1771
int fsl_cx_emitf(fsl_cx *f, fsl_msg_e type, char const *zFmt,...)
Elipsis counterpart of fsl_cx_emitfv().
struct fsl_cx fsl_cx
Definition core.h:98
FSL_EXPORT int fsl_cx_format_buffer(fsl_cx *f, fsl_buffer *tgt, char const *zFmt,...)
Convenience formof fsl_cx_format() which appends the formatted output to tgt.
FSL_EXPORT fsl_db * fsl_cx_db_ckout(fsl_cx *f)
If f is not NULL and has had a checkout opened via fsl_ckout_open_dir() or similar,...
FSL_EXPORT int fsl_close_scm_dbs(fsl_cx *f)
Closes any opened repository and/or checkout database(s) opened by f, freeing any associated resource...
FSL_EXPORT fsl_db * fsl_cx_db(fsl_cx *f)
Returns a handle to f's main db (which may or may not have any relationship to the repo/checkout/conf...
The fsl namespace is reserved for an eventual C++ wrapper for the API.
Definition core.h:28
Holds an allocator function and its related state.
Definition util.h:403
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
A struct for passing on interactive questions to fsl_confirmer_callback_f implementations.
Definition util.h:6040
A response for use with the fsl_confirmer API.
Definition util.h:6004
A fsl_confirm_callback_f and its callback state, packaged into a neat little struct for easy copy/rep...
Definition util.h:6128
A part of the configuration used by fsl_cx_init() and friends.
Definition core.h:817
struct fsl_cx_config::@251106123110033004002313117274342103023123040065 see
Config state for use with the SQLite3 Encryption Extension (SEE).
fsl_outputer output
The output channel for the Fossil instance.
Definition core.h:853
fsl_hashpolicy_e hashPolicy
Specifies the default hash policy.
Definition core.h:835
fsl_see_key_f getSEEKey
If this is non NULL, it is called when the library needs to fetch the encryption key to use for a db.
Definition core.h:868
void * pState
Optional state for use as the first argument to getSEEKey.
Definition core.h:877
fsl_msg_listener listener
Listener for fsl_msg-type events.
Definition core.h:842
bool traceSql
If true, all SQL which goes through the fossil engine will be traced to stdout.
Definition core.h:825
bool sqlPrint
If true, the fsl_print() SQL function will output its output to the fsl_output()-configured channel,...
Definition core.h:830
The main Fossil "context" type.
Definition internal.h:400
Db handle wrapper class.
Definition db.h:313
A container for storing generic error state.
Definition util.h:781
A simple wrapper around the stat(2) structure resp.
Definition util.h:3321
This type, accessible to clients via the fsl_lib_configurable global, contains configuration-related ...
Definition core.h:566
fsl_allocator allocator
Library-wide allocator.
Definition core.h:584
Generic list container type.
Definition util.h:156
Message payload type for FSL_MSG_type_blob.
Definition core.h:716
char const * hash
Definition core.h:717
fsl_int_t size
Definition core.h:718
Client callback info for receiving various events during fossil sync processing.
Definition core.h:803
void * state
State for the final argument to this->callback().
Definition core.h:807
fsl_msg_f callback
Callback function.
Definition core.h:805
A message object type for use with fsl_sc::status().
Definition core.h:737
fsl_cx * f
This message's fsl_cx context, providing the callback with access to the associated SCM state.
Definition core.h:753
void const * payload
An optional bit of informative text.
Definition core.h:747
fsl_msg_e type
The type of status message.
Definition core.h:739
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Definition util.h:337
Represents a prepared statement handle.
Definition db.h:555
This file declares a number of utility classes and routines used by libfossil.
int(* fsl_output_f)(void *state, void const *src, fsl_size_t n)
Generic interface for streaming out data.
Definition util.h:292