/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 
/* vim: set ts=2 et sw=2 tw=80: */
#if !defined(NET_FOSSIL_SCM_FOSSIL2_H_INCLUDED)
#define NET_FOSSIL_SCM_FOSSIL2_H_INCLUDED
/*
** Copyright (c) 2013 D. Richard Hipp
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the Simplified BSD License (also
** known as the "2-Clause License" or "FreeBSD License".)
**
** This program is distributed in the hope that it will be useful,
** but without any warranty; without even the implied warranty of
** merchantability or fitness for a particular purpose.
**
** Author contact information:
**   drh@hwaci.com
**   http://www.hwaci.com/drh/
**
*******************************************************************************
**
*/
#include <stdio.h> /* FILE type */
#include "config.h"

/*
** This file sketches out a potential API for a library form of the
** Fossil SCM. This API concerns itself only with the components of
** fossil which do not need user interaction or the display of UI
** components (including HTML and CLI output). It is intended only to
** model the core internals of fossil, off of which user-level
** applications could be built.
**
** This code is 100% hypothetical/potential, and does not represent
** any Official Version 2.0. All Fossil users are encouraged to
** participate in its development, but if you are reading this then
** you probably already knew that :). Rather than think of this as v2,
** i would prefer for people to think of it as a refactoring of v1, as
** the intention is for it to be completely compatible with v1
** repositories, just providing other means of accessing them.
**
** Conventions:
**
** - API docs (as you have probably already noticed), follow Fossil's
** comment style (see the '**' at the start of each line? That's what
** i mean) EXCEPT that each block MUST start with two or more
** asterisks, or '*!', or doxygen apparently doesn't understand it
** (http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html). When
** adding code snippets and whatnot to docs, please use doxygen
** conventions if it is not too much of an inconvenience. All public
** APIs must be documented with a useful amount of detail. If you hate
** documenting, let me know and i'll document it (it's what i do for
** fun).
**
** - API members have a fsl_ or FSL_ prefix (fossil_ seems too long?)
**
** - Structs and functions use lower_underscore_style()
**
** - Overall style should follow Fossil v1.x.
**
** - Structs and enums all get the optional typedef so that they do
** not need to be qualified with 'struct' resp. 'enum' when used.
**
** - Structs intended to be created on the stack are accompanied by a
** const instance named fsl_STRUCT_NAME_empty, and possibly by a macro
** named fsl_STRUCT_NAME_empty_m, both of which are
** "default-initialized" instances of that struct. This is superiour
** to using memset() for struct initialization because we can set
** arbitrary default values this way and all clients who
** copy-construct them are unaffected by many types of changes to the
** struct's signature (though they may need a recompile).
**
** - Function typedefs are named fsl_XXX_f. Implementations of such
** typedefs/interfaces are typically named fsl_XXX_f_SUFFIX(), where
** SUFFIX describes the implementation's specialization.
**
** - Typedefs for non-struct types tend to be named fsl_XXX_t and
** structs do not have a _t extensions.
**
** Notes about "my style" (this===stephan)... i tend to add a lot of
** little things which most people consider frivilous, mysterious,
** overkill, or YAGNI, e.g. the various fsl_XXX_empty_m macros. They
** are there because my experience has been that they're really
** useful. They are of course open to discussion (as is everything in
** here - none of this is holy!).
**
** Happy Hacking!
**
** ----- stephan@wanderinghorse.net / sgbeal@googlemail.com
*/

#include <stdarg.h> /* va_list */

#if defined(__cplusplus)
extern "C" {
#endif

  typedef struct fsl_outputer fsl_outputer;
  typedef struct fsl_cx fsl_cx;
  typedef struct fsl_allocator fsl_allocator;
  typedef struct fsl_db fsl_db;
  typedef struct fsl_stmt fsl_stmt;
  typedef struct fsl_buffer fsl_buffer;
  typedef struct fsl_error fsl_error;
  typedef struct fsl_state fsl_state;
  typedef struct fsl_cx_config fsl_cx_config;

  /**
   ** @struct fsl_cx
   **
   ** The main Fossil "context" type. This is the first argument to
   ** many Fossil library API routines, and holds all state related
   ** to a checkout and/or repository database.
   **
   ** This type will likely eventually be made opaque to client code -
   ** do not depend on any of its members/contents. Having it
   ** non-opaque also has advantages, though. We'll see. Binary
   ** compatibility concerns might force us to make it opaque.  But for
   ** now having it public simplifies testing and debugging.
   **
   ** An instance's lifetime looks like:
   **
   ** @code
   ** int rc;
   ** fsl_cx * f = NULL;
   ** rc = fsl_cx_init( &f, NULL );
   ** assert(!rc);
   ** rc = fsl_repo_open_db( f, "myrepo.fsl" );
   ** ...
   ** fsl_cx_finalize(f);
   ** @endcode
   */
  
  
  /**
   ** Most funcs return error codes from the fsl_rc_t enum.  None of
   ** these entries are (currently) guaranteed to have a specific value
   ** across Fossil versions except for FSL_RC_OK, which is guaranteed
   ** to always be 0.
   **
   ** The only reasons numbers are hard-coded to the values (or some of
   ** them) is to simplify debugging during development.
   */
  enum fsl_rc_t {
  /**
   ** The quintessential not-an-error value.
   */
  FSL_RC_OK = 0,
  /**
   ** Generic/unknown error.
   */
  FSL_RC_ERROR = 100,
  /**
   ** A placeholder return value for "not yet implemented" functions.
   */
  FSL_RC_NYI = 101,
  /**
   ** Out of memory. Indicates that a resource allocation request
   ** failed.
   */
  FSL_RC_OOM = 102,
  /*
  ** API misuse (invalid args)
  */
  FSL_RC_MISUSE = 103,
  /**
   ** Some range was violated (function argument, UTF character, etc.).
   */
  FSL_RC_RANGE = 104,
  /**
   ** Indicates that access to or locking of a resource was denied
   ** by some security mechanism or other.
   */
  FSL_RC_ACCESS = 105,
  /**
   ** Indicates an I/O error. Whether it was reading or writing is
   ** context-dependent.
   */
  FSL_RC_IO = 106,
  /**
   ** requested resource not found
   */
  FSL_RC_NOT_FOUND = 107,
  /**
   ** Immutable resource already exists
   */
  FSL_RC_ALREADY_EXISTS = 108,
  /**
   ** Data consistency problem
   */
  FSL_RC_CONSISTENCY = 109,

  /**
   ** Indicates that the requested repo needs to be rebuilt.
   */
  FSL_RC_REPO_NEEDS_REBUILD = 110,

  /**
   ** Indicates that the requested repo is not, in fact, a repo. Also
   ** used by some APIs to indicate that no repo has been opened yet.
   */
  FSL_RC_NOT_A_REPO = 111,
  /**
   ** Tried to load a too-old or too-new repo
   */
  FSL_RC_REPO_VERSION = 112,
  /**
   ** db-level error (e.g. statement prep failed)
   */
  FSL_RC_DB = 113,
  /**
   ** Used by some iteration routines to indicate that iteration should
   ** stop prematurely without an error.
   */
  FSL_RC_BREAK = 114,

  /**
   ** Indicates that a row has been fetched and the cursor may be used
   ** to access the current row state.
   */
  FSL_RC_STEP_ROW = 115,

  /**
   ** Indicates that the end of the result set has been reached and
   ** that there is no row data to process. This is also the result for
   ** non-fetching queries (INSERT and friends).
   */
  FSL_RC_STEP_DONE = 116,

  /**
   ** Indicates that a db-level error occurred during step() iteration.
   */
  FSL_RC_STEP_ERROR = 117,

  /**
   ** Indicates that some data type is incorrect.
   */
  FSL_RC_TYPE = 118,

  FSL_RC_NOT_A_CHECKOUT,

  /* ...more to come... */
  FSL_RC_TRAILING_COMMA_KLUDGE /* don't ask. hint: emacs macros */
  };
  typedef enum fsl_rc_t fsl_rc_t;

  /**
   ** Returns a "standard" string form for a fsl_rc_t code.  The string
   ** is primarily intended for debugging purposes.  The returned bytes
   ** are guaranteed to be static and NUL-terminated. They are not
   ** guaranteed to contain anything useful for any purposes other than
   ** debugging and tracking down problems.
   */
  char const * fsl_rc_cstr(int);

  /**
   ** Returns the value of FSL_LIBRARY_VERSION used to compile the
   ** library. If this value differs from the value the caller was
   ** compiled with, Chaos might ensue.
   **
   ** The API does not yet have any mechanism for determining
   ** compatibility between repository versions, but it also currently
   ** does no explicit checking to disallow incompatible versions.
   */
  char const * fsl_library_version();

  /**
   ** Returns true (non-0) if yourLibVersion compares lexically
   ** equal to FSL_LIBRARY_VERSION, else it returns false (0).
   */
  char fsl_library_version_matches(char const * yourLibVersion);
  
  /**
   ** Generic interface for streaming out data. Implementations must
   ** write n bytes from s to their destination channel and return 0 on
   ** success, non-0 on error (assumed to be a value from the fsl_rc_t
   ** enum). The state parameter is the implementation-specified
   ** output channel.
   */
  typedef int (*fsl_output_f)( void * state,
                               void const * src, fsl_size_t n );

  /**
   ** Generic interface for streaming in data. Implementations must
   ** read (at most) *n bytes from their input, copy it to dest, assign
   ** *n to the number of bytes actually read, return 0 on success, and
   ** return non-0 on error (assumed to be a value from the fsl_rc_t
   ** enum). When called, *n is the max length to read. On return, *n
   ** is the actual amount read. The state parameter is the
   ** implementation-specified input file/buffer/whatever channel.
   */
  typedef int (*fsl_input_f)( void * state, void * dest, fsl_size_t * n );

  /**
   ** A fsl_input_f() implementation which requires that state be
   ** a readable (FILE*) handle.
   */
  int fsl_input_FILE( void * state, void * dest, fsl_size_t * n );
  
  /**
   ** Generic interface for finalizing/freeing memory. Intended
   ** primarily for use as a destructor/finalizer for high-level
   ** structs. Implementations must semantically behave like free(mem),
   ** regardless of whether or not they actually free the memory. At
   ** the very least, they generally should clean up any memory owned by
   ** mem (e.g. db resources or buffers), even if they do not free() mem.
   ** some implementations assume that mem is stack-allocated
   ** and they only clean up resources owned by mem.
   **
   ** The state parameter is any state needed by the finalizer
   ** (e.g. a memory allocation context) and mem is the memory which is
   ** being finalized. 
   **
   ** The exact interpretaion of the state and mem are of course
   ** implementation-specific.
   */
  typedef void (*fsl_finalizer_f)( void * state, void * mem );

  /**
   ** Generic interface for memory finalizers.
   */
  struct fsl_finalizer {
    /**
     ** State to be passed as the first argument to f().
     */
    void * state;
    /**
     ** Finalizer function. Should be called like this->f( this->state, ... ).
     */
    fsl_finalizer_f f;
  };
  typedef struct fsl_finalizer fsl_finalizer;
  /** Empty-initialized fsl_finalizer instance. */
#define fsl_finalizer_empty_m {NULL,NULL}

  /**
   ** Generic list container type.
   **
   ** It is up to the APIs using this type to manage the entry count
   ** member and use fsl_list_reserve() to manage the "alloced"
   ** member.
   **
   ** @see fsl_list_reserve()
   **  @see fsl_list_append()
   */
  struct fsl_list {
    /**
     ** Array of entries. It contains this->alloced entries,
     ** this->count of which are "valid" (in use).
     */
    void ** list;
    /**
     ** Number of "used" entries in the list.
     */
    fsl_size_t count;
    /**
     ** Number of slots allocated in this->list. Use fsl_list_reserve()
     ** to modify this. Doing so might move the this->list pointer but
     ** the values it points to will stay stable.
     */
    fsl_size_t alloced;
  };
  typedef struct fsl_list fsl_list;
  /**
   ** Empty-initialized fsl_list object.
   */
#define fsl_list_empty_m { NULL, 0, 0 }
  /**
   ** Empty-initialized fsl_list object.
   */
  extern const fsl_list fsl_list_empty;

  
  /** Generic state-with-finalizer holder */
  struct fsl_state {
    /**
     ** Arbitrary context-dependent state.
     */
    void * state;
    /**
     ** Finalizer for this->state. If used, it should be called like:
     **
     ** @code
     ** this->finalize.f( this->finalize.state, this->state );
     ** @endcode
     **
     ** After which this->state must be treated as if it has been
     ** free(3)'d.
     */
    fsl_finalizer finalize;
  };
  /** Empty-initialized fsl_state instance. */
#define fsl_state_empty_m {NULL,fsl_finalizer_empty_m}

  /**
   ** Generic interface for flushing arbitrary output streams.  Must
   ** return 0 on success, non-0 on error, but the result code "should"
   ** (to avoid downstream confusion) be one of the fsl_rc_t
   ** values. When in doubt, return FSL_RC_IO on error.
   */
  typedef int (*fsl_flush_f)(void * state);

  /**
   ** A fsl_flush_f() impl which expects _FILE to be-a (FILE*), which
   ** this function passes the call on to fflush(). If fflush() returns
   ** 0, so does this function, else it returns FSL_RC_IO.
   */
  int fsl_flush_f_FILE(void * _FILE);

  /**
   ** A fsl_finalizer_f() impl which requires that mem be-a (FILE*).
   ** If mem is not (stdout, stderr) then this function fclose()es
   ** it, else it is a no-op. The state parameter is ignored.
   */
  void fsl_finalizer_f_FILE( void * state, void * mem );

  /**
   ** A fsl_output_f() impl which requires state to be-a (FILE*), which
   ** this function passes the call on to fwrite(). Returns 0 on
   ** success, FSL_RC_IO on error.
   */
  int fsl_output_f_FILE( void * state, void const * src, fsl_size_t n );

  /**
   ** A fsl_output_f() impl which requires state to be-a (fsl_buffer*),
   ** which this function passes to fsl_buffer_append(). Returns 0 on
   ** success, FSL_RC_OOM (probably) on error.
   */
  int fsl_output_f_buffer( void * state, void const * src, fsl_size_t n );

  /**
   ** fsl_finalizer_f() impl which requires that mem be-a
   ** (fsl_buffer*).  This function frees all memory associated with
   ** that buffer and zeroes out the structure, but does not free mem
   ** (because it is rare that fsl_buffers are created on the
   ** heap). The state parameter is ignored.
   */
  int fsl_finalizer_f_buffer( void * state, void * mem );

  /**
   ** An interface which encapsulates data for managing an output
   ** destination, primarily intended for use with fsl_output(). Why
   ** abstract it to this level? So that we can do interesting things
   ** like output to buffers, files, sockets, etc., using the core
   ** output mechanism. e.g. so script bindings can send their output
   ** to the same channel used by the library and other library
   ** clients.
   */
  struct fsl_outputer {
    /**
     ** Output channel.
     */
    fsl_output_f out;
    /**
     ** flush() implementation.
     */
    fsl_flush_f flush;
    /**
     ** State to be used when calling this->out(), namely:
     ** this->out( this->state.state, ... ).
     */
    fsl_state state;
  };
  /** Empty-initialized fsl_outputer instance. */
#define fsl_outputer_empty_m {NULL,NULL,fsl_state_empty_m}

  /**
   ** A fsl_outputer instance which is initialized to output to a
   ** (FILE*). To use it, this value then set the copy's state.state
   ** member to an opened-for-write (FILE*) handle. By default it will
   ** use stdout. Its finalizer (if called!) will fclose(3)
   ** self.state.state if self.state.state is not one of (stdout,
   ** stderr). To disable the closing behaviour (and not close the
   ** file), set self.state.finalize.f to NULL (but then be sure that
   ** the file handle outlives this object and to fclose(3) it when
   ** finished with it).
   */
  extern const fsl_outputer fsl_outputer_FILE;

  /**
   ** fsl_flush_f() implementation which requires state to be
   ** a writeable (FILE*) handle.
   */
  int fsl_flush_f_FILE(void * state);

  /**
   ** fsl_output_f() implementation which requires state to be
   ** a writeable (FILE*) handle.
   */
  int fsl_output_f_FILE( void * state, void const * src, fsl_size_t n );

  /**
   ** fsl_outputer initializer which uses fsl_flush_f_FILE(),
   ** fsl_output_f_FILE(), and fsl_finalizer_f_FILE().
   */
#define fsl_outputer_FILE_m {                   \
    fsl_output_f_FILE,                          \
      fsl_flush_f_FILE,                         \
      {/*state*/                                \
        NULL,                                   \
        {NULL,fsl_finalizer_f_FILE}             \
      }                                         \
  }
    
  /**
   **
   ** A general-purpose buffer buffer, analog to Fossil v1's Blob
   ** class. It is not called fsl_blob to avoid confusion with DB-side
   ** Blobs. Buffers are used extensively in fossil to do everything
   ** from reading files to compressing artifacts to creating
   ** dynamically-formatted strings. Because they are such a pervasive
   ** low-level type, and have such a simple structure, their members
   ** (unlike most other structs in this API) may be considered public
   ** and used directly by client code (as long as they do not mangle
   ** their state, e.g. by setting this->capacity smaller than
   ** this->used!).
   **
   ** @see fsl_buffer_reserve()
   ** @see fsl_buffer_append()
   ** @see fsl_buffer_appendf()
   */
  struct fsl_buffer {
    /**
     ** The raw memory owned by this buffer. It is this->capacity bytes
     ** long, of which this->used are considered "used" by the client.
     ** The difference beween (this->capacity - this->used) represents
     ** space the buffer has available for use before it will require
     ** another expansion/reallocation.
     */
    unsigned char * mem;
    /**
     ** Number of bytes allocated for this buffer.
     */
    fsl_size_t capacity;
    /**
     ** Number of "used" bytes in the buffer. This is generally
     ** interpreted as the virtual EOF (the one-past-the-end) position
     ** of this->mem.
     **
     ** Library routines which manipulate buffers must ensure that
     ** (this->used<=this->capacity) is always true, expanding the
     ** buffer if necessary. Much of the API assumes that precondition
     ** is always met, and any violation of it opens the code to
     ** undefined behaviour (which is okay, just don't ever break that
     ** precondition).
     */
    fsl_size_t used;
  };
  /** Empty-initialized fsl_buffer instance. */
#define fsl_buffer_empty_m {NULL,0U,0U}
  /** Empty-initialized fsl_buffer instance. */
  extern const fsl_buffer fsl_buffer_empty;
    
  /**
   ** A container for storing generic error state.
   */
  struct fsl_error {
    /**
     ** Error message text is stored in this->msg.mem.  The usable text
     ** part is this->msg.used bytes long.
     */
    fsl_buffer msg;
    /**
     ** Error code, generally assumed to be a fsl_rc_t value.
     */
    int code;
  };
  /** Empty-initialized fsl_error instance. */
#define fsl_error_empty_m {fsl_buffer_empty_m,0}
  /** Empty-initialized fsl_error instance. */
  extern const fsl_error fsl_error_empty;

  /**
   ** Populates err with the given code and formatted string, replacing
   ** any existing state. If fmt==NULL then fsl_rc_cstr(rc) is used to
   ** get the error string.
   **
   ** Returns code on success, some other non-0 code on error.
   **
   ** As a special case, if 0==code then fmt is ignored and the error
   ** state is cleared. This will not free any memory held by err but
   ** will re-set its string to start with a NUL byte, read for re-use
   ** later on.
   **
   ** As a special case, if code==FSL_RC_OOM then fmt is ignored
   ** to avoid a memory allocation (which would presumably fail).
   **
   ** @see fsl_error_get()
   ** @see fsl_error_clean()
   ** @see fsl_error_move()
   */
  int fsl_error_set( fsl_error * err, int code, char const * fmt,
                     ... );

  /** va_list counterpart to fsl_cx_err_set(). */
  int fsl_error_setv( fsl_error * err, int code, char const * fmt,
                      va_list args );

  /**
   ** Fetches the error state from err. If !err it returns
   ** FSL_RC_MISUSE without side-effects, else it returns err's current
   ** error code.
   **
   ** If str is not NULL then *str will point to the raw
   ** (NUL-terminated) error string (which might be empty or even
   ** NULL). The memory for the string is owned by err and may be
   ** invalidated by any calls which take err as a non-const parameter
   ** OR which might modify it indirectly through its container, so the
   ** client is required to copy it if it is needed for later on.
   **
   ** If len is not NULL then *len will hold the length of the string
   ** (in bytes).
   **
   ** @see fsl_error_set()
   ** @see fsl_error_clean()
   ** @see fsl_error_move()
   */
  int fsl_error_get( fsl_error * err, char const ** str, fsl_size_t * len );

  /**
   ** Frees up any resources owned by err and sets its error code to 0,
   ** but does not free err. This is harmless no-op if !err or if err
   ** holds no dynamically allocated no memory.
   **
   ** @see fsl_error_set()
   ** @see fsl_error_get()
   ** @see fsl_error_move()
   */
  void fsl_error_clean( fsl_error * err );

  /**
   ** Swaps the error state of the two given error objects and then
   ** sets lower->code to 0 and lower->msg.used = 0, effectively
   ** clearing the error state but not immediately deallocating the
   ** memory.
   **
   ** This is intended for "uplifting" an error from one context
   ** to a higher one.
   **
   ** Results are undefined if either parameter is NULL or either is
   ** not properly initialized. i.e. neither may refer to uninitialized
   ** memory. Copying fsl_error_empty at declaration-time is a simple
   ** way to ensure that instances are cleanly initialized.
   */
  void fsl_error_move( fsl_error * lower, fsl_error * higher );

  /**
   ** This code replaces the v1 concept of g.zMainDbType, and provides
   ** a type ID tag which can be applied to fsl_db instances so that
   ** the library can figure out which DB is which. This is primarily
   ** important for certain queries, which need to know whether they
   ** are accessing the repo or config db, for example.
   **
   ** All that said, i'm not yet fully convinced that a straight port
   ** of the v1 model is the best option for how we internally manage
   ** DBs, so this is subject to eventual change or removal.
   **
   */
  enum fsl_db_role_t {
  /**
   ** Sentinel "no role" value.
   */
  FSL_DB_ROLE_NONE = 0,
  /**
   ** Analog to v1's "configdb".
   */
  FSL_DB_ROLE_CONFIG = 0x01,
  /**
   ** Analog to v1's "repository".
   */
  FSL_DB_ROLE_REPO = 0x02,
  /**
   ** Analog to v1's "localdb".
   */
  FSL_DB_ROLE_CHECKOUT = 0x04,
  /**
   ** Analog to v1's "main", which is basically an alias for the
   ** first checkout db opened.
   */
  FSL_DB_ROLE_MAIN = 0x08
  };
  typedef enum fsl_db_role_t fsl_db_role_t;

  /**
   ** Placeholder for sqlite3/4 type. We currently use v3 but will
   ** almost certainly switch to v4 at some point. Before we can do
   ** that we need an upgrade/migration path.
   */
  typedef struct sqlite3 sqlite3;

  /**
   ** A level of indirection to hide the actual db driver
   ** implementation from the public API. Whether or not the API
   ** uses/will use sqlite3 or 4 is undecided at this point.  We
   ** currently use 3 because (A) it bootstraps development and
   ** testing by letting us use existing fossil repos for testing and
   ** (B) it reduces the number of potential problems when porting
   ** SQL-heavy code from the v1 tree.
   */
  typedef sqlite3 fsl_dbh_t;

  /**
   ** Db handle wrapper/helper.
   */
  struct fsl_db {
    /**
     ** Fossil Context on whose behalf this instance is operating.
     */
    fsl_cx * f;
    /**
     ** Underlying db driver handle.
     */
    fsl_dbh_t * dbh;

    /**
     ** Holds error state from the underlying driver.  fsl_db and
     ** fsl_stmt operations which fail at the driver level "should"
     ** update this state to include error info from the driver.
     ** fsl_cx APIs which fail at the DB level then uplift this (using
     ** fsl_error_move()) so that they can pass it on to the caller.
     */
    fsl_error error;

    /**
     ** Holds the file name used when opening this db.
     */
    fsl_buffer filename;

    /**
     ** Holds the database name for use in creating queries.
     ** Might or might not be set/needed, depending on
     ** the context.
     */
    fsl_buffer name;

    
    /**
     ** Describes what role this db connection plays in
     ** fossil (if any). We may or may not still need this.
     */
    int role;
    
    /**
     ** Debugging/test counter. Closing a db with opened statements
     ** might assert() or trigger debug output when the db is closed.
     */
    int openStatementCount;

    /**
     ** A marker which tells fsl_db_close() whether or not this
     ** API allocated this instance (in which case fsl_db_close()
     ** will fsl_free() it) or not (in which case it does not free()
     ** it).
     */
    void const * allocStamp;
  };
  /** Empty-initialized fsl_db instance. */
#define fsl_db_empty_m {                        \
    NULL/*f*/,                                  \
      NULL/*dbh*/,                              \
      fsl_error_empty_m /*error*/,              \
      fsl_buffer_empty_m/*filename*/,           \
      fsl_buffer_empty_m/*name*/,               \
      FSL_DB_ROLE_NONE,                         \
      0/*openStatementCount*/,                  \
      NULL/*allocStamp*/                        \
      }

  /** Empty-initialized fsl_db instance. */
  extern const fsl_db fsl_db_empty;

  /**
   ** If db is not NULL then this function returns its name (the one
   ** used to open it). The bytes are valid until the db connection is
   ** closed. If len is not NULL then *len is (on success) assigned to
   ** the length of the returned string, in bytes.  The string is
   ** NUL-terminated, so fetching the length (by passing a non-NULL 2nd
   ** parameter) is optional.
   **
   ** Returns NULL if !f or f has no checkout opened.
   */
  char const * fsl_db_filename(fsl_db const * db, fsl_size_t * len);


  /**
   ** Generic memory alloc/free/realloc interface().
   **
   ** Implementations must behave as follows:
   **
   ** - If 0==n then semantically behave like free(3) and return
   ** NULL.
   **
   ** - If 0!=n and !mem then semantically behave like malloc(3).
   **
   ** - If 0!=n and NULL!=mem then semantically behave like
   ** realloc(3). Note that realloc specifies: "If n was equal to 0,
   ** either NULL or a pointer suitable to be passed to free() is
   ** returned." Which is kind of useless, and thus implementations
   ** MUST return NULL when n==0.
   */
  typedef void *(*fsl_realloc_f)(void * state, void * mem, fsl_size_t n);

  /**
   ** Holds an allocator function and its related state.
   */
  struct fsl_allocator {
    /**
     ** Base allocator function. It must be passed this->state
     ** as its first parameter.
     */
    fsl_realloc_f f;
    /**
     ** State intended to be passed as the first parameter to
     ** this->f().
     */
    void * state;
  };

  /** Empty-initialized fsl_allocator instance. */
#define fsl_allocator_empty_m {NULL,NULL}


  /**
   ** A fsl_realloc_f() implementation which uses the standard
   ** malloc()/free()/realloc(). The state parameter is ignored.
   */
  void * fsl_realloc_f_stdalloc(void * state, void * mem, fsl_size_t n);

  /**
   ** Library-wide allocator. If modified by the client then it must be
   ** changed before the library allocates any resources. The default
   ** uses the C-standard de/re/allocators.
   */
  extern fsl_allocator fsl_memory_allocator;
  /**
   ** Placeholder for external sqlite3_stmt.
   */
  typedef struct sqlite3_stmt sqlite3_stmt;
  typedef sqlite3_stmt fsl_stmt_t;
  /**
   ** Represents a prepared statement handle.
   ** Intended usage:
   **
   ** @code
   ** fsl_stmt st = fsl_stmt_empty;
   ** int rc = fsl_stmt_prepare( f, &st, "..." );
   ** if(rc){
   **   assert(!st.stmt);
   **   // Error! Use fsl_cx_err_get() to find out if
   **   // the db driver told us something helpful.
   ** }else{
   **   // ...use st and eventually finalize it:
   **   fsl_stmt_finalize( &st );
   ** }
   ** @endcode
   */
  struct fsl_stmt {
    /**
     ** The db which prepared this statement.
     */
    fsl_db * db;
    /**
     ** Underlying db driver-level statement handle.
     */
    fsl_stmt_t * stmt;
    /**
     ** SQL used for preparing this statement.
     */
    fsl_buffer sql;
    /**
     ** Number of result columns in this statement.
     */
    int colCount;
    /**
     ** Number of bound parameter indexes in this statement.
     */
    int paramCount;

    /**
     ** A marker which tells fsl_stmt_finalize() whether or not this
     ** API allocated this instance (in which case fsl_stmt_finalize()
     ** will fsl_free() it) or not (in which case it does not free()
     ** it).
     */
    void const * allocStamp;
  };
  /**
   ** Empty-initialized fsl_stmt instance, intended for
   ** copy-constructing.
   */
  extern const fsl_stmt fsl_stmt_empty;

  /**
   ** Prepares an SQL statement for execution. On success it returns 0,
   ** populates tgt with the statement's state, and the caller is
   ** obligated to eventually pass tgt to fsl_stmt_finalize().
   **
   ** On error non-0 is returned and tgt is not modified. If
   ** preparation of the statement fails at the db level then FSL_RC_DB
   ** is returned f's error state (fsl_cx_err_get()) will contain more
   ** details about the problem.
   **
   ** sql and the following arguments are applied as printf-style formatting,
   ** and any formatting options supported by fsl_appendf() may be used
   ** here. 
   ** 
   */
  int fsl_stmt_prepare( fsl_db *db, fsl_stmt * tgt, char const * sql, ... );

  /**
   ** va_list counterpart of fsl_stmt_prepare().
   */
  int fsl_stmt_preparev( fsl_db *db, fsl_stmt * tgt, char const * sql, va_list args );

  /**
   ** Frees memory associated with stmt but does not free stmt unless
   ** it was allocated by fsl_stmt_malloc(). These objects are normally
   ** stack-allocated. Returns FSL_RC_MISUSE if !stmt or it has already
   ** been finalized (but was not freed).
   */
  int fsl_stmt_finalize( fsl_stmt * stmt );

  /**
   ** "Steps" the given SQL cursor one time and returns one of the
   ** following: FSL_RC_STEP_ROW, FSL_RC_STEP_DONE, FSL_RC_STEP_ERROR.
   ** On a db error this will update the underlying the underlying db's
   ** error state.
   **
   ** Returns FSL_RC_MISUSE if !stmt or stmt has not been prepared.
   */
  int fsl_stmt_step( fsl_stmt * stmt );

  /**
   ** A callback for use with fsl_stmt_each(). It will be called one
   ** time for each row fetched, passed the statement object and the
   ** state parameter passed as the 3rd parameter to fsl_stmt_each().
   ** If it returns non-0 then iteration stops and that code is
   ** returned UNLESS it returns FSL_RC_BREAK, in which case
   ** fsl_stmt_each() stops iteration and returns 0.
   **
   ** It is strictly illegal for a callback to step() the statement.
   ** It must only read the current column data (or similar metatdata,
   ** e.g. column names) from the statement.
   */
  typedef int (*fsl_stmt_each_f)( void * state, fsl_stmt * stmt );

  /**
   ** Calls the given callback one time for each result row in the
   ** given statement. It applies no meaning to the callbackState
   ** parameter - that is passed as-is to the callback. See
   ** fsl_stmt_each_f() for the semantics of the callback.
   **
   ** Returns 0 on success. Returns FSL_RC_MISUSE if !stmt or
   ** !callback.
   */
  int fsl_stmt_each( fsl_stmt * stmt, fsl_stmt_each_f callback,
                     void * callbackState );

  /**
   ** Resets the given statement, analog to sqlite3_reset(). Should be
   ** called one time between step() iterations when running multiple
   ** INSERTS, UPDATES, etc. via the same statement.
   **
   ** Returns 0 on success.
   */
  int fsl_stmt_reset( fsl_stmt * stmt );

  /**
   ** Returns the name of the given 0-based result column index, or
   ** NULL if !stmt, stmt is not prepared, or index is out out of
   ** range. The returned bytes are owned by the statement object and
   ** may be invalidated shortly after this is called, so the caller
   ** must copy the returned value if it needs to have any useful
   ** lifetime guarantees. It's a bit more complicated than this, but
   ** assume that any API calls involving the statement handle might
   ** invalidate the colum name bytes.
   **
   ** The API guarantees that the returned value is either NULL or
   ** NUL-terminated.
   */
  char const * fsl_stmt_col_name(fsl_stmt * stmt, int index);
  
  /**
   ** Returns the result column count for the given statement, or -1 if
   ** !stmt or it has not been prepared. Note that this value is cached
   ** when the statement is created. Note that non-fetching queries
   ** (e.g. INSERT and UPDATE) have a column count of 0. Some non-SELECT
   ** constructs, e.g. PRAGMA table_info(tname), behave like SELECT
   ** and have a positive column count.
   */
  int fsl_stmt_col_count( fsl_stmt const * stmt );

  /**
   ** Returns the bound parameter count for the given statement, or -1
   ** if !stmt or it has not been prepared. Note that this value is
   ** cached when the statement is created.
   */
  int fsl_stmt_param_count( fsl_stmt const * stmt );

  /**
   ** Binds NULL to the given 1-based parameter index.  Returns 0 on
   ** succcess. Sets the DB's error state on error.
   */
  int fsl_stmt_bind_null( fsl_stmt * stmt, int index );

  /**
   ** Binds v to the given 1-based parameter index.  Returns 0 on
   ** succcess. Sets the DB's error state on error.
   */
  int fsl_stmt_bind_int32( fsl_stmt * stmt, int index, fsl_int32_t v );

  /**
   ** Binds v to the given 1-based parameter index.  Returns 0 on
   ** succcess. Sets the DB's error state on error.
   */
  int fsl_stmt_bind_int64( fsl_stmt * stmt, int index, fsl_int64_t v );

  /**
   ** Binds v to the given 1-based parameter index.  Returns 0 on
   ** succcess. Sets the Fossil context's error state on error.
   */
  int fsl_stmt_bind_double( fsl_stmt * stmt, int index, fsl_double_t v );

  /**
   ** Binds the first n bytes of v as text to the given 1-based bound
   ** parameter column in the given statement. If makeCopy is true then
   ** the binding makes an copy of the data. Set makeCopy to false ONLY
   ** if you KNOW that the bytes will outlive the binding.
   **
   ** Returns 0 on success. On error stmt's underlying db's error state
   ** is updated, hopefully with a useful error message.
   */
  int fsl_stmt_bind_text( fsl_stmt * stmt, int index,
                          char const * v, fsl_int_t n,
                          char makeCopy );
  /**
   ** Binds the first n bytes of v as a blob to the given 1-based bound
   ** parameter column in the given statement. See fsl_stmt_bind_text()
   ** for the semantics of the makeCopy parameter and return value.
   */
  int fsl_stmt_bind_blob( fsl_stmt * stmt, int index,
                          void const * v, fsl_int_t len,
                          char makeCopy );

  /**
   ** Gets an integer value from the given 0-based result set column,
   ** assigns *v to that value, and returns 0 on success.
   **
   ** Returns FSL_RC_RANGE if index is out of range for stmt.
   */
  int fsl_stmt_get_int32( fsl_stmt * stmt, int index, fsl_int32_t * v );

  /**
   ** Gets an integer value from the given 0-based result set column,
   ** assigns *v to that value, and returns 0 on success.
   **
   ** Returns FSL_RC_RANGE if index is out of range for stmt.
   */
  int fsl_stmt_get_int64( fsl_stmt * stmt, int index, fsl_int64_t * v );

  /**
   ** Gets double value from the given 0-based result set column,
   ** assigns *v to that value, and returns 0 on success.
   **
   ** Returns FSL_RC_RANGE if index is out of range for stmt.
   */
  int fsl_stmt_get_double( fsl_stmt * stmt, int index, fsl_double_t * v );

  /**
   ** Gets a string value from the given 0-based result set column,
   ** assigns *out (if out is not NULL) to that value, assigns *outLen
   ** (if outLen is not NULL) to *out's length, and returns 0 on
   ** success. Ownership of the string memory is passed to the caller,
   ** who must eventually pass it to fsl_free() to free it.
   **
   ** Returns FSL_RC_RANGE if index is out of range for stmt.
   */
  int fsl_stmt_get_text( fsl_stmt * stmt, int index, char const **out, fsl_int_t * outLen );

  /**
   ** The Blob counterpart of fsl_stmt_get_text(). Identical to that
   ** function except that its output result (3rd paramter) type
   ** differs, and it fetches the data as a raw blob, without any sort
   ** of string interpretation.
   **
   ** Returns FSL_RC_RANGE if index is out of range for stmt.
   */
  int fsl_stmt_get_blob( fsl_stmt * stmt, int index, void const **out, fsl_int_t * outLen );

  /**
   ** Executes multiple SQL statements, ignoring any results they might
   ** collect. Returns 0 on success, non-0 on error.  On error
   ** db->error might be updated to report the problem.
   */
  int fsl_db_exec_multi( fsl_db * db, const char * sql, ...);

  /**
   ** va_list counterpart of db_exec_multi().
   */
  int fsl_db_exec_multiv( fsl_db * db, const char * sql, va_list args);

  /**
   ** Executes a single SQL statement, skipping over any results
   ** it may have. Returns 0 on success. On error db's error state
   ** may be updated.
   */
  int fsl_db_exec( fsl_db * db, char const * sql, ... );

  /**
   ** va_list counterpart of fs_db_exec().
   */
  int fsl_db_execv( fsl_db * db, char const * sql, va_list args );

  /**
   ** UNTESTED.
   **
   ** Runs a fetch-style SQL query against DB and returns the first
   ** column of the first result row via *rv. If the query returns no
   ** rows, *rv is not modified. The intention is that the caller sets
   ** *rv to his preferred default (or sentinel) value before calling
   ** this.
   **
   ** The format string (the sql parameter) accepts all formatting
   ** options supported by fsl_appendf().
   **
   ** Returns 0 on success. On error db's error state is updated and
   ** *rv is not modified.
   **
   ** Returns FSL_RC_MISUSE without side effects if !db, !rv, !sql,
   ** or !*sql.
   */
  int fsl_db_get_int32( fsl_db * db, fsl_int32_t * rv,
                        char const * sql, ... );
  /**
   ** va_list counterpart of fsl_db_get_int32().
   */
  int fsl_db_get_int32v( fsl_db * db, fsl_int32_t * rv,
                         char const * sql, va_list args);

  /**
   ** UNTESTED.
   **
   ** The int64 counterpart of fsl_db_get_int32().
   */
  int fsl_db_get_int64( fsl_db * db, fsl_int64_t * rv,
                        char const * sql, ... );

  /**
   ** va_list counterpart of fsl_db_get_int64().
   */
  int fsl_db_get_int64v( fsl_db * db, fsl_int64_t * rv,
                         char const * sql, va_list args);

  /**
   ** UNTESTED.
   **
   ** The double counterpart of fsl_db_get_int32().
   */
  int fsl_db_get_double( fsl_db * db, fsl_double_t * rv,
                         char const * sql, ... );

  /**
   ** va_list counterpart of fsl_db_get_double().
   */
  int fsl_db_get_doublev( fsl_db * db, fsl_double_t * rv,
                          char const * sql, va_list args);
  
  /**
   ** UNTESTED.
   **
   ** The String counterpart of fsl_db_get_int32(). On success *rv will
   ** be set to a dynamically allocated string copied from the first
   ** column of the first result row. If rvLen is not NULL then *rvLen
   ** will be assigned the byte length of that string. If no row is
   ** found, *rv is not modified.
   */
  int fsl_db_get_text( fsl_db * db, char ** rv, fsl_size_t * rvLen,
                       char const * sql, ... );

  /**
   ** va_list counterpart of fsl_db_get_text().
   */
  int fsl_db_get_textv( fsl_db * db, char ** rv, fsl_size_t * rvLen,
                        char const * sql, va_list args );

  /**
   ** UNTESTED.
   **
   ** The Blob counterpart of fsl_db_get_text(). Identical to that
   ** function except that its output result (2nd paramter) type
   ** differs, and it fetches the data as a raw blob, without any sort
   ** of string interpretation.
   */
  int fsl_db_get_blob( fsl_db * db, void ** rv, fsl_size_t * stmtLen,
                       char const * sql, ... );

  /**
   ** va_list counterpart of fsl_db_get_blob().
   */
  int fsl_db_get_blobv( fsl_db * db, void ** rv, fsl_size_t * stmtLen,
                        char const * sql, va_list args );

  /**
   ** UNTESTED.
   **
   ** Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes
   ** its result to tgt, overwriting any existing memory it might hold.
   **
   ** If asBlob is true then the underlying BLOB API is used to
   ** populate the buffer, else the underlying STRING/TEXT API is used.
   */
  int fsl_db_get_buffer( fsl_db * db, fsl_buffer * tgt,
                         char asBlob,
                         char const * sql, ... );

  /**
   ** va_list counterpart of fsl_db_get_buffer().
   */
  int fsl_db_get_bufferv( fsl_db * db, fsl_buffer * tgt,
                          char asBlob,
                          char const * sql, va_list args );

  /**
   ** Expects sql to be a SELECT-style query which (potentially)
   ** returns a result set. For each row in the set callback() is
   ** called, as described for fsl_stmt_each(). Returns 0 on success.
   **
   ** Returns FSL_RC_MISUSE if !db, db is not opened, !callback,
   ** !sql, or !*sql.
   */
  int fsl_db_each( fsl_db * db, fsl_stmt_each_f callback,
                   void * callbackState, char const * sql, ... );

  /**
   ** va_list counterpart to fsl_db_each().
   */
  int fsl_db_eachv( fsl_db * db, fsl_stmt_each_f callback,
                    void * callbackState, char const * sql, va_list args );

  /**
   ** A part of the configuration used by fsl_cx_init() and friends.
   **
   */
  struct fsl_cx_config {
    /**
     ** If true, all SQL which goes through the fossil engine
     ** will be traced to the fsl_output()-configured channel.
     */
    char traceSql;
    /**
     ** If true, the print() SQL function will output its output to the
     ** fsl_output()-configured channel, else it is a no-op.
     */
    char sqlPrint;
  };
  /**
   ** fsl_cx_config instance initialized with useful defaults.
   */
#define fsl_cx_config_empty_m {                 \
    0/*traceSql*/,                              \
      0/*sqlPrint*/                             \
      }
  extern const fsl_cx_config fsl_cx_config_empty;
  /**
     Parameters for fsl_cx_init().
  */
  struct fsl_init_param {
    /**
       The output channel for the Fossil instance.
    */
    fsl_outputer output;
    /** ... what else? Config db file name? Default repo file to open? 
        We have a chicken/egg scenario with some bits,
        e.g. fsl_buffer_reserve() requires a fsl_cx, so we can't use
        buffers to create file name strings until after the ctx is
        initialized. Or we need extra buffer APIs which take a
        fsl_allocator instead of a fsl_cx parameter. Or we need to set
        the allocator as part of the buffer class. That would not be
        bad but would be memory-expensive - buffers are showing up
        everywhere.
    */
    fsl_cx_config config;
  };
  typedef struct fsl_init_param fsl_init_param;

  /** Empty-initialized fsl_init_param instance. */
#define fsl_init_param_empty_m {fsl_outputer_empty_m, fsl_cx_config_empty_m}
  /**
   ** fsl_init_param instance initialized to use stdout for output and
   ** the standard system memory allocator.
   */
#define fsl_init_param_default_m {fsl_outputer_FILE_m, fsl_cx_config_empty_m}

  /** Empty-initialized fsl_init_param instance. */
  extern const fsl_init_param fsl_init_param_empty;

  /**
   ** fsl_init_param instance initialized to use stdout for output and
   ** the standard system memory allocator. Used as the default when
   ** fsl_cx_init() is passed a NULL value for this parameter.
   */
  extern const fsl_init_param fsl_init_param_default;

  /**
   ** Initializes a fsl_cx instance. tgt must be a pointer to NULL,
   ** e.g.:
   **
   ** @code
   ** fsl_cxt * f = NULL;
   ** int rc = fsl_cx_init( &f, NULL );
   ** @endcode
   **
   ** If the second parameter is NULL then default implementations
   ** are used for the context's output and allocation routines.  If
   ** it is not NULL then param->allocator and param->output must be
   ** initialized properly before calling this function. The contents
   ** of param are bitwise copied by this function and ownership is
   ** transfered to *tgt in all cases except one:
   **
   ** If this function cannot allocate a new instance it immediately
   ** returns FSL_RC_OOM and does not modify *tgt. In this case,
   ** ownership of param's contents is not changed. On any other
   ** error, ownership of param's contents are transfered to *tgt and
   ** the client is responsible for passing *tgt ot
   ** fsl_cxt_finalize() when he is done with it. Note that (like in
   ** sqlite3), *tgt may be valid memory even if this function fails,
   ** and the caller must pass it to fsl_cx_finalize() whether or
   ** not this function succeeds unless it fails at the initial OOM
   ** (which the client can check by seeing if (*tgt) is NULL, but
   ** only if he set it to NULL before calling this).
   **
   ** Returns 0 on success, FSL_RC_OOM on an allocation error,
   ** FSL_RC_MISUSE if (!tgt).
   */
  int fsl_cx_init( fsl_cx ** tgt, fsl_init_param * param );

  /**
   ** Frees all memory associated with f, which must have been
   ** initialized using fsl_cx_init() (or equivalent).
   **
   ** Returns FSL_RC_MISUSE if !f, else 0.
   */
  int fsl_cx_finalize( fsl_cx * f );

  /**
   ** Sets the Fossil error state to the given error code and
   ** fsl_appendf()-style format string/arguments. On success it
   ** returns the code parameter. It does not return 0 unless code is
   ** 0, and if it returns a value other than code then something went
   ** seriously wrong (e.g. allocation error: FSL_RC_OOM) or the
   ** arguments were invalid: !f results in FSL_RC_MISUSE.
   **
   ** If !fmt then fsl_rc_cstr(code) is used to create the
   ** error string.
   **
   ** As a special case, if code is FSL_RC_OOM, no error string is
   ** allocated (because it would likely fail, assuming the OOM
   ** is real).
   **
   ** As a special case, if code is 0 (the non-error value) then fmt is
   ** ignored and any error state is cleared.
   */
  int fsl_cx_err_set( fsl_cx * f, int code, char const * fmt, ... );

  /**
   ** va_list counterpart to fsl_cx_err_set().
   */
  int fsl_cx_err_setv( fsl_cx * f, int code, char const * fmt,
                       va_list args );

  /**
   ** Fetches the error state from f. See fsl_error_get() for the semantics
   ** of the parameters and return value.
   */
  int fsl_cx_err_get( fsl_cx * f, char const ** str, fsl_size_t * len );

  /**
   ** Roles equate to permissions in Fossil v1. Here we implement them
   ** as a bitmask and hope we never need more than 31 of them.
   */
  enum fsl_roles_t {
  FSL_ROLE_GUEST = 0,
  FSL_ROLE_ANONYMOUS = 1,
  FSL_ROLE_ADMIN = 1 << 1,
  FSL_ROLE_SETUP  = 1 << 2,
  FSL_ROLE_READ = 1 << 3,
  FSL_ROLE_COMMIT = 1 << 4,
  FSL_ROLE_ALL = 0x7FFFFFFF
  /* unsigned 32-bit+ enums are not portable :/ */
  };
  typedef enum fsl_roles_t fsl_roles_t;

  /**
   ** Holds type ID tags for the db-level types which have a
   ** fsl_db_record-derived class.
   */
  enum fsl_db_type_t {
  FSL_TYPE_INVALID = 0,
  FSL_TYPE_USER = 1,
  FSL_TYPE_TAG = 2
  /* ... */
  };
  typedef enum fsl_db_type_t fsl_db_type_t;

  /**
   ** Base type for db record classes. Each db record subclass must
   ** have a fsl_db_record instance as its first struct member (for
   ** C-level casting reasons).
   */
  struct fsl_db_record {
    fsl_db_type_t typeId; /* const? */
    fsl_id_t dbId;
    /* maybe put mtime field here b/c it's used by several classes */

    /**
     ** For creating linked lists of records, for algorithms which
     ** want to return multiple records. Its concrete type is
     ** determined by this->typeId.
     */
    void * next;
  };
  typedef struct fsl_db_record fsl_db_record;
  extern const fsl_db_record fsl_db_record_empty;

  struct fsl_user {
    fsl_db_record base;
    fsl_buffer name;
    fsl_int32_t roles; /* bitmask of fsl_roles_t values */
    fsl_time_t mtime; /* ??? */
  };
  typedef struct fsl_user fsl_user;
  extern const fsl_user fsl_user_empty;
    
  struct fsl_tag {
    fsl_db_record base;
    fsl_buffer key;
    fsl_buffer value;
  };
  typedef struct fsl_tag fsl_tag;
  extern const fsl_tag fsl_tag_empty;

  /**
   ** Represents a db blob, not fossil's Blob class.
   */
  struct fsl_blob {
    fsl_db_record base;
    fsl_time_t mtime;
#if 0
    /* "raw" SHA1 digest */
    unsigned char digest[20]; 
    /* OR... */
#else
    /**
     ** 40-byte SHA1 plus terminating NUL.
     */
    char sha1[41];
#endif
    /* the latter is probably more useful/easier */
  };
  typedef struct fsl_blob fsl_blob;
#if 0
  /**
   ** Elided: abstractions   suitable for  adding an ORM-like  layer.
   ** That would   be taking it  too far,  i  think. If,  however, we
   ** decide   to   abstract away  the    DB  completely then  a CRUD
   ** abstraction API would   indeed make sense.  Except  that fossil
   ** hasn't much  need for  the  'D'  in CRUD,   so  it'd be  a  CRU
   ** abstraction API.
   */
#endif


  /**
   ** Semantically behaves like malloc(3), but may introduce instrumentation,
   ** error checking, or similar.
   */
  void * fsl_malloc( fsl_size_t n );

  /**
   ** Semantically behaves like free(3), but may introduce instrumentation,
   ** error checking, or similar.
   */
  void fsl_free( void * mem );

  /**
   ** Behaves like realloc(3). Clarifications on the behaviour (because
   ** the standard has one case of unfortunate wording involving what
   ** it returns when n==0):
   **
   ** - If passed (NULL, n>0) then it semantically behaves like
   ** fsl_malloc(f, n).
   **
   ** - If 0==n then it semantically behaves like free(2) and returns
   ** NULL (clarifying the aforementioned wording problem).
   **
   ** - If passed (non-NULL, n) then it semantically behaves like
   ** realloc(mem,n).
   **
   ** Returns NULL if !f.
   ** 
   */
  void * fsl_realloc( void * mem, fsl_size_t n );

  /**
   ** Reserves at least n bytes of capacity in buf. Returns 0 on
   ** success, FSL_RC_OOM if allocation fails, FSL_RC_MISUSE if !buf.
   **
   ** This does not change buf->used, nor will it shrink the buffer
   ** (reduce buf->capacity) unless n is 0, in which case it
   ** immediately frees buf->mem and sets buf->capacity and buf->used
   ** to 0.
   */
  int fsl_buffer_reserve( fsl_buffer * buf, fsl_size_t n );

  /**
   ** Resets buf->used to 0 and sets buf->mem[0] (if buf->mem is not
   ** NULL) to 0. Does not (de)allocate memory, only changes the
   ** logical "used" size of the buffer. Returns 0 on success,
   ** FSL_RC_MISUSE if !buf.
   **
   ** Achtung for v1 porters: this function's semantics are much
   ** different from the v1 blob_reset(). To get those semantics,
   ** use fsl_buffer_reserve(buf, 0).
   */
  int fsl_buffer_reset( fsl_buffer * buf );

  /**
   ** Similar to fsl_buffer_reserve() except that...
   **
   ** - It does not free all memory when n==0. Instead it essentially
   ** makes the memory a length-0, NUL-terminated string.
   **
   ** - It will try to shrink (realloc) buf's memory if (n<buf->capacity).
   **
   ** - It sets buf->capacity to (n+1) and buf->used to n. This routine
   ** allocates one extra byte to ensure that buf is always
   ** NUL-terminated.
   **
   ** - On success it always NUL-terminates the buffer at
   ** offset buf->used.
   **
   ** Returns 0 on success, FSL_RC_MISUSE if !buf, FSL_RC_OOM if
   ** (re)allocation fails.
   */
  int fsl_buffer_resize( fsl_buffer * buf, fsl_size_t n );

  /**
   ** Swaps the contents of the left and right arguments. Results are
   ** undefined if either argument is NULL or points to uninitialized
   ** memory.
   */
  void fsl_buffer_swap( fsl_buffer * left, fsl_buffer * right );

  /**
   ** Similar fsl_buffer_swap() but it also optionally frees one of
   ** the buffer's memories after swapping them. If clearWhich is
   ** negative then the left buffer (1st arg) is cleared _after_
   ** swapping (i.e., the NEW left hand side gets cleared). If
   ** clearWhich is greater than 0 then the right buffer (2nd arg) is
   ** cleared _after_ swapping (i.e. the NEW right hand side gets
   ** cleared). If clearWhich is 0, this function behaves identically
   ** to fsl_buffer_swap().
   */
  void fsl_buffer_swap_free( fsl_buffer * left, fsl_buffer * right, char clearWhich );  
  /**
   **
   ** Appends the first n bytes of src to b, expanding b as
   ** necessary. If n is less than 0 then the equivalent of
   ** fsl_strlen((char const*)src) is used to calculate the length.
   **
   ** Returns 0 on success, FSL_RC_MISUSE if !f, !b, or !src,
   ** FSL_RC_OOM if allocation of memory fails. It returns 0 without
   ** side-effects if 0==n or if ((n<0) and !*src).
   **
   ** If this function appends anything, it guarantees that it
   ** NUL-terminates the buffer (but that the NUL terminator is not
   ** counted in b->used).
   */
  int fsl_buffer_append( fsl_buffer * b,
                         void const * src, fsl_int_t n );

  /**
   ** Uses fsl_appendf() to append formatted output to the given buffer.
   ** Returns 0 on success, FSL_RC_MISUSE if !f or !dest,
   */
  int fsl_buffer_appendf( fsl_buffer * dest,
                          char const * fmt, ... );

  /** va_list counterpart to fsl_buffer_appendfv(). */
  int fsl_buffer_appendfv( fsl_buffer * dest,
                           char const * fmt, va_list args );

  /**
   ** Compresses the first pIn->used bytes of pIn to pOut. It is ok for
   ** pIn and pOut to be the same blob.
   **
   ** pOut must either be the same as pIn or else cleanly
   ** initialized/empty.
   **
   ** Results are undefined if any argument is NULL.
   **
   ** Returns 0 on success, FSL_RC_OOM on allocation error, and FSL_RC_ERROR
   ** if the lower-level compression routines fail.
   **
   ** TODO: add a streaming variant which takes the input from a
   ** fsl_input_f() and pushes the output to a fsl_output_f(). The code
   ** exists in the libwhio source tree already.
   **
   ** TODO: if pOut!=pIn1 then re-use pOut's memory, if it has any.
   */
  int fsl_buffer_compress(fsl_buffer const *pIn, fsl_buffer *pOut);

  /**
   ** Compress the concatenation of a blobs pIn1 and pIn2 into pOut.
   **
   ** pOut must be either uninitialized or must be the same as either pIn1 or
   ** pIn2.
   **
   ** Results are undefined if any argument is NULL.
   **
   ** Returns 0 on success, FSL_RC_OOM on allocation error, and FSL_RC_ERROR
   ** if the lower-level compression routines fail.
   **
   ** TODO: if pOut!=(pIn1 or pIn2) then re-use its memory, if it has any.
   */
  int fsl_buffer_compress2(fsl_buffer *pIn1,
                           fsl_buffer *pIn2, fsl_buffer *pOut);

  /**
   ** Uncompress buffer pIn and store the result in pOut. It is ok for
   ** pIn and pOut to be the same buffer. Returns 0 on success. On
   ** error pOut is not modified.
   **
   ** pOut must be either cleanly initialized/empty or the same as pIn.
   **
   ** Results are undefined if any argument is NULL.
   **
   ** Returns 0 on success, FSL_RC_OOM on allocation error, and
   ** FSL_RC_ERROR if the lower-level decompression routines fail.
   **
   ** TODO: add a streaming variant which takes the input from a
   ** fsl_input_f() and pushes the output to a fsl_output_f(). The code
   ** exists in the libwhio source tree already.
   **
   ** TODO: if pOut!=(pIn1 or pIn2) then re-use its memory, if it has any.
   */
  int fsl_buffer_uncompress(fsl_buffer const *pIn, fsl_buffer *pOut);

  /**
   ** Returns true if this function believes that mem (which must be
   ** at least len bytes of valid memory long) appears to have been
   ** compressed by fsl_buffer_compress() or equivalent. This is not
   ** a 100% reliable check - it could have false positives on certain
   ** inputs, but it is thought to be unlikely.
   **
   ** Returns 0 if mem is NULL.
   */
  char fsl_data_is_compressed(unsigned char const * mem, fsl_size_t len);

  /**
   ** Equivalent to fsl_data_is_compressed(buf->mem, buf->used).
   */
  char fsl_buffer_is_compressed(fsl_buffer const * buf);

  /**
   ** Equivalent to ((char const *)b->mem), but returns NULL if !b. The
   ** returned memory is effectively b->used bytes long unless the user
   ** decides to apply his own conventions.
   */
  char const * fsl_buffer_cstr(fsl_buffer const *b);

  /**
   ** If buf is not NULL and has any memory allocated to it, that
   ** memory is returned. If both b and len are not NULL then *len is
   ** set to b->used. If b has no dynamic memory then NULL is returned
   ** and *len (if len is not NULL) is set to 0.
   **/
  char const * fsl_buffer_cstr2(fsl_buffer const *b, fsl_size_t * len);

  /**
   ** Equivalent to ((char *)b->mem), but returns NULL if !b. The
   ** returned memory is effectively b->used bytes long unless the user
   ** decides to apply his own conventions.
   */
  char * fsl_buffer_str(fsl_buffer const *b);

  /*
  ** Returns the "used" size of b, or 0 if !b.
  */
  fsl_size_t fsl_buffer_size(fsl_buffer const * b);
  /*
  ** Returns the current capacity of b, or 0 if !b.
  */
  fsl_size_t fsl_buffer_capacity(fsl_buffer const * b);
  
  /**
   ** Compares the contents of buffers lhs and rhs using memcmp(3)
   ** semantics. Return negative, zero, or positive if the first
   ** buffer is less then, equal to, or greater than the second.
   ** Results are undefined if either argument is NULL.
   **
   ** When buffers of different length match on the first N bytes,
   ** where N is the shorter of the two buffers' lengths, it treats the
   ** shorter buffer as being "less than" the longer one.
   */
  int fsl_buffer_compare(fsl_buffer const * lhs, fsl_buffer const * rhs);

  /**
   ** Compare two buffers in constant (a.k.a. O(1)) time and return
   ** zero if they are equal.  Constant time comparison only applies
   ** for buffers of the same length.  If lengths are different,
   ** immediately returns 1.
   */
  int fsl_buffer_compare_O1(fsl_buffer const * lhs, fsl_buffer const * rhs);


  /**
   ** Uses a fsl_input_f() function to buffer input into a fsl_buffer.
   **
   ** dest must be a non-NULL, initialized (though possibly empty)
   ** fsl_buffer object. Its contents, if any, will be overwritten by
   ** this function, and any memory it holds might be re-used.
   **
   ** The src function is called, and passed the state parameter, to
   ** fetch the input. If it returns non-0, this function returns that
   ** error code. src() is called, possibly repeatedly, until it
   ** reports that there is no more data.
   **
   ** Whether or not this function succeeds, dest still owns any memory
   ** pointed to by dest->mem, and the client must eventually free it
   ** by calling fsl_buffer_reserve(dest,0).
   **
   ** dest->mem might (and possibly will) be (re)allocated by this
   ** function, so any pointers to it held from before this call might
   ** be invalidated by this call.
   **
   ** On error non-0 is returned and dest has almost certainly been
   ** modified but its state must be considered incomplete.
   **
   ** Errors include:
   **
   ** dest or src are NULL (FSL_RC_MISUSE)
   **
   ** Allocation error (FSL_RC_OOM)
   **
   ** src() returns an error code
   **
   ** Whether or not the state parameter may be NULL depends on the src
   ** implementation requirements.
   **
   ** On success dest will contain the contents read from the input
   ** source. dest->used will be the length of the read-in data, and
   ** dest->mem will point to the memory. dest->mem is automatically
   ** NUL-terminated if this function succeeds, but dest->used does not
   ** count that terminator. On error the state of dest->mem must be
   ** considered incomplete, and is not guaranteed to be
   ** NUL-terminated.
   **
   ** Example usage:
   **
   ** @code
   ** fsl_buffer buf = fsl_buffer_empty;
   ** int rc = fsl_buffer_fill_from( &buf,
   **                                fsl_input_FILE,
   **                                stdin );
   ** if( rc ){
   **   fprintf(stderr,"Error %d (%s) while filling buffer.\n",
   **   rc, fsl_rc_cstr(rc));
   **   fsl_buffer_reserve( &buf, 0 );
   **   return ...;
   ** }
   ** ... use the buf->mem ...
   ** ... clean up the buffer ...
   ** fsl_buffer_reserve( &buf, 0 );
   ** @endcode
   **
   ** To take over ownership of the buffer's memory, do:
   **
   ** @code
   ** void * mem = buf.mem;
   ** buf = fsl_buffer_empty;
   ** @endcode
   **
   **
   ** In which case the memory must eventually be passed to fsl_free()
   ** to free it.
   */
  int fsl_buffer_fill_from( fsl_buffer * dest, fsl_input_f src, void * state );

  /**
     A fsl_buffer_fill_from() proxy which overwrite's dest->mem
     with the contents of the given FILE handler (which must be
     opened for read access).  Returns 0 on success, after which
     dest->mem contains dest->used bytes of content from the input
     source. On error dest may be partially filled.
  */
  int fsl_buffer_fill_from_FILE( fsl_buffer * dest, FILE * src );

  /**
     Wrapper for fsl_buffer_fill_from_FILE() which gets its input
     from the given file name. As a special case it interprets the
     name "-" as stdin.
  */
  int fsl_buffer_fill_from_filename( fsl_buffer * dest, char const * filename );    

  
  /**
   ** Outputs the first n bytes of src to f's configured output
   ** channel. Returns 0 on success, FSL_RC_MISUSE if (!f || !src),
   ** 0 (without side effects) if !n, else it returns the result of
   ** the underlying output call. This is a harmless no-op if f is
   ** configured with no output channel.
   */
  int fsl_output( fsl_cx * f, void const * src, fsl_size_t n );

  /**
   ** Uses fsl_appendf() to append formatted output to the channel
   ** configured for use with fsl_output().
   */
  int fsl_outputf( fsl_cx * f, char const * fmt, ... );

  /** va_list counterpart to fsl_outputf(). */
  int fsl_outputfv( fsl_cx * f, char const * fmt, va_list args );

  /**
   ** Uses fsl_appendf() to create a dynamically-allocated string.
   ** On success the new string is returned to the caller, who must
   ** eventually pass it to fsl_free() or fsl_realloc() to free it.
   */
  char * fsl_mprintf( char const * fmt, ... );

  /** Equivalent to fsl_mprintfv(). */
  char * fsl_mprintfv( char const * fmt, va_list args );

  /**
   ** Equivalent to strdup(3) but returns NULL if !src.  The returned
   ** memory must eventually be passed to fsl_free().
   */
  char * fsl_strdup( char const * src );
  
  /**
   ** Equivalent to strlen(3) but returns 0 if src is NULL.
   ** Note that it counts bytes, not UTF characters.
   */
  fsl_size_t fsl_strlen( char const * src );

  /**
   ** Like strcmp() except that it accepts NULL pointers.  NULL sorts
   ** before all non-NULL string pointers.  Also, this strcmp() is a
   ** binary comparison that does not consider locale.
   */
  int fsl_strcmp( char const * lhs, char const * rhs );

  /**
   ** Case-insensitive form of fsl_strcmp().
   */
  int fsl_stricmp(const char *zA, const char *zB);

  /**
   ** fsl_strcmp() variant which compares at most nByte bytes
   ** of the given strings, case-insensitively.
   */
  int fsl_strnicmp(const char *zA, const char *zB, int nByte);

  /**
   ** fsl_strcmp() variant which compares at most nByte bytes
   ** of the given strings, case-sensitively.
   */
  int fsl_strncmp(const char *zA, const char *zB, int nByte);

  /**
   ** Flags for use with fsl_db_open() and friends.
   */
  enum fsl_open_flags {
  /**
   ** The "no flags" value.
   */
  FSL_OPEN_F_NONE = 0,
  /**
   ** Flag for fsl_db_open() specifying that the db should be opened
   ** in read-only mode.
   */
  FSL_OPEN_F_RO = 0x01,
  /**
   ** Flag for fsl_db_open() specifying that the db should be opened
   ** in read-write mode, but should not create the db if it does
   ** not already exist.
   */
  FSL_OPEN_F_RW = 0x02,
  /**
   ** Flag for fsl_db_open() specifying that the db should be opened in
   ** read-write mode, creating the db if it does not already exist.
   */
  FSL_OPEN_F_CREATE = 0x04,
  /**
   ** Shorthand for RW+CREATE flags.
   */
  FSL_OPEN_F_RWC = FSL_OPEN_F_RW | FSL_OPEN_F_CREATE,
  /**
   ** Indicates that a routine should not fail if the given file
   ** does not yet exist. It should create it in this case (if possible
   ** for the given routine). Not all routines honor this flag.
   */
  FSL_OPEN_F_NOT_FOUND_OK = 0x10,
  /**
   ** Tells fsl_cx_repo_open_xxx() to confirm that the db
   ** is a repository.
   */
  FSL_OPEN_F_SCHEMA_VALIDATE = 0x20
  };
  
 
  /**
   ** Quivalent to fopen(3) but expects name to be UTF8-encoded.
   */
  FILE * fsl_fopen(char const * name, char const *mode);

  /**
   ** Opens the given db file and populates db with its handle.  db
   ** must have been cleanly initialized by copy-constructing it from
   ** fsl_db_empty or allocating it using fsl_db_malloc(). Failure to
   ** do so will lead to undefined behaviour.
   **
   ** openFlags may be a mask of FSL_OPEN_F_xxx values. If
   ** FSL_OPEN_F_NOT_FOUND_OK is _not_ set in openFlags and dbFile
   ** does not exist, it will return FSL_RC_NOT_FOUND. The existence
   ** of FSL_OPEN_F_CREATE in the flags trumps FSL_OPEN_F_NOT_FOUND_OK,
   ** so a not-found error is not reported if openMode contains has the
   ** FSL_OPEN_F_CREATE bit set.
   **
   ** Returns FSL_RC_MISUSE if !db, !dbFile, !*dbFile, or
   ** if db->dbh is not NULL.
   **
   ** On error db->dbh will not be set, but db->dbh.error might contain
   ** error details.
   **
   ** Regardless of success or failure, db should be passed to
   ** fsl_db_close() to free up all memory associated with it. It is
   ** not closed automatically by this function because doing so cleans
   ** up the error state, which the caller will presumably want to
   ** have.
   **
   ** If db->f is not NULL then it is assumed that db should be plugged
   ** in to the repository system, and the following additions things
   ** happen:
   **
   ** - A number of SQL functions are registered with the db.
   **
   ** - If db->FSL_OPEN_F_SCHEMA_VALIDATE is set in openFlags then the
   ** db is validated to see if it has a fossil schema.  If that
   ** validation fails, FSL_RC_REPO_NEEDS_REBUILD or FSL_RC_NOT_A_REPO
   ** will be returned and db's error state will be updated.
   **
   **
   ** Note that this is a lower level operation than the fossil
   ** binary's 'open' command, and simply initializes f's db-related
   ** resources, and does not check out any files.
   */
  int fsl_db_open( fsl_db * db, char const * dbFile, int openFlags );

  /**
   ** Closes the given db handle and frees any resources owned by
   ** db. Returns 0 on success.
   **
   ** If db was allocated using fsl_db_alloc() (as determined by
   ** examining db->allocStamp) then this routine also fsl_free()s it,
   ** otherwise it is assumed to either be on the stack or part of a
   ** larger struct and is not freed.
   */
  int fsl_db_close( fsl_db * db );

  /**
   ** Allocates a new fsl_db instance(). Returns NULL on allocation
   ** error. Note that fsl_db instances can often be used from the
   ** stack - allocating them dynamically is an uncommon case necessary
   ** for script bindings.
   **
   ** Achtung: the returned value's allocStamp member is used for
   ** determining if fsl_db_close() should free the value or not.  Thus
   ** if clients copy over this value without adjusting allocStamp back
   ** to its original value, the library will likely leak the instance.
   ** Been there, done that.
   */
  fsl_db * fsl_db_malloc();

  /**
   ** The fsl_stmt counterpart of fsl_db_malloc(). See that function
   ** for when you might want to use this and a caveat involving the
   ** allocStamp member of the returned value. fsl_stmt_finalize() will
   ** free statements created with this function.
   */
  fsl_stmt * fsl_stmt_malloc();
  
  /**
   ** Opens the given db file name as f's repository. Returns 0 on
   ** success. On error it sets f's error state and returns that code
   ** unless the error was FSL_RC_MISUSE (which indicates invalid
   ** arguments and it does not set the error state).
   **
   ** Fails with FSL_RC_MISUSE if !f, !repoDbFile, !*repoDbFile. Returns
   ** FSL_RC_ACCESS if f already has an opened repo db.
   **
   ** Returns FSL_RC_NOT_FOUND if repoDbFile is not found, as this
   ** routine cannot create a new repository db.
   **
   ** openFlags is a bitmask of FSL_OPEN_F_xxx. If it is 0 then this
   ** default is used: (FSL_OPEN_F_RW | FSL_OPEN_F_SCHEMA_VALIDATE).
   **
   ** fsl_db_open() for the meaning of the openFlags parameter
   ** and various other details.
   */
  int fsl_cx_repo_open_db( fsl_cx * f, char const * repoDbFile, int openFlags );

  /**
   **
   ** Tries to open a checked-out fossil repository db in the given
   ** directory. It looks for files named (_FOSSIL_, .fslckout), in
   ** that order in the given directory. If neither is found then it
   ** moves up the path one directory and tries again, until it
   ** hits the root of the dirPath (see below for a note/caveat).
   **
   ** If dirName is NULL then it behaves as if it has been passed the
   ** absolute path of the current directory (as determined by
   ** fsl_getcwd()).
   **
   ** dirName is not NULL and dirNameLen is <0 then fsl_strlen() is
   ** used to calculate dirName's len.
   **
   ** Achtung: if dirName is relative, this routine might not find a
   ** checkout where it would find one if given an absolute path
   ** (because it traverses the path string given it instead of its
   ** canonical form). Wether or not this is a bug or a feature is not
   ** yet clear. When in doubt, use fsl_file_canonical_name() to
   ** normalize the directory name before passing it in here. If it
   ** turns out that we always want that behaviour, this routine
   ** will/should be modified to canonicalize the name.
   **
   ** If this routine finds/opens a checkout, it also tries to open
   ** the repository database from which the checkout derives.
   **
   ** Returns 0 on success. If there is an error opening or validating
   ** the checkout or its repository db, f's error state will be
   ** updated. Error codes/conditions include:
   **
   ** - FSL_RC_MISUSE if f is NULL.
   **
   ** - FSL_RC_ACCESS if f has already opened a checkout as
   ** its main database (it can only handle one at a time).
   **
   ** - FSL_RC_OOM if an allocation fails.
   **
   ** - FSL_RC_RANGE if dirname is not NULL but has a length of 0,
   ** either because 0 was passed in for dirNameLen or because
   ** dirNameLen was negative and *dirName is a NUL byte.
   **
   ** - Various codes from fsl_getcwd() (if dirName is NULL).
   **
   **
   ** TODOs:
   **
   ** - automatically open repo db based on checkout's repo. Awaiting
   ** porting of some db-level utility code.
   **
   ** - If a repo db has already been opened, ensure that it belongs
   ** to the checkout being opened, else return FSL_RC_MISUSE or
   ** FSL_RC_CONSISTENCY, or maybe a new code.
   ** 
   */
  int fsl_cx_checkout_open( fsl_cx * f, char const * dirName, fsl_int_t dirNameLen );

  /**
   ** If fsl_cx_checkout_open() has been used to open a checkout db,
   ** this call closes that db and returns 0. Returns FSL_RC_MISUSE if
   ** !f, FSL_RC_NOT_A_CHECKOUT if f has not opened a checkout as its
   ** primary DB.
   **
   ** If alsoCloseRepo is true and a repository DB is opened then
   ** it is also closed.
   **
   ** TODO: also close repo db here?
   */
  int fsl_cx_checkout_close( fsl_cx * f, char alsoCloseRepo );
  
  /**
   ** If f is not NULL and has a checkout db opened then this function
   ** returns its name. The bytes are valid until that checkout db
   ** connection is closed. If len is not NULL then *len is (on
   ** success) assigned to the length of the returned string, in
   ** bytes. The string is NUL-terminated, so fetching the length (by
   ** passing a non-NULL 2nd parameter) is optional.
   **
   ** Returns NULL if !f or f has no checkout opened.
   **
   ** @see fsl_cx_checkout_open()
   ** @see fsl_cx_checkout_dir_name()
   */
  char const * fsl_cx_checkout_db_file(fsl_cx const * f,
                                       fsl_size_t * len);


  /**
   ** Equivalent to fsl_cx_checkout_db_file() except that
   ** it applies to the name of the opened repository db,
   ** if any.
   */
  char const * fsl_cx_repo_db_file(fsl_cx const * f,
                                   fsl_size_t * len);

  /**
   ** Equivalent to fsl_cx_checkout_db_file() except that
   ** it applies to the name of the opened config db,
   ** if any.
   */
  char const * fsl_cx_config_db_file(fsl_cx const * f,
                                     fsl_size_t * len);

  /**
   ** Equivalent to fsl_cx_checkout_db_file() except that
   ** it applies to db file implied by the specified role
   ** (2nd parameter). If no such role is opened, or the
   ** role is invalid, NULL is returned.
   **
   ** FIXME: the 1st parameter "should" be const - it is not modified
   ** here - but it currently cannot be without violating an internal
   ** constness guaranty which can be fixed with a little code
   ** duplication.
   */
  char const * fsl_cx_db_file_for_role(fsl_cx * f,
                                       fsl_db_role_t r,
                                       fsl_size_t * len);

  /**
   ** If f has an opened checkout db (from fsl_cx_checkout_open())
   ** then this function returns the directory part of the path
   ** for the checkout. The returned bytes are valid until that db
   ** connection is closed. If len is not NULL then *len is (on
   ** success) assigned to the length of the returned string, in bytes.
   ** The string is NUL-terminated, so fetching the length (by passing
   ** a non-NULL 2nd parameter) is optional.
   **
   ** Returns NULL if !f or f has no checkout opened.
   **
   ** @see fsl_cx_checkout_open()
   ** @see fsl_cx_checkout_db_name()
   */
  char const * fsl_cx_checkout_dir_name(fsl_cx const * f,
                                        fsl_size_t * len);


  /**
   ** Returns a handle to f's main db, or NULL if !f.
   **
   ** The current architecture sets up an in-memory DB
   ** as the main db and ATTACHes all others. Whether or not
   ** this is a simpler/better approach than managing
   ** multiple DB connections is as yet unclear.
   **/
  fsl_db * fsl_cx_db( fsl_cx * f );

  /**
   ** If f is not NULL and has had its repo opened via
   ** fsl_cx_repo_open_db() or similar, this returns a pointer to that
   ** database, else it returns NULL.
   */
  fsl_db * fsl_cx_db_repo( fsl_cx * f );

  /**
   ** If f is not NULL and has had a checkout opened via
   ** fsl_cx_checkout_open() or similar, this returns a pointer to that
   ** database, else it returns NULL.
   */
  fsl_db * fsl_cx_db_checkout( fsl_cx * f );

  /**
   ** IN PROGRESS/INCOMPLETE
   **
   ** Opens the given database file as f's configuration database. If f
   ** already has a config database opened, it is closed before opening
   ** the new one. The database is created and populated with an
   ** initial schema if needed.
   **
   ** If dbName is NULL or empty then it uses a default db name,
   ** "probably" under the user's home directory. To get the name of
   ** the database after it has been opened/attached, use
   ** fsl_cx_config_db_file().
   **
   **
   ** TODO: strongly consider supporting non-attached use of
   ** the config db. Comments in v1 suggest that it is possible
   ** to lock the config db for other apps when it is attached
   ** to a long-running op by a fossil process.
   **
   ** These notes do not apply, but it may be (re)added later:
   **
   ** If useAttach is 0 (the most common case), the db is opened in
   ** its own connection, otherwise it is ATTACH'd to the currently
   ** opened db. The latter case is unusual, but allows one to create
   ** queries which join against multiple databases. When in doubt,
   ** pass 0 here.
   **
   */
  int fsl_cx_config_open( fsl_cx * f, char const * dbName );

  /**
   ** Closes/detaches the database connection opened by
   ** fsl_cx_config_open().   
   */
  int fsl_cx_config_close( fsl_cx * f );
  
  /*
  ** If f has an opened configuration db then its handle is returned.
  ** It will return NULL if the config db was opened via "attaching"
  ** it. See fsl_cx_config_open().
  */
  fsl_db * fsl_cx_db_config( fsl_cx * f );
  
#if 0
  /**
   ** TODO.
   **
   ** Should create a new fossil repo db. Do we need some sort of progress
   ** callback here? Creation is fast, so probably not.
   **
   */
  int fsl_cx_repo_create_db( fsl_cx * f, char const * repoDbFile, int flags /**???*/ );
#endif

  /**
   ** If fsl_cx_repo_open_xxx() has been used to open a respository db,
   ** this call closes that db and returns 0. Returns FSL_RC_MISUSE if
   ** !f.
   **
   ** FSL_RC_NOT_A_REPO if f has not opened a repository.
   **
   ** TODO: also close checkout db here?
   */
  int fsl_cx_repo_close( fsl_cx * f );

  /**
   ** Convenience form of fsl_stmt_prepare() which uses f's db.
   ** Returns 0 on success, FSL_RC_MISUSE if !f or !sql, FSL_RC_RANGE
   ** if !*sql.
   */
  int fsl_cx_prepare( fsl_cx *f, fsl_stmt * tgt, char const * sql, ... );

  /**
   ** va_list counterpart of fsl_cx_prepare().
   */
  int fsl_cx_preparev( fsl_cx *f, fsl_stmt * tgt, char const * sql, va_list args );

  /**
   ** @typedef long (*fsl_appendf_f)( void * arg, char const * data, long n )
   **
   ** The fsl_appendf_f typedef is used to provide fsl_appendfv() with
   ** a flexible output routine, so that it can be easily send its
   ** output to arbitrary targets.
   **
   ** The policies which implementations need to follow are:
   **
   ** - arg is an implementation-specific pointer (may be 0) which is
   ** passed to vappendf. fsl_appendfv() doesn't know what this
   ** argument is but passes it to its fsl_appendf_f. Typically it
   ** will be an object or resource handle to which string data is
   ** pushed or output.
   **
   ** - The 'data' parameter is the data to append. If it contains
   ** embedded nulls, this function will stop at the first one. Thus
   ** it is not binary-safe.
   **
   ** - n is the number of bytes to read from data. If n<0 then
   ** strlen(data) should be used.
   **
   ** - Returns, on success, the number of bytes appended (may be 0).
   **
   ** - Returns, on error, an implementation-specified negative
   ** number.  Returning a negative error code will cause
   ** fsl_appendfv() to stop the processing of that string. Note that
   ** 0 is a success value (some printf format specifiers do not add
   ** anything to the output).
   */
  typedef long (*fsl_appendf_f)( void * arg,
                                 char const * data,
                                 long n );

  /**
   ** This function works similarly to classical printf
   ** implementations, but instead of outputing somewhere specific, it
   ** uses a callback function to push its output somewhere. This
   ** allows it to be used for arbitrary external representations. It
   ** can be used, for example, to output to an external string, a UI
   ** widget, or file handle (it can also emulate printf by outputing
   ** to stdout this way).
   **
   ** INPUTS:
   **
   ** pfAppend: The is a fsl_appendf_f function which is responsible
   ** for accumulating the output. If pfAppend returns a negative
   ** integer then processing stops immediately.
   **
   ** pfAppendArg: is ignored by this function but passed as the first
   ** argument to pfAppend. pfAppend will presumably use it as a data
   ** store for accumulating its string.
   **
   ** fmt: This is the format string, as in the usual printf().
   **
   ** ap: This is a pointer to a list of arguments.  Same as in
   ** vprintf() and friends.
   **
   **
   ** OUTPUTS:
   **
   ** The return value is the total number of characters sent to the
   ** function "func", or a negative number on a pre-output error. If
   ** this function returns an integer greater than 1 it is in general
   ** impossible to know if all of the elements were output. As such
   ** failure can only happen if the callback function returns an
   ** error, and this type of error is very rare in a printf-like
   ** context, this is not considered to be a significant problem. (The
   ** same is true for any classical printf implementations.) Clients
   ** may use their own state objects which can propagate errors from
   ** their own internals back to the caller, but generically speaking
   ** it is difficult to trace errors back through this routine.  Then
   ** again, it only breaks when using using a broken output routine or
   ** bad output state.
   **
   ** CURRENT (documented) PRINTF EXTENSIONS:
   **
   ** %%z works like %%s, but takes a non-const (char *) and vappendf
   ** deletes the string (using fsl_free()) after appending it to the
   ** output.
   **
   ** %%h (HTML) works like $%s but converts certain characters (namely
   ** '<' and '&') to their HTML escaped equivalents.
   **
   ** %%t (URL encode) works like %%s but converts certain characters
   ** into a representation suitable for use in an HTTP URL. (e.g. ' ' 
   ** gets converted to %%20)
   **
   ** %%T (URL decode) does the opposite of %t - it decodes URL-encoded
   ** strings.
   **
   ** %%r requires an int and renders it in "ordinal form". That is,
   ** the number 1 converts to "1st" and 398 converts to "398th".
   **
   ** %%q quotes a string as required for SQL. That is, '\'' characters
   ** get doubled.
   **
   ** %%Q as %%q, but includes the outer '\'' characters and null
   ** pointers replaced by SQL NULL.
   **
   ** %%/: requires a C-string parameter. Normalizes path-like strings
   ** by replacing backslashes with the One True Slash.
   **
   ** %%b: works like %%s but takes its input from a (fsl_buffer*)
   ** argument.
   **
   ** %%B: works like %%Q but takes its input from a (fsl_buffer*)
   ** argument.
   **
   ** These extensions may be disabled by setting certain macros when
   ** compiling fsl_appendf.c (see that file for details).
   **
   **
   ** FIXME? fsl_appendf_f() is an artifact of older code from which
   ** this implementation derives. The first parameter should arguably
   ** be replaced with fsl_output_f(), which does the same thing _but_
   ** has different return semantics (more reliable, because the
   ** current semantics report partial success as success in some
   ** cases). Doing this would require us to change the return
   ** semantics of this function, but that wouldn't necessarily be a
   ** bad thing (we don't rely on sprintf()-like return semantics all
   ** that much, AFAIK?). Or we just add a proxy which forwards to a
   ** fsl_output_f(). Oh, hey, that's what fsl_outputf() does.
   **
   ** TODO?: replace 'long' with either an int (using fsl_output_f()
   ** semantics) or an int using sprintf() semantics (as it is now).
   */
  long fsl_appendfv(fsl_appendf_f pfAppend, void * pfAppendArg,
                    const char *fmt, va_list ap );

  /**
   **
   ** Identical to fsl_appendfv() but takes a (...) ellipses list
   ** instead of a va_list.
   */
  long fsl_appendf(fsl_appendf_f pfAppend,
                   void * pfAppendArg,
                   const char *fmt,
                   ... );

  /**
   ** Emulates fprintf() using fsl_appendf(). Returns the result of
   ** passing the data through fsl_appendf() to the given file handle.
   */
  long fsl_appendf_FILE( FILE * fp, char const * fmt, ... );


  /**
   ** Works like fsl_appendfv(), but appends all output to a
   ** dynamically-allocated string, expanding the string as necessary
   ** to collect all formatted data. The returned NUL-terminated string
   ** is owned by the caller and it must be cleaned up using
   ** fsl_free(...). If !fmt, NULL is returned. It is conceivable that
   ** it returns NULL on a zero-length formatted string, e.g.  (%.*s)
   ** with (0,"...") as arguments, but it will only do that if the
   ** whole format string resolves to empty.
   */
  char * fsl_mprintf( char const * fmt, ... );

  /**
   ** va_list counterpart to fsl_mprintf().
   */
  char * fsl_mprintfv(char const * fmt, va_list vargs );

  /**
   ** Possibly reallocates self->list, changing its size. This function
   ** ensures that self->list has at least n entries. If n is 0 then
   ** the list is deallocated (but the self object is not), BUT THIS
   ** DOES NOT DO ANY TYPE-SPECIFIC CLEANUP of the items. If n is less
   ** than or equal to self->alloced then there are no side effects. If
   ** n is greater than self->alloced, self->list is reallocated and
   ** self->alloced is adjusted to be at least n (it might be bigger -
   ** this function may pre-allocate a larger value).
   **
   ** Passing an n of 0 when self->alloced is 0 is a no-op.
   **
   ** Newly-allocated slots will be initialized with NUL bytes.
   **
   ** Returns the total number of items allocated for self->list.  On
   ** success, the value will be equal to or greater than n (in the
   ** special case of n==0, 0 is returned). Thus a return value smaller
   ** than n is an error. Note that if n is 0 or self is NULL then 0 is
   ** returned.
   **
   ** The return value should be used like this:
   **
   ** @code
   ** fsl_size_t const n = number of bytes to allocate;
   ** if( n > fsl_list_reserve( myList, n ) ) { ... error ... }
   ** // Or the other way around:
   ** if( fsl_list_reserve( myList, n ) < n ) { ... error ... }
   ** @endcode
   */
  fsl_size_t fsl_list_reserve( fsl_list * self, fsl_size_t n );

  /**
   ** Appends a bitwise copy of cp to self->list, expanding the list as
   ** necessary and adjusting self->count.
   **
   ** Ownership of cp is unchanged by this call. cp may not be NULL.
   **
   ** Returns 0 on success, FSL_RC_MISUSE if any argument is NULL, or
   ** FSL_RC_OOM on allocation error.
   */
  int fsl_list_append( fsl_list * self, void * cp );

  /** @typedef typedef int (*fsl_list_visitor_f)(void * p, void * visitorState )
   **
   ** Generic visitor interface for fsl_list lists.  Used by
   ** fsl_list_visit(). p is the pointer held by that list entry and
   ** visitorState is the 4th argument passed to fsl_list_visit().
   **
   ** Implementations must return 0 on success. Any other value causes
   ** looping to stop and that value to be returned, but interpration
   ** of the value is up to the caller (it might or might not be an
   ** error, depending on the context). Note that client code may use
   ** custom values, and is not restricted to FSL_RC_xxx values.
   */
  typedef int (*fsl_list_visitor_f)(void * obj, void * visitorState );

  /**
   ** For each item in self->list, visitor(item,visitorState) is
   ** called.  The item is owned by self. The visitor function MUST
   ** NOT free the item, but may manipulate its contents if
   ** application rules do not specify otherwise.
   **
   **
   ** If order is 0 or greater then the list is traversed from start
   ** to finish, else it is traverse from end to begin.
   **
   **
   ** Returns 0 on success, non-0 on error.
   **
   ** If visitor() returns non-0 then looping stops and that code is
   ** returned.
   */
  int fsl_list_visit( fsl_list * self, char order,
                      fsl_list_visitor_f visitor, void * visitorState );

  /**
   **
   **
   ** Works similarly to the visit operation without the _p suffix
   ** except that the pointer the visitor function gets is a (**)
   ** pointing back to the entry within this list. That means that
   ** callers can assign the entry in the list to another value during
   ** the traversal process (e.g. set it to 0). If shiftIfNulled is
   ** true then if the callback sets the list's value to 0 then it is
   ** removed from the list and self->count is adjusted (self->alloced
   ** is not changed).
   */
  int fsl_list_visit_p( fsl_list * self, char order, char shiftIfNulled,
                        fsl_list_visitor_f visitor, void * visitorState );


  /**
   ** Returns 0 if the given file is readable. Flags may be any values
   ** accepted by the accept(2) resp. _waccept() system calls.
   */
  int fsl_file_access(const char *zFilename, int flags);

  /**
   ** Compute a canonical pathname for a file or directory.
   ** Make the name absolute if it is relative.
   ** Remove redundant / characters.
   ** Remove all /./ path elements.
   ** Convert /A/../ to just /.
   ** If the slash parameter is non-zero, the trailing slash, if any,
   ** is retained.
   **
   ** Returns 0 on success, FSL_RC_MISUSE if !zOrigName or !pOut,
   ** FSL_RC_OOM if an allocation fails.
   **
   ** pOut is _appended_ to, so be sure to set pOut->used=0 (or pass it
   ** to fsl_buffer_reset()) before calling this if you want to start
   ** writing at the beginning.
   */
  int fsl_file_canonical_name(const char *zOrigName,
                              fsl_buffer *pOut, char slash);

  /**
   ** Writes the absolute path name of the current directory to zBuf,
   ** which must be at least nBuf bytes long (nBuf includes the space
   ** for a trailing NUL terminator).
   **
   ** Returns FSL_RC_RANGE if the name would be too long for nBuf,
   ** FSL_RC_IO if it cannot determine the current directory (e.g. a
   ** side effect of having removed the directory at runtime or similar
   ** things), and 0 on success.
   **
   ** On success, if outLen is not NULL then the length of the string
   ** written to zBuf is assigned to *outLen The output string is
   ** always NUL-terminated.
   **
   ** On Windows, the name is converted from unicode to UTF8 and all '\\'
   ** characters are converted to '/'.  No conversions are needed on
   ** Unix.
   */
  int fsl_getcwd(char *zBuf, fsl_size_t nBuf, fsl_size_t * outLen);

  /**
   ** Return non-zero if string z matches glob pattern zGlob and zero
   ** if the pattern does not match. Always returns 0 if either
   ** argument is NULL.
   **
   ** Globbing rules:
   **
   **      '*'       Matches any sequence of zero or more characters.
   **
   **      '?'       Matches exactly one character.
   **
   **     [...]      Matches one character from the enclosed list of
   **                characters.
   **
   **     [^...]     Matches one character not in the enclosed list.
   */
  char fsl_str_glob(const char *zGlob, const char *z);

  /**
   ** Return the size of a file in bytes.  Return -1 if the file does not
   ** exist or is not stat()able.
   */
  fsl_int64_t fsl_file_size(const char *zFilename);

  /**
   ** Same as fsl_file_size(), but takes into account symlinks.
   ** (What does that mean, anyway?)
   */
  fsl_int64_t fsl_file_wd_size(const char *zFilename);

  /**
   ** Return the modification time for a file.  Return -1 if the file
   ** does not exist.
   */
  fsl_time_t fsl_file_mtime(const char *zFilename);

  /**
   ** Same as fsl_file_mtime(), but takes into account symlinks.
   */
  fsl_time_t fsl_file_wd_mtime(const char *zFilename);

  /**
   ** Return TRUE if the named file is an ordinary file or symlink
   ** and symlinks are allowed.
   ** Return false for directories, devices, fifos, etc.
   */
  int fsl_file_wd_isfile_or_link(const char *zFilename);

  /**
   ** Return TRUE if the named file is an ordinary file.  Return false
   ** for directories, devices, fifos, symlinks, etc.
   */
  int fsl_file_isfile(const char *zFilename);

  /**
   ** Same as fsl_file_isfile(), but takes into account symlinks.
   */
  int fsl_file_wd_isfile(const char *zFilename);
  /**
   ** Returns true if the given path appears to be absolute, else
   ** false. On Unix a path is absolute if it starts with a '/'.  On
   ** Windows a path is also absolute if it starts with a letter, a
   ** colon, and a backslash.
   */
  char fsl_file_is_absolute_path(const char *zPath);
  
  /**
   ** Returns true, else false if the given letter is an ASCII alphabet
   ** character.
   */
  char fsl_isalpha(int ch);
  char fsl_islower(int ch);
  char fsl_isspace(int c);
  char fsl_islower(int c);
  char fsl_isupper(int c);
  char fsl_isdigit(int c);
  char fsl_tolower(int c);
  char fsl_toupper(int c);
  char fsl_isalpha(int c);
  char fsl_isalnum(int c);

  typedef struct fsl_sha1_cx fsl_sha1_cx;

  /**
   ** Holds state for SHA1 calculations. They are to be used like this:
   **
   ** @code
   **  unsigned char digest[20]
   **  char hex[41];
   **  fsl_sha1_cx cx;
   **  fsl_sha1_init(&cx);
   **  ...call fsl_sha1_update(&cx,...) any number of times to
   **  ...incrementally calculate the hash.
   **  fsl_sha1_final(&cx, digest); // ends the calculation
   **  fsl_sha1_digest_to_base16(&cx, hex);
   **  // digest now contains the raw 20-byte SHA1 digest.
   **  // hex now contains the 40-byte SHA1 + a trailing NUL
   ** @endcode
   */
  struct fsl_sha1_cx {
    unsigned int state[5];
    unsigned int count[2];
    unsigned char buffer[64];
  };

  /**
   ** Initializes the given context with the initial SHA1 state.  This
   ** must be the first routine called on an SHA1 context, and passing
   ** this context to other SHA1 routines without first having passed
   ** it to this will lead to undefined results.
   */
  void fsl_sha1_init(fsl_sha1_cx *context);

  /**
   ** Updates the given context to include the hash of the first len bytes
   ** of the given data.
   */
  void fsl_sha1_update( fsl_sha1_cx *context, const unsigned char *data, unsigned int len);

  /**
   ** Add padding and finalizes the message digest. If digest is not
   ** NULL then it writes 20 bytes of digest to the 2nd parameter.
   */
  void fsl_sha1_final(fsl_sha1_cx *context, unsigned char * digest);

  /**
   ** Convert a digest into base-16.  digest must be at least 20
   ** bytes long (the SHA1 digest is stored in the first 20 bytes).
   ** zBuf must be at least 41 bytes long, for 40 characters of SHA1
   ** hash and 1 NUL byte.
   */
  void fsl_sha1_digest_to_base16(unsigned char *digest, char *zBuf);

  /**
   ** Compute the SHA1 checksum of pIn and stores the resulting
   ** checksum in the buffer pCksum.  pCksum's memory is re-used if is
   ** has any allocated to it. pCksum may == pIn, in which case this is
   ** a destructive operation (replacing the data to hash with its
   ** hash code).
   **
   ** Return 0 on success, FSL_RC_OOM if (re)allocating pCksum fails.
   */
  int fsl_sha1sum_buffer(fsl_buffer const *pIn, fsl_buffer *pCksum);

  /**
   ** Computes the SHA1 checksum of the first len bytes of the given
   ** string.  If len is negative then zInt must be NUL-terminated and
   ** fsl_strlen() is used to find its length..  The result is a
   ** length-40 string (+NUL byte) returned in memory obtained from
   ** fsl_malloc(), so it must be passed to fsl_free() to free it. If
   ** NULL==zIn or !len then NULL is returned.
   */
  char *fsl_sha1sum_cstr(const char *zIn, int len);

  /**
   ** NYI: missing some permissions bits from v1.
   **
   ** Compute the SHA1 checksum of a file on disk.  Store the resulting
   ** checksum in the buffer pCksum.
   **
   ** Returns 0 on success.
   */
  int fsl_sha1sum_file(const char *zFilename, fsl_buffer *pCksum);
  
  
#if defined(__cplusplus)
} /*extern "C"*/
#endif

#endif
/* NET_FOSSIL_SCM_FOSSIL2_H_INCLUDED */
