svn_fs.h

Go to the documentation of this file.

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2008 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_fs.h
 * @brief Interface to the Subversion filesystem.
 */

#ifndef SVN_FS_H
#define SVN_FS_H

#include <apr.h>
#include <apr_pools.h>
#include <apr_hash.h>
#include <apr_tables.h>
#include <apr_time.h>    /* for apr_time_t */

#include "svn_types.h"
#include "svn_string.h"
#include "svn_delta.h"
#include "svn_io.h"
#include "svn_mergeinfo.h"
#include "svn_checksum.h"


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


/**
 * Get libsvn_fs version information.
 *
 * @since New in 1.1.
 */
const svn_version_t *
svn_fs_version(void);

/**
 * @defgroup fs_handling Filesystem interaction subsystem
 * @{
 */

/* Opening and creating filesystems.  */


/** An object representing a Subversion filesystem.  */
typedef struct svn_fs_t svn_fs_t;


/**
 * @name Filesystem configuration options
 * @{
 */
#define SVN_FS_CONFIG_BDB_TXN_NOSYNC            "bdb-txn-nosync"
#define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE        "bdb-log-autoremove"

/* See also svn_fs_type(). */
/** @since New in 1.1. */
#define SVN_FS_CONFIG_FS_TYPE                   "fs-type"
/** @since New in 1.1. */
#define SVN_FS_TYPE_BDB                         "bdb"
/** @since New in 1.1. */
#define SVN_FS_TYPE_FSFS                        "fsfs"

/** Create repository format compatible with Subversion versions
 * earlier than 1.4.
 *
 *  @since New in 1.4.
 */
#define SVN_FS_CONFIG_PRE_1_4_COMPATIBLE        "pre-1.4-compatible"

/** Create repository format compatible with Subversion versions
 * earlier than 1.5.
 *
 * @since New in 1.5.
 */
#define SVN_FS_CONFIG_PRE_1_5_COMPATIBLE        "pre-1.5-compatible"

/** Create repository format compatible with Subversion versions
 * earlier than 1.6.
 *
 * @since New in 1.6.
 */
#define SVN_FS_CONFIG_PRE_1_6_COMPATIBLE        "pre-1.6-compatible"
/** @} */


/**
 * Callers should invoke this function to initialize global state in
 * the FS library before creating FS objects.  If this function is
 * invoked, no FS objects may be created in another thread at the same
 * time as this invocation, and the provided @a pool must last longer
 * than any FS object created subsequently.
 *
 * If this function is not called, the FS library will make a best
 * effort to bootstrap a mutex for protecting data common to FS
 * objects; however, there is a small window of failure.  Also, a
 * small amount of data will be leaked if the Subversion FS library is
 * dynamically unloaded, and using the bdb FS can potentially segfault
 * or invoke other undefined behavior if this function is not called
 * with an appropriate pool (such as the pool the module was loaded into)
 * when loaded dynamically.
 *
 * If this function is called multiple times before the pool passed to
 * the first call is destroyed or cleared, the later calls will have
 * no effect.
 *
 * @since New in 1.2.
 */
svn_error_t *
svn_fs_initialize(apr_pool_t *pool);


/** The type of a warning callback function.  @a baton is the value specified
 * in the call to svn_fs_set_warning_func(); the filesystem passes it through
 * to the callback.  @a err contains the warning message.
 *
 * The callback function should not clear the error that is passed to it;
 * its caller should do that.
 */
typedef void (*svn_fs_warning_callback_t)(void *baton, svn_error_t *err);


/** Provide a callback function, @a warning, that @a fs should use to
 * report (non-fatal) errors.  To print an error, the filesystem will call
 * @a warning, passing it @a warning_baton and the error.
 *
 * By default, this is set to a function that will crash the process.
 * Dumping to @c stderr or <tt>/dev/tty</tt> is not acceptable default
 * behavior for server processes, since those may both be equivalent to
 * <tt>/dev/null</tt>.
 */
void
svn_fs_set_warning_func(svn_fs_t *fs,
                        svn_fs_warning_callback_t warning,
                        void *warning_baton);



/**
 * Create a new, empty Subversion filesystem, stored in the directory
 * @a path, and return a pointer to it in @a *fs_p.  @a path must not
 * currently exist, but its parent must exist.  If @a fs_config is not
 * @c NULL, the options it contains modify the behavior of the
 * filesystem.  The interpretation of @a fs_config is specific to the
 * filesystem back-end.  The new filesystem may be closed by
 * destroying @a pool.
 *
 * @note The lifetime of @a fs_config must not be shorter than @a
 * pool's. It's a good idea to allocate @a fs_config from @a pool or
 * one of its ancestors.
 *
 * If @a fs_config contains a value for @c SVN_FS_CONFIG_FS_TYPE, that
 * value determines the filesystem type for the new filesystem.
 * Currently defined values are:
 *
 *   SVN_FS_TYPE_BDB   Berkeley-DB implementation
 *   SVN_FS_TYPE_FSFS  Native-filesystem implementation
 *
 * If @a fs_config is @c NULL or does not contain a value for
 * @c SVN_FS_CONFIG_FS_TYPE then the default filesystem type will be used.
 * This will typically be BDB for version 1.1 and FSFS for later versions,
 * though the caller should not rely upon any particular default if they
 * wish to ensure that a filesystem of a specific type is created.
 *
 * @since New in 1.1.
 */
svn_error_t *
svn_fs_create(svn_fs_t **fs_p,
              const char *path,
              apr_hash_t *fs_config,
              apr_pool_t *pool);

/**
 * Open a Subversion filesystem located in the directory @a path, and
 * return a pointer to it in @a *fs_p.  If @a fs_config is not @c
 * NULL, the options it contains modify the behavior of the
 * filesystem.  The interpretation of @a fs_config is specific to the
 * filesystem back-end.  The opened filesystem may be closed by
 * destroying @a pool.
 *
 * @note The lifetime of @a fs_config must not be shorter than @a
 * pool's. It's a good idea to allocate @a fs_config from @a pool or
 * one of its ancestors.
 *
 * Only one thread may operate on any given filesystem object at once.
 * Two threads may access the same filesystem simultaneously only if
 * they open separate filesystem objects.
 *
 * @note You probably don't want to use this directly.  Take a look at
 * svn_repos_open() instead.
 *
 * @since New in 1.1.
 */
svn_error_t *
svn_fs_open(svn_fs_t **fs_p,
            const char *path,
            apr_hash_t *fs_config,
            apr_pool_t *pool);

/**
 * Upgrade the Subversion filesystem located in the directory @a path
 * to the latest version supported by this library.  Return @c
 * SVN_ERR_FS_UNSUPPORTED_UPGRADE and make no changes to the
 * filesystem if the requested upgrade is not supported.  Use @a pool
 * for necessary allocations.
 *
 * @note You probably don't want to use this directly.  Take a look at
 * svn_repos_upgrade() instead.
 *
 * @since New in 1.5.
 */
svn_error_t *
svn_fs_upgrade(const char *path,
               apr_pool_t *pool);

/**
 * Return, in @a *fs_type, a string identifying the back-end type of
 * the Subversion filesystem located in @a path.  Allocate @a *fs_type
 * in @a pool.
 *
 * The string should be equal to one of the @c SVN_FS_TYPE_* defined
 * constants, unless the filesystem is a new back-end type added in
 * a later version of Subversion.
 *
 * In general, the type should make no difference in the filesystem's
 * semantics, but there are a few situations (such as backups) where
 * it might matter.
 *
 * @since New in 1.3.
 */
svn_error_t *
svn_fs_type(const char **fs_type,
            const char *path,
            apr_pool_t *pool);

/**
 * Return the path to @a fs's repository, allocated in @a pool.
 * @note This is just what was passed to svn_fs_create() or
 * svn_fs_open() -- might be absolute, might not.
 *
 * @since New in 1.1.
 */
const char *
svn_fs_path(svn_fs_t *fs,
            apr_pool_t *pool);

/**
 * Delete the filesystem at @a path.
 *
 * @since New in 1.1.
 */
svn_error_t *
svn_fs_delete_fs(const char *path,
                 apr_pool_t *pool);

/**
 * Copy a possibly live Subversion filesystem from @a src_path to
 * @a dest_path.  If @a clean is @c TRUE, perform cleanup on the
 * source filesystem as part of the copy operation; currently, this
 * means deleting copied, unused logfiles for a Berkeley DB source
 * filesystem.
 *
 * @since New in 1.1.
 */
svn_error_t *
svn_fs_hotcopy(const char *src_path,
               const char *dest_path,
               svn_boolean_t clean,
               apr_pool_t *pool);

/** Perform any necessary non-catastrophic recovery on the Subversion
 * filesystem located at @a path.
 *
 * If @a cancel_func is not @c NULL, it is called periodically with
 * @a cancel_baton as argument to see if the client wishes to cancel
 * recovery.  BDB filesystems do not currently support cancellation.
 *
 * Do any necessary allocation within @a pool.
 *
 * For FSFS filesystems, recovery is currently limited to recreating
 * the db/current file, and does not require exclusive access.
 *
 * For BDB filesystems, recovery requires exclusive access, and is
 * described in detail below.
 *
 * After an unexpected server exit, due to a server crash or a system
 * crash, a Subversion filesystem based on Berkeley DB needs to run
 * recovery procedures to bring the database back into a consistent
 * state and release any locks that were held by the deceased process.
 * The recovery procedures require exclusive access to the database
 * --- while they execute, no other process or thread may access the
 * database.
 *
 * In a server with multiple worker processes, like Apache, if a
 * worker process accessing the filesystem dies, you must stop the
 * other worker processes, and run recovery.  Then, the other worker
 * processes can re-open the database and resume work.
 *
 * If the server exited cleanly, there is no need to run recovery, but
 * there is no harm in it, either, and it take very little time.  So
 * it's a fine idea to run recovery when the server process starts,
 * before it begins handling any requests.
 *
 * @since New in 1.5.
 */
svn_error_t *
svn_fs_recover(const char *path,
               svn_cancel_func_t cancel_func,
               void *cancel_baton,
               apr_pool_t *pool);


/** Subversion filesystems based on Berkeley DB.
 *
 * The following functions are specific to Berkeley DB filesystems.
 *
 * @defgroup svn_fs_bdb Berkeley DB filesystems
 * @{
 */

/** Register an error handling function for Berkeley DB error messages.
 *
 * @deprecated Provided for backward compatibility with the 1.2 API.
 *
 * Despite being first declared deprecated in Subversion 1.3, this API
 * is redundant in versions 1.1 and 1.2 as well.
 *
 * Berkeley DB's error codes are seldom sufficiently informative to allow
 * adequate troubleshooting.  Berkeley DB provides extra messages through
 * a callback function - if an error occurs, the @a handler will be called
 * with two strings: an error message prefix, which will be zero, and
 * an error message.  @a handler might print it out, log it somewhere,
 * etc.
 *
 * Subversion 1.1 and later install their own handler internally, and
 * wrap the messages from Berkeley DB into the standard svn_error_t object,
 * making any information gained through this interface redundant.
 *
 * It is only worth using this function if your program will be used
 * with Subversion 1.0.
 *
 * This function connects to the Berkeley DB @c DBENV->set_errcall interface.
 * Since that interface supports only a single callback, Subversion's internal
 * callback is registered with Berkeley DB, and will forward notifications to
 * a user provided callback after performing its own processing.
 */
SVN_DEPRECATED
svn_error_t *
svn_fs_set_berkeley_errcall(svn_fs_t *fs,
                            void (*handler)(const char *errpfx,
                                            char *msg));

/** Set @a *logfiles to an array of <tt>const char *</tt> log file names
 * of Berkeley DB-based Subversion filesystem.
 *
 * If @a only_unused is @c TRUE, set @a *logfiles to an array which
 * contains only the names of Berkeley DB log files no longer in use
 * by the filesystem.  Otherwise, all log files (used and unused) are
 * returned.

 * This function wraps the Berkeley DB 'log_archive' function
 * called by the db_archive binary.  Repository administrators may
 * want to run this function periodically and delete the unused log
 * files, as a way of reclaiming disk space.
 */
svn_error_t *
svn_fs_berkeley_logfiles(apr_array_header_t **logfiles,
                         const char *path,
                         svn_boolean_t only_unused,
                         apr_pool_t *pool);


/**
 * The following functions are similar to their generic counterparts.
 *
 * In Subversion 1.2 and earlier, they only work on Berkeley DB filesystems.
 * In Subversion 1.3 and later, they perform largely as aliases for their
 * generic counterparts (with the exception of recover, which only gained
 * a generic counterpart in 1.5).
 *
 * @defgroup svn_fs_bdb_deprecated Berkeley DB filesystem compatibility
 * @{
 */

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
svn_fs_t *
svn_fs_new(apr_hash_t *fs_config,
           apr_pool_t *pool);

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
svn_error_t *
svn_fs_create_berkeley(svn_fs_t *fs,
                       const char *path);

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
svn_error_t *
svn_fs_open_berkeley(svn_fs_t *fs,
                     const char *path);

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
const char *
svn_fs_berkeley_path(svn_fs_t *fs,
                     apr_pool_t *pool);

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
svn_error_t *
svn_fs_delete_berkeley(const char *path,
                       apr_pool_t *pool);

/** @deprecated Provided for backward compatibility with the 1.0 API. */
SVN_DEPRECATED
svn_error_t *
svn_fs_hotcopy_berkeley(const char *src_path,
                        const char *dest_path,
                        svn_boolean_t clean_logs,
                        apr_pool_t *pool);

/** @deprecated Provided for backward compatibility with the 1.4 API. */
SVN_DEPRECATED
svn_error_t *
svn_fs_berkeley_recover(const char *path,
                        apr_pool_t *pool);
/** @} */

/** @} */


/** Filesystem Access Contexts.
 *
 * @since New in 1.2.
 *
 * At certain times, filesystem functions need access to temporary
 * user data.  For example, which user is changing a file?  If the
 * file is locked, has an appropriate lock-token been supplied?
 *
 * This temporary user data is stored in an "access context" object,
 * and the access context is then connected to the filesystem object.
 * Whenever a filesystem function requires information, it can pull
 * things out of the context as needed.
 *
 * @defgroup svn_fs_access_ctx Filesystem access contexts
 * @{
 */

/** An opaque object representing temporary user data. */
typedef struct svn_fs_access_t svn_fs_access_t;


/** Set @a *access_ctx to a new @c svn_fs_access_t object representing
 *  @a username, allocated in @a pool.  @a username is presumed to
 *  have been authenticated by the caller.
 *
 *  Make a deep copy of @a username.
 */
svn_error_t *
svn_fs_create_access(svn_fs_access_t **access_ctx,
                     const char *username,
                     apr_pool_t *pool);


/** Associate @a access_ctx with an open @a fs.
 *
 * This function can be run multiple times on the same open
 * filesystem, in order to change the filesystem access context for
 * different filesystem operations.  Pass a NULL value for @a
 * access_ctx to disassociate the current access context from the
 * filesystem.
 */
svn_error_t *
svn_fs_set_access(svn_fs_t *fs,
                  svn_fs_access_t *access_ctx);


/** Set @a *access_ctx to the current @a fs access context, or NULL if
 * there is no current fs access context.
 */
svn_error_t *
svn_fs_get_access(svn_fs_access_t **access_ctx,
                  svn_fs_t *fs);


/** Accessors for the access context: */

/** Set @a *username to the name represented by @a access_ctx. */
svn_error_t *
svn_fs_access_get_username(const char **username,
                           svn_fs_access_t *access_ctx);


/** Push a lock-token @a token associated with path @a path into the
 * context @a access_ctx.  The context remembers all tokens it
 * receives, and makes them available to fs functions.  The token and
 * path are not duplicated into @a access_ctx's pool; make sure the
 * token's lifetime is at least as long as @a access_ctx.
 *
 * @since New in 1.6. */
svn_error_t *
svn_fs_access_add_lock_token2(svn_fs_access_t *access_ctx,
                              const char *path,
                              const char *token);
/**
 * Same as svn_fs_access_add_lock_token2(), but with @a path set to value 1.
 *
 * @deprecated Provided for backward compatibility with the 1.1 API.
 */

SVN_DEPRECATED
svn_error_t *
svn_fs_access_add_lock_token(svn_fs_access_t *access_ctx,
                             const char *token);

/** @} */


/** Filesystem Nodes.
 *
 * In a Subversion filesystem, a `node' corresponds roughly to an
 * `inode' in a Unix filesystem:
 * - A node is either a file or a directory.
 * - A node's contents change over time.
 * - When you change a node's contents, it's still the same node; it's
 *   just been changed.  So a node's identity isn't bound to a specific
 *   set of contents.
 * - If you rename a node, it's still the same node, just under a
 *   different name.  So a node's identity isn't bound to a particular
 *   filename.
 *
 * A `node revision' refers to a node's contents at a specific point in
 * time.  Changing a node's contents always creates a new revision of that
 * node.  Once created, a node revision's contents never change.
 *
 * When we create a node, its initial contents are the initial revision of
 * the node.  As users make changes to the node over time, we create new
 * revisions of that same node.  When a user commits a change that deletes
 * a file from the filesystem, we don't delete the node, or any revision
 * of it --- those stick around to allow us to recreate prior revisions of
 * the filesystem.  Instead, we just remove the reference to the node
 * from the directory.
 *
 * @defgroup svn_fs_nodes Filesystem nodes
 * @{
 */

/** An object representing a node-id.  */
typedef struct svn_fs_id_t svn_fs_id_t;


/** Return -1, 0, or 1 if node revisions @a a and @a b are unrelated,
 * equivalent, or otherwise related (respectively).
 */
int
svn_fs_compare_ids(const svn_fs_id_t *a,
                   const svn_fs_id_t *b);



/** Return non-zero IFF the nodes associated with @a id1 and @a id2 are
 * related, else return zero.
 */
svn_boolean_t
svn_fs_check_related(const svn_fs_id_t *id1,
                     const svn_fs_id_t *id2);


/**
 * @note This function is not guaranteed to work with all filesystem
 * types.  There is currently no un-deprecated equivalent; contact the
 * Subversion developers if you have a need for it.
 *
 * @deprecated Provided for backward compatibility with the 1.0 API.
 */
SVN_DEPRECATED
svn_fs_id_t *
svn_fs_parse_id(const char *data,
                apr_size_t len,
                apr_pool_t *pool);


/** Return a Subversion string containing the unparsed form of the
 * node or node revision id @a id.  Allocate the string containing the
 * unparsed form in @a pool.
 */
svn_string_t *
svn_fs_unparse_id(const svn_fs_id_t *id,
                  apr_pool_t *pool);

/** @} */


/** Filesystem Transactions.
 *
 * To make a change to a Subversion filesystem:
 * - Create a transaction object, using svn_fs_begin_txn().
 * - Call svn_fs_txn_root(), to get the transaction's root directory.
 * - Make whatever changes you like in that tree.
 * - Commit the transaction, using svn_fs_commit_txn().
 *
 * The filesystem implementation guarantees that your commit will
 * either:
 * - succeed completely, so that all of the changes are committed to
 *   create a new revision of the filesystem, or
 * - fail completely, leaving the filesystem unchanged.
 *
 * Until you commit the transaction, any changes you make are
 * invisible.  Only when your commit succeeds do they become visible
 * to the outside world, as a new revision of the filesystem.
 *
 * If you begin a transaction, and then decide you don't want to make
 * the change after all (say, because your net connection with the
 * client disappeared before the change was complete), you can call
 * svn_fs_abort_txn(), to cancel the entire transaction; this
 * leaves the filesystem unchanged.
 *
 * The only way to change the contents of files or directories, or
 * their properties, is by making a transaction and creating a new
 * revision, as described above.  Once a revision has been committed, it
 * never changes again; the filesystem interface provides no means to
 * go back and edit the contents of an old revision.  Once history has
 * been recorded, it is set in stone.  Clients depend on this property
 * to do updates and commits reliably; proxies depend on this property
 * to cache changes accurately; and so on.
 *
 * There are two kinds of nodes in the filesystem: mutable, and
 * immutable.  Revisions in the filesystem consist entirely of
 * immutable nodes, whose contents never change.  A transaction in
 * progress, which the user is still constructing, uses mutable nodes
 * for those nodes which have been changed so far, and refers to
 * immutable nodes from existing revisions for portions of the tree
 * which haven't been changed yet in that transaction.
 *
 * Immutable nodes, as part of revisions, never refer to mutable
 * nodes, which are part of uncommitted transactions.  Mutable nodes
 * may refer to immutable nodes, or other mutable nodes.
 *
 * Note that the terms "immutable" and "mutable" describe whether or
 * not the nodes have been changed as part of a transaction --- not
 * the permissions on the nodes they refer to.  Even if you aren't
 * authorized to modify the filesystem's root directory, you might be
 * authorized to change some descendant of the root; doing so would
 * create a new mutable copy of the root directory.  Mutability refers
 * to the role of the node: part of an existing revision, or part of a
 * new one.  This is independent of your authorization to make changes
 * to a given node.
 *
 * Transactions are actually persistent objects, stored in the
 * database.  You can open a filesystem, begin a transaction, and
 * close the filesystem, and then a separate process could open the
 * filesystem, pick up the same transaction, and continue work on it.
 * When a transaction is successfully committed, it is removed from
 * the database.
 *
 * Every transaction is assigned a name.  You can open a transaction
 * by name, and resume work on it, or find out the name of a
 * transaction you already have open.  You can also list all the
 * transactions currently present in the database.
 *
 * You may assign properties to transactions; these are name/value
 * pairs.  When you commit a transaction, all of its properties become
 * unversioned revision properties of the new revision.  (There is one
 * exception: the svn:date property will be automatically set on new
 * transactions to the date that the transaction was created, and will
 * be overwritten when the transaction is committed by the current
 * time; changes to a transaction's svn:date property will not affect
 * its committed value.)
 *
 * Transaction names are guaranteed to contain only letters (upper-
 * and lower-case), digits, `-', and `.', from the ASCII character
 * set.
 *
 * The Subversion filesystem will make a best effort to not reuse
 * transaction names.  The Berkeley DB backend generates transaction
 * names using a sequence, or a counter, which is stored in the BDB
 * database.  Each new transaction increments the counter.  The
 * current value of the counter is not serialized into a filesystem
 * dump file, so dumping and restoring the repository will reset the
 * sequence and reuse transaction names.  The FSFS backend generates a
 * transaction name using the hostname, process ID and current time in
 * microseconds since 00:00:00 January 1, 1970 UTC.  So it is
 * extremely unlikely that a transaction name will be reused.
 *
 * @defgroup svn_fs_txns Filesystem transactions
 * @{
 */

/** The type of a Subversion transaction object.  */
typedef struct svn_fs_txn_t svn_fs_txn_t;


/** @defgroup svn_fs_begin_txn2_flags Bitmask flags for svn_fs_begin_txn2()
 * @since New in 1.2.
 * @{ */

/** Do on-the-fly out-of-dateness checks.  That is, an fs routine may
 * throw error if a caller tries to edit an out-of-date item in the
 * transaction.
 *
 * @warning ### Not yet implemented.
 */
#define SVN_FS_TXN_CHECK_OOD                     0x00001

/** Do on-the-fly lock checks.  That is, an fs routine may throw error
 * if a caller tries to edit a locked item without having rights to the lock.
 */
#define SVN_FS_TXN_CHECK_LOCKS                   0x00002
/** @} */

/**
 * Begin a new transaction on the filesystem @a fs, based on existing
 * revision @a rev.  Set @a *txn_p to a pointer to the new transaction.
 * When committed, this transaction will create a new revision.
 *
 * Allocate the new transaction in @a pool; when @a pool is freed, the new
 * transaction will be closed (neither committed nor aborted).
 *
 * @a flags determines transaction enforcement behaviors, and is composed
 * from the constants SVN_FS_TXN_* (@c SVN_FS_TXN_CHECK_OOD etc.).
 *
 * @note If you're building a txn for committing, you probably
 * don't want to call this directly.  Instead, call
 * svn_repos_fs_begin_txn_for_commit(), which honors the
 * repository's hook configurations.
 *
 * @since New in 1.2.
 */
svn_error_t *
svn_fs_begin_txn2(svn_fs_txn_t **txn_p,
                  svn_fs_t *fs,
                  svn_revnum_t rev,
                  apr_uint32_t flags,
                  apr_pool_t *pool);


/**
 * Same as svn_fs_begin_txn2(), but with @a flags set to 0.
 *
 * @deprecated Provided for backward compatibility with the 1.1 API.
 */
SVN_DEPRECATED
svn_error_t *
svn_fs_begin_txn(svn_fs_txn_t **txn_p,
                 svn_fs_t *fs,
                 svn_revnum_t rev,
                 apr_pool_t *pool);



/** Commit @a txn.
 *
 * @note You usually don't want to call this directly.
 * Instead, call svn_repos_fs_commit_txn(), which honors the
 * repository's hook configurations.
 *
 * If the transaction conflicts with other changes committed to the
 * repository, return an @c SVN_ERR_FS_CONFLICT error.  Otherwise, create
 * a new filesystem revision containing the changes made in @a txn,
 * storing that new revision number in @a *new_rev, and return zero.
 *
 * If @a conflict_p is non-zero, use it to provide details on any
 * conflicts encountered merging @a txn with the most recent committed
 * revisions.  If a conflict occurs, set @a *conflict_p to the path of
 * the conflict in @a txn, with the same lifetime as @a txn;
 * otherwise, set @a *conflict_p to NULL.
 *
 * If the commit succeeds, @a txn is invalid.
 *
 * If the commit fails, @a txn is still valid; you can make more
 * operations to resolve the conflict, or call svn_fs_abort_txn() to
 * abort the transaction.
 *
 * @note Success or failure of the commit of @a txn is determined by
 * examining the value of @a *new_rev upon this function's return.  If
 * the value is a valid revision number, the commit was successful,
 * even though a non-@c NULL function return value may indicate that
 * something else went wrong.
 */
svn_error_t *
svn_fs_commit_txn(const char **conflict_p,
                  svn_revnum_t *new_rev,
                  svn_fs_txn_t *txn,
                  apr_pool_t *pool);


/** Abort the transaction @a txn.  Any changes made in @a txn are
 * discarded, and the filesystem is left unchanged.  Use @a pool for
 * any necessary allocations.
 *
 * @note This function first sets the state of @a txn to "dead", and
 * then attempts to purge it and any related data from the filesystem.
 * If some part of the cleanup process fails, @a txn and some portion
 * of its data may remain in the database after this function returns.
 * Use svn_fs_purge_txn() to retry the transaction cleanup.
 */
svn_error_t *
svn_fs_abort_txn(svn_fs_txn_t *txn,
                 apr_pool_t *pool);


/** Cleanup the dead transaction in @a fs whose ID is @a txn_id.  Use
 * @a pool for all allocations.  If the transaction is not yet dead,
 * the error @c SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned.  (The
 * caller probably forgot to abort the transaction, or the cleanup
 * step of that abort failed for some reason.)
 */
svn_error_t *
svn_fs_purge_txn(svn_fs_t *fs,
                 const char *txn_id,
                 apr_pool_t *pool);


/** Set @a *name_p to the name of the transaction @a txn, as a
 * NULL-terminated string.  Allocate the name in @a pool.
 */
svn_error_t *
svn_fs_txn_name(const char **name_p,
                svn_fs_txn_t *txn,
                apr_pool_t *pool);

/** Return @a txn's base revision. */
svn_revnum_t
svn_fs_txn_base_revision(svn_fs_txn_t *txn);



/** Open the transaction named @a name in the filesystem @a fs.  Set @a *txn
 * to the transaction.
 *
 * If there is no such transaction, @c SVN_ERR_FS_NO_SUCH_TRANSACTION is
 * the error returned.
 *
 * Allocate the new transaction in @a pool; when @a pool is freed, the new
 * transaction will be closed (neither committed nor aborted).
 */
svn_error_t *
svn_fs_open_txn(svn_fs_txn_t **txn,
                svn_fs_t *fs,
                const char *name,
                apr_pool_t *pool);


/** Set @a *names_p to an array of <tt>const char *</tt> ids which are the
 * names of all the currently active transactions in the filesystem @a fs.
 * Allocate the array in @a pool.
 */
svn_error_t *
svn_fs_list_transactions(apr_array_header_t **names_p,
                         svn_fs_t *fs,
                         apr_pool_t *pool);

/* Transaction properties */

/** Set @a *value_p to the value of the property named @a propname on
 * transaction @a txn.  If @a txn has no property by that name, set
 * @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *
svn_fs_txn_prop(svn_string_t **value_p,
                svn_fs_txn_t *txn,
                const char *propname,
                apr_pool_t *pool);


/** Set @a *table_p to the entire property list of transaction @a txn, as
 * an APR hash table allocated in @a pool.  The resulting table maps property
 * names to pointers to @c svn_string_t objects containing the property value.
 */
svn_error_t *
svn_fs_txn_proplist(apr_hash_t **table_p,
                    svn_fs_txn_t *txn,
                    apr_pool_t *pool);


/** Change a transactions @a txn's property's value, or add/delete a
 * property.  @a name is the name of the property to change, and @a value
 * is the new value of the property, or zero if the property should be
 * removed altogether.  Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_change_txn_prop(svn_fs_txn_t *txn,
                       const char *name,
                       const svn_string_t *value,
                       apr_pool_t *pool);


/** Change, add, and/or delete transaction property values in
 * transaction @a txn.  @a props is an array of <tt>svn_prop_t</tt>
 * elements.  This is equivalent to calling svn_fs_change_txp_prop
 * multiple times with the @c name and @c value fields of each
 * successive <tt>svn_prop_t</tt>, but may be more efficient.
 * (Properties not mentioned are left alone.)  Do any necessary
 * temporary allocation in @a pool.
 *
 * @since New in 1.5.
 */
svn_error_t *
svn_fs_change_txn_props(svn_fs_txn_t *txn,
                        apr_array_header_t *props,
                        apr_pool_t *pool);

/** @} */


/** Roots.
 *
 * An @c svn_fs_root_t object represents the root directory of some
 * revision or transaction in a filesystem.  To refer to particular
 * node, you provide a root, and a directory path relative that root.
 *
 * @defgroup svn_fs_roots Filesystem roots
 * @{
 */

/** The Filesystem Root object. */
typedef struct svn_fs_root_t svn_fs_root_t;


/** Set @a *root_p to the root directory of revision @a rev in filesystem
 * @a fs.  Allocate @a *root_p in @a pool.
 */
svn_error_t *
svn_fs_revision_root(svn_fs_root_t **root_p,
                     svn_fs_t *fs,
                     svn_revnum_t rev,
                     apr_pool_t *pool);


/** Set @a *root_p to the root directory of @a txn.  Allocate @a *root_p in
 * @a pool.
 */
svn_error_t *
svn_fs_txn_root(svn_fs_root_t **root_p,
                svn_fs_txn_t *txn,
                apr_pool_t *pool);


/** Free the root directory @a root.  Simply clearing or destroying the
 * pool @a root was allocated in will have the same effect as calling
 * this function.
 */
void
svn_fs_close_root(svn_fs_root_t *root);


/** Return the filesystem to which @a root belongs.  */
svn_fs_t *
svn_fs_root_fs(svn_fs_root_t *root);


/** Return @c TRUE iff @a root is a transaction root.  */
svn_boolean_t
svn_fs_is_txn_root(svn_fs_root_t *root);

/** Return @c TRUE iff @a root is a revision root.  */
svn_boolean_t
svn_fs_is_revision_root(svn_fs_root_t *root);


/** If @a root is the root of a transaction, return the name of the
 * transaction, allocated in @a pool; otherwise, return NULL.
 */
const char *
svn_fs_txn_root_name(svn_fs_root_t *root,
                     apr_pool_t *pool);

/** If @a root is the root of a transaction, return the number of the
 * revision on which is was based when created.  Otherwise, return @c
 * SVN_INVALID_REVNUM.
 *
 * @since New in 1.5.
 */
svn_revnum_t
svn_fs_txn_root_base_revision(svn_fs_root_t *root);

/** If @a root is the root of a revision, return the revision number.
 * Otherwise, return @c SVN_INVALID_REVNUM.
 */
svn_revnum_t
svn_fs_revision_root_revision(svn_fs_root_t *root);

/** @} */


/** Directory entry names and directory paths.
 *
 * Here are the rules for directory entry names, and directory paths:
 *
 * A directory entry name is a Unicode string encoded in UTF-8, and
 * may not contain the NULL character (U+0000).  The name should be in
 * Unicode canonical decomposition and ordering.  No directory entry
 * may be named '.', '..', or the empty string.  Given a directory
 * entry name which fails to meet these requirements, a filesystem
 * function returns an SVN_ERR_FS_PATH_SYNTAX error.
 *
 * A directory path is a sequence of zero or more directory entry
 * names, separated by slash characters (U+002f), and possibly ending
 * with slash characters.  Sequences of two or more consecutive slash
 * characters are treated as if they were a single slash.  If a path
 * ends with a slash, it refers to the same node it would without the
 * slash, but that node must be a directory, or else the function
 * returns an SVN_ERR_FS_NOT_DIRECTORY error.
 *
 * A path consisting of the empty string, or a string containing only
 * slashes, refers to the root directory.
 *
 * @defgroup svn_fs_directories Filesystem directories
 * @{
 */



/** The kind of change that occurred on the path. */
typedef enum
{
  /** path modified in txn */
  svn_fs_path_change_modify = 0,

  /** path added in txn */
  svn_fs_path_change_add,

  /** path removed in txn */
  svn_fs_path_change_delete,

  /** path removed and re-added in txn */
  svn_fs_path_change_replace,

  /** ignore all previous change items for path (internal-use only) */
  svn_fs_path_change_reset

} svn_fs_path_change_kind_t;

/** Change descriptor.
 *
 * @note Fields may be added to the end of this structure in future
 * versions.  Therefore, to preserve binary compatibility, users
 * should not directly allocate structures of this type.
 *
 * @since New in 1.6. */
typedef struct svn_fs_path_change2_t
{
  /** node revision id of changed path */
  const svn_fs_id_t *node_rev_id;

  /** kind of change */
  svn_fs_path_change_kind_t change_kind;

  /** were there text mods? */
  svn_boolean_t text_mod;

  /** were there property mods? */
  svn_boolean_t prop_mod;

  /** what node kind is the path?
      (Note: it is legal for this to be @c svn_node_unknown.) */
  svn_node_kind_t node_kind;

  /** Copyfrom revision and path; this is only valid if copyfrom_known
   * is true. */
  svn_boolean_t copyfrom_known;
  svn_revnum_t copyfrom_rev;
  const char *copyfrom_path;

  /* NOTE! Please update svn_fs_path_change2_create() when adding new
     fields here. */
} svn_fs_path_change2_t;


/** Similar to @c svn_fs_path_change2_t, but without kind and copyfrom
 * information.
 *
 * @deprecated Provided for backwards compatibility with the 1.5 API.
 */

typedef struct svn_fs_path_change_t
{
  /** node revision id of changed path */
  const svn_fs_id_t *node_rev_id;

  /** kind of change */
  svn_fs_path_change_kind_t change_kind;

  /** were there text mods? */
  svn_boolean_t text_mod;

  /** were there property mods? */
  svn_boolean_t prop_mod;

} svn_fs_path_change_t;

/**
 * Allocate an @c svn_fs_path_change2_t structure in @a pool, initialize and
 * return it.
 *
 * Set the @c node_rev_id field of the created struct to @a node_rev_id, and
 * @c change_kind to @a change_kind.  Set all other fields to their
 * @c _unknown, @c NULL or invalid value, respectively.
 *
 * @since New in 1.6.
 */
svn_fs_path_change2_t *
svn_fs_path_change2_create(const svn_fs_id_t *node_rev_id,
                           svn_fs_path_change_kind_t change_kind,
                           apr_pool_t *pool);

/** Determine what has changed under a @a root.
 *
 * Allocate and return a hash @a *changed_paths2_p containing descriptions
 * of the paths changed under @a root.  The hash is keyed with
 * <tt>const char *</tt> paths, and has @c svn_fs_path_change2_t * values.
 *
 * Callers can assume that this function takes time proportional to
 * the amount of data output, and does not need to do tree crawls;
 * however, it is possible that some of the @c node_kind fields in the
 * @c svn_fs_path_change2_t * values will be @c svn_node_unknown or
 * that and some of the @c copyfrom_known fields will be FALSE.
 *
 * Use @c pool for all allocations, including the hash and its values.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_fs_paths_changed2(apr_hash_t **changed_paths2_p,
                      svn_fs_root_t *root,
                      apr_pool_t *pool);


/** Same as svn_fs_paths_changed2(), only with @c svn_fs_path_change_t * values
 * in the hash (and thus no kind or copyfrom data).
 *
 * @deprecated Provided for backward compatibility with the 1.5 API.
 */
SVN_DEPRECATED
svn_error_t *
svn_fs_paths_changed(apr_hash_t **changed_paths_p,
                     svn_fs_root_t *root,
                     apr_pool_t *pool);

/** @} */


/* Operations appropriate to all kinds of nodes.  */

/** Set @a *kind_p to the type of node present at @a path under @a
 * root.  If @a path does not exist under @a root, set @a *kind_p to @c
 * svn_node_none.  Use @a pool for temporary allocation.
 */
svn_error_t *
svn_fs_check_path(svn_node_kind_t *kind_p,
                  svn_fs_root_t *root,
                  const char *path,
                  apr_pool_t *pool);


/** An opaque node history object. */
typedef struct svn_fs_history_t svn_fs_history_t;


/** Set @a *history_p to an opaque node history object which
 * represents @a path under @a root.  @a root must be a revision root.
 * Use @a pool for all allocations.
 */
svn_error_t *
svn_fs_node_history(svn_fs_history_t **history_p,
                    svn_fs_root_t *root,
                    const char *path,
                    apr_pool_t *pool);


/** Set @a *prev_history_p to an opaque node history object which
 * represents the previous (or "next oldest") interesting history
 * location for the filesystem node represented by @a history, or @c
 * NULL if no such previous history exists.  If @a cross_copies is @c
 * FALSE, also return @c NULL if stepping backwards in history to @a
 * *prev_history_p would cross a filesystem copy operation.
 *
 * @note If this is the first call to svn_fs_history_prev() for the @a
 * history object, it could return a history object whose location is
 * the same as the original.  This will happen if the original
 * location was an interesting one (where the node was modified, or
 * took place in a copy event).  This behavior allows looping callers
 * to avoid the calling svn_fs_history_location() on the object
 * returned by svn_fs_node_history(), and instead go ahead and begin
 * calling svn_fs_history_prev().
 *
 * @note This function uses node-id ancestry alone to determine
 * modifiedness, and therefore does NOT claim that in any of the
 * returned revisions file contents changed, properties changed,
 * directory entries lists changed, etc.
 *
 * @note The revisions returned for @a path will be older than or
 * the same age as the revision of that path in @a root.  That is, if
 * @a root is a revision root based on revision X, and @a path was
 * modified in some revision(s) younger than X, those revisions
 * younger than X will not be included for @a path.  */
svn_error_t *
svn_fs_history_prev(svn_fs_history_t **prev_history_p,
                    svn_fs_history_t *history,
                    svn_boolean_t cross_copies,
                    apr_pool_t *pool);


/** Set @a *path and @a *revision to the path and revision,
 * respectively, of the @a history object.  Use @a pool for all
 * allocations.
 */
svn_error_t *
svn_fs_history_location(const char **path,
                        svn_revnum_t *revision,
                        svn_fs_history_t *history,
                        apr_pool_t *pool);


/** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_is_dir(svn_boolean_t *is_dir,
              svn_fs_root_t *root,
              const char *path,
              apr_pool_t *pool);


/** Set @a *is_file to @c TRUE iff @a path in @a root is a file.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_is_file(svn_boolean_t *is_file,
               svn_fs_root_t *root,
               const char *path,
               apr_pool_t *pool);


/** Get the id of a node.
 *
 * Set @a *id_p to the node revision ID of @a path in @a root, allocated in
 * @a pool.
 *
 * If @a root is the root of a transaction, keep in mind that other
 * changes to the transaction can change which node @a path refers to,
 * and even whether the path exists at all.
 */
svn_error_t *
svn_fs_node_id(const svn_fs_id_t **id_p,
               svn_fs_root_t *root,
               const char *path,
               apr_pool_t *pool);

/** Set @a *revision to the revision in which @a path under @a root was
 * created.  Use @a pool for any temporary allocations.  @a *revision will
 * be set to @c SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes
 * under a transaction root).  Note that the root of an unmodified transaction
 * is not itself considered to be modified; in that case, return the revision
 * upon which the transaction was based.
 */
svn_error_t *
svn_fs_node_created_rev(svn_revnum_t *revision,
                        svn_fs_root_t *root,
                        const char *path,
                        apr_pool_t *pool);

/** Set @a *revision to the revision in which the line of history
 * represented by @a path under @a root originated.  Use @a pool for
 * any temporary allocations.  If @a root is a transaction root, @a
 * *revision will be set to @c SVN_INVALID_REVNUM for any nodes newly
 * added in that transaction (brand new files or directories created
 * using @c svn_fs_make_dir or @c svn_fs_make_file).
 *
 * @since New in 1.5.
 */
svn_error_t *
svn_fs_node_origin_rev(svn_revnum_t *revision,
                       svn_fs_root_t *root,
                       const char *path,
                       apr_pool_t *pool);

/** Set @a *created_path to the path at which @a path under @a root was
 * created.  Use @a pool for all allocations.  Callers may use this
 * function in conjunction with svn_fs_node_created_rev() to perform a
 * reverse lookup of the mapping of (path, revision) -> node-id that
 * svn_fs_node_id() performs.
 */
svn_error_t *
svn_fs_node_created_path(const char **created_path,
                         svn_fs_root_t *root,
                         const char *path,
                         apr_pool_t *pool);


/** Set @a *value_p to the value of the property named @a propname of
 * @a path in @a root.  If the node has no property by that name, set
 * @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *
svn_fs_node_prop(svn_string_t **value_p,
                 svn_fs_root_t *root,
                 const char *path,
                 const char *propname,
                 apr_pool_t *pool);


/** Set @a *table_p to the entire property list of @a path in @a root,
 * as an APR hash table allocated in @a pool.  The resulting table maps
 * property names to pointers to @c svn_string_t objects containing the
 * property value.
 */
svn_error_t *
svn_fs_node_proplist(apr_hash_t **table_p,
                     svn_fs_root_t *root,
                     const char *path,
                     apr_pool_t *pool);


/** Change a node's property's value, or add/delete a property.
 *
 * - @a root and @a path indicate the node whose property should change.
 *   @a root must be the root of a transaction, not the root of a revision.
 * - @a name is the name of the property to change.
 * - @a value is the new value of the property, or zero if the property should
 *   be removed altogether.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_change_node_prop(svn_fs_root_t *root,
                        const char *path,
                        const char *name,
                        const svn_string_t *value,
                        apr_pool_t *pool);


/** Determine if the properties of two path/root combinations are different.
 *
 * Set @a *changed_p to 1 if the properties at @a path1 under @a root1 differ
 * from those at @a path2 under @a root2, or set it to 0 if they are the
 * same.  Both paths must exist under their respective roots, and both
 * roots must be in the same filesystem.
 */
svn_error_t *
svn_fs_props_changed(svn_boolean_t *changed_p,
                     svn_fs_root_t *root1,
                     const char *path1,
                     svn_fs_root_t *root2,
                     const char *path2,
                     apr_pool_t *pool);


/** Discover a node's copy ancestry, if any.
 *
 * If the node at @a path in @a root was copied from some other node, set
 * @a *rev_p and @a *path_p to the revision and path of the other node,
 * allocating @a *path_p in @a pool.
 *
 * Else if there is no copy ancestry for the node, set @a *rev_p to
 * @c SVN_INVALID_REVNUM and @a *path_p to NULL.
 *
 * If an error is returned, the values of @a *rev_p and @a *path_p are
 * undefined, but otherwise, if one of them is set as described above,
 * you may assume the other is set correspondingly.
 *
 * @a root may be a revision root or a transaction root.
 *
 * Notes:
 *    - Copy ancestry does not descend.  After copying directory D to
 *      E, E will have copy ancestry referring to D, but E's children
 *      may not.  See also svn_fs_copy().
 *
 *    - Copy ancestry *under* a copy is preserved.  That is, if you
 *      copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then
 *      /G/pi2 will still have copy ancestry pointing to /A/D/G/pi.
 *      We don't know if this is a feature or a bug yet; if it turns
 *      out to be a bug, then the fix is to make svn_fs_copied_from()
 *      observe the following logic, which currently callers may
 *      choose to follow themselves: if node X has copy history, but
 *      its ancestor A also has copy history, then you may ignore X's
 *      history if X's revision-of-origin is earlier than A's --
 *      because that would mean that X's copy history was preserved in
 *      a copy-under-a-copy scenario.  If X's revision-of-origin is
 *      the same as A's, then it was copied under A during the same
 *      transaction that created A.  (X's revision-of-origin cannot be
 *      greater than A's, if X has copy history.)  @todo See how
 *      people like this, it can always be hidden behind the curtain
 *      if necessary.
 *
 *    - Copy ancestry is not stored as a regular subversion property
 *      because it is not inherited.  Copying foo to bar results in a
 *      revision of bar with copy ancestry; but committing a text
 *      change to bar right after that results in a new revision of
 *      bar without copy ancestry.
 */
svn_error_t *
svn_fs_copied_from(svn_revnum_t *rev_p,
                   const char **path_p,
                   svn_fs_root_t *root,
                   const char *path,
                   apr_pool_t *pool);


/** Set @a *root_p and @a *path_p to the revision root and path of the
 * destination of the most recent copy event that caused @a path to
 * exist where it does in @a root, or to NULL if no such copy exists.
 * When non-NULL, allocate @a *root_p and @a *path_p in @a pool.
 *
 * @a *path_p might be a parent of @a path, rather than @a path
 * itself.  However, it will always be the deepest relevant path.
 * That is, if a copy occurs underneath another copy in the same txn,
 * this function makes sure to set @a *path_p to the longest copy
 * destination path that is still a parent of or equal to @a path.
 *
 * @since New in 1.3.
 */
svn_error_t *
svn_fs_closest_copy(svn_fs_root_t **root_p,
                    const char **path_p,
                    svn_fs_root_t *root,
                    const char *path,
                    apr_pool_t *pool);


/** Retrieve mergeinfo for multiple nodes.
 *
 * @a *catalog is a catalog for @a paths.  It will never be @c NULL,
 * but may be empty.
 *
 * @a root is revision root to use when looking up paths.
 *
 * @a paths are the paths you are requesting information for.
 *
 * @a inherit indicates whether to retrieve explicit,
 * explicit-or-inherited, or only inherited mergeinfo.
 *
 * If @a include_descendants is TRUE, then additionally return the
 * mergeinfo for any descendant of any element of @a paths which has
 * the @c SVN_PROP_MERGEINFO property explicitly set on it.  (Note
 * that inheritance is only taken into account for the elements in @a
 * paths; descendants of the elements in @a paths which get their
 * mergeinfo via inheritance are not included in @a *mergeoutput.)
 *
 * Do any necessary temporary allocation in @a pool.
 *
 * @since New in 1.5.
 */
svn_error_t *
svn_fs_get_mergeinfo(svn_mergeinfo_catalog_t *catalog,
                     svn_fs_root_t *root,
                     const apr_array_header_t *paths,
                     svn_mergeinfo_inheritance_t inherit,
                     svn_boolean_t include_descendants,
                     apr_pool_t *pool);

/** Merge changes between two nodes into a third node.
 *
 * Given nodes @a source and @a target, and a common ancestor @a ancestor,
 * modify @a target to contain all the changes made between @a ancestor and
 * @a source, as well as the changes made between @a ancestor and @a target.
 * @a target_root must be the root of a transaction, not a revision.
 *
 * @a source, @a target, and @a ancestor are generally directories; this
 * function recursively merges the directories' contents.  If they are
 * files, this function simply returns an error whenever @a source,
 * @a target, and @a ancestor are all distinct node revisions.
 *
 * If there are differences between @a ancestor and @a source that conflict
 * with changes between @a ancestor and @a target, this function returns an
 * @c SVN_ERR_FS_CONFLICT error.
 *
 * If the merge is successful, @a target is left in the merged state, and
 * the base root of @a target's txn is set to the root node of @a source.
 * If an error is returned (whether for conflict or otherwise), @a target
 * is left unaffected.
 *
 * If @a conflict_p is non-NULL, then: a conflict error sets @a *conflict_p
 * to the name of the node in @a target which couldn't be merged,
 * otherwise, success sets @a *conflict_p to NULL.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_merge(const char **conflict_p,
             svn_fs_root_t *source_root,
             const char *source_path,
             svn_fs_root_t *target_root,
             const char *target_path,
             svn_fs_root_t *ancestor_root,
             const char *ancestor_path,
             apr_pool_t *pool);



/* Directories.  */


/** The type of a Subversion directory entry.  */
typedef struct svn_fs_dirent_t
{

  /** The name of this directory entry.  */
  const char *name;

  /** The node revision ID it names.  */
  const svn_fs_id_t *id;

  /** The node kind. */
  svn_node_kind_t kind;

} svn_fs_dirent_t;


/** Set @a *entries_p to a newly allocated APR hash table containing the
 * entries of the directory at @a path in @a root.  The keys of the table
 * are entry names, as byte strings, excluding the final NULL
 * character; the table's values are pointers to @c svn_fs_dirent_t
 * structures.  Allocate the table and its contents in @a pool.
 */
svn_error_t *
svn_fs_dir_entries(apr_hash_t **entries_p,
                   svn_fs_root_t *root,
                   const char *path,
                   apr_pool_t *pool);


/** Create a new directory named @a path in @a root.  The new directory has
 * no entries, and no properties.  @a root must be the root of a transaction,
 * not a revision.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_make_dir(svn_fs_root_t *root,
                const char *path,
                apr_pool_t *pool);


/** Delete the node named @a path in @a root.  If the node being deleted is
 * a directory, its contents will be deleted recursively.  @a root must be
 * the root of a transaction, not of a revision.  Use @a pool for
 * temporary allocation.
 *
 * This function may be more efficient than making the equivalent
 * series of calls to svn_fs_delete(), because it takes advantage of the
 * fact that, to delete an immutable subtree, shared with some
 * committed revision, you need only remove the directory entry.  The
 * dumb algorithm would recurse into the subtree and end up cloning
 * each non-empty directory it contains, only to delete it later.
 *
 * If return @c SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is
 * missing from its parent, that is, the final target of the deletion
 * is missing.
 *
 * Attempting to remove the root dir also results in an error,
 * @c SVN_ERR_FS_ROOT_DIR, even if the dir is empty.
 */
svn_error_t *
svn_fs_delete(svn_fs_root_t *root,
              const char *path,
              apr_pool_t *pool);


/** Create a copy of @a from_path in @a from_root named @a to_path in
 * @a to_root.  If @a from_path in @a from_root is a directory, copy the
 * tree it refers to recursively.
 *
 * The copy will remember its source; use svn_fs_copied_from() to
 * access this information.
 *
 * @a to_root must be the root of a transaction; @a from_root must be the
 * root of a revision.  (Requiring @a from_root to be the root of a
 * revision makes the implementation trivial: there is no detectable
 * difference (modulo node revision ID's) between copying @a from and
 * simply adding a reference to it.  So the operation takes place in
 * constant time.  However, there's no reason not to extend this to
 * mutable nodes --- it's just more code.)  Further, @a to_root and @a
 * from_root must represent the same filesystem.
 *
 * @note To do a copy without preserving copy history, use
 * svn_fs_revision_link().
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_copy(svn_fs_root_t *from_root,
            const char *from_path,
            svn_fs_root_t *to_root,
            const char *to_path,
            apr_pool_t *pool);


/** Like svn_fs_copy(), but doesn't record copy history, and preserves
 * the PATH.  You cannot use svn_fs_copied_from() later to find out
 * where this copy came from.
 *
 * Use svn_fs_revision_link() in situations where you don't care
 * about the copy history, and where @a to_path and @a from_path are
 * the same, because it is cheaper than svn_fs_copy().
 */
svn_error_t *
svn_fs_revision_link(svn_fs_root_t *from_root,
                     svn_fs_root_t *to_root,
                     const char *path,
                     apr_pool_t *pool);

/* Files.  */

/** Set @a *length_p to the length of the file @a path in @a root, in bytes.
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_file_length(svn_filesize_t *length_p,
                   svn_fs_root_t *root,
                   const char *path,
                   apr_pool_t *pool);


/** Set @a *checksum to the checksum of type @a kind for the file @a path.
 * @a *checksum will be allocated out of @a pool, which will also be used
 * for temporary allocations.
 *
 * If the filesystem does not have a prerecorded checksum of @a kind for
 * @a path, and @a force is not TRUE, do not calculate a checksum
 * dynamically, just put NULL into @a checksum.  (By convention, the NULL
 * checksum is considered to match any checksum.)
 *
 * Notes:
 *
 * You might wonder, why do we only provide this interface for file
 * contents, and not for properties or directories?
 *
 * The answer is that property lists and directory entry lists are
 * essentially data structures, not text.  We serialize them for
 * transmission, but there is no guarantee that the consumer will
 * parse them into the same form, or even the same order, as the
 * producer.  It's difficult to find a checksumming method that
 * reaches the same result given such variation in input.  (I suppose
 * we could calculate an independent MD5 sum for each propname and
 * value, and XOR them together; same with directory entry names.
 * Maybe that's the solution?)  Anyway, for now we punt.  The most
 * important data, and the only data that goes through svndiff
 * processing, is file contents, so that's what we provide
 * checksumming for.
 *
 * Internally, of course, the filesystem checksums everything, because
 * it has access to the lowest level storage forms: strings behind
 * representations.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_fs_file_checksum(svn_checksum_t **checksum,
                     svn_checksum_kind_t kind,
                     svn_fs_root_t *root,
                     const char *path,
                     svn_boolean_t force,
                     apr_pool_t *pool);

/**
 * Same as svn_fs_file_checksum(), only always put the MD5 checksum of file
 * @a path into @a digest, which should point to @c APR_MD5_DIGESTSIZE bytes
 * of storage.  If the checksum doesn't exist, put all 0's into @a digest.
 *
 * @deprecated Provided for backward compatibility with the 1.5 API.
 */
SVN_DEPRECATED
svn_error_t *
svn_fs_file_md5_checksum(unsigned char digest[],
                         svn_fs_root_t *root,
                         const char *path,
                         apr_pool_t *pool);


/** Set @a *contents to a readable generic stream that will yield the
 * contents of the file @a path in @a root.  Allocate the stream in
 * @a pool.  You can only use @a *contents for as long as the underlying
 * filesystem is open.  If @a path is not a file, return
 * @c SVN_ERR_FS_NOT_FILE.
 *
 * If @a root is the root of a transaction, it is possible that the
 * contents of the file @a path will change between calls to
 * svn_fs_file_contents().  In that case, the result of reading from
 * @a *contents is undefined.
 *
 * ### @todo kff: I am worried about lifetime issues with this pool vs
 * the trail created farther down the call stack.  Trace this function
 * to investigate...
 */
svn_error_t *
svn_fs_file_contents(svn_stream_t **contents,
                     svn_fs_root_t *root,
                     const char *path,
                     apr_pool_t *pool);


/** Create a new file named @a path in @a root.  The file's initial contents
 * are the empty string, and it has no properties.  @a root must be the
 * root of a transaction, not a revision.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_make_file(svn_fs_root_t *root,
                 const char *path,
                 apr_pool_t *pool);


/** Apply a text delta to the file @a path in @a root.  @a root must be the
 * root of a transaction, not a revision.
 *
 * Set @a *contents_p to a function ready to receive text delta windows
 * describing how to change the file's contents, relative to its
 * current contents.  Set @a *contents_baton_p to a baton to pass to
 * @a *contents_p.
 *
 * If @a path does not exist in @a root, return an error.  (You cannot use
 * this routine to create new files;  use svn_fs_make_file() to create
 * an empty file first.)
 *
 * @a base_checksum is the hex MD5 digest for the base text against
 * which the delta is to be applied; it is ignored if NULL, and may be
 * ignored even if not NULL.  If it is not ignored, it must match the
 * checksum of the base text against which svndiff data is being
 * applied; if not, svn_fs_apply_textdelta() or the @a *contents_p call
 * which detects the mismatch will return the error
 * @c SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
 * still be an error if @a base_checksum is neither NULL nor the
 * checksum of the empty string).
 *
 * @a result_checksum is the hex MD5 digest for the fulltext that
 * results from this delta application.  It is ignored if NULL, but if
 * not NULL, it must match the checksum of the result; if it does not,
 * then the @a *contents_p call which detects the mismatch will return
 * the error @c SVN_ERR_CHECKSUM_MISMATCH.
 *
 * The caller must send all delta windows including the terminating
 * NULL window to @a *contents_p before making further changes to the
 * transaction.
 *
 * Do temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_apply_textdelta(svn_txdelta_window_handler_t *contents_p,
                       void **contents_baton_p,
                       svn_fs_root_t *root,
                       const char *path,
                       const char *base_checksum,
                       const char *result_checksum,
                       apr_pool_t *pool);


/** Write data directly to the file @a path in @a root.  @a root must be the
 * root of a transaction, not a revision.
 *
 * Set @a *contents_p to a stream ready to receive full textual data.
 * When the caller closes this stream, the data replaces the previous
 * contents of the file.  The caller must write all file data and close
 * the stream before making further changes to the transaction.
 *
 * If @a path does not exist in @a root, return an error.  (You cannot use
 * this routine to create new files;  use svn_fs_make_file() to create
 * an empty file first.)
 *
 * @a result_checksum is the hex MD5 digest for the final fulltext
 * written to the stream.  It is ignored if NULL, but if not null, it
 * must match the checksum of the result; if it does not, then the @a
 * *contents_p call which detects the mismatch will return the error
 * @c SVN_ERR_CHECKSUM_MISMATCH.
 *
 * Do any necessary temporary allocation in @a pool.
 *
 * ### This is like svn_fs_apply_textdelta(), but takes the text
 * straight.  It is currently used only by the loader, see
 * libsvn_repos/load.c.  It should accept a checksum, of course, which
 * would come from an (optional) header in the dump file.  See
 * http://subversion.tigris.org/issues/show_bug.cgi?id=1102 for more.
 */
svn_error_t *
svn_fs_apply_text(svn_stream_t **contents_p,
                  svn_fs_root_t *root,
                  const char *path,
                  const char *result_checksum,
                  apr_pool_t *pool);


/** Check if the contents of two root/path combos have changed.
 *
 * Set @a *changed_p to 1 if the contents at @a path1 under @a root1 differ
 * from those at @a path2 under @a root2, or set it to 0 if they are the
 * same.  Both paths must exist under their respective roots, and both
 * roots must be in the same filesystem.
 */
svn_error_t *
svn_fs_contents_changed(svn_boolean_t *changed_p,
                        svn_fs_root_t *root1,
                        const char *path1,
                        svn_fs_root_t *root2,
                        const char *path2,
                        apr_pool_t *pool);



/* Filesystem revisions.  */


/** Set @a *youngest_p to the number of the youngest revision in filesystem
 * @a fs.  Use @a pool for all temporary allocation.
 *
 * The oldest revision in any filesystem is numbered zero.
 */
svn_error_t *
svn_fs_youngest_rev(svn_revnum_t *youngest_p,
                    svn_fs_t *fs,
                    apr_pool_t *pool);


/** Provide filesystem @a fs the opportunity to compress storage relating to
 * associated with  @a revision in filesystem @a fs.  Use @a pool for all
 * allocations.
 *
 * @note This can be a time-consuming process, depending the breadth
 * of the changes made in @a revision, and the depth of the history of
 * those changed paths.  This may also be a no op.
 */
svn_error_t *
svn_fs_deltify_revision(svn_fs_t *fs,
                        svn_revnum_t revision,
                        apr_pool_t *pool);


/** Set @a *value_p to the value of the property named @a propname on
 * revision @a rev in the filesystem @a fs.  If @a rev has no property by
 * that name, set @a *value_p to zero.  Allocate the result in @a pool.
 */
svn_error_t *
svn_fs_revision_prop(svn_string_t **value_p,
                     svn_fs_t *fs,
                     svn_revnum_t rev,
                     const char *propname,
                     apr_pool_t *pool);


/** Set @a *table_p to the entire property list of revision @a rev in
 * filesystem @a fs, as an APR hash table allocated in @a pool.  The table
 * maps <tt>char *</tt> property names to @c svn_string_t * values; the names
 * and values are allocated in @a pool.
 */
svn_error_t *
svn_fs_revision_proplist(apr_hash_t **table_p,
                         svn_fs_t *fs,
                         svn_revnum_t rev,
                         apr_pool_t *pool);


/** Change a revision's property's value, or add/delete a property.
 *
 * - @a fs is a filesystem, and @a rev is the revision in that filesystem
 *   whose property should change.
 * - @a name is the name of the property to change.
 * - @a value is the new value of the property, or zero if the property should
 *   be removed altogether.
 *
 * Note that revision properties are non-historied --- you can change
 * them after the revision has been committed.  They are not protected
 * via transactions.
 *
 * Do any necessary temporary allocation in @a pool.
 */
svn_error_t *
svn_fs_change_rev_prop(svn_fs_t *fs,
                       svn_revnum_t rev,
                       const char *name,
                       const svn_string_t *value,
                       apr_pool_t *pool);



/* Computing deltas.  */


/** Set @a *stream_p to a pointer to a delta stream that will turn the
 * contents of the file @a source into the contents of the file @a target.
 * If @a source_root is zero, use a file with zero length as the source.
 *
 * This function does not compare the two files' properties.
 *
 * Allocate @a *stream_p, and do any necessary temporary allocation, in
 * @a pool.
 */
svn_error_t *
svn_fs_get_file_delta_stream(svn_txdelta_stream_t **stream_p,
                             svn_fs_root_t *source_root,
                             const char *source_path,
                             svn_fs_root_t *target_root,
                             const char *target_path,
                             apr_pool_t *pool);



/* UUID manipulation. */

/** Populate @a *uuid with the UUID associated with @a fs.  Allocate
    @a *uuid in @a pool.  */
svn_error_t *
svn_fs_get_uuid(svn_fs_t *fs,
                const char **uuid,
                apr_pool_t *pool);


/** If not @c NULL, associate @a *uuid with @a fs.  Otherwise (if @a
 * uuid is @c NULL), generate a new UUID for @a fs.  Use @a pool for
 * any scratchwork.
 */
svn_error_t *
svn_fs_set_uuid(svn_fs_t *fs,
                const char *uuid,
                apr_pool_t *pool);


/* Non-historical properties.  */

/* [[Yes, do tell.]] */



/** @defgroup svn_fs_locks Filesystem locks
 * @{
 * @since New in 1.2. */

/** A lock represents one user's exclusive right to modify a path in a
 * filesystem.  In order to create or destroy a lock, a username must
 * be associated with the filesystem's access context (see @c
 * svn_fs_access_t).
 *
 * When a lock is created, a 'lock-token' is returned.  The lock-token
 * is a unique URI that represents the lock (treated as an opaque
 * string by the client), and is required to make further use of the
 * lock (including removal of the lock.)  A lock-token can also be
 * queried to return a svn_lock_t structure that describes the details
 * of the lock.  lock-tokens must not contain any newline character,
 * mainly due to the serialization for tokens for pre-commit hook.
 *
 * Locks are not secret; anyone can view existing locks in a
 * filesystem.  Locks are not omnipotent: they can broken and stolen
 * by people who don't "own" the lock.  (Though admins can tailor a
 * custom break/steal policy via libsvn_repos pre-lock hook script.)
 *
 * Locks can be created with an optional expiration date.  If a lock
 * has an expiration date, then the act of fetching/reading it might
 * cause it to automatically expire, returning either nothing or an
 * expiration error (depending on the API).
 */


/** Lock @a path in @a fs, and set @a *lock to a lock
 * representing the new lock, allocated in @a pool.
 *
 * @warning You may prefer to use svn_repos_fs_lock() instead,
 * which see.
 *
 * @a fs must have a username associated with it (see @c
 * svn_fs_access_t), else return @c SVN_ERR_FS_NO_USER.  Set the
 * 'owner' field in the new lock to the fs username.
 *
 * @a comment is optional: it's either an xml-escapable UTF8 string
 * which describes the lock, or it is @c NULL.
 *
 * @a is_dav_comment describes whether the comment was created by a
 * generic DAV client; only mod_dav_svn's autoversioning feature needs
 * to use it.  If in doubt, pass 0.
 *
 * If path is already locked, then return @c SVN_ERR_FS_PATH_ALREADY_LOCKED,
 * unless @a steal_lock is TRUE, in which case "steal" the existing
 * lock, even if the FS access-context's username does not match the
 * current lock's owner: delete the existing lock on @a path, and
 * create a new one.
 *
 * @a token is a lock token such as can be generated using
 * svn_fs_generate_lock_token() (indicating that the caller wants to
 * dictate the lock token used), or it is @c NULL (indicating that the
 * caller wishes to have a new token generated by this function).  If
 * @a token is not @c NULL, and represents an existing lock, then @a
 * path must match the path associated with that existing lock.
 *
 * If @a expiration_date is zero, then create a non-expiring lock.
 * Else, the lock will expire at @a expiration_date.
 *
 * If @a current_rev is a valid revnum, then do an out-of-dateness
 * check.  If the revnum is less than the last-changed-revision of @a
 * path (or if @a path doesn't exist in HEAD), return @c
 * SVN_ERR_FS_OUT_OF_DATE.
 *
 * @note At this time, only files can be locked.
 */
svn_error_t *
svn_fs_lock(svn_lock_t **lock,
            svn_fs_t *fs,
            const char *path,
            const char *token,
            const char *comment,
            svn_boolean_t is_dav_comment,
            apr_time_t expiration_date,
            svn_revnum_t current_rev,
            svn_boolean_t steal_lock,
            apr_pool_t *pool);


/** Generate a unique lock-token using @a fs. Return in @a *token,
 * allocated in @a pool.
 *
 * This can be used in to populate lock->token before calling
 * svn_fs_attach_lock().
 */
svn_error_t *
svn_fs_generate_lock_token(const char **token,
                           svn_fs_t *fs,
                           apr_pool_t *pool);


/** Remove the lock on @a path represented by @a token in @a fs.
 *
 * If @a token doesn't point to a lock, return @c SVN_ERR_FS_BAD_LOCK_TOKEN.
 * If @a token points to an expired lock, return @c SVN_ERR_FS_LOCK_EXPIRED.
 * If @a fs has no username associated with it, return @c SVN_ERR_FS_NO_USER
 * unless @a break_lock is specified.
 *
 * If @a token points to a lock, but the username of @a fs's access
 * context doesn't match the lock's owner, return @c
 * SVN_ERR_FS_LOCK_OWNER_MISMATCH.  If @a break_lock is TRUE, however, don't
 * return error;  allow the lock to be "broken" in any case.  In the latter
 * case, @a token shall be @c NULL.
 *
 * Use @a pool for temporary allocations.
 */
svn_error_t *
svn_fs_unlock(svn_fs_t *fs,
              const char *path,
              const char *token,
              svn_boolean_t break_lock,
              apr_pool_t *pool);


/** If @a path is locked in @a fs, set @a *lock to an svn_lock_t which
 *  represents the lock, allocated in @a pool.
 *
 * If @a path is not locked, set @a *lock to NULL.
 */
svn_error_t *
svn_fs_get_lock(svn_lock_t **lock,
                svn_fs_t *fs,
                const char *path,
                apr_pool_t *pool);


/** The type of a lock discovery callback function.  @a baton is the
 * value specified in the call to svn_fs_get_locks(); the filesystem
 * passes it through to the callback.  @a lock is a lock structure.
 * @a pool is a temporary subpool for use by the callback
 * implementation -- it is cleared after invocation of the callback.
 */
typedef svn_error_t *(*svn_fs_get_locks_callback_t)(void *baton,
                                                    svn_lock_t *lock,
                                                    apr_pool_t *pool);


/** Report locks on or below @a path in @a fs using the @a
 * get_locks_func / @a get_locks_baton.  Use @a pool for necessary
 * allocations.
 *
 * If the @a get_locks_func callback implementation returns an error,
 * lock iteration will terminate and that error will be returned by
 * this function.
 */
svn_error_t *
svn_fs_get_locks(svn_fs_t *fs,
                 const char *path,
                 svn_fs_get_locks_callback_t get_locks_func,
                 void *get_locks_baton,
                 apr_pool_t *pool);

/** @} */

/**
 * Append a textual list of all available FS modules to the stringbuf
 * @a output.
 *
 * @since New in 1.2.
 */
svn_error_t *
svn_fs_print_modules(svn_stringbuf_t *output,
                     apr_pool_t *pool);


/** The kind of action being taken by 'pack'. */
typedef enum
{
  /** packing of the shard has commenced */
  svn_fs_pack_notify_start = 0,

  /** packing of the shard is completed */
  svn_fs_pack_notify_end

} svn_fs_pack_notify_action_t;

/** The type of a pack notification function.  @a shard is the shard being
 * acted upon; @a action is the type of action being performed.  @a baton is
 * the corresponding baton for the notification function, and @a pool can
 * be used for temporary allocations, but will be cleared between invocations.
 */
typedef svn_error_t *(*svn_fs_pack_notify_t)(void *baton,
                                             apr_int64_t shard,
                                             svn_fs_pack_notify_action_t action,
                                             apr_pool_t *pool);

/**
 * Possibly update the filesystem located in the directory @a path
 * to use disk space more efficiently.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_fs_pack(const char *db_path,
            svn_fs_pack_notify_t notify_func,
            void *notify_baton,
            svn_cancel_func_t cancel_func,
            void *cancel_baton,
            apr_pool_t *pool);


/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_FS_H */