svn_fs.h

linux subdivision ying gai ke yi le ba

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2004 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_pools.h>
#include <apr_hash.h>
#include <apr_tables.h>
#include "svn_types.h"
#include "svn_error.h"
#include "svn_delta.h"
#include "svn_io.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);


/* Opening and creating filesystems.  */


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


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

/* @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"


/** The type of a warning callback function.  @a baton is the value specified
 * in the call to @c 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);




/**
 * @since New in 1.1.
 *
 * 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
 *
 * Otherwise, the BDB filesystem type is assumed.  Once the filesystem
 * is created, its type will be recorded so that other functions will
 * know how to operate on it.
 */
svn_error_t *svn_fs_create (svn_fs_t **fs_p, const char *path,
                            apr_hash_t *fs_config, apr_pool_t *pool);

/** 
 * @since New in 1.1.
 *
 * 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
 * @c svn_repos_open() instead.
 */
svn_error_t *svn_fs_open (svn_fs_t **fs_p, const char *path,
                          apr_hash_t *config, apr_pool_t *pool);

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

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

/** 
 * @since New in 1.1.
 *
 * 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.
 */
svn_error_t *svn_fs_hotcopy (const char *src_path, const char *dest_path,
                             svn_boolean_t clean, 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.
 * If a Berkeley DB error occurs, the filesystem will call @a handler
 * with two strings: an error message prefix, which will be zero, and
 * an error message.  @a handler should print it out, log it somewhere,
 * etc.
 *
 * Since Berkeley DB's error messages are sometimes much more
 * informative than the error codes the functions return, it's worth
 * calling this function and providing some kind of error message
 * handler.
 *
 * This function calls @c DBENV->set_errcall, with @a handler as the
 * @c db_errcall_fcn argument.
 */
svn_error_t *svn_fs_set_berkeley_errcall (svn_fs_t *fs, 
                                          void (*handler) (const char *errpfx,
                                                           char *msg));

/** Perform any necessary non-catastrophic recovery on a Berkeley
 * DB-based Subversion filesystem, stored in the environment @a path.
 * Do any necessary allocation within @a pool.
 *
 * 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.
 */
svn_error_t *svn_fs_berkeley_recover (const char *path,
                                      apr_pool_t *pool);


/** Set @a *logfiles to array of <tt>const char *</tt> log file names
 * of Berkeley DB-based Subversion filesystem.
 *
 * If @a only_unused is used is @c TRUE, @a *logfiles will contain
 * only the names of Berkeley DB log files still 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,
 * but only work on Berkeley DB filesystems.
 *
 * @defgroup svn_fs_bdb_deprecated berkeley db filesystem compatibility
 * @{
 */

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

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

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

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

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

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

/** @} */


/** 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);


/** @deprecated Provided for backward compatibility with the 1.0.0 API.
 *
 * 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.
 */
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.