libfossil
fossil-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(NET_FOSSIL_SCM_FSL_CORE_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_CORE_H_INCLUDED
5 /*
6  Copyright (c) 2013 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program is distributed in the hope that it will be useful,
13  but without any warranty; without even the implied warranty of
14  merchantability or fitness for a particular purpose.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  *******************************************************************
21  This file declares the core SCM-related public APIs.
22 */
23 
24 #include "fossil-scm/fossil-util.h" /* MUST come first b/c of config macros */
25 #include <time.h> /* struct tm, time_t */
26 #if defined(__cplusplus)
27 /*
28  The fsl namespace is reserved for an eventual C++ wrapper for the API.
29 */
30 namespace fsl {}
31 extern "C" {
32 #endif
33 
34 /**
35  @struct fsl_cx
36 
37  The main Fossil "context" type. This is the first argument to
38  many Fossil library API routines, and holds all state related
39  to a checkout and/or repository and/or global fossil configuration
40  database(s).
41 
42  An instance's lifetime looks something like this:
43 
44  @code
45  int rc;
46  fsl_cx * f = NULL; // ALWAYS initialize to NULL or results are undefined
47  rc = fsl_cx_init( &f, NULL );
48  assert(!rc);
49  rc = fsl_repo_open( f, "myrepo.fsl" );
50  ...use the context, and clean up when done...
51  fsl_cx_finalize(f);
52  @endcode
53 
54  The contents of an fsl_cx instance are strictly private, for use
55  only by APIs in this library. Any client-side dependencies on
56  them will lead to undefined behaviour at some point.
57 
58  Design note: this type is currently opaque to client
59  code. Having it non-opaque also has advantages, though, and i'd
60  generally prefer that (to allow client-side allocation and
61  embedding in other structs). Binary compatibility concerns might
62  force us to keep it opaque.
63 
64 */
65 
66 typedef struct fsl_cx fsl_cx;
68 typedef struct fsl_db fsl_db;
70 typedef struct fsl_stmt fsl_stmt;
71 
72 /**
73  This enum defines type ID tags with which the API tags fsl_db
74  instances so that the library can figure out which DB is
75  which. This is primarily important for certain queries, which
76  need to know whether they are accessing the repo or config db,
77  for example.
78 
79  All that said, i'm not yet fully convinced that a straight port
80  of the v1 model is the best option for how we internally manage
81  DBs, so this is subject to eventual change or removal.
82 */
84 /**
85  Sentinel "no role" value.
86 */
88 /**
89  Analog to v1's "configdb".
90 */
92 /**
93  Analog to v1's "repository".
94 */
96 /**
97  Analog to v1's "localdb".
98 */
100 /**
101  Analog to v1's "main", which is basically an alias for the first
102  db opened.
103 */
105 };
107 
108 /**
109  Roles equate to permissions in Fossil v1. Here we implement them
110  as a bitmask and hope we never need more than 31 of them.
111 
112  Actually... all of this app-level stuff. The library doesn't
113  really care about users (and therefore access rights) at all.
114  Nonetheless, the library should provide some base functionality
115  for it, based on the v1 model. Clients are of course not
116  prohibited from adding their own security models/policies.
117 */
124 FSL_UROLE_READ = 1 << 3,
131 FSL_UROLE_CLONE = 1 << 10,
145 FSL_UROLE_ZIP = 1 << 24,
147 
148 FSL_UROLE_ALL = 0x7FFFFFFF
149 /* unsigned 32-bit+ enums are not portable :/ */
150 };
152 
153 
154 
155 /**
156  Bitmask values specifying "configuration sets." The values in
157  this enum come directly from fossil(1), but they are not part of
158  the db structure, so may be changed over time.
159 */
161 /** Sentinel value. */
162 FSL_CONFSET_NONE = 0x000000,
163 /** Style sheet only */
164 FSL_CONFIGSET_CSS = 0x000001,
165 /** WWW interface appearance */
167 /** Ticket configuration */
168 FSL_CONFIGSET_TKT = 0x000004,
169 /** Project name */
171 /** Shun settings */
173 /** The USER table */
175 /** The CONCEALED table */
177 /** Transfer configuration */
179 /** Everything */
180 FSL_CONFIGSET_ALL = 0x0000ff,
181 /** Causes overwrite instead of merge */
183 /** Use the legacy format */
185 };
187 
188 /**
189  Runtime-configurable flags for a fsl_cx instance.
190 */
193 /**
194  Tells us whether or not we want to calculate R-cards by default.
195  Historically they were initially required but eventually made
196  optional due largely to their memory costs.
197 */
199 /**
200  Internal use only to prevent duplicate initialization of some
201  bits.
202 */
204 
205 /**
206  Default flags for all fsl_cx instances.
207 */
209 
210 };
212 
213 /**
214  Most functions in this API which return an int type return error
215  codes from the fsl_rc_t enum. None of these entries are
216  (currently) guaranteed to have a specific value across Fossil
217  versions except for FSL_RC_OK, which is guaranteed to always be
218  0 (and the API guarantees that no other code shall have a value
219  of zero).
220 
221  The only reasons numbers are hard-coded to the values (or some of
222  them) is to simplify debugging during development. Clients may use
223  fsl_rc_cstr() to get some human-readable (or programmer-readable)
224  form for any given value in this enum.
225 
226  Maintenance reminder: as entries are added/changed, update
227  fsl_rc_cstr().
228 */
229 enum fsl_rc_t {
230 /**
231  The quintessential not-an-error value.
232 */
234 /**
235  Generic/unknown error.
236 */
238 /**
239  A placeholder return value for "not yet implemented" functions.
240 */
242 /**
243  Out of memory. Indicates that a resource allocation request
244  failed.
245 */
247 /*
248  API misuse (invalid args)
249 */
251 /**
252  Some range was violated (function argument, UTF character, etc.).
253 */
255 /**
256  Indicates that access to or locking of a resource was denied
257  by some security mechanism or other.
258 */
260 /**
261  Indicates an I/O error. Whether it was reading or writing is
262  context-dependent.
263 */
264 FSL_RC_IO = 106,
265 /**
266  requested resource not found
267 */
269 /**
270  Indicates that a to-be-created resource already exists.
271 */
273 /**
274  Data consistency problem
275 */
277 
278 /**
279  Indicates that the requested repo needs to be rebuilt.
280 */
282 
283 /**
284  Indicates that the requested repo is not, in fact, a repo. Also
285  used by some APIs to indicate that they require a repository db
286  but none has been opened.
287 */
289 
290 /**
291  Indicates an attempt to open a too-old or too-new repository db.
292 */
294 
295 /**
296  Indicates db-level error (e.g. statement prep failed). In such
297  cases, the error state of the related db handle (fsl_db) or
298  Fossilc context (fsl_cx) will be updated to contain more
299  information directly from the db driver.
300 */
301 FSL_RC_DB = 113,
302 
303 /**
304  Used by some iteration routines to indicate that iteration should
305  stop prematurely without an error.
306 */
308 
309 /**
310  Indicates that fsl_stmt_step() has fetched a row and the cursor
311  may be used to access the current row state (e.g. using
312  fsl_stmt_get_int32() and friends). It is strictly illegal to use
313  the fsl_stmt_get_xxx() APIs unless fsl_stmt_step() has returned
314  this code.
315 */
317 
318 /**
319  Indicates that fsl_stmt_step() has reached the end of the result
320  set and that there is no row data to process. This is also the
321  result for non-fetching queries (INSERT and friends). It is strictly
322  illegal to use the fsl_stmt_get_xxx() APIs after fsl_stmt_step() has
323  returned this code.
324 */
326 
327 /**
328  Indicates that a db-level error occurred during a
329  fsl_stmt_step() iteration.
330 */
332 
333 /**
334  Indicates that some data type or logical type is incorrect
335  (e.g. an invalid card type in conjunction with a given
336  fsl_deck).
337 */
339 
340 /**
341  Indicates that an operation which requires a checkout does not
342  have a checkout to work on.
343 */
345 
346 /**
347  Not yet used. Indicates that a repo and checkout do not belong
348  together. The public API currently does not allow that to
349  happen.
350 */
352 /**
353  Indicates that a checksum comparison failed, possibly indicating
354  that corrupted or unexpected data was just read.
355 */
357 
358 /**
359  This is a special case of FSL_RC_NOT_FOUND, intended specifically
360  to differentiate from "file not found in filesystem"
361  (FSL_RC_NOT_FOUND) and "fossil does not know about this file" in
362  routines for which both might be an error case. An example is a
363  an operation which wants to update a repo file with contents
364  from the filesystem - the file might not exist or it might not be
365  in the current repo db.
366 
367  That said, this can also be used for APIs which search for other
368  resources (UUIDs, tickets, etc.), but FSL_RC_NOT_FOUND is already
369  fairly well entrenched in those cases and is unambiguous, so this
370  code is only needed by APIs for which both cases described above
371  might happen.
372 */
374 
375 /**
376  Indicates that a size comparison check failed.
377 
378  TODO: remove this if it is not used.
379 */
381 
382 /**
383  Indicates that an invalid separator was encountered while
384  parsing a delta.
385 */
387 
388 /**
389  Indicates that an invalid size value was encountered while
390  parsing a delta.
391 */
393 
394 /**
395  Indicates that an invalid operator was encountered while parsing
396  a delta.
397 */
399 
400 /**
401  Indicates that an invalid terminator was encountered while
402  parsing a delta.
403 */
405 
406 /**
407  Indicates a generic syntax error in a control artifact. Some
408  types of manifest-releated errors are reported with more
409  specific error codes, e.g. FSL_RC_RANGE if a given Card type
410  appears too often.
411 */
413 
414 /**
415  Indicates that some value or expression is ambiguous. Typically
416  caused by trying to resolve ambiguous symbolic names or partial
417  UUIDs to their full UUIDs.
418 */
420 };
421 typedef enum fsl_rc_t fsl_rc_t;
422 
423 /**
424  Filesystem-level permissions flags supported by fossil
425  Manifests. Their numeric values are a hard-coded part of the
426  Fossil architecture and must not be changed. Note that these
427  refer to manifest-level permissions and not filesystem-level
428  permissions (though they translate to/from filesystem-level
429  meanings at some point).
430 */
432 /** Indicates a regular, writable file. */
434 /** Indicates a regular file with the executable bit set. */
436 /** Indicates a symlink. Note that symlinks do not have the
437  executable bit set separately on Unix systems. Also note
438  that libfossil does NOT YET IMPLEMENT symlink support
439  like fossil(1) does - it currently treats symlinks as
440  Unix treats symlinks.
441 */
443 };
445 
446 
447 /**
448  Returns a "standard" string form for a fsl_rc_t code. The string
449  is primarily intended for debugging purposes. The returned bytes
450  are guaranteed to be static and NUL-terminated. They are not
451  guaranteed to contain anything useful for any purposes other than
452  debugging and tracking down problems.
453 */
454 FSL_EXPORT char const * fsl_rc_cstr(int);
455 
456 /**
457  Returns the value of FSL_LIBRARY_VERSION used to compile the
458  library. If this value differs from the value the caller was
459  compiled with, Chaos might ensue.
460 
461  The API does not yet have any mechanism for determining
462  compatibility between repository versions and it also currently
463  does no explicit checking to disallow incompatible versions.
464 */
465 FSL_EXPORT char const * fsl_library_version();
466 
467 /**
468  Returns true (non-0) if yourLibVersion compares lexically
469  equal to FSL_LIBRARY_VERSION, else it returns false (0).
470 */
471 FSL_EXPORT char fsl_library_version_matches(char const * yourLibVersion);
472 
473 /**
474  This type, accessible to clients via the ::fsl_lib_configurable
475  global, contains configuration-related data for the library
476  which can be swapped out by clients.
477 */
479  /**
480  Library-wide allocator. It may be replaced by the client IFF
481  it is replaced before the library allocates any memory. The
482  default implementation uses the C-standard
483  de/re/allocators. Modifying this member while any memory
484  allocated through it is still "live" leads to undefined
485  results. There is an exception: a "read-only" middleman proxy
486  which does not change how the memory is allocated or
487  intepreted can safely be swapped in or out at any time
488  provided the underlying allocator stays the same and the
489  client can ensure that there are no thread-related race
490  conditions. e.g. it is legal to swap this out with a proxy
491  which logs allocation requests and then forwards the call on
492  to the original implementation, and it is legal to do so at
493  essentially any time. The important thing this that all of the
494  library-allocated memory goes through a single underlying
495  (de)allocator for the lifetime of the application.
496  */
498 };
501 
502 /**
503  A part of the configuration used by fsl_cx_init() and friends.
504 
505 */
507  /**
508  If true, all SQL which goes through the fossil engine
509  will be traced to the fsl_output()-configured channel.
510  */
511  char traceSql;
512  /**
513  If true, the fsl_print() SQL function will output its output to the
514  fsl_output()-configured channel, else it is a no-op.
515  */
516  char sqlPrint;
517 };
518 
519 /**
520  fsl_cx_config instance initialized with defaults, intended for
521  in-struct initialization.
522 */
523 #define fsl_cx_config_empty_m { \
524  0/*traceSql*/, \
525  0/*sqlPrint*/ \
526 }
527 
528 /**
529  fsl_cx_config instance initialized with defaults, intended for
530  copy-initialization.
531 */
533 
534 /**
535  Parameters for fsl_cx_init().
536 */
538  /**
539  The output channel for the Fossil instance.
540  */
542  /**
543  Basic configuration parameters.
544  */
546 };
547 
548 
549 /** Empty-initialized fsl_cx_init_opt instance. */
550 #define fsl_cx_init_opt_empty_m {fsl_outputer_empty_m, fsl_cx_config_empty_m}
551 /**
552  fsl_cx_init_opt instance initialized to use stdout for output and
553  the standard system memory allocator.
554 */
555 #define fsl_cx_init_opt_default_m {fsl_outputer_FILE_m, fsl_cx_config_empty_m}
556 
557 /** Empty-initialized fsl_cx_init_opt instance. */
559 
560 /**
561  fsl_cx_init_opt instance initialized to use stdout for output and
562  the standard system memory allocator. Used as the default when
563  fsl_cx_init() is passed a NULL value for this parameter.
564 */
566 
567 /**
568  Allocates a new fsl_cx instance, which must eventually
569  be passed to fsl_cx_finalize() to clean it up.
570  Normally clients do not need this - they can simply pass
571  a pointer to NULL as the first argument to fsl_cx_init()
572  to let it allocate an instance for them.
573 */
575 
576 /**
577  Initializes a fsl_cx instance. tgt must be a pointer to NULL,
578  e.g.:
579 
580  @code
581  fsl_cxt * f = NULL; // NULL is important - see below
582  int rc = fsl_cx_init( &f, NULL );
583  @endcode
584 
585  It is very important that f be initialized to NULL _or_ to an
586  instance which has been properly allocated and empty-initialized
587  (e.g. via fsl_cx_malloc()). If *tgt is NULL, this routine
588  allocates the context, else it assumes the caller did. If f
589  points to unitialized memory then results are undefined.
590 
591  If the second parameter is NULL then default implementations are
592  used for the context's output routine and other options. If it
593  is not NULL then param->allocator and param->output must be
594  initialized properly before calling this function. The contents
595  of param are bitwise copied by this function and ownership of
596  the returned value is transfered to *tgt in all cases except
597  one:
598 
599  If this function cannot allocate a new instance it
600  returns FSL_RC_OOM and does not modify *tgt. In this case,
601  ownership of param's contents is not changed. On any other
602  error, ownership of param's contents are transfered to *tgt and
603  the client is responsible for passing *tgt ot
604  fsl_cxt_finalize() when he is done with it. Note that (like in
605  sqlite3), *tgt may be valid memory even if this function fails,
606  and the caller must pass it to fsl_cx_finalize() whether or
607  not this function succeeds unless it fails at the initial OOM
608  (which the client can check by seeing if (*tgt) is NULL, but
609  only if he set it to NULL before calling this).
610 
611  Returns 0 on success, FSL_RC_OOM on an allocation error,
612  FSL_RC_MISUSE if (!tgt).
613 
614  @see fsl_cx_finalize()
615  @see fsl_cx_reset()
616 */
617 FSL_EXPORT int fsl_cx_init( fsl_cx ** tgt, fsl_cx_init_opt const * param );
618 
619 /**
620  Clears (most) dynamic state in f, but does not free f and does
621  not free "static" state (that set up by the init process). If
622  closeDatabases is true then any databases managed by f are
623  closed, else they are kept open.
624 
625  Client code will not normally need this - it is intended for a
626  particular potential memory optimization case. If (and only if)
627  closeDatabases is true then after calling this, f may be legally
628  re-used as a target for fsl_cx_init().
629 
630  This function does not trigger any finializers set for f's
631  client state or output channel. It _does_ clear any user name
632  set fsl_cx_user_set().
633 
634  This is a no-op if !f.
635 */
636 FSL_EXPORT void fsl_cx_reset( fsl_cx * f, char closeDatabases );
637 
638 /**
639  Frees all memory associated with f, which must have been
640  allocated/initialized using fsl_cx_malloc(), fsl_cx_init(), or
641  equivalent, or created on the stack and properly initialized
642  (via fsl_cx_init() or copy-constructed from fsl_cx_empty).
643 
644  This function triggers any finializers set for f's client state
645  or output channel.
646 
647  This is a no-op if !f and is effectively a no-op if f has no
648  state to destruct.
649 */
650 FSL_EXPORT void fsl_cx_finalize( fsl_cx * f );
651 
652 
653 /**
654  Sets or unsets one or more option flags on the given fossil
655  context. flags is the flag or a bitmask of flags to set (from
656  the fsl_cx_flag_t enum). If enable is true the flag(s) is (are)
657  set, else it (they) is (are) unset. Returns the new set of
658  flags, or -1 if !f.
659 */
660 FSL_EXPORT int fsl_cx_flag_set( fsl_cx * f, int flags, char enable );
661 
662 /**
663  Returns f's flags, or -1 if !f.
664 */
666 
667 /**
668  Sets the Fossil error state to the given error code and
669  fsl_appendf()-style format string/arguments. On success it
670  returns the code parameter. It does not return 0 unless code is
671  0, and if it returns a value other than code then something went
672  seriously wrong (e.g. allocation error: FSL_RC_OOM) or the
673  arguments were invalid: !f results in FSL_RC_MISUSE.
674 
675  If !fmt then fsl_rc_cstr(code) is used to create the
676  error string.
677 
678  As a special case, if code is FSL_RC_OOM, no error string is
679  allocated (because it would likely fail, assuming the OOM
680  is real).
681 
682  As a special case, if code is 0 (the non-error value) then fmt is
683  ignored and any error state is cleared.
684 */
685 FSL_EXPORT int fsl_cx_err_set( fsl_cx * f, int code, char const * fmt, ... );
686 
687 /**
688  va_list counterpart to fsl_cx_err_set().
689 */
690 FSL_EXPORT int fsl_cx_err_setv( fsl_cx * f, int code, char const * fmt,
691  va_list args );
692 
693 /**
694  Fetches the error state from f. See fsl_error_get() for the semantics
695  of the parameters and return value.
696 */
697 FSL_EXPORT int fsl_cx_err_get( fsl_cx * f, char const ** str, fsl_size_t * len );
698 
699 /**
700  Returns f's error state object. This pointer is guaranteed by the
701  API to be stable until f is finalized, but its contents are
702  modified my routines as part of the error reporting process.
703 
704  Returns NULL if !f.
705 */
706 FSL_EXPORT fsl_error const * fsl_cx_err_get_e(fsl_cx const * f);
707 
708 /**
709  Resets's f's error state, basically equivalent to
710  fsl_cx_err_set(f,0,NULL). Is a no-op if f is NULL. This may be
711  necessary for apps if they rely on looking at fsl_cx_err_get()
712  at the end of their app/routine, because error state survives
713  until it is cleared, even if the error held there was caught and
714  recovered. This function might keep error string memory around
715  for re-use later on.
716 */
718 
719 /**
720  Replaces f's error state with the contents of err, taking over
721  any memory owned by err (but not err itself). Returns the new
722  error state code (the value of err->code before this call) on
723  success. The only error case is if !f (FSL_RC_MISUSE). If err is
724  NULL then f's error state is cleared and 0 is returned. err's
725  error state is cleared by this call.
726 */
727 FSL_EXPORT int fsl_cx_err_set_e( fsl_cx * f, fsl_error * err );
728 
729 /**
730  If f has error state then it outputs its error state to its
731  output channel and returns the result of fsl_output(). Returns
732  FSL_RC_MISUSE if !f, 0 if f has no error state our output of the
733  state succeeds. If addNewline is true then it adds a trailing
734  newline to the output, else it does not.
735 
736  This is intended for testing and debugging only, and not as an
737  error reporting mechanism for a full-fledged application.
738 */
739 FSL_EXPORT int fsl_cx_err_report( fsl_cx * f, char addNewline );
740 
741 /**
742  Moves db->error's state into f. If db is NULL then f's primary
743  db connection is used. Returns FSL_RC_MISUSE if !f or (!db &&
744  f-is-not-opened). On success it returns f's new error code.
745 
746  The main purpose of this function is to propagate db-level
747  errors up to higher-level code which deals directly with the f
748  object but not the underlying db(s).
749 */
751 
752 /**
753  Outputs the first n bytes of src to f's configured output
754  channel. Returns 0 on success, FSL_RC_MISUSE if (!f || !src),
755  0 (without side effects) if !n, else it returns the result of
756  the underlying output call. This is a harmless no-op if f is
757  configured with no output channel.
758 
759  @see fsl_outputf()
760  @see fsl_flush()
761 */
762 FSL_EXPORT int fsl_output( fsl_cx * f, void const * src, fsl_size_t n );
763 
764 /**
765  Flushes f's output channel. Returns 0 on success, FSL_RC_MISUSE
766  if !f. If the flush routine is NULL then this is a harmless
767  no-op.
768 
769  @see fsl_outputf()
770  @see fsl_output()
771 */
772 FSL_EXPORT int fsl_flush( fsl_cx * f );
773 
774 /**
775  Uses fsl_appendf() to append formatted output to the channel
776  configured for use with fsl_output(). Returns 0 on success,
777  FSL_RC_MISUSE if !f or !fmt, FSL_RC_RANGE if !*fmt, and
778  FSL_RC_IO if the underlying fsl_appendf() operation fails.
779 
780  Note, however, that due to the printf()-style return semantics
781  of fsl_appendf(), it is not generically possible to distinguish
782  a partially-successful (i.e. failed in the middle) write from
783  success. e.g. if fmt contains a format specifier which performs
784  memory allocation and that allocation fails, it is unlikely that
785  this function will be able to be aware of that error. The only
786  way to fix that is to change the return semantics of
787  fsl_appendf() (and adjust any existing code which relies on
788  them).
789 
790  @see fsl_output()
791  @see fsl_flush()
792 */
793 FSL_EXPORT int fsl_outputf( fsl_cx * f, char const * fmt, ... );
794 
795 /**
796  va_list counterpart to fsl_outputf().
797 */
798 FSL_EXPORT int fsl_outputfv( fsl_cx * f, char const * fmt, va_list args );
799 
800 /**
801  Opens the given db file name as f's repository. Returns 0 on
802  success. On error it sets f's error state and returns that code
803  unless the error was FSL_RC_MISUSE (which indicates invalid
804  arguments and it does not set the error state).
805 
806  Fails with FSL_RC_MISUSE if !f, !repoDbFile, !*repoDbFile. Returns
807  FSL_RC_ACCESS if f already has an opened repo db.
808 
809  Returns FSL_RC_NOT_FOUND if repoDbFile is not found, as this
810  routine cannot create a new repository db.
811 
812  When a repository is opened, the fossil-level user name
813  associated with f (if any) is overwritten with the default user
814  from the repo's login table (the one with uid=1). Thus
815  fsl_cx_user_get() may return a value even if the client has not
816  called fsl_cx_user_set().
817 
818  It would be nice to have a parameter specifying that the repo
819  should be opened read-only. That's not as straightforward as it
820  sounds because of how the various dbs are internally managed
821  (via one db handle). Until then, the permissions of the
822  underlying repo file will determine how it is opened. i.e. a
823  read-only repo will be opened read-only.
824 
825 
826  Potentially interesting side-effects:
827 
828  - On success this re-sets the "allow-symlinks" option on f to
829  match that of the opened repo, keeping its current setting if
830  the repo specifies no value for that option.
831 
832  @see fsl_repo_create()
833  @see fsl_repo_close()
834 */
835 FSL_EXPORT int fsl_repo_open( fsl_cx * f, char const * repoDbFile/*, char readOnlyCurrentlyIgnored*/ );
836 
837 /**
838  If fsl_repo_open_xxx() or fsl_checkout_open_dir() has been
839  used to open a respository db, this call closes that db and
840  returns 0. Returns FSL_RC_MISUSE if !f. FSL_RC_NOT_FOUND if f
841  has not opened a repository.
842 
843  If the repo is the "main" db, this also closes any associated
844  checkout and config dbs.
845 
846  If a repository is opened "indirectly" via
847  fsl_checkout_open_dir() then clients must not close it using
848  this function; they should allow it to be closed implicitly when
849  the checkout db is closed.
850 
851  @see fsl_repo_open()
852  @see fsl_repo_create()
853 */
854 FSL_EXPORT int fsl_repo_close( fsl_cx * f );
855 
856 /**
857  Sets or clears (if userName is NULL or empty) the default
858  repository user name for operations which require one.
859 
860  Returns 0 on success, FSL_RC_MISUSE if f is NULL,
861  FSL_RC_OOM if copying of the userName fails.
862 
863  Example usage:
864  @code
865  char * u = fsl_guess_user_name();
866  int rc = fsl_cx_user_set(f, u);
867  fsl_free(u);
868  @endcode
869 
870  (Sorry about the extra string copy there, but adding a function
871  which passes ownership of the name string seems like overkill.)
872 */
873 FSL_EXPORT int fsl_cx_user_set( fsl_cx * f, char const * userName );
874 
875 /**
876  Returns the name set by fsl_cx_user_set(), or NULL if f has no
877  default user name set. The returned bytes are owned by f and may
878  be invalidated by any call to fsl_cx_user_set().
879 */
880 FSL_EXPORT char const * fsl_cx_user_get( fsl_cx const * f );
881 
882 /**
883  Configuration parameters for fsl_repo_create(). Always
884  copy-construct these from fsl_repo_create_opt_empty
885  resp. fsl_repo_create_opt_empty_m in order to ensure proper
886  behaviour vis-a-vis default values.
887 
888  TODOs:
889 
890  - Add project name/description, and possibly other
891  configuration bits.
892 
893  - Allow client to set password for default user (currently set
894  randomly, as fossil(1) does).
895 */
897  /**
898  The file name for the new repository.
899  */
900  char const * filename;
901  /**
902  Fossil user name for the admin user in the new repo. If NULL,
903  defaults to the Fossil context's user (see
904  fsl_cx_user_get()). If that is NULL, it defaults to
905  "root" for historical reasons.
906  */
907  char const * username;
908 
909  /**
910  The comment text used for the initial commit. If NULL or empty
911  (starts with a NUL byte) then no initial check is
912  created. fossil(1) is largely untested with that scenario (but
913  it seems to work), so for compatibility it is not recommended
914  that this be set to NULL.
915 
916  The default value (when copy-initialized) is "egg". There's a
917  story behind the use of "egg" as the initial checkin comment,
918  and it all started with a typo: "initial chicken"
919  */
920  char const * commitMessage;
921 
922  /**
923  If not NULL and not empty, fsl_repo_create() will use this
924  repository database to copy the configuration, copying over
925  the following settings:
926 
927  - The reportfmt table, overwriting any existing entries.
928 
929  - The user table fields (cap, info, mtime, photo) are copied
930  for the "system users". The system users are: anonymous,
931  nobody, developer, reader.
932 
933  - The vast majority of the config table is copied, arguably
934  more than it should (e.g. the 'manifest' setting).
935  */
936  char const * configRepo;
937 
938  /**
939  If false, fsl_repo_create() will fail if this->filename
940  already exists.
941  */
943 };
945 
946 /** Initialized-with-defaults fsl_repo_create_opt struct, intended
947  for in-struct initialization. */
948 #define fsl_repo_create_opt_empty_m { \
949  NULL/*filename*/, \
950  NULL/*username*/, \
951  "egg"/*commitMessage*/, \
952  NULL/*configRepo*/, \
953  0/*allowOverwrite*/ \
954  }
955 
956 /** Initialized-with-defaults fsl_repo_create_opt struct, intended
957  for copy-initialization. */
959 
960 /**
961  Creates a new repository database using the options provided in
962  the second argument. If f is not NULL, it must be a valid
963  context instance, though it need not have an opened
964  checkout/repository (if it does, it/they will be closed by this
965  operation). If f is NULL, a temporary context is used for
966  creating the repository, in which case the caller will not have
967  access to detailed error information (only the result code) if
968  this operation fails. The opt argument may not be NULL.
969 
970  If opt->allowOverwrite is false (0) and the file exists, it
971  fails with FSL_RC_ALREADY_EXISTS, otherwise is
972  creates/overwrites the file. This is a destructive operation if
973  opt->allowOverwrite is true (non-0), so be careful.
974 
975  This operation installs the various "static" repository schemas
976  into the db, sets up some default settings, and installs a
977  default user.
978 
979  This operation always closes any repository/checkout opened by f
980  because setting up the new db requires wiring it to f to set up
981  some of the db-side infrastructure. The one exception is if
982  argument validation fails, in which case f's
983  repo/checkout-related state are not modified.
984 
985  See the fsl_repo_create_opt docs for more details regarding the
986  creation options.
987 
988  On success, 0 is returned and f (if not NULL) is left with the
989  new repository opened and ready for use. On error, f's error
990  state is updated and any number of the FSL_RC_xxx codes may be
991  returned - there are no less than 30 different _potential_ error
992  conditions on the way to creating a new repository.
993 
994  Example usage:
995 
996  @code
997  fsl_repo_create_opt opt = fsl_repo_create_opt_empty;
998  int rc;
999  opt.filename = "my.fossil";
1000  // ... any other opt.xxx you want to set, e.g.:
1001  // opt.user = "fred";
1002  // Assume fsl is a valid fsl_cx instance:
1003  rc = fsl_repo_create(fsl, &opt );
1004  if(rc) { ...error... }
1005  else {
1006  fsl_db * db = fsl_cx_db_repo(f);
1007  assert(db); // == the new repo db
1008  ...
1009  }
1010  @endcode
1011 
1012  @see fsl_repo_open()
1013  @see fsl_repo_close()
1014 */
1015 FSL_EXPORT int fsl_repo_create(fsl_cx * f, fsl_repo_create_opt const * opt );
1016 
1017 /**
1018  UNTESTED.
1019 
1020  Returns true if f has an opened repository database which is
1021  opened in read-only mode, else returns false.
1022 */
1023 FSL_EXPORT char fsl_repo_is_readonly(fsl_cx const * f);
1024 
1025 /**
1026  Tries to open a checked-out fossil repository db in the given
1027  directory. The (dirName, dirNameLen, checkParentDirs) parameters
1028  are passed on as-is to fsl_checkout_db_search() to find
1029  a checkout db, so see that routine for how it searches.
1030 
1031  If this routine finds/opens a checkout, it also tries to open
1032  the repository database from which the checkout derives (and
1033  fails if it cannot).
1034 
1035  Returns 0 on success. If there is an error opening or validating
1036  the checkout or its repository db, f's error state will be
1037  updated. Error codes/conditions include:
1038 
1039  - FSL_RC_MISUSE if f is NULL.
1040 
1041  - FSL_RC_ACCESS if f already has and opened checkout.
1042 
1043  - FSL_RC_OOM if an allocation fails.
1044 
1045  - FSL_RC_NOT_FOUND if no checkout is foud or if a checkout's
1046  repository is not found.
1047 
1048  - FSL_RC_RANGE if dirname is not NULL but has a length of 0,
1049  either because 0 was passed in for dirNameLen or because
1050  dirNameLen was negative and *dirName is a NUL byte.
1051 
1052  - Various codes from fsl_getcwd() (if dirName is NULL).
1053 
1054  - Various codes if opening the associated repository DB fails.
1055 
1056  TODO: there's really nothing in the architecture which restricts
1057  a checkout db to being in the same directory as the checkout,
1058  except for some historical bits which "could" be refactored. It
1059  "might be interesting" to eventually provide a variant which
1060  opens a checkout db file directly. We have the infrastructure,
1061  just need some refactoring. We would need to add the working
1062  directory path to the checkout db's config, but should otherwise
1063  require no trickery or incompatibilities with fossil(1).
1064 */
1065 FSL_EXPORT int fsl_checkout_open_dir( fsl_cx * f, char const * dirName,
1066  fsl_int_t dirNameLen,
1067  char checkParentDirs );
1068 
1069 
1070 /**
1071  Searches the given directory (or the current directory if dirName
1072  is 0) for a fossil checkout database file named one of (_FOSSIL_,
1073  .fslckout). If it finds one, it returns 0 and appends the file's
1074  path to pOut if pOut is not 0. If neither is found AND if
1075  checkParentDirs is true (non-0) an then it moves up the path one
1076  directory and tries again, until it hits the root of the dirPath
1077  (see below for a note/caveat).
1078 
1079  If dirName is NULL then it behaves as if it had been passed the
1080  absolute path of the current directory (as determined by
1081  fsl_getcwd()).
1082 
1083  If dirName is not NULL and dirNameLen is <0 then fsl_strlen() is
1084  used to calculate dirName's len. If dirName is NULL then dirNameLen
1085  is ignored.
1086 
1087  This function does no normalization of dirName. Because of that...
1088 
1089  Achtung: if dirName is relative, this routine might not find a
1090  checkout where it would find one if given an absolute path (because
1091  it traverses the path string given it instead of its canonical
1092  form). Wether this is a bug or a feature is not yet clear. When in
1093  doubt, use fsl_file_canonical_name() to normalize the directory
1094  name before passing it in here. If it turns out that we always want
1095  that behaviour, this routine will be modified to canonicalize the
1096  name.
1097 
1098  This routine can return at least the following error codes:
1099 
1100  - FSL_RC_NOT_FOUND: either no checkout db was found or the given
1101  directory was not found.
1102 
1103  - FSL_RC_RANGE if dirName is an empty string. (We could arguably
1104  interpret this as a NULL string, i.e. the current directory.)
1105 
1106  - FSL_RC_OOM if allocation of a filename buffer fails.
1107 
1108 */
1109 FSL_EXPORT int fsl_checkout_db_search( char const * dirName, fsl_int_t dirNameLen,
1110  char checkParentDirs, fsl_buffer * pOut );
1111 
1112 
1113 /**
1114  If fsl_checkout_open_dir() has been used to open a checkout db,
1115  this call closes that db and returns 0. Returns FSL_RC_MISUSE if
1116  !f, FSL_RC_NOT_FOUND if f has not opened a checkout (which can
1117  safely be ignored and does not update f's error state).
1118 
1119  This also closes the repository implicitly opened for the
1120  checkout.
1121 
1122  If the checkout is the "main" db, this also closes any
1123  associated config db.
1124 */
1126 
1127 /**
1128  Closes any opened databases (repo/checkout/config). Any errors
1129  triggered by (e.g.) trying to close an unopened db are
1130  suppressed.
1131 */
1132 FSL_EXPORT void fsl_cx_close_dbs( fsl_cx * f );
1133 
1134 /**
1135  Returs version information for the current checkout.
1136 
1137  If f is not NULL and has an opened checkout then...
1138 
1139  If uuid is not NULL then *uuid is set to the UUID of the opened
1140  checkout. If rid is not NULL, *rid is set to the record ID of
1141  that checkout. The returned uuid bytes and rid are valid until
1142  the library closes the checkout db or updates its state to a
1143  newer checkout version. When in doubt about lifetime issues,
1144  copy the UUID immediately after calling this if they will be
1145  needed later.
1146 
1147  Corner case: a new repo with no checkins has an RID of 0
1148  and a UUID of NULL.
1149 
1150  If f is NULL or has no checkout then *uuid will be set to NULL
1151  and *rid will be set to 0.
1152 */
1154 
1155 /**
1156  If f is not NULL and has a checkout db opened then this function
1157  returns its name. The bytes are valid until that checkout db
1158  connection is closed. If len is not NULL then *len is (on
1159  success) assigned to the length of the returned string, in
1160  bytes. The string is NUL-terminated, so fetching the length (by
1161  passing a non-NULL 2nd parameter) is optional.
1162 
1163  Returns NULL if !f or f has no checkout opened.
1164 
1165  @see fsl_checkout_open_dir()
1166  @see fsl_cx_checkout_dir_name()
1167  @see fsl_cx_db_file_config()
1168  @see fsl_cx_db_file_repo()
1169 */
1170 FSL_EXPORT char const * fsl_cx_db_file_checkout(fsl_cx const * f,
1171  fsl_size_t * len);
1172 
1173 /**
1174  Equivalent to fsl_checkout_db_file() except that
1175  it applies to the name of the opened repository db,
1176  if any.
1177 
1178  @see fsl_cx_db_file_checkout()
1179  @see fsl_cx_db_file_config()
1180 */
1181 FSL_EXPORT char const * fsl_cx_db_file_repo(fsl_cx const * f,
1182  fsl_size_t * len);
1183 
1184 /**
1185  Equivalent to fsl_checkout_db_file() except that
1186  it applies to the name of the opened config db,
1187  if any.
1188 
1189  @see fsl_cx_db_file_checkout()
1190  @see fsl_cx_db_file_repo()
1191 */
1192 FSL_EXPORT char const * fsl_cx_db_file_config(fsl_cx const * f,
1193  fsl_size_t * len);
1194 
1195 /**
1196  Similar to fsl_cx_db_file_checkout() and friends except that it
1197  applies to db file implied by the specified role (2nd
1198  parameter). If no such role is opened, or the role is invalid,
1199  NULL is returned.
1200 */
1201 FSL_EXPORT char const * fsl_cx_db_file_for_role(fsl_cx const * f,
1202  fsl_db_role_t r,
1203  fsl_size_t * len);
1204 
1205 /**
1206  Similar to fsl_cx_db_file_checkout() and friends except that it
1207  applies to db name implied by the specified role (2nd
1208  parameter). If no such role is opened, or the role is invalid,
1209  NULL is returned.
1210 
1211  This is the "easiest" way to figure out the DB name of the given
1212  role, independent of what order f's databases were opened
1213  (because the first-opened db is always called 'main').
1214 
1215  The Fossil-standard names of its primary databases are: "ckout",
1216  "repo", and "cfg" (global config db). When opening its main DB,
1217  fsl_cx also ATTACHes the db to its well-known name for the given
1218  role, making this function essentially obsolete.
1219 */
1220 FSL_EXPORT char const * fsl_cx_db_name_for_role(fsl_cx const * f,
1221  fsl_db_role_t r,
1222  fsl_size_t * len);
1223 
1224 /**
1225  If f has an opened checkout db (from fsl_checkout_open_dir())
1226  then this function returns the directory part of the path
1227  for the checkout. The returned bytes are valid until that db
1228  connection is closed. If len is not NULL then *len is (on
1229  success) assigned to the length of the returned string, in bytes.
1230  The string is NUL-terminated, so fetching the length (by passing
1231  a non-NULL 2nd parameter) is optional.
1232 
1233  Returns NULL if !f or f has no checkout opened.
1234 
1235  @see fsl_checkout_open_dir()
1236  @see fsl_checkout_db_file()
1237 */
1238 FSL_EXPORT char const * fsl_cx_checkout_dir_name(fsl_cx const * f,
1239  fsl_size_t * len);
1240 
1241 /**
1242  Returns a handle to f's main db (which may or may not have any
1243  relationship to the repo/checkout/config databases - that's
1244  unspecified!), or NULL if !f. The returned object is owned by f and
1245  the client MUST NOT do any of the following:
1246 
1247  - Close the db handle.
1248 
1249  - Use transactions without using fsl_db_transaction_begin()
1250  and friends.
1251 
1252  - Fiddle with the handle's internals. Doing so might confuse its
1253  owning context.
1254 
1255  Clients MAY add new user-defined functions, use the handle with
1256  fsl_db_prepare(), and other "mundane" db-related tasks.
1257 
1258  Design notes:
1259 
1260  The current architecture designates the first db opened for a
1261  context as its "main" db, and the other databases (if opened)
1262  get attached to that one. As long as there are no table name
1263  collisions across databases, this does not affect how queries
1264  are formulated. It does, however, pose problems when
1265  constructing full-qualified db table names.
1266 
1267  @see fsl_cx_db_repo()
1268  @see fsl_cx_db_checkout()
1269 */
1271 
1272 /**
1273  If f is not NULL and has had its repo opened via
1274  fsl_repo_open(), fsl_checkout_open_dir(), or similar, this
1275  returns a pointer to that database, else it returns NULL.
1276 
1277  @see fsl_cx_db()
1278 */
1280 
1281 /**
1282  If f is not NULL and has had a checkout opened via
1283  fsl_checkout_open_dir() or similar, this returns a pointer to that
1284  database, else it returns NULL.
1285 
1286  @see fsl_cx_db()
1287 */
1289 
1290 /**
1291  A helper which fetches f's repository db. If f has no repo db
1292  then it sets f's error state to FSL_RC_NOT_A_REPO with a message
1293  describing the requirement, then returns NULL. Returns NULL if
1294  !f.
1295 
1296 
1297  @see fsl_cx_db()
1298  @see fsl_cx_db_repo()
1299  @see fsl_needs_checkout()
1300 */
1302 
1303 /**
1304  The checkout-db counterpart of fsl_needs_repo().
1305 
1306  @see fsl_cx_db()
1307  @see fsl_needs_repo()
1308  @see fsl_cx_db_checkout()
1309 */
1311 
1312 
1313 /**
1314  The versioned settings counterpart of fsl_cx_db_checkout(). This
1315  will only return a handle if f's checkout db is opened, else it
1316  returns 0.
1317 
1318  @see fsl_cx_db()
1319  @see fsl_cx_db_repo()
1320  @see fsl_cx_db_checkout()
1321 */
1323 
1324 /**
1325  Returns the db handle associated with the configuration
1326  settings virtual db table. It only returns a handle
1327  once one of f's databases has been opened, and it will
1328  return a handle to the "main" database. If no db is opened,
1329  or f is 0, it returns 0.
1330 
1331  The settings metadata virtual able contains read-only descriptions
1332  of fossil(1) and libfossil configuration settings.
1333 
1334  @see fsl_cx_db()
1335  @see fsl_cx_db_repo()
1336  @see fsl_cx_db_checkout()
1337 */
1339 
1340 
1341 /**
1342  Opens the given database file as f's configuration database. If f
1343  already has a config database opened, it is closed before opening
1344  the new one. The database is created and populated with an
1345  initial schema if needed.
1346 
1347  If dbName is NULL or empty then it uses a default db name,
1348  "probably" under the user's home directory. To get the name of
1349  the database after it has been opened/attached, use
1350  fsl_cx_db_file_config().
1351 
1352  TODO: strongly consider supporting non-attached use of
1353  the config db. Comments in v1 suggest that it is possible
1354  to lock the config db for other apps when it is attached
1355  to a long-running op by a fossil process.
1356 
1357  @see fsl_cx_db_config()
1358  @see fsl_config_close()
1359 */
1360 FSL_EXPORT int fsl_config_open( fsl_cx * f, char const * dbName );
1361 
1362 /**
1363  Closes/detaches the database connection opened by
1364  fsl_config_open(). Returns 0 on succes, FSL_RC_MISUSE if !f,
1365  FSL_RC_NOT_FOUND if no config db connection is opened/attached.
1366 
1367  @see fsl_cx_db_config()
1368  @see fsl_config_open()
1369 */
1371 
1372 /**
1373  If f has an opened/attached configuration db then its handle is
1374  returned, else 0 is returned.
1375 
1376  @see fsl_config_open()
1377  @see fsl_config_close()
1378 */
1380 
1381 /**
1382  Convenience form of fsl_db_prepare() which uses f's main db.
1383  Returns 0 on success, FSL_RC_MISUSE if !f or !sql, FSL_RC_RANGE
1384  if !*sql.
1385 */
1386 FSL_EXPORT int fsl_cx_prepare( fsl_cx *f, fsl_stmt * tgt, char const * sql, ... );
1387 
1388 /**
1389  va_list counterpart of fsl_cx_prepare().
1390 */
1391 FSL_EXPORT int fsl_cx_preparev( fsl_cx *f, fsl_stmt * tgt, char const * sql, va_list args );
1392 
1393 /**
1394  Wrapper around fsl_db_last_insert_id() which uses f's main
1395  database. Returns -1 if !f or f has no opened db.
1396 
1397  @see fsl_cx_db()
1398 */
1400 
1401 /**
1402  Returns the raw SQL code for a Fossil global config database.
1403 */
1404 FSL_EXPORT char const * fsl_schema_config();
1405 
1406 /**
1407  Returns the raw SQL code for the "static" parts of a Fossil
1408  repository database. These are the parts which are immutable
1409  (for the most part) between Fossil versions. They change _very_
1410  rarely.
1411 */
1412 FSL_EXPORT char const * fsl_schema_repo1();
1413 
1414 /**
1415  Returns the raw SQL code for the "transient" parts of a Fossil
1416  repository database - any parts which can be calculated via data
1417  held in the primary "static" schemas. These parts are
1418  occassionally recreated, e.g. via a 'rebuild' of a repository.
1419 */
1420 FSL_EXPORT char const * fsl_schema_repo2();
1421 
1422 /**
1423  Returns the raw SQL code for a Fossil checkout database.
1424 */
1425 FSL_EXPORT char const * fsl_schema_checkout();
1426 
1427 /**
1428  Returns the raw SQL code for a Fossil checkout db's
1429  _default_ core ticket-related tables.
1430 
1431  @see fsl_cx_schema_ticket()
1432 */
1433 FSL_EXPORT char const * fsl_schema_ticket();
1434 
1435 /**
1436  If f's opened repository has a config non-empty entry named
1437  'ticket-table', this returns its text via appending it to
1438  pOut. If no entry is found, fsl_schema_ticket() is appended to
1439  pOut.
1440 
1441  Returns 0 on success. On error the contents of pOut must not be
1442  considered valid but pOut might be partially populated.
1443 */
1445 
1446 /**
1447  Returns the raw SQL code for Fossil ticket reports schemas.
1448  This gets installed as needed into repository databases.
1449 */
1450 FSL_EXPORT char const * fsl_schema_ticket_reports();
1451 
1452 /**
1453  Works similarly to fsl_stat(), except that zName must refer to a
1454  path under f's current checkout directory. Note that this stats
1455  local files, not repository-level content.
1456 
1457  If relativeToCwd is true (non-0) then the filename is
1458  resolved/canonicalized based on the current working directory
1459  (see fsl_getcwd()), otherwise f's current checkout directory is
1460  used as the virtual root. This makes a subtle yet important
1461  difference in how the name is resolved. Applications taking
1462  input from users (e.g. CLI apps) will normally want to resolve
1463  from the current working dir (assuming the filenames were passed
1464  in from the CLI). In a GUI environment, where the current
1465  directory is likely not the checkout root, resolving based on
1466  the checkout root (i.e. relativeToCwd=0) is probably saner.
1467 
1468  Returns 0 on success. Errors include, but are not limited to:
1469 
1470  - FSL_RC_MISUSE if !f or !zName.
1471 
1472  - FSL_RC_NOT_A_CHECKOUT if f has no opened checkout.
1473 
1474  - If fsl_is_simple_pathname(zName) returns false then
1475  fsl_checkout_filename_check() is used o normalize the name. If
1476  that fails, its failure core is returned.
1477 
1478  - As for fsl_stat().
1479 
1480  See fsl_stat() for more details regarding the tgt parameter.
1481 
1482  TODO: fossil-specific symlink support. Currently it does not
1483  distinguish between symlinks and non-links.
1484 
1485  @see fsl_cx_stat2()
1486 */
1487 FSL_EXPORT int fsl_cx_stat( fsl_cx * f, char relativeToCwd,
1488  char const * zName, fsl_fstat * tgt );
1489 
1490 /**
1491  This works identically to fsl_cx_stat(), but provides more
1492  information about the file being stat'd.
1493 
1494  If nameOut is not NULL then the resolved/normalized path to to
1495  that file is appended to nameOut. If fullPath is true then an
1496  absolute path is written to nameOut, otherwise a
1497  checkout-relative path is written.
1498 
1499  Returns 0 on success. On stat() error, nameOut is not updated,
1500  but after stat()'ing, allocation of memory for nameOut's buffer
1501  may fail.
1502 
1503  If zName ends with a trailing slash, that slash is retained in
1504  nameOut.
1505 
1506  @see fsl_cx_stat()
1507 */
1508 FSL_EXPORT int fsl_cx_stat2( fsl_cx * f, char relativeToCwd, char const * zName,
1509  fsl_fstat * tgt, fsl_buffer * nameOut, char fullPath);
1510 
1511 
1512 /**
1513  Sets the case-sensitivity flag for f to the given value. This
1514  flag alters how some filename-search/comparison operations
1515  operate. This option is only intended to have an effect on
1516  plaforms with case-insensitive filesystems.
1517 
1518  @see fsl_cx_is_case_sensitive()
1519 */
1520 FSL_EXPORT void fsl_cx_case_sensitive_set(fsl_cx * f, char caseSensitive);
1521 
1522 /**
1523  Returns true (non-0) if f is set for case-sensitive filename
1524  handling, else 0. Returns 0 if !f.
1525 
1526  @see fsl_cx_case_sensitive_set()
1527 */
1529 
1530 /**
1531  If f is set to use case-sensitive filename handling,
1532  returns a pointer to an empty string, otherwise a pointer
1533  to the string "COLLATE nocase" is returned.
1534  Results are undefined if f is NULL. The returned bytes
1535  are static.
1536 
1537  @see fsl_cx_case_sensitive_set()
1538  @see fsl_cx_is_case_sensitive()
1539 */
1540 FSL_EXPORT char const * fsl_cx_filename_collation(fsl_cx const * f);
1541 
1542 /**
1543  An enumeration of the types of control artifacts used by
1544  Fossil. Their numeric values (with the exception of
1545  FSL_TYPE_CATYPE_INVALID) are a hard-coded part of the Fossil db
1546  architecture and must never be changed.
1547 */
1549 /**
1550  Sentinel value used for some error reporting.
1551 */
1553 /**
1554  Sentinel value used to mark a deck as being "any" type. This is
1555  a placeholder on a deck's way to completion.
1556 */
1558 /**
1559  Indicates a "manifest" artifact (a checkin record).
1560 */
1562 /**
1563  Indicates a "cluster" artifact. These are used during synchronization.
1564 */
1566 /**
1567  Indicates a "control" artifact (a tag change).
1568 */
1570 /**
1571  Indicates a "wiki" artifact.
1572 */
1574 /**
1575  Indicates a "ticket" artifact.
1576 */
1578 /**
1579  Indicates an "attachment" artifact (used in the ticketing
1580  subsystem).
1581 */
1583 /**
1584  Indicates an "event" artifact (kind of like a blog entry).
1585 */
1587 };
1589 
1590 /**
1591  Returns some arbitrary but distinct string for the given
1592  fsl_catype_t. The returned bytes are static and
1593  NUL-terminated. Intended primarily for debugging and informative
1594  purposes, not actual user output.
1595 */
1596 FSL_EXPORT char const * fsl_catype_cstr(fsl_catype_t t);
1597 
1598 /**
1599  For a given artifact type, it returns the key string used in the
1600  event.type db table. Returns NULL if passed an unknown value or
1601  a type which is not used in the event table, otherwise the
1602  returned bytes are static and NUL-terminated.
1603 
1604  The returned strings for a given type are as follows:
1605 
1606  - FSL_CATYPE_ANY returns "*"
1607  - FSL_CATYPE_CHECKIN returns "ci"
1608  - FSL_CATYPE_WIKI returns "w"
1609  - FSL_CATYPE_TAG returns "g"
1610  - FSL_CATYPE_TICKET returns "t"
1611  - FSL_CATYPE_EVENT returns "e"
1612 
1613  The other control artifact types to not have representations
1614  in the event table, and NULL is returned for them.
1615 
1616  All of the returned values can be used in comparison clauses in
1617  queries on the event table's 'type' field (but use GLOB instead
1618  of '=' so that the "*" returned by FSL_ATYPE_ANY can match!).
1619  For example, to get the comments from the most recent 5 commits:
1620 
1621  @code
1622  SELECT
1623  datetime(mtime),
1624  coalesce(ecomment,comment),
1625  user
1626  FROM event WHERE type='ci'
1627  ORDER BY mtime DESC LIMIT 5;
1628  @endcode
1629 
1630  Where 'ci' in the SQL is the non-NULL return value from this
1631  function. When escaping this value via fsl_buffer_appendf() (or
1632  anything functionally similar), use the %%q/%%Q format
1633  specifiers to escape it.
1634 */
1635 FSL_EXPORT char const * fsl_catype_event_cstr(fsl_catype_t t);
1636 
1637 /**
1638  Resolves client-provided symbol as an artifact's db record ID.
1639  f must have an opened repository db, and some symbols can only
1640  be looked up if it has an opened checkout (see the list below).
1641 
1642  Returns 0 and sets *rv to the id if it finds an unambiguous
1643  match.
1644 
1645  Returns FSL_RC_MISUSE if !f, !sym, !*sym, or !rv.
1646 
1647  Returns FSL_RC_NOT_A_REPO if f has no opened repository.
1648 
1649  Returns FSL_RC_AMBIGUOUS if sym is a partial UUID which matches
1650  multiple full UUIDs.
1651 
1652  Returns FSL_RC_NOT_FOUND if it cannot find anything.
1653 
1654  Symbols supported by this function:
1655 
1656  - SHA1 hash
1657  - SHA1 hash prefix of at least 4 characters
1658  - Symbolic Name
1659  - "tag:" + symbolic name
1660  - Date or date-time
1661  - "date:" + Date or date-time
1662  - symbolic-name ":" date-time
1663  - "tip"
1664  - "root:" resolves to the root manifest of the given checkin. In
1665  the trunk this will always resolve to the first "empty checkin"
1666  manifest.
1667 
1668  The following additional forms are available in local checkouts:
1669 
1670  - "current"
1671  - "prev" or "previous"
1672  - "next"
1673 
1674  If type is not FSL_CATYPE_ANY then it will only match artifacts
1675  of the specified type. In order to resolve arbitrary UUIDs, e.g.
1676  those of arbitrary blob content, type needs to be
1677  FSL_CATYPE_ANY.
1678 
1679 */
1680 FSL_EXPORT int fsl_sym_to_rid( fsl_cx * f, char const * sym, fsl_catype_t type,
1681  fsl_id_t * rv );
1682 
1683 /**
1684  Similar to fsl_sym_to_rid() but on success if returns a UUID
1685  string by assigning it to *rv. If rid is not NULL then on
1686  success the db record ID corresponding to the returned UUID is
1687  assigned to *rid. The caller must eventually free the returned
1688  string memory by passing it to fsl_free().
1689 */
1690 FSL_EXPORT int fsl_sym_to_uuid( fsl_cx * f, char const * sym,
1691  fsl_catype_t type, fsl_uuid_str * rv,
1692  fsl_id_t * rid );
1693 
1694 /**
1695  Searches f's repo database for the a blob with the given uuid
1696  (any unique UUID prefix). On success a positive record ID is
1697  returned. On error one of several unspecified negative values is
1698  returned. If no uuid match is found 0 is returned.
1699 
1700  Error cases include: either argument is NULL, uuid does not
1701  appear to be a full or partial UUID (or is too long),
1702  uuid is ambiguous (try providing a longer one)
1703 
1704  This implementation is more efficient when given a full,
1705  valid UUID (one for which fsl_is_uuid() returns true).
1706 */
1707 FSL_EXPORT fsl_id_t fsl_uuid_to_rid( fsl_cx * f, char const * uuid );
1708 
1709 /**
1710  The opposite of fsl_uuid_to_rid(), this returns the UUID string
1711  of the given blob record ID. Ownership of the string is passed
1712  to the caller and it must eventually be freed using
1713  fsl_free(). Returns NULL on error (invalid arguments or f has no
1714  repo opened) or if no blob record is found. If no record is
1715  found, f's error state is updated with an explanation of the
1716  problem.
1717 */
1719 
1720 /**
1721  This works identically to fsl_uuid_to_rid() except that it will
1722  only resolve to a UUID if an artifact matching the given type has
1723  that UUID. If no entry is found, f's error state gets updated
1724  with a description of the problem.
1725 
1726  This can be used to distinguish artifact UUIDs from file blob
1727  content UUIDs by passing the type FSL_CATYPE_ANY. A non-artifact
1728  blob will return NULL in that, but any artifact type will match
1729  (assuming rid is valid).
1730 */
1732  fsl_catype_t type);
1733 
1734 
1735 /**
1736  A collection of bitmaskable values indicating categories
1737  of fossil-standard glob sets. These correspond to the following
1738  configurable settings:
1739 
1740  ignore-glob, crnl-glob, binary-glob
1741 */
1743 /** Corresponds to the ignore-glob config setting. */
1745 /** Corresponds to the crnl-glob config setting. */
1747 /** Corresponds to the binary-glob config setting. */
1749 /** A superset of all config-level glob categories. */
1751 };
1753 
1754 /**
1755  Checks one or more of f's configurable glob lists to see if str
1756  matches one of them. If it finds a match, it returns a pointer to
1757  the matching glob (as per fsl_glob_list_matches()), the bytes
1758  of which are owned by f and may be invalidated via modification
1759  or reloading of the underlying glob list. In generally the return
1760  value can be used as a boolean - clients generally do not need
1761  to know exactly which glob matched.
1762 
1763  gtype specifies the glob list(s) to check in the form of a
1764  bitmask of fsl_glob_category_t values. Note that the order of the
1765  lists is unspecified, so if that is important for you then be
1766  sure that gtype only specifies one glob list
1767  (e.g. FSL_GLOBS_IGNORE) and call it again (e.g. passing
1768  FSL_GLOBS_BINARY) if you need to distinguish between those two
1769  cases.
1770 
1771  str must be a non-NULL, non-empty empty string.
1772 
1773  Returns NULL if !f, !str, !*str, gtype does not specify any known
1774  glob list(s), or no glob match is found.
1775 
1776  Performance is, abstractly speaking, horrible, because we're
1777  comparing arbitrarily long lists of glob patterns against an
1778  arbitrary string. That said, it's fast enough for our purposes.
1779 */
1780 FSL_EXPORT char const * fsl_cx_glob_matches( fsl_cx * f, int gtype,
1781  char const * str );
1782 
1783 #if 0
1784 /**
1785  DO NOT USE - not yet tested and ready.
1786 
1787  Returns the result of either localtime(clock) or gmtime(clock),
1788  depending on f:
1789 
1790  - If f is NULL, returns localtime(clock).
1791 
1792  - If f has had its FSL_CX_F_LOCALTIME_GMT flag set (see
1793  fsl_cx_flag_set()) then returns gmtime(clock), else
1794  localtime(clock).
1795 
1796  If clock is NULL, NULL is returned.
1797 
1798  Note that fsl_cx instances default to using UTC for everything,
1799  which is the opposite of fossil(1).
1800 */
1801 FSL_EXPORT struct tm * fsl_cx_localtime( fsl_cx const * f, const time_t * clock );
1802 
1803 /**
1804  Equivalent to fsl_cx_localtime(NULL, clock).
1805 */
1806 FSL_EXPORT struct tm * fsl_localtime( const time_t * clock );
1807 
1808 /**
1809  DO NOT USE - not yet tested and ready.
1810 
1811  This function passes (f, clock) to fsl_cx_localtime(),
1812  then returns the result of mktime(3) on it. So...
1813  it adjusts a UTC Unix timestamp to either the same UTC
1814  local timestamp or to the local time.
1815 */
1816 FSL_EXPORT time_t fsl_cx_time_adj(fsl_cx const * f, time_t clock);
1817 #endif
1818 
1819 #if defined(__cplusplus)
1820 } /*extern "C"*/
1821 #endif
1822 #endif
1823 /* NET_FOSSIL_SCM_FSL_CORE_H_INCLUDED */
FSL_EXPORT fsl_db * fsl_needs_repo(fsl_cx *f)
A helper which fetches f's repository db.
fsl_cx_config config
Basic configuration parameters.
Definition: fossil-core.h:545
Project name.
Definition: fossil-core.h:170
The quintessential not-an-error value.
Definition: fossil-core.h:233
fsl_uint_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
fsl_catype_t
An enumeration of the types of control artifacts used by Fossil.
Definition: fossil-core.h:1548
Holds an allocator function and its related state.
Definition: fossil-util.h:395
Indicates a "control" artifact (a tag change).
Definition: fossil-core.h:1569
char const * filename
The file name for the new repository.
Definition: fossil-core.h:900
Indicates that some data type or logical type is incorrect (e.g.
Definition: fossil-core.h:338
Indicates a "manifest" artifact (a checkin record).
Definition: fossil-core.h:1561
char const * commitMessage
The comment text used for the initial commit.
Definition: fossil-core.h:920
Indicates a regular file with the executable bit set.
Definition: fossil-core.h:435
FSL_EXPORT fsl_db * fsl_cx_db_versioned(fsl_cx *f)
The versioned settings counterpart of fsl_cx_db_checkout().
Indicates that an invalid size value was encountered while parsing a delta.
Definition: fossil-core.h:392
Indicates that the requested repo is not, in fact, a repo.
Definition: fossil-core.h:288
A superset of all config-level glob categories.
Definition: fossil-core.h:1750
Indicates an attempt to open a too-old or too-new repository db.
Definition: fossil-core.h:293
Indicates that fsl_stmt_step() has reached the end of the result set and that there is no row data to...
Definition: fossil-core.h:325
License as yet undecided!
Definition: fossil-core.h:30
Use the legacy format.
Definition: fossil-core.h:184
FSL_EXPORT void fsl_cx_close_dbs(fsl_cx *f)
Closes any opened databases (repo/checkout/config).
FSL_EXPORT char const * fsl_cx_db_file_checkout(fsl_cx const *f, fsl_size_t *len)
If f is not NULL and has a checkout db opened then this function returns its name.
The main Fossil "context" type.
FSL_EXPORT fsl_uuid_str fsl_rid_to_artifact_uuid(fsl_cx *f, fsl_id_t rid, fsl_catype_t type)
This works identically to fsl_uuid_to_rid() except that it will only resolve to a UUID if an artifact...
FSL_EXPORT int fsl_cx_schema_ticket(fsl_cx *f, fsl_buffer *pOut)
If f's opened repository has a config non-empty entry named 'ticket-table', this returns its text via...
A part of the configuration used by fsl_cx_init() and friends.
Definition: fossil-core.h:506
Analog to v1's "configdb".
Definition: fossil-core.h:91
FSL_EXPORT int fsl_outputf(fsl_cx *f, char const *fmt,...)
Uses fsl_appendf() to append formatted output to the channel configured for use with fsl_output()...
FSL_EXPORT fsl_db * fsl_cx_db_metadata(fsl_cx *f)
Returns the db handle associated with the configuration settings virtual db table.
WWW interface appearance.
Definition: fossil-core.h:166
fsl_outputer output
The output channel for the Fossil instance.
Definition: fossil-core.h:541
FSL_EXPORT char const * fsl_schema_repo1()
Returns the raw SQL code for the "static" parts of a Fossil repository database.
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.
Indicates that access to or locking of a resource was denied by some security mechanism or other...
Definition: fossil-core.h:259
Indicates a "wiki" artifact.
Definition: fossil-core.h:1573
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_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.
Used by some iteration routines to indicate that iteration should stop prematurely without an error...
Definition: fossil-core.h:307
FSL_EXPORT int fsl_sym_to_uuid(fsl_cx *f, char const *sym, fsl_catype_t type, fsl_uuid_str *rv, fsl_id_t *rid)
Similar to fsl_sym_to_rid() but on success if returns a UUID string by assigning it to *rv...
FSL_EXPORT char const * fsl_cx_db_file_repo(fsl_cx const *f, fsl_size_t *len)
Equivalent to fsl_checkout_db_file() except that it applies to the name of the opened repository db...
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Definition: fossil-util.h:325
Indicates that a size comparison check failed.
Definition: fossil-core.h:380
Style sheet only.
Definition: fossil-core.h:164
A container for storing generic error state.
Definition: fossil-util.h:692
fsl_db_role_t
This enum defines type ID tags with which the API tags fsl_db instances so that the library can figur...
Definition: fossil-core.h:83
FSL_EXPORT fsl_cx * fsl_cx_malloc()
Allocates a new fsl_cx instance, which must eventually be passed to fsl_cx_finalize() to clean it up...
FSL_EXPORT int fsl_cx_flag_set(fsl_cx *f, int flags, char enable)
Sets or unsets one or more option flags on the given fossil context.
Indicates that an invalid operator was encountered while parsing a delta.
Definition: fossil-core.h:398
This is a special case of FSL_RC_NOT_FOUND, intended specifically to differentiate from "file not fou...
Definition: fossil-core.h:373
FSL_EXPORT int fsl_repo_close(fsl_cx *f)
If fsl_repo_open_xxx() or fsl_checkout_open_dir() has been used to open a respository db...
FSL_EXPORT char const * fsl_catype_cstr(fsl_catype_t t)
Returns some arbitrary but distinct string for the given fsl_catype_t.
Indicates an "attachment" artifact (used in the ticketing subsystem).
Definition: fossil-core.h:1582
Db handle wrapper class.
Definition: fossil-db.h:105
#define FSL_EXPORT
Definition: fossil-config.h:19
char const * fsl_uuid_cstr
The const counterpart of fsl_uuid_str.
Definition: fossil-util.h:92
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.
This file declares a number of utility classes and routines used by libfossil.
FSL_EXPORT int fsl_checkout_close(fsl_cx *f)
If fsl_checkout_open_dir() has been used to open a checkout db, this call closes that db and returns ...
FSL_EXPORT int fsl_config_close(fsl_cx *f)
Closes/detaches the database connection opened by fsl_config_open().
FSL_EXPORT int fsl_cx_flags_get(fsl_cx *f)
Returns f's flags, or -1 if !f.
Indicates that an operation which requires a checkout does not have a checkout to work on...
Definition: fossil-core.h:344
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()...
Represents a prepared statement handle.
Definition: fossil-db.h:321
FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_empty
Empty-initialized fsl_cx_init_opt instance.
Definition: fossil-core.h:558
Indicates that an invalid terminator was encountered while parsing a delta.
Definition: fossil-core.h:404
Sentinel value used to mark a deck as being "any" type.
Definition: fossil-core.h:1557
Indicates a "ticket" artifact.
Definition: fossil-core.h:1577
The CONCEALED table.
Definition: fossil-core.h:176
FSL_EXPORT char fsl_repo_is_readonly(fsl_cx const *f)
UNTESTED.
fsl_rc_t
Most functions in this API which return an int type return error codes from the fsl_rc_t enum...
Definition: fossil-core.h:229
Analog to v1's "repository".
Definition: fossil-core.h:95
FSL_EXPORT fsl_error const * fsl_cx_err_get_e(fsl_cx const *f)
Returns f's error state object.
Analog to v1's "localdb".
Definition: fossil-core.h:99
Indicates a generic syntax error in a control artifact.
Definition: fossil-core.h:412
FSL_EXPORT fsl_db * fsl_cx_db_checkout(fsl_cx *f)
If f is not NULL and has had a checkout opened via fsl_checkout_open_dir() or similar, this returns a pointer to that database, else it returns NULL.
fsl_allocator allocator
Library-wide allocator.
Definition: fossil-core.h:497
Sentinel "no role" value.
Definition: fossil-core.h:87
Indicates that an invalid separator was encountered while parsing a delta.
Definition: fossil-core.h:386
FSL_EXPORT fsl_uuid_str fsl_rid_to_uuid(fsl_cx *f, fsl_id_t rid)
The opposite of fsl_uuid_to_rid(), this returns the UUID string of the given blob record ID...
FSL_EXPORT int fsl_repo_create(fsl_cx *f, fsl_repo_create_opt const *opt)
Creates a new repository database using the options provided in the second argument.
fsl_glob_category_t
A collection of bitmaskable values indicating categories of fossil-standard glob sets.
Definition: fossil-core.h:1742
Causes overwrite instead of merge.
Definition: fossil-core.h:182
fsl_file_perm_t
Filesystem-level permissions flags supported by fossil Manifests.
Definition: fossil-core.h:431
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.
Indicates that a checksum comparison failed, possibly indicating that corrupted or unexpected data wa...
Definition: fossil-core.h:356
FSL_EXPORT char const * fsl_cx_db_file_config(fsl_cx const *f, fsl_size_t *len)
Equivalent to fsl_checkout_db_file() except that it applies to the name of the opened config db...
FSL_EXPORT int fsl_checkout_db_search(char const *dirName, fsl_int_t dirNameLen, char checkParentDirs, fsl_buffer *pOut)
Searches the given directory (or the current directory if dirName is 0) for a fossil checkout databas...
Indicates that a to-be-created resource already exists.
Definition: fossil-core.h:272
char * fsl_uuid_str
fsl_uuid_str and fsl_uuid_cstr are "for documentation and readability purposes" typedefs used to deno...
Definition: fossil-util.h:85
Transfer configuration.
Definition: fossil-core.h:178
FSL_EXPORT char const * fsl_schema_ticket_reports()
Returns the raw SQL code for Fossil ticket reports schemas.
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
FSL_EXPORT char const * fsl_rc_cstr(int)
Returns a "standard" string form for a fsl_rc_t code.
Internal use only to prevent duplicate initialization of some bits.
Definition: fossil-core.h:203
FSL_EXPORT fsl_db * fsl_cx_db_repo(fsl_cx *f)
If f is not NULL and has had its repo opened via fsl_repo_open(), fsl_checkout_open_dir(), or similar, this returns a pointer to that database, else it returns NULL.
Indicates that a db-level error occurred during a fsl_stmt_step() iteration.
Definition: fossil-core.h:331
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...
FSL_EXPORT void fsl_cx_case_sensitive_set(fsl_cx *f, char caseSensitive)
Sets the case-sensitivity flag for f to the given value.
A placeholder return value for "not yet implemented" functions.
Definition: fossil-core.h:241
FSL_EXPORT int fsl_sym_to_rid(fsl_cx *f, char const *sym, fsl_catype_t type, fsl_id_t *rv)
Resolves client-provided symbol as an artifact's db record ID.
Indicates that the requested repo needs to be rebuilt.
Definition: fossil-core.h:281
FSL_EXPORT int fsl_checkout_open_dir(fsl_cx *f, char const *dirName, fsl_int_t dirNameLen, char checkParentDirs)
Tries to open a checked-out fossil repository db in the given directory.
This type, accessible to clients via the fsl_lib_configurable global, contains configuration-related ...
Definition: fossil-core.h:478
Data consistency problem.
Definition: fossil-core.h:276
Indicates a symlink.
Definition: fossil-core.h:442
A general-purpose buffer class, analog to Fossil v1's Blob class, but it is not called fsl_blob to av...
Definition: fossil-util.h:632
FSL_EXPORT fsl_id_t fsl_uuid_to_rid(fsl_cx *f, char const *uuid)
Searches f's repo database for the a blob with the given uuid (any unique UUID prefix).
FSL_EXPORT int fsl_repo_open(fsl_cx *f, char const *repoDbFile)
Opens the given db file name as f's repository.
fsl_user_role_t
Roles equate to permissions in Fossil v1.
Definition: fossil-core.h:118
FSL_EXPORT char fsl_cx_is_case_sensitive(fsl_cx const *f)
Returns true (non-0) if f is set for case-sensitive filename handling, else 0.
Indicates a regular, writable file.
Definition: fossil-core.h:433
FSL_EXPORT fsl_db * fsl_needs_checkout(fsl_cx *f)
The checkout-db counterpart of fsl_needs_repo().
FSL_EXPORT char const * fsl_cx_checkout_dir_name(fsl_cx const *f, fsl_size_t *len)
If f has an opened checkout db (from fsl_checkout_open_dir()) then this function returns the director...
Default flags for all fsl_cx instances.
Definition: fossil-core.h:208
Everything.
Definition: fossil-core.h:180
Indicates that some value or expression is ambiguous.
Definition: fossil-core.h:419
FSL_EXPORT char const * fsl_schema_ticket()
Returns the raw SQL code for a Fossil checkout db's _default_ core ticket-related tables...
char allowOverwrite
If false, fsl_repo_create() will fail if this->filename already exists.
Definition: fossil-core.h:942
Indicates db-level error (e.g.
Definition: fossil-core.h:301
Configuration parameters for fsl_repo_create().
Definition: fossil-core.h:896
FSL_EXPORT char const * fsl_catype_event_cstr(fsl_catype_t t)
For a given artifact type, it returns the key string used in the event.type db table.
FSL_EXPORT int fsl_cx_stat2(fsl_cx *f, char relativeToCwd, char const *zName, fsl_fstat *tgt, fsl_buffer *nameOut, char fullPath)
This works identically to fsl_cx_stat(), but provides more information about the file being stat'd...
Some range was violated (function argument, UTF character, etc.).
Definition: fossil-core.h:254
char traceSql
If true, all SQL which goes through the fossil engine will be traced to the fsl_output()-configured c...
Definition: fossil-core.h:511
requested resource not found
Definition: fossil-core.h:268
FSL_EXPORT int fsl_flush(fsl_cx *f)
Flushes f's output channel.
FSL_EXPORT int fsl_outputfv(fsl_cx *f, char const *fmt, va_list args)
va_list counterpart to fsl_outputf().
fsl_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...
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...
char sqlPrint
If true, the fsl_print() SQL function will output its output to the fsl_output()-configured channel...
Definition: fossil-core.h:516
Shun settings.
Definition: fossil-core.h:172
FSL_EXPORT char const * fsl_library_version()
Returns the value of FSL_LIBRARY_VERSION used to compile the library.
Sentinel value used for some error reporting.
Definition: fossil-core.h:1552
Indicates an I/O error.
Definition: fossil-core.h:264
Analog to v1's "main", which is basically an alias for the first db opened.
Definition: fossil-core.h:104
Indicates that fsl_stmt_step() has fetched a row and the cursor may be used to access the current row...
Definition: fossil-core.h:316
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().
Corresponds to the ignore-glob config setting.
Definition: fossil-core.h:1744
Generic/unknown error.
Definition: fossil-core.h:237
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 char const * fsl_schema_checkout()
Returns the raw SQL code for a Fossil checkout database.
FSL_EXPORT char const * fsl_schema_config()
Returns the raw SQL code for a Fossil global config database.
Not yet used.
Definition: fossil-core.h:351
FSL_EXPORT int fsl_cx_init(fsl_cx **tgt, fsl_cx_init_opt const *param)
Initializes a fsl_cx instance.
A simple wrapper around the stat(2) structure resp.
Definition: fossil-util.h:2570
FSL_EXPORT int fsl_output(fsl_cx *f, void const *src, fsl_size_t n)
Outputs the first n bytes of src to f's configured output channel.
FSL_EXPORT int fsl_cx_err_report(fsl_cx *f, char addNewline)
If f has error state then it outputs its error state to its output channel and returns the result of ...
FSL_EXPORT void fsl_cx_reset(fsl_cx *f, char closeDatabases)
Clears (most) dynamic state in f, but does not free f and does not free "static" state (that set up b...
Ticket configuration.
Definition: fossil-core.h:168
FSL_EXPORT int fsl_cx_stat(fsl_cx *f, char relativeToCwd, char const *zName, fsl_fstat *tgt)
Works similarly to fsl_stat(), except that zName must refer to a path under f's current checkout dire...
FSL_EXPORT char const * fsl_schema_repo2()
Returns the raw SQL code for the "transient" parts of a Fossil repository database - any parts which ...
FSL_EXPORT const fsl_cx_config fsl_cx_config_empty
fsl_cx_config instance initialized with defaults, intended for copy-initialization.
Definition: fossil-core.h:532
Parameters for fsl_cx_init().
Definition: fossil-core.h:537
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 fsl_lib_configurable_t fsl_lib_configurable
Definition: fossil-core.h:500
Sentinel value.
Definition: fossil-core.h:162
FSL_EXPORT void fsl_checkout_version_info(fsl_cx *f, fsl_id_t *rid, fsl_uuid_cstr *uuid)
Returs version information for the current checkout.
Indicates a "cluster" artifact.
Definition: fossil-core.h:1565
Out of memory.
Definition: fossil-core.h:246
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_cx_db_name_for_role(fsl_cx const *f, fsl_db_role_t r, fsl_size_t *len)
Similar to fsl_cx_db_file_checkout() and friends except that it applies to db name implied by the spe...
char const * username
Fossil user name for the admin user in the new repo.
Definition: fossil-core.h:907
Indicates an "event" artifact (kind of like a blog entry).
Definition: fossil-core.h:1586
FSL_EXPORT const fsl_repo_create_opt fsl_repo_create_opt_empty
Initialized-with-defaults fsl_repo_create_opt struct, intended for copy-initialization.
Definition: fossil-core.h:958
FSL_EXPORT char const * fsl_cx_db_file_for_role(fsl_cx const *f, fsl_db_role_t r, fsl_size_t *len)
Similar to fsl_cx_db_file_checkout() and friends except that it applies to db file implied by the spe...
Corresponds to the binary-glob config setting.
Definition: fossil-core.h:1748
FSL_EXPORT int fsl_cx_err_get(fsl_cx *f, char const **str, fsl_size_t *len)
Fetches the error state from f.
The USER table.
Definition: fossil-core.h:174
FSL_EXPORT const fsl_cx_init_opt fsl_cx_init_opt_default
fsl_cx_init_opt instance initialized to use stdout for output and the standard system memory allocato...
Definition: fossil-core.h:565
FSL_EXPORT fsl_db * fsl_cx_db_config(fsl_cx *f)
If f has an opened/attached configuration db then its handle is returned, else 0 is returned...
char const * configRepo
If not NULL and not empty, fsl_repo_create() will use this repository database to copy the configurat...
Definition: fossil-core.h:936
FSL_EXPORT int fsl_cx_uplift_db_error(fsl_cx *f, fsl_db *db)
Moves db->error's state into f.
FSL_EXPORT char fsl_library_version_matches(char const *yourLibVersion)
Returns true (non-0) if yourLibVersion compares lexically equal to FSL_LIBRARY_VERSION, else it returns false (0).
Corresponds to the crnl-glob config setting.
Definition: fossil-core.h:1746
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...
Tells us whether or not we want to calculate R-cards by default.
Definition: fossil-core.h:198
fsl_configset_t
Bitmask values specifying "configuration sets." The values in this enum come directly from fossil(1)...
Definition: fossil-core.h:160
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_cx_flag_t
Runtime-configurable flags for a fsl_cx instance.
Definition: fossil-core.h:191