svn_fs.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2008 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_fs.h
00019  * @brief Interface to the Subversion filesystem.
00020  */
00021 
00022 
00023 #ifndef SVN_FS_H
00024 #define SVN_FS_H
00025 
00026 #include <apr_pools.h>
00027 #include <apr_hash.h>
00028 #include <apr_tables.h>
00029 #include "svn_types.h"
00030 #include "svn_error.h"
00031 #include "svn_delta.h"
00032 #include "svn_io.h"
00033 #include "svn_mergeinfo.h"
00034 
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif /* __cplusplus */
00039 
00040 
00041 /**
00042  * Get libsvn_fs version information.
00043  *
00044  * @since New in 1.1.
00045  */
00046 const svn_version_t *svn_fs_version(void);
00047 
00048 /**
00049  * @defgroup fs_handling Filesystem interaction subsystem
00050  * @{
00051  */
00052 
00053 /* Opening and creating filesystems.  */
00054 
00055 
00056 /** An object representing a Subversion filesystem.  */
00057 typedef struct svn_fs_t svn_fs_t;
00058 
00059 
00060 /**
00061  * @name Filesystem configuration options
00062  * @{
00063  */
00064 #define SVN_FS_CONFIG_BDB_TXN_NOSYNC            "bdb-txn-nosync"
00065 #define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE        "bdb-log-autoremove"
00066 
00067 /* See also svn_fs_type(). */
00068 /** @since New in 1.1. */
00069 #define SVN_FS_CONFIG_FS_TYPE                   "fs-type"
00070 /** @since New in 1.1. */
00071 #define SVN_FS_TYPE_BDB                         "bdb"
00072 /** @since New in 1.1. */
00073 #define SVN_FS_TYPE_FSFS                        "fsfs"
00074 
00075 /** Create repository format compatible with Subversion versions
00076  * earlier than 1.4.
00077  *
00078  *  @since New in 1.4.
00079  */
00080 #define SVN_FS_CONFIG_PRE_1_4_COMPATIBLE        "pre-1.4-compatible"
00081 
00082 /** Create repository format compatible with Subversion versions
00083  * earlier than 1.5.
00084  *
00085  * @since New in 1.5.
00086  */
00087 #define SVN_FS_CONFIG_PRE_1_5_COMPATIBLE        "pre-1.5-compatible"
00088 /** @} */
00089 
00090 
00091 /**
00092  * Callers should invoke this function to initialize global state in
00093  * the FS library before creating FS objects.  If this function is
00094  * invoked, no FS objects may be created in another thread at the same
00095  * time as this invocation, and the provided @a pool must last longer
00096  * than any FS object created subsequently.
00097  *
00098  * If this function is not called, the FS library will make a best
00099  * effort to bootstrap a mutex for protecting data common to FS
00100  * objects; however, there is a small window of failure.  Also, a
00101  * small amount of data will be leaked if the Subversion FS library is
00102  * dynamically unloaded, and using the bdb FS can potentially segfault
00103  * or invoke other undefined behavior if this function is not called
00104  * with an appropriate pool (such as the pool the module was loaded into)
00105  * when loaded dynamically.
00106  *
00107  * If this function is called multiple times before the pool passed to
00108  * the first call is destroyed or cleared, the later calls will have
00109  * no effect.
00110  *
00111  * @since New in 1.2.
00112  */
00113 svn_error_t *svn_fs_initialize(apr_pool_t *pool);
00114 
00115 
00116 /** The type of a warning callback function.  @a baton is the value specified
00117  * in the call to svn_fs_set_warning_func(); the filesystem passes it through
00118  * to the callback.  @a err contains the warning message.
00119  *
00120  * The callback function should not clear the error that is passed to it;
00121  * its caller should do that.
00122  */
00123 typedef void (*svn_fs_warning_callback_t)(void *baton, svn_error_t *err);
00124 
00125 
00126 /** Provide a callback function, @a warning, that @a fs should use to
00127  * report (non-fatal) errors.  To print an error, the filesystem will call
00128  * @a warning, passing it @a warning_baton and the error.
00129  *
00130  * By default, this is set to a function that will crash the process.
00131  * Dumping to @c stderr or <tt>/dev/tty</tt> is not acceptable default
00132  * behavior for server processes, since those may both be equivalent to
00133  * <tt>/dev/null</tt>.
00134  */
00135 void
00136 svn_fs_set_warning_func(svn_fs_t *fs,
00137                         svn_fs_warning_callback_t warning,
00138                         void *warning_baton);
00139 
00140 
00141 
00142 /**
00143  * Create a new, empty Subversion filesystem, stored in the directory
00144  * @a path, and return a pointer to it in @a *fs_p.  @a path must not
00145  * currently exist, but its parent must exist.  If @a fs_config is not
00146  * @c NULL, the options it contains modify the behavior of the
00147  * filesystem.  The interpretation of @a fs_config is specific to the
00148  * filesystem back-end.  The new filesystem may be closed by
00149  * destroying @a pool.
00150  *
00151  * @note The lifetime of @a fs_config must not be shorter than @a
00152  * pool's. It's a good idea to allocate @a fs_config from @a pool or
00153  * one of its ancestors.
00154  *
00155  * If @a fs_config contains a value for @c SVN_FS_CONFIG_FS_TYPE, that
00156  * value determines the filesystem type for the new filesystem.
00157  * Currently defined values are:
00158  *
00159  *   SVN_FS_TYPE_BDB   Berkeley-DB implementation
00160  *   SVN_FS_TYPE_FSFS  Native-filesystem implementation
00161  *
00162  * If @a fs_config is @c NULL or does not contain a value for
00163  * @c SVN_FS_CONFIG_FS_TYPE then the default filesystem type will be used.
00164  * This will typically be BDB for version 1.1 and FSFS for later versions,
00165  * though the caller should not rely upon any particular default if they
00166  * wish to ensure that a filesystem of a specific type is created.
00167  *
00168  * @since New in 1.1.
00169  */
00170 svn_error_t *
00171 svn_fs_create(svn_fs_t **fs_p,
00172               const char *path,
00173               apr_hash_t *fs_config,
00174               apr_pool_t *pool);
00175 
00176 /**
00177  * Open a Subversion filesystem located in the directory @a path, and
00178  * return a pointer to it in @a *fs_p.  If @a fs_config is not @c
00179  * NULL, the options it contains modify the behavior of the
00180  * filesystem.  The interpretation of @a fs_config is specific to the
00181  * filesystem back-end.  The opened filesystem may be closed by
00182  * destroying @a pool.
00183  *
00184  * @note The lifetime of @a fs_config must not be shorter than @a
00185  * pool's. It's a good idea to allocate @a fs_config from @a pool or
00186  * one of its ancestors.
00187  *
00188  * Only one thread may operate on any given filesystem object at once.
00189  * Two threads may access the same filesystem simultaneously only if
00190  * they open separate filesystem objects.
00191  *
00192  * @note You probably don't want to use this directly.  Take a look at
00193  * svn_repos_open() instead.
00194  *
00195  * @since New in 1.1.
00196  */
00197 svn_error_t *
00198 svn_fs_open(svn_fs_t **fs_p,
00199             const char *path,
00200             apr_hash_t *fs_config,
00201             apr_pool_t *pool);
00202 
00203 /**
00204  * Upgrade the Subversion filesystem located in the directory @a path
00205  * to the latest version supported by this library.  Return @c
00206  * SVN_ERR_FS_UNSUPPORTED_UPGRADE and make no changes to the
00207  * filesystem if the requested upgrade is not supported.  Use @a pool
00208  * for necessary allocations.
00209  *
00210  * @note You probably don't want to use this directly.  Take a look at
00211  * svn_repos_upgrade() instead.
00212  *
00213  * @since New in 1.5.
00214  */
00215 svn_error_t *
00216 svn_fs_upgrade(const char *path,
00217                apr_pool_t *pool);
00218 
00219 /**
00220  * Return, in @a *fs_type, a string identifying the back-end type of
00221  * the Subversion filesystem located in @a path.  Allocate @a *fs_type
00222  * in @a pool.
00223  *
00224  * The string should be equal to one of the @c SVN_FS_TYPE_* defined
00225  * constants, unless the filesystem is a new back-end type added in
00226  * a later version of Subversion.
00227  *
00228  * In general, the type should make no difference in the filesystem's
00229  * semantics, but there are a few situations (such as backups) where
00230  * it might matter.
00231  *
00232  * @since New in 1.3.
00233  */
00234 svn_error_t *
00235 svn_fs_type(const char **fs_type,
00236             const char *path,
00237             apr_pool_t *pool);
00238 
00239 /**
00240  * Return the path to @a fs's repository, allocated in @a pool.
00241  * @note This is just what was passed to svn_fs_create() or
00242  * svn_fs_open() -- might be absolute, might not.
00243  *
00244  * @since New in 1.1.
00245  */
00246 const char *svn_fs_path(svn_fs_t *fs, apr_pool_t *pool);
00247 
00248 /**
00249  * Delete the filesystem at @a path.
00250  *
00251  * @since New in 1.1.
00252  */
00253 svn_error_t *svn_fs_delete_fs(const char *path, apr_pool_t *pool);
00254 
00255 /**
00256  * Copy a possibly live Subversion filesystem from @a src_path to
00257  * @a dest_path.  If @a clean is @c TRUE, perform cleanup on the
00258  * source filesystem as part of the copy operation; currently, this
00259  * means deleting copied, unused logfiles for a Berkeley DB source
00260  * filesystem.
00261  *
00262  * @since New in 1.1.
00263  */
00264 svn_error_t *
00265 svn_fs_hotcopy(const char *src_path,
00266                const char *dest_path,
00267                svn_boolean_t clean,
00268                apr_pool_t *pool);
00269 
00270 /** Perform any necessary non-catastrophic recovery on the Subversion
00271  * filesystem located at @a path.
00272  *
00273  * If @a cancel_func is not @c NULL, it is called periodically with
00274  * @a cancel_baton as argument to see if the client wishes to cancel
00275  * recovery.  BDB filesystems do not currently support cancellation.
00276  *
00277  * Do any necessary allocation within @a pool.
00278  *
00279  * For FSFS filesystems, recovery is currently limited to recreating
00280  * the db/current file, and does not require exclusive access.
00281  *
00282  * For BDB filesystems, recovery requires exclusive access, and is
00283  * described in detail below.
00284  *
00285  * After an unexpected server exit, due to a server crash or a system
00286  * crash, a Subversion filesystem based on Berkeley DB needs to run
00287  * recovery procedures to bring the database back into a consistent
00288  * state and release any locks that were held by the deceased process.
00289  * The recovery procedures require exclusive access to the database
00290  * --- while they execute, no other process or thread may access the
00291  * database.
00292  *
00293  * In a server with multiple worker processes, like Apache, if a
00294  * worker process accessing the filesystem dies, you must stop the
00295  * other worker processes, and run recovery.  Then, the other worker
00296  * processes can re-open the database and resume work.
00297  *
00298  * If the server exited cleanly, there is no need to run recovery, but
00299  * there is no harm in it, either, and it take very little time.  So
00300  * it's a fine idea to run recovery when the server process starts,
00301  * before it begins handling any requests.
00302  *
00303  * @since New in 1.5.
00304  */
00305 svn_error_t *
00306 svn_fs_recover(const char *path,
00307                svn_cancel_func_t cancel_func,
00308                void *cancel_baton,
00309                apr_pool_t *pool);
00310 
00311 
00312 /** Subversion filesystems based on Berkeley DB.
00313  *
00314  * The following functions are specific to Berkeley DB filesystems.
00315  *
00316  * @defgroup svn_fs_bdb Berkeley DB filesystems
00317  * @{
00318  */
00319 
00320 /** Register an error handling function for Berkeley DB error messages.
00321  *
00322  * @deprecated Provided for backward compatibility with the 1.2 API.
00323  *
00324  * Despite being first declared deprecated in Subversion 1.3, this API
00325  * is redundant in versions 1.1 and 1.2 as well.
00326  *
00327  * Berkeley DB's error codes are seldom sufficiently informative to allow
00328  * adequate troubleshooting.  Berkeley DB provides extra messages through
00329  * a callback function - if an error occurs, the @a handler will be called
00330  * with two strings: an error message prefix, which will be zero, and
00331  * an error message.  @a handler might print it out, log it somewhere,
00332  * etc.
00333  *
00334  * Subversion 1.1 and later install their own handler internally, and
00335  * wrap the messages from Berkeley DB into the standard svn_error_t object,
00336  * making any information gained through this interface redundant.
00337  *
00338  * It is only worth using this function if your program will be used
00339  * with Subversion 1.0.
00340  *
00341  * This function connects to the Berkeley DB @c DBENV->set_errcall interface.
00342  * Since that interface supports only a single callback, Subversion's internal
00343  * callback is registered with Berkeley DB, and will forward notifications to
00344  * a user provided callback after performing its own processing.
00345  */
00346 svn_error_t *
00347 svn_fs_set_berkeley_errcall(svn_fs_t *fs,
00348                             void (*handler)(const char *errpfx,
00349                                             char *msg));
00350 
00351 /** Set @a *logfiles to an array of <tt>const char *</tt> log file names
00352  * of Berkeley DB-based Subversion filesystem.
00353  *
00354  * If @a only_unused is @c TRUE, set @a *logfiles to an array which
00355  * contains only the names of Berkeley DB log files no longer in use
00356  * by the filesystem.  Otherwise, all log files (used and unused) are
00357  * returned.
00358 
00359  * This function wraps the Berkeley DB 'log_archive' function
00360  * called by the db_archive binary.  Repository administrators may
00361  * want to run this function periodically and delete the unused log
00362  * files, as a way of reclaiming disk space.
00363  */
00364 svn_error_t *
00365 svn_fs_berkeley_logfiles(apr_array_header_t **logfiles,
00366                          const char *path,
00367                          svn_boolean_t only_unused,
00368                          apr_pool_t *pool);
00369 
00370 
00371 /**
00372  * The following functions are similar to their generic counterparts.
00373  *
00374  * In Subversion 1.2 and earlier, they only work on Berkeley DB filesystems.
00375  * In Subversion 1.3 and later, they perform largely as aliases for their
00376  * generic counterparts (with the exception of recover, which only gained
00377  * a generic counterpart in 1.5).
00378  *
00379  * @defgroup svn_fs_bdb_deprecated Berkeley DB filesystem compatibility
00380  * @{
00381  */
00382 
00383 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00384 svn_fs_t *svn_fs_new(apr_hash_t *fs_config, apr_pool_t *pool);
00385 
00386 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00387 svn_error_t *svn_fs_create_berkeley(svn_fs_t *fs, const char *path);
00388 
00389 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00390 svn_error_t *svn_fs_open_berkeley(svn_fs_t *fs, const char *path);
00391 
00392 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00393 const char *svn_fs_berkeley_path(svn_fs_t *fs, apr_pool_t *pool);
00394 
00395 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00396 svn_error_t *svn_fs_delete_berkeley(const char *path, apr_pool_t *pool);
00397 
00398 /** @deprecated Provided for backward compatibility with the 1.0 API. */
00399 svn_error_t *
00400 svn_fs_hotcopy_berkeley(const char *src_path,
00401                         const char *dest_path,
00402                         svn_boolean_t clean_logs,
00403                         apr_pool_t *pool);
00404 
00405 /** @deprecated Provided for backward compatibility with the 1.4 API. */
00406 svn_error_t *
00407 svn_fs_berkeley_recover(const char *path,
00408                         apr_pool_t *pool);
00409 /** @} */
00410 
00411 /** @} */
00412 
00413 
00414 /** Filesystem Access Contexts.
00415  *
00416  * @since New in 1.2.
00417  *
00418  * At certain times, filesystem functions need access to temporary
00419  * user data.  For example, which user is changing a file?  If the
00420  * file is locked, has an appropriate lock-token been supplied?
00421  *
00422  * This temporary user data is stored in an "access context" object,
00423  * and the access context is then connected to the filesystem object.
00424  * Whenever a filesystem function requires information, it can pull
00425  * things out of the context as needed.
00426  *
00427  * @defgroup svn_fs_access_ctx Filesystem access contexts
00428  * @{
00429  */
00430 
00431 /** An opaque object representing temporary user data. */
00432 typedef struct svn_fs_access_t svn_fs_access_t;
00433 
00434 
00435 /** Set @a *access_ctx to a new @c svn_fs_access_t object representing
00436  *  @a username, allocated in @a pool.  @a username is presumed to
00437  *  have been authenticated by the caller.
00438  */
00439 svn_error_t *
00440 svn_fs_create_access(svn_fs_access_t **access_ctx,
00441                      const char *username,
00442                      apr_pool_t *pool);
00443 
00444 
00445 /** Associate @a access_ctx with an open @a fs.
00446  *
00447  * This function can be run multiple times on the same open
00448  * filesystem, in order to change the filesystem access context for
00449  * different filesystem operations.  Pass a NULL value for @a
00450  * access_ctx to disassociate the current access context from the
00451  * filesystem.
00452  */
00453 svn_error_t *
00454 svn_fs_set_access(svn_fs_t *fs,
00455                   svn_fs_access_t *access_ctx);
00456 
00457 
00458 /** Set @a *access_ctx to the current @a fs access context, or NULL if
00459  * there is no current fs access context.
00460  */
00461 svn_error_t *
00462 svn_fs_get_access(svn_fs_access_t **access_ctx,
00463                   svn_fs_t *fs);
00464 
00465 
00466 /** Accessors for the access context: */
00467 
00468 /** Set @a *username to the name represented by @a access_ctx. */
00469 svn_error_t *
00470 svn_fs_access_get_username(const char **username,
00471                            svn_fs_access_t *access_ctx);
00472 
00473 
00474 /** Push a lock-token @a token into the context @a access_ctx.  The
00475  * context remembers all tokens it receives, and makes them available
00476  * to fs functions.  The token is not duplicated into @a access_ctx's
00477  * pool;  make sure the token's lifetime is at least as long as @a
00478  * access_ctx. */
00479 svn_error_t *
00480 svn_fs_access_add_lock_token(svn_fs_access_t *access_ctx,
00481                              const char *token);
00482 
00483 /** @} */
00484 
00485 
00486 /** Filesystem Nodes.
00487  *
00488  * In a Subversion filesystem, a `node' corresponds roughly to an
00489  * `inode' in a Unix filesystem:
00490  * - A node is either a file or a directory.
00491  * - A node's contents change over time.
00492  * - When you change a node's contents, it's still the same node; it's
00493  *   just been changed.  So a node's identity isn't bound to a specific
00494  *   set of contents.
00495  * - If you rename a node, it's still the same node, just under a
00496  *   different name.  So a node's identity isn't bound to a particular
00497  *   filename.
00498  *
00499  * A `node revision' refers to a node's contents at a specific point in
00500  * time.  Changing a node's contents always creates a new revision of that
00501  * node.  Once created, a node revision's contents never change.
00502  *
00503  * When we create a node, its initial contents are the initial revision of
00504  * the node.  As users make changes to the node over time, we create new
00505  * revisions of that same node.  When a user commits a change that deletes
00506  * a file from the filesystem, we don't delete the node, or any revision
00507  * of it --- those stick around to allow us to recreate prior revisions of
00508  * the filesystem.  Instead, we just remove the reference to the node
00509  * from the directory.
00510  *
00511  * @defgroup svn_fs_nodes Filesystem nodes
00512  * @{
00513  */
00514 
00515 /** An object representing a node-id.  */
00516 typedef struct svn_fs_id_t svn_fs_id_t;
00517 
00518 
00519 /** Return -1, 0, or 1 if node revisions @a a and @a b are unrelated,
00520  * equivalent, or otherwise related (respectively).
00521  */
00522 int svn_fs_compare_ids(const svn_fs_id_t *a, const svn_fs_id_t *b);
00523 
00524 
00525 
00526 /** Return non-zero IFF the nodes associated with @a id1 and @a id2 are
00527  * related, else return zero.
00528  */
00529 svn_boolean_t
00530 svn_fs_check_related(const svn_fs_id_t *id1,
00531                      const svn_fs_id_t *id2);
00532 
00533 
00534 /**
00535  * @note This function is not guaranteed to work with all filesystem
00536  * types.  There is currently no un-deprecated equivalent; contact the
00537  * Subversion developers if you have a need for it.
00538  *
00539  * @deprecated Provided for backward compatibility with the 1.0 API.
00540  */
00541 svn_fs_id_t *
00542 svn_fs_parse_id(const char *data,
00543                 apr_size_t len,
00544                 apr_pool_t *pool);
00545 
00546 
00547 /** Return a Subversion string containing the unparsed form of the
00548  * node or node revision id @a id.  Allocate the string containing the
00549  * unparsed form in @a pool.
00550  */
00551 svn_string_t *
00552 svn_fs_unparse_id(const svn_fs_id_t *id,
00553                   apr_pool_t *pool);
00554 
00555 /** @} */
00556 
00557 
00558 /** Filesystem Transactions.
00559  *
00560  * To make a change to a Subversion filesystem:
00561  * - Create a transaction object, using svn_fs_begin_txn().
00562  * - Call svn_fs_txn_root(), to get the transaction's root directory.
00563  * - Make whatever changes you like in that tree.
00564  * - Commit the transaction, using svn_fs_commit_txn().
00565  *
00566  * The filesystem implementation guarantees that your commit will
00567  * either:
00568  * - succeed completely, so that all of the changes are committed to
00569  *   create a new revision of the filesystem, or
00570  * - fail completely, leaving the filesystem unchanged.
00571  *
00572  * Until you commit the transaction, any changes you make are
00573  * invisible.  Only when your commit succeeds do they become visible
00574  * to the outside world, as a new revision of the filesystem.
00575  *
00576  * If you begin a transaction, and then decide you don't want to make
00577  * the change after all (say, because your net connection with the
00578  * client disappeared before the change was complete), you can call
00579  * svn_fs_abort_txn(), to cancel the entire transaction; this
00580  * leaves the filesystem unchanged.
00581  *
00582  * The only way to change the contents of files or directories, or
00583  * their properties, is by making a transaction and creating a new
00584  * revision, as described above.  Once a revision has been committed, it
00585  * never changes again; the filesystem interface provides no means to
00586  * go back and edit the contents of an old revision.  Once history has
00587  * been recorded, it is set in stone.  Clients depend on this property
00588  * to do updates and commits reliably; proxies depend on this property
00589  * to cache changes accurately; and so on.
00590  *
00591  * There are two kinds of nodes in the filesystem: mutable, and
00592  * immutable.  Revisions in the filesystem consist entirely of
00593  * immutable nodes, whose contents never change.  A transaction in
00594  * progress, which the user is still constructing, uses mutable nodes
00595  * for those nodes which have been changed so far, and refers to
00596  * immutable nodes from existing revisions for portions of the tree
00597  * which haven't been changed yet in that transaction.
00598  *
00599  * Immutable nodes, as part of revisions, never refer to mutable
00600  * nodes, which are part of uncommitted transactions.  Mutable nodes
00601  * may refer to immutable nodes, or other mutable nodes.
00602  *
00603  * Note that the terms "immutable" and "mutable" describe whether or
00604  * not the nodes have been changed as part of a transaction --- not
00605  * the permissions on the nodes they refer to.  Even if you aren't
00606  * authorized to modify the filesystem's root directory, you might be
00607  * authorized to change some descendant of the root; doing so would
00608  * create a new mutable copy of the root directory.  Mutability refers
00609  * to the role of the node: part of an existing revision, or part of a
00610  * new one.  This is independent of your authorization to make changes
00611  * to a given node.
00612  *
00613  * Transactions are actually persistent objects, stored in the
00614  * database.  You can open a filesystem, begin a transaction, and
00615  * close the filesystem, and then a separate process could open the
00616  * filesystem, pick up the same transaction, and continue work on it.
00617  * When a transaction is successfully committed, it is removed from
00618  * the database.
00619  *
00620  * Every transaction is assigned a name.  You can open a transaction
00621  * by name, and resume work on it, or find out the name of a
00622  * transaction you already have open.  You can also list all the
00623  * transactions currently present in the database.
00624  *
00625  * You may assign properties to transactions; these are name/value
00626  * pairs.  When you commit a transaction, all of its properties become
00627  * unversioned revision properties of the new revision.  (There is one
00628  * exception: the svn:date property will be automatically set on new
00629  * transactions to the date that the transaction was created, and will
00630  * be overwritten when the transaction is committed by the current
00631  * time; changes to a transaction's svn:date property will not affect
00632  * its committed value.)
00633  *
00634  * Transaction names are guaranteed to contain only letters (upper-
00635  * and lower-case), digits, `-', and `.', from the ASCII character
00636  * set.
00637  *
00638  * The Subversion filesystem will make a best effort to not reuse
00639  * transaction names.  The Berkeley DB backend generates transaction
00640  * names using a sequence, or a counter, which is stored in the BDB
00641  * database.  Each new transaction increments the counter.  The
00642  * current value of the counter is not serialized into a filesystem
00643  * dump file, so dumping and restoring the repository will reset the
00644  * sequence and reuse transaction names.  The FSFS backend generates a
00645  * transaction name using the hostname, process ID and current time in
00646  * microseconds since 00:00:00 January 1, 1970 UTC.  So it is
00647  * extremely unlikely that a transaction name will be reused.
00648  *
00649  * @defgroup svn_fs_txns Filesystem transactions
00650  * @{
00651  */
00652 
00653 /** The type of a Subversion transaction object.  */
00654 typedef struct svn_fs_txn_t svn_fs_txn_t;
00655 
00656 
00657 /** @defgroup svn_fs_begin_txn2_flags Bitmask flags for svn_fs_begin_txn2()
00658  * @since New in 1.2.
00659  * @{ */
00660 
00661 /** Do on-the-fly out-of-dateness checks.  That is, an fs routine may
00662  * throw error if a caller tries to edit an out-of-date item in the
00663  * transaction.
00664  *
00665  * @warning ### Not yet implemented.
00666  */
00667 #define SVN_FS_TXN_CHECK_OOD                     0x00001
00668 
00669 /** Do on-the-fly lock checks.  That is, an fs routine may throw error
00670  * if a caller tries to edit a locked item without having rights to the lock.
00671  */
00672 #define SVN_FS_TXN_CHECK_LOCKS                   0x00002
00673 /** @} */
00674 
00675 /**
00676  * Begin a new transaction on the filesystem @a fs, based on existing
00677  * revision @a rev.  Set @a *txn_p to a pointer to the new transaction.
00678  * When committed, this transaction will create a new revision.
00679  *
00680  * Allocate the new transaction in @a pool; when @a pool is freed, the new
00681  * transaction will be closed (neither committed nor aborted).
00682  *
00683  * @a flags determines transaction enforcement behaviors, and is composed
00684  * from the constants SVN_FS_TXN_* (@c SVN_FS_TXN_CHECK_OOD etc.).
00685  *
00686  * @note If you're building a txn for committing, you probably
00687  * don't want to call this directly.  Instead, call
00688  * svn_repos_fs_begin_txn_for_commit(), which honors the
00689  * repository's hook configurations.
00690  *
00691  * @since New in 1.2.
00692  */
00693 svn_error_t *
00694 svn_fs_begin_txn2(svn_fs_txn_t **txn_p,
00695                   svn_fs_t *fs,
00696                   svn_revnum_t rev,
00697                   apr_uint32_t flags,
00698                   apr_pool_t *pool);
00699 
00700 
00701 /**
00702  * Same as svn_fs_begin_txn2(), but with @a flags set to 0.
00703  *
00704  * @deprecated Provided for backward compatibility with the 1.1 API.
00705  */
00706 svn_error_t *
00707 svn_fs_begin_txn(svn_fs_txn_t **txn_p,
00708                  svn_fs_t *fs,
00709                  svn_revnum_t rev,
00710                  apr_pool_t *pool);
00711 
00712 
00713 
00714 /** Commit @a txn.
00715  *
00716  * @note You usually don't want to call this directly.
00717  * Instead, call svn_repos_fs_commit_txn(), which honors the
00718  * repository's hook configurations.
00719  *
00720  * If the transaction conflicts with other changes committed to the
00721  * repository, return an @c SVN_ERR_FS_CONFLICT error.  Otherwise, create
00722  * a new filesystem revision containing the changes made in @a txn,
00723  * storing that new revision number in @a *new_rev, and return zero.
00724  *
00725  * If @a conflict_p is non-zero, use it to provide details on any
00726  * conflicts encountered merging @a txn with the most recent committed
00727  * revisions.  If a conflict occurs, set @a *conflict_p to the path of
00728  * the conflict in @a txn, with the same lifetime as @a txn;
00729  * otherwise, set @a *conflict_p to NULL.
00730  *
00731  * If the commit succeeds, @a txn is invalid.
00732  *
00733  * If the commit fails, @a txn is still valid; you can make more
00734  * operations to resolve the conflict, or call svn_fs_abort_txn() to
00735  * abort the transaction.
00736  *
00737  * @note Success or failure of the commit of @a txn is determined by
00738  * examining the value of @a *new_rev upon this function's return.  If
00739  * the value is a valid revision number, the commit was successful,
00740  * even though a non-@c NULL function return value may indicate that
00741  * something else went wrong.
00742  */
00743 svn_error_t *
00744 svn_fs_commit_txn(const char **conflict_p,
00745                   svn_revnum_t *new_rev,
00746                   svn_fs_txn_t *txn,
00747                   apr_pool_t *pool);
00748 
00749 
00750 /** Abort the transaction @a txn.  Any changes made in @a txn are
00751  * discarded, and the filesystem is left unchanged.  Use @a pool for
00752  * any necessary allocations.
00753  *
00754  * @note This function first sets the state of @a txn to "dead", and
00755  * then attempts to purge it and any related data from the filesystem.
00756  * If some part of the cleanup process fails, @a txn and some portion
00757  * of its data may remain in the database after this function returns.
00758  * Use svn_fs_purge_txn() to retry the transaction cleanup.
00759  */
00760 svn_error_t *
00761 svn_fs_abort_txn(svn_fs_txn_t *txn,
00762                  apr_pool_t *pool);
00763 
00764 
00765 /** Cleanup the dead transaction in @a fs whose ID is @a txn_id.  Use
00766  * @a pool for all allocations.  If the transaction is not yet dead,
00767  * the error @c SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned.  (The
00768  * caller probably forgot to abort the transaction, or the cleanup
00769  * step of that abort failed for some reason.)
00770  */
00771 svn_error_t *
00772 svn_fs_purge_txn(svn_fs_t *fs,
00773                  const char *txn_id,
00774                  apr_pool_t *pool);
00775 
00776 
00777 /** Set @a *name_p to the name of the transaction @a txn, as a
00778  * NULL-terminated string.  Allocate the name in @a pool.
00779  */
00780 svn_error_t *
00781 svn_fs_txn_name(const char **name_p,
00782                 svn_fs_txn_t *txn,
00783                 apr_pool_t *pool);
00784 
00785 /** Return @a txn's base revision. */
00786 svn_revnum_t svn_fs_txn_base_revision(svn_fs_txn_t *txn);
00787 
00788 
00789 
00790 /** Open the transaction named @a name in the filesystem @a fs.  Set @a *txn
00791  * to the transaction.
00792  *
00793  * If there is no such transaction, @c SVN_ERR_FS_NO_SUCH_TRANSACTION is
00794  * the error returned.
00795  *
00796  * Allocate the new transaction in @a pool; when @a pool is freed, the new
00797  * transaction will be closed (neither committed nor aborted).
00798  */
00799 svn_error_t *
00800 svn_fs_open_txn(svn_fs_txn_t **txn,
00801                 svn_fs_t *fs,
00802                 const char *name,
00803                 apr_pool_t *pool);
00804 
00805 
00806 /** Set @a *names_p to an array of <tt>const char *</tt> ids which are the
00807  * names of all the currently active transactions in the filesystem @a fs.
00808  * Allocate the array in @a pool.
00809  */
00810 svn_error_t *
00811 svn_fs_list_transactions(apr_array_header_t **names_p,
00812                          svn_fs_t *fs,
00813                          apr_pool_t *pool);
00814 
00815 /* Transaction properties */
00816 
00817 /** Set @a *value_p to the value of the property named @a propname on
00818  * transaction @a txn.  If @a txn has no property by that name, set
00819  * @a *value_p to zero.  Allocate the result in @a pool.
00820  */
00821 svn_error_t *
00822 svn_fs_txn_prop(svn_string_t **value_p,
00823                 svn_fs_txn_t *txn,
00824                 const char *propname,
00825                 apr_pool_t *pool);
00826 
00827 
00828 /** Set @a *table_p to the entire property list of transaction @a txn, as
00829  * an APR hash table allocated in @a pool.  The resulting table maps property
00830  * names to pointers to @c svn_string_t objects containing the property value.
00831  */
00832 svn_error_t *
00833 svn_fs_txn_proplist(apr_hash_t **table_p,
00834                     svn_fs_txn_t *txn,
00835                     apr_pool_t *pool);
00836 
00837 
00838 /** Change a transactions @a txn's property's value, or add/delete a
00839  * property.  @a name is the name of the property to change, and @a value
00840  * is the new value of the property, or zero if the property should be
00841  * removed altogether.  Do any necessary temporary allocation in @a pool.
00842  */
00843 svn_error_t *
00844 svn_fs_change_txn_prop(svn_fs_txn_t *txn,
00845                        const char *name,
00846                        const svn_string_t *value,
00847                        apr_pool_t *pool);
00848 
00849 
00850 /** Change, add, and/or delete transaction property values in
00851  * transaction @a txn.  @a props is an array of <tt>svn_prop_t</tt>
00852  * elements.  This is equivalent to calling svn_fs_change_txp_prop
00853  * multiple times with the @c name and @c value fields of each
00854  * successive <tt>svn_prop_t</tt>, but may be more efficient.
00855  * (Properties not mentioned are left alone.)  Do any necessary
00856  * temporary allocation in @a pool.
00857  *
00858  * @since New in 1.5.
00859  */
00860 svn_error_t *
00861 svn_fs_change_txn_props(svn_fs_txn_t *txn,
00862                         apr_array_header_t *props,
00863                         apr_pool_t *pool);
00864 
00865 /** @} */
00866 
00867 
00868 /** Roots.
00869  *
00870  * An @c svn_fs_root_t object represents the root directory of some
00871  * revision or transaction in a filesystem.  To refer to particular
00872  * node, you provide a root, and a directory path relative that root.
00873  *
00874  * @defgroup svn_fs_roots Filesystem roots
00875  * @{
00876  */
00877 
00878 /** The Filesystem Root object. */
00879 typedef struct svn_fs_root_t svn_fs_root_t;
00880 
00881 
00882 /** Set @a *root_p to the root directory of revision @a rev in filesystem
00883  * @a fs.  Allocate @a *root_p in @a pool.
00884  */
00885 svn_error_t *
00886 svn_fs_revision_root(svn_fs_root_t **root_p,
00887                      svn_fs_t *fs,
00888                      svn_revnum_t rev,
00889                      apr_pool_t *pool);
00890 
00891 
00892 /** Set @a *root_p to the root directory of @a txn.  Allocate @a *root_p in
00893  * @a pool.
00894  */
00895 svn_error_t *
00896 svn_fs_txn_root(svn_fs_root_t **root_p,
00897                 svn_fs_txn_t *txn,
00898                 apr_pool_t *pool);
00899 
00900 
00901 /** Free the root directory @a root.  Simply clearing or destroying the
00902  * pool @a root was allocated in will have the same effect as calling
00903  * this function.
00904  */
00905 void svn_fs_close_root(svn_fs_root_t *root);
00906 
00907 
00908 /** Return the filesystem to which @a root belongs.  */
00909 svn_fs_t *svn_fs_root_fs(svn_fs_root_t *root);
00910 
00911 
00912 /** Return @c TRUE iff @a root is a transaction root.  */
00913 svn_boolean_t svn_fs_is_txn_root(svn_fs_root_t *root);
00914 
00915 /** Return @c TRUE iff @a root is a revision root.  */
00916 svn_boolean_t svn_fs_is_revision_root(svn_fs_root_t *root);
00917 
00918 
00919 /** If @a root is the root of a transaction, return the name of the
00920  * transaction, allocated in @a pool; otherwise, return NULL.
00921  */
00922 const char *
00923 svn_fs_txn_root_name(svn_fs_root_t *root,
00924                      apr_pool_t *pool);
00925 
00926 /** If @a root is the root of a transaction, return the number of the
00927  * revision on which is was based when created.  Otherwise, return @c
00928  * SVN_INVALID_REVNUM.
00929  *
00930  * @since New in 1.5.
00931  */
00932 svn_revnum_t svn_fs_txn_root_base_revision(svn_fs_root_t *root);
00933 
00934 /** If @a root is the root of a revision, return the revision number.
00935  * Otherwise, return @c SVN_INVALID_REVNUM.
00936  */
00937 svn_revnum_t svn_fs_revision_root_revision(svn_fs_root_t *root);
00938 
00939 /** @} */
00940 
00941 
00942 /** Directory entry names and directory paths.
00943  *
00944  * Here are the rules for directory entry names, and directory paths:
00945  *
00946  * A directory entry name is a Unicode string encoded in UTF-8, and
00947  * may not contain the NULL character (U+0000).  The name should be in
00948  * Unicode canonical decomposition and ordering.  No directory entry
00949  * may be named '.', '..', or the empty string.  Given a directory
00950  * entry name which fails to meet these requirements, a filesystem
00951  * function returns an SVN_ERR_FS_PATH_SYNTAX error.
00952  *
00953  * A directory path is a sequence of zero or more directory entry
00954  * names, separated by slash characters (U+002f), and possibly ending
00955  * with slash characters.  Sequences of two or more consecutive slash
00956  * characters are treated as if they were a single slash.  If a path
00957  * ends with a slash, it refers to the same node it would without the
00958  * slash, but that node must be a directory, or else the function
00959  * returns an SVN_ERR_FS_NOT_DIRECTORY error.
00960  *
00961  * A path consisting of the empty string, or a string containing only
00962  * slashes, refers to the root directory.
00963  *
00964  * @defgroup svn_fs_directories Filesystem directories
00965  * @{
00966  */
00967 
00968 
00969 
00970 /** The kind of change that occurred on the path. */
00971 typedef enum
00972 {
00973   /** default value */
00974   svn_fs_path_change_modify = 0,
00975 
00976   /** path added in txn */
00977   svn_fs_path_change_add,
00978 
00979   /** path removed in txn */
00980   svn_fs_path_change_delete,
00981 
00982   /** path removed and re-added in txn */
00983   svn_fs_path_change_replace,
00984 
00985   /** ignore all previous change items for path (internal-use only) */
00986   svn_fs_path_change_reset
00987 
00988 } svn_fs_path_change_kind_t;
00989 
00990 /** Change descriptor. */
00991 typedef struct svn_fs_path_change_t
00992 {
00993   /** node revision id of changed path */
00994   const svn_fs_id_t *node_rev_id;
00995 
00996   /** kind of change */
00997   svn_fs_path_change_kind_t change_kind;
00998 
00999   /** were there text mods? */
01000   svn_boolean_t text_mod;
01001 
01002   /** were there property mods? */
01003   svn_boolean_t prop_mod;
01004 
01005 } svn_fs_path_change_t;
01006 
01007 
01008 /** Determine what has changed under a @a root.
01009  *
01010  * Allocate and return a hash @a *changed_paths_p containing descriptions
01011  * of the paths changed under @a root.  The hash is keyed with
01012  * <tt>const char *</tt> paths, and has @c svn_fs_path_change_t * values.
01013  * Use @c pool for all allocations, including the hash and its values.
01014  */
01015 svn_error_t *
01016 svn_fs_paths_changed(apr_hash_t **changed_paths_p,
01017                      svn_fs_root_t *root,
01018                      apr_pool_t *pool);
01019 
01020 /** @} */
01021 
01022 
01023 /* Operations appropriate to all kinds of nodes.  */
01024 
01025 /** Set @a *kind_p to the type of node present at @a path under @a
01026  * root.  If @a path does not exist under @a root, set @a *kind_p to @c
01027  * svn_node_none.  Use @a pool for temporary allocation.
01028  */
01029 svn_error_t *
01030 svn_fs_check_path(svn_node_kind_t *kind_p,
01031                   svn_fs_root_t *root,
01032                   const char *path,
01033                   apr_pool_t *pool);
01034 
01035 
01036 /** An opaque node history object. */
01037 typedef struct svn_fs_history_t svn_fs_history_t;
01038 
01039 
01040 /** Set @a *history_p to an opaque node history object which
01041  * represents @a path under @a root.  @a root must be a revision root.
01042  * Use @a pool for all allocations.
01043  */
01044 svn_error_t *
01045 svn_fs_node_history(svn_fs_history_t **history_p,
01046                     svn_fs_root_t *root,
01047                     const char *path,
01048                     apr_pool_t *pool);
01049 
01050 
01051 /** Set @a *prev_history_p to an opaque node history object which
01052  * represents the previous (or "next oldest") interesting history
01053  * location for the filesystem node represented by @a history, or @c
01054  * NULL if no such previous history exists.  If @a cross_copies is @c
01055  * FALSE, also return @c NULL if stepping backwards in history to @a
01056  * *prev_history_p would cross a filesystem copy operation.
01057  *
01058  * @note If this is the first call to svn_fs_history_prev() for the @a
01059  * history object, it could return a history object whose location is
01060  * the same as the original.  This will happen if the original
01061  * location was an interesting one (where the node was modified, or
01062  * took place in a copy event).  This behavior allows looping callers
01063  * to avoid the calling svn_fs_history_location() on the object
01064  * returned by svn_fs_node_history(), and instead go ahead and begin
01065  * calling svn_fs_history_prev().
01066  *
01067  * @note This function uses node-id ancestry alone to determine
01068  * modifiedness, and therefore does NOT claim that in any of the
01069  * returned revisions file contents changed, properties changed,
01070  * directory entries lists changed, etc.
01071  *
01072  * @note The revisions returned for @a path will be older than or
01073  * the same age as the revision of that path in @a root.  That is, if
01074  * @a root is a revision root based on revision X, and @a path was
01075  * modified in some revision(s) younger than X, those revisions
01076  * younger than X will not be included for @a path.  */
01077 svn_error_t *
01078 svn_fs_history_prev(svn_fs_history_t **prev_history_p,
01079                     svn_fs_history_t *history,
01080                     svn_boolean_t cross_copies,
01081                     apr_pool_t *pool);
01082 
01083 
01084 /** Set @a *path and @a *revision to the path and revision,
01085  * respectively, of the @a history object.  Use @a pool for all
01086  * allocations.
01087  */
01088 svn_error_t *
01089 svn_fs_history_location(const char **path,
01090                         svn_revnum_t *revision,
01091                         svn_fs_history_t *history,
01092                         apr_pool_t *pool);
01093 
01094 
01095 /** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory.
01096  * Do any necessary temporary allocation in @a pool.
01097  */
01098 svn_error_t *
01099 svn_fs_is_dir(svn_boolean_t *is_dir,
01100               svn_fs_root_t *root,
01101               const char *path,
01102               apr_pool_t *pool);
01103 
01104 
01105 /** Set @a *is_file to @c TRUE iff @a path in @a root is a file.
01106  * Do any necessary temporary allocation in @a pool.
01107  */
01108 svn_error_t *
01109 svn_fs_is_file(svn_boolean_t *is_file,
01110                svn_fs_root_t *root,
01111                const char *path,
01112                apr_pool_t *pool);
01113 
01114 
01115 /** Get the id of a node.
01116  *
01117  * Set @a *id_p to the node revision ID of @a path in @a root, allocated in
01118  * @a pool.
01119  *
01120  * If @a root is the root of a transaction, keep in mind that other
01121  * changes to the transaction can change which node @a path refers to,
01122  * and even whether the path exists at all.
01123  */
01124 svn_error_t *
01125 svn_fs_node_id(const svn_fs_id_t **id_p,
01126                svn_fs_root_t *root,
01127                const char *path,
01128                apr_pool_t *pool);
01129 
01130 /** Set @a *revision to the revision in which @a path under @a root was
01131  * created.  Use @a pool for any temporary allocations.  @a *revision will
01132  * be set to @c SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes
01133  * under a transaction root).  Note that the root of an unmodified transaction
01134  * is not itself considered to be modified; in that case, return the revision
01135  * upon which the transaction was based.
01136  */
01137 svn_error_t *
01138 svn_fs_node_created_rev(svn_revnum_t *revision,
01139                         svn_fs_root_t *root,
01140                         const char *path,
01141                         apr_pool_t *pool);
01142 
01143 /** Set @a *revision to the revision in which the line of history
01144  * represented by @a path under @a root originated.  Use @a pool for
01145  * any temporary allocations.  If @a root is a transaction root, @a
01146  * *revision will be set to @c SVN_INVALID_REVNUM for any nodes newly
01147  * added in that transaction (brand new files or directories created
01148  * using @c svn_fs_make_dir or @c svn_fs_make_file).
01149  *
01150  * @since New in 1.5.
01151  */
01152 svn_error_t *
01153 svn_fs_node_origin_rev(svn_revnum_t *revision,
01154                        svn_fs_root_t *root,
01155                        const char *path,
01156                        apr_pool_t *pool);
01157 
01158 /** Set @a *created_path to the path at which @a path under @a root was
01159  * created.  Use @a pool for all allocations.  Callers may use this
01160  * function in conjunction with svn_fs_node_created_rev() to perform a
01161  * reverse lookup of the mapping of (path, revision) -> node-id that
01162  * svn_fs_node_id() performs.
01163  */
01164 svn_error_t *
01165 svn_fs_node_created_path(const char **created_path,
01166                          svn_fs_root_t *root,
01167                          const char *path,
01168                          apr_pool_t *pool);
01169 
01170 
01171 /** Set @a *value_p to the value of the property named @a propname of
01172  * @a path in @a root.  If the node has no property by that name, set
01173  * @a *value_p to zero.  Allocate the result in @a pool.
01174  */
01175 svn_error_t *
01176 svn_fs_node_prop(svn_string_t **value_p,
01177                  svn_fs_root_t *root,
01178                  const char *path,
01179                  const char *propname,
01180                  apr_pool_t *pool);
01181 
01182 
01183 /** Set @a *table_p to the entire property list of @a path in @a root,
01184  * as an APR hash table allocated in @a pool.  The resulting table maps
01185  * property names to pointers to @c svn_string_t objects containing the
01186  * property value.
01187  */
01188 svn_error_t *
01189 svn_fs_node_proplist(apr_hash_t **table_p,
01190                      svn_fs_root_t *root,
01191                      const char *path,
01192                      apr_pool_t *pool);
01193 
01194 
01195 /** Change a node's property's value, or add/delete a property.
01196  *
01197  * - @a root and @a path indicate the node whose property should change.
01198  *   @a root must be the root of a transaction, not the root of a revision.
01199  * - @a name is the name of the property to change.
01200  * - @a value is the new value of the property, or zero if the property should
01201  *   be removed altogether.
01202  * Do any necessary temporary allocation in @a pool.
01203  */
01204 svn_error_t *
01205 svn_fs_change_node_prop(svn_fs_root_t *root,
01206                         const char *path,
01207                         const char *name,
01208                         const svn_string_t *value,
01209                         apr_pool_t *pool);
01210 
01211 
01212 /** Determine if the properties of two path/root combinations are different.
01213  *
01214  * Set @a *changed_p to 1 if the properties at @a path1 under @a root1 differ
01215  * from those at @a path2 under @a root2, or set it to 0 if they are the
01216  * same.  Both paths must exist under their respective roots, and both
01217  * roots must be in the same filesystem.
01218  */
01219 svn_error_t *
01220 svn_fs_props_changed(svn_boolean_t *changed_p,
01221                      svn_fs_root_t *root1,
01222                      const char *path1,
01223                      svn_fs_root_t *root2,
01224                      const char *path2,
01225                      apr_pool_t *pool);
01226 
01227 
01228 /** Discover a node's copy ancestry, if any.
01229  *
01230  * If the node at @a path in @a root was copied from some other node, set
01231  * @a *rev_p and @a *path_p to the revision and path of the other node,
01232  * allocating @a *path_p in @a pool.
01233  *
01234  * Else if there is no copy ancestry for the node, set @a *rev_p to
01235  * @c SVN_INVALID_REVNUM and @a *path_p to NULL.
01236  *
01237  * If an error is returned, the values of @a *rev_p and @a *path_p are
01238  * undefined, but otherwise, if one of them is set as described above,
01239  * you may assume the other is set correspondingly.
01240  *
01241  * @a root may be a revision root or a transaction root.
01242  *
01243  * Notes:
01244  *    - Copy ancestry does not descend.  After copying directory D to
01245  *      E, E will have copy ancestry referring to D, but E's children
01246  *      may not.  See also svn_fs_copy().
01247  *
01248  *    - Copy ancestry *under* a copy is preserved.  That is, if you
01249  *      copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then
01250  *      /G/pi2 will still have copy ancestry pointing to /A/D/G/pi.
01251  *      We don't know if this is a feature or a bug yet; if it turns
01252  *      out to be a bug, then the fix is to make svn_fs_copied_from()
01253  *      observe the following logic, which currently callers may
01254  *      choose to follow themselves: if node X has copy history, but
01255  *      its ancestor A also has copy history, then you may ignore X's
01256  *      history if X's revision-of-origin is earlier than A's --
01257  *      because that would mean that X's copy history was preserved in
01258  *      a copy-under-a-copy scenario.  If X's revision-of-origin is
01259  *      the same as A's, then it was copied under A during the same
01260  *      transaction that created A.  (X's revision-of-origin cannot be
01261  *      greater than A's, if X has copy history.)  @todo See how
01262  *      people like this, it can always be hidden behind the curtain
01263  *      if necessary.
01264  *
01265  *    - Copy ancestry is not stored as a regular subversion property
01266  *      because it is not inherited.  Copying foo to bar results in a
01267  *      revision of bar with copy ancestry; but committing a text
01268  *      change to bar right after that results in a new revision of
01269  *      bar without copy ancestry.
01270  */
01271 svn_error_t *
01272 svn_fs_copied_from(svn_revnum_t *rev_p,
01273                    const char **path_p,
01274                    svn_fs_root_t *root,
01275                    const char *path,
01276                    apr_pool_t *pool);
01277 
01278 
01279 /** Set @a *root_p and @a *path_p to the revision root and path of the
01280  * destination of the most recent copy event that caused @a path to
01281  * exist where it does in @a root, or to NULL if no such copy exists.
01282  * When non-NULL, allocate @a *root_p and @a *path_p in @a pool.
01283  *
01284  * @a *path_p might be a parent of @a path, rather than @a path
01285  * itself.  However, it will always be the deepest relevant path.
01286  * That is, if a copy occurs underneath another copy in the same txn,
01287  * this function makes sure to set @a *path_p to the longest copy
01288  * destination path that is still a parent of or equal to @a path.
01289  *
01290  * @since New in 1.3.
01291  */
01292 svn_error_t *
01293 svn_fs_closest_copy(svn_fs_root_t **root_p,
01294                     const char **path_p,
01295                     svn_fs_root_t *root,
01296                     const char *path,
01297                     apr_pool_t *pool);
01298 
01299 
01300 /** Retrieve mergeinfo for multiple nodes.
01301  *
01302  * @a *catalog is a catalog for @a paths.  It will never be @c NULL,
01303  * but may be empty.
01304  *
01305  * @a root is revision root to use when looking up paths.
01306  *
01307  * @a paths are the paths you are requesting information for.
01308  *
01309  * @a inherit indicates whether to retrieve explicit,
01310  * explicit-or-inherited, or only inherited mergeinfo.
01311  *
01312  * If @a include_descendants is TRUE, then additionally return the
01313  * mergeinfo for any descendant of any element of @a paths which has
01314  * the @c SVN_PROP_MERGEINFO property explicitly set on it.  (Note
01315  * that inheritance is only taken into account for the elements in @a
01316  * paths; descendants of the elements in @a paths which get their
01317  * mergeinfo via inheritance are not included in @a *mergeoutput.)
01318  *
01319  * Do any necessary temporary allocation in @a pool.
01320  *
01321  * @since New in 1.5.
01322  */
01323 svn_error_t *
01324 svn_fs_get_mergeinfo(svn_mergeinfo_catalog_t *catalog,
01325                      svn_fs_root_t *root,
01326                      const apr_array_header_t *paths,
01327                      svn_mergeinfo_inheritance_t inherit,
01328                      svn_boolean_t include_descendants,
01329                      apr_pool_t *pool);
01330 
01331 /** Merge changes between two nodes into a third node.
01332  *
01333  * Given nodes @a source and @a target, and a common ancestor @a ancestor,
01334  * modify @a target to contain all the changes made between @a ancestor and
01335  * @a source, as well as the changes made between @a ancestor and @a target.
01336  * @a target_root must be the root of a transaction, not a revision.
01337  *
01338  * @a source, @a target, and @a ancestor are generally directories; this
01339  * function recursively merges the directories' contents.  If they are
01340  * files, this function simply returns an error whenever @a source,
01341  * @a target, and @a ancestor are all distinct node revisions.
01342  *
01343  * If there are differences between @a ancestor and @a source that conflict
01344  * with changes between @a ancestor and @a target, this function returns an
01345  * @c SVN_ERR_FS_CONFLICT error.
01346  *
01347  * If the merge is successful, @a target is left in the merged state, and
01348  * the base root of @a target's txn is set to the root node of @a source.
01349  * If an error is returned (whether for conflict or otherwise), @a target
01350  * is left unaffected.
01351  *
01352  * If @a conflict_p is non-NULL, then: a conflict error sets @a *conflict_p
01353  * to the name of the node in @a target which couldn't be merged,
01354  * otherwise, success sets @a *conflict_p to NULL.
01355  *
01356  * Do any necessary temporary allocation in @a pool.
01357  */
01358 svn_error_t *
01359 svn_fs_merge(const char **conflict_p,
01360              svn_fs_root_t *source_root,
01361              const char *source_path,
01362              svn_fs_root_t *target_root,
01363              const char *target_path,
01364              svn_fs_root_t *ancestor_root,
01365              const char *ancestor_path,
01366              apr_pool_t *pool);
01367 
01368 
01369 
01370 /* Directories.  */
01371 
01372 
01373 /** The type of a Subversion directory entry.  */
01374 typedef struct svn_fs_dirent_t
01375 {
01376 
01377   /** The name of this directory entry.  */
01378   const char *name;
01379 
01380   /** The node revision ID it names.  */
01381   const svn_fs_id_t *id;
01382 
01383   /** The node kind. */
01384   svn_node_kind_t kind;
01385 
01386 } svn_fs_dirent_t;
01387 
01388 
01389 /** Set @a *entries_p to a newly allocated APR hash table containing the
01390  * entries of the directory at @a path in @a root.  The keys of the table
01391  * are entry names, as byte strings, excluding the final NULL
01392  * character; the table's values are pointers to @c svn_fs_dirent_t
01393  * structures.  Allocate the table and its contents in @a pool.
01394  */
01395 svn_error_t *
01396 svn_fs_dir_entries(apr_hash_t **entries_p,
01397                    svn_fs_root_t *root,
01398                    const char *path,
01399                    apr_pool_t *pool);
01400 
01401 
01402 /** Create a new directory named @a path in @a root.  The new directory has
01403  * no entries, and no properties.  @a root must be the root of a transaction,
01404  * not a revision.
01405  *
01406  * Do any necessary temporary allocation in @a pool.
01407  */
01408 svn_error_t *
01409 svn_fs_make_dir(svn_fs_root_t *root,
01410                 const char *path,
01411                 apr_pool_t *pool);
01412 
01413 
01414 /** Delete the node named @a path in @a root.  If the node being deleted is
01415  * a directory, its contents will be deleted recursively.  @a root must be
01416  * the root of a transaction, not of a revision.  Use @a pool for
01417  * temporary allocation.
01418  *
01419  * This function may be more efficient than making the equivalent
01420  * series of calls to svn_fs_delete(), because it takes advantage of the
01421  * fact that, to delete an immutable subtree, shared with some
01422  * committed revision, you need only remove the directory entry.  The
01423  * dumb algorithm would recurse into the subtree and end up cloning
01424  * each non-empty directory it contains, only to delete it later.
01425  *
01426  * If return @c SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is
01427  * missing from its parent, that is, the final target of the deletion
01428  * is missing.
01429  *
01430  * Attempting to remove the root dir also results in an error,
01431  * @c SVN_ERR_FS_ROOT_DIR, even if the dir is empty.
01432  */
01433 svn_error_t *
01434 svn_fs_delete(svn_fs_root_t *root,
01435               const char *path,
01436               apr_pool_t *pool);
01437 
01438 
01439 /** Create a copy of @a from_path in @a from_root named @a to_path in
01440  * @a to_root.  If @a from_path in @a from_root is a directory, copy the
01441  * tree it refers to recursively.
01442  *
01443  * The copy will remember its source; use svn_fs_copied_from() to
01444  * access this information.
01445  *
01446  * @a to_root must be the root of a transaction; @a from_root must be the
01447  * root of a revision.  (Requiring @a from_root to be the root of a
01448  * revision makes the implementation trivial: there is no detectable
01449  * difference (modulo node revision ID's) between copying @a from and
01450  * simply adding a reference to it.  So the operation takes place in
01451  * constant time.  However, there's no reason not to extend this to
01452  * mutable nodes --- it's just more code.)  Further, @a to_root and @a
01453  * from_root must represent the same filesystem.
01454  *
01455  * @note To do a copy without preserving copy history, use
01456  * svn_fs_revision_link().
01457  *
01458  * Do any necessary temporary allocation in @a pool.
01459  */
01460 svn_error_t *
01461 svn_fs_copy(svn_fs_root_t *from_root,
01462             const char *from_path,
01463             svn_fs_root_t *to_root,
01464             const char *to_path,
01465             apr_pool_t *pool);
01466 
01467 
01468 /** Like svn_fs_copy(), but doesn't record copy history, and preserves
01469  * the PATH.  You cannot use svn_fs_copied_from() later to find out
01470  * where this copy came from.
01471  *
01472  * Use svn_fs_revision_link() in situations where you don't care
01473  * about the copy history, and where @a to_path and @a from_path are
01474  * the same, because it is cheaper than svn_fs_copy().
01475  */
01476 svn_error_t *
01477 svn_fs_revision_link(svn_fs_root_t *from_root,
01478                      svn_fs_root_t *to_root,
01479                      const char *path,
01480                      apr_pool_t *pool);
01481 
01482 /* Files.  */
01483 
01484 /** Set @a *length_p to the length of the file @a path in @a root, in bytes.
01485  * Do any necessary temporary allocation in @a pool.
01486  */
01487 svn_error_t *
01488 svn_fs_file_length(svn_filesize_t *length_p,
01489                    svn_fs_root_t *root,
01490                    const char *path,
01491                    apr_pool_t *pool);
01492 
01493 
01494 /** Put the MD5 checksum of file @a path into @a digest, which points
01495  * to @c APR_MD5_DIGESTSIZE bytes of storage.  Use @a pool only for temporary
01496  * allocations.
01497  *
01498  * If the filesystem does not have a prerecorded checksum for @a path,
01499  * do not calculate a checksum dynamically, just put all 0's into @a
01500  * digest.  (By convention, the all-zero checksum is considered to
01501  * match any checksum.)
01502  *
01503  * Notes:
01504  *
01505  * You might wonder, why do we only provide this interface for file
01506  * contents, and not for properties or directories?
01507  *
01508  * The answer is that property lists and directory entry lists are
01509  * essentially data structures, not text.  We serialize them for
01510  * transmission, but there is no guarantee that the consumer will
01511  * parse them into the same form, or even the same order, as the
01512  * producer.  It's difficult to find a checksumming method that
01513  * reaches the same result given such variation in input.  (I suppose
01514  * we could calculate an independent MD5 sum for each propname and
01515  * value, and XOR them together; same with directory entry names.
01516  * Maybe that's the solution?)  Anyway, for now we punt.  The most
01517  * important data, and the only data that goes through svndiff
01518  * processing, is file contents, so that's what we provide
01519  * checksumming for.
01520  *
01521  * Internally, of course, the filesystem checksums everything, because
01522  * it has access to the lowest level storage forms: strings behind
01523  * representations.
01524  */
01525 svn_error_t *
01526 svn_fs_file_md5_checksum(unsigned char digest[],
01527                          svn_fs_root_t *root,
01528                          const char *path,
01529                          apr_pool_t *pool);
01530 
01531 
01532 /** Set @a *contents to a readable generic stream that will yield the
01533  * contents of the file @a path in @a root.  Allocate the stream in
01534  * @a pool.  You can only use @a *contents for as long as the underlying
01535  * filesystem is open.  If @a path is not a file, return
01536  * @c SVN_ERR_FS_NOT_FILE.
01537  *
01538  * If @a root is the root of a transaction, it is possible that the
01539  * contents of the file @a path will change between calls to
01540  * svn_fs_file_contents().  In that case, the result of reading from
01541  * @a *contents is undefined.
01542  *
01543  * ### @todo kff: I am worried about lifetime issues with this pool vs
01544  * the trail created farther down the call stack.  Trace this function
01545  * to investigate...
01546  */
01547 svn_error_t *
01548 svn_fs_file_contents(svn_stream_t **contents,
01549                      svn_fs_root_t *root,
01550                      const char *path,
01551                      apr_pool_t *pool);
01552 
01553 
01554 /** Create a new file named @a path in @a root.  The file's initial contents
01555  * are the empty string, and it has no properties.  @a root must be the
01556  * root of a transaction, not a revision.
01557  *
01558  * Do any necessary temporary allocation in @a pool.
01559  */
01560 svn_error_t *
01561 svn_fs_make_file(svn_fs_root_t *root,
01562                  const char *path,
01563                  apr_pool_t *pool);
01564 
01565 
01566 /** Apply a text delta to the file @a path in @a root.  @a root must be the
01567  * root of a transaction, not a revision.
01568  *
01569  * Set @a *contents_p to a function ready to receive text delta windows
01570  * describing how to change the file's contents, relative to its
01571  * current contents.  Set @a *contents_baton_p to a baton to pass to
01572  * @a *contents_p.
01573  *
01574  * If @a path does not exist in @a root, return an error.  (You cannot use
01575  * this routine to create new files;  use svn_fs_make_file() to create
01576  * an empty file first.)
01577  *
01578  * @a base_checksum is the hex MD5 digest for the base text against
01579  * which the delta is to be applied; it is ignored if NULL, and may be
01580  * ignored even if not NULL.  If it is not ignored, it must match the
01581  * checksum of the base text against which svndiff data is being
01582  * applied; if not, svn_fs_apply_textdelta() or the @a *contents_p call
01583  * which detects the mismatch will return the error
01584  * @c SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
01585  * still be an error if @a base_checksum is neither NULL nor the
01586  * checksum of the empty string).
01587  *
01588  * @a result_checksum is the hex MD5 digest for the fulltext that
01589  * results from this delta application.  It is ignored if NULL, but if
01590  * not NULL, it must match the checksum of the result; if it does not,
01591  * then the @a *contents_p call which detects the mismatch will return
01592  * the error @c SVN_ERR_CHECKSUM_MISMATCH.
01593  *
01594  * The caller must send all delta windows including the terminating
01595  * NULL window to @a *contents_p before making further changes to the
01596  * transaction.
01597  *
01598  * Do temporary allocation in @a pool.
01599  */
01600 svn_error_t *
01601 svn_fs_apply_textdelta(svn_txdelta_window_handler_t *contents_p,
01602                        void **contents_baton_p,
01603                        svn_fs_root_t *root,
01604                        const char *path,
01605                        const char *base_checksum,
01606                        const char *result_checksum,
01607                        apr_pool_t *pool);
01608 
01609 
01610 /** Write data directly to the file @a path in @a root.  @a root must be the
01611  * root of a transaction, not a revision.
01612  *
01613  * Set @a *contents_p to a stream ready to receive full textual data.
01614  * When the caller closes this stream, the data replaces the previous
01615  * contents of the file.  The caller must write all file data and close
01616  * the stream before making further changes to the transaction.
01617  *
01618  * If @a path does not exist in @a root, return an error.  (You cannot use
01619  * this routine to create new files;  use svn_fs_make_file() to create
01620  * an empty file first.)
01621  *
01622  * @a result_checksum is the hex MD5 digest for the final fulltext
01623  * written to the stream.  It is ignored if NULL, but if not null, it
01624  * must match the checksum of the result; if it does not, then the @a
01625  * *contents_p call which detects the mismatch will return the error
01626  * @c SVN_ERR_CHECKSUM_MISMATCH.
01627  *
01628  * Do any necessary temporary allocation in @a pool.
01629  *
01630  * ### This is like svn_fs_apply_textdelta(), but takes the text
01631  * straight.  It is currently used only by the loader, see
01632  * libsvn_repos/load.c.  It should accept a checksum, of course, which
01633  * would come from an (optional) header in the dump file.  See
01634  * http://subversion.tigris.org/issues/show_bug.cgi?id=1102 for more.
01635  */
01636 svn_error_t *
01637 svn_fs_apply_text(svn_stream_t **contents_p,
01638                   svn_fs_root_t *root,
01639                   const char *path,
01640                   const char *result_checksum,
01641                   apr_pool_t *pool);
01642 
01643 
01644 /** Check if the contents of two root/path combos have changed.
01645  *
01646  * Set @a *changed_p to 1 if the contents at @a path1 under @a root1 differ
01647  * from those at @a path2 under @a root2, or set it to 0 if they are the
01648  * same.  Both paths must exist under their respective roots, and both
01649  * roots must be in the same filesystem.
01650  */
01651 svn_error_t *
01652 svn_fs_contents_changed(svn_boolean_t *changed_p,
01653                         svn_fs_root_t *root1,
01654                         const char *path1,
01655                         svn_fs_root_t *root2,
01656                         const char *path2,
01657                         apr_pool_t *pool);
01658 
01659 
01660 
01661 /* Filesystem revisions.  */
01662 
01663 
01664 /** Set @a *youngest_p to the number of the youngest revision in filesystem
01665  * @a fs.  Use @a pool for all temporary allocation.
01666  *
01667  * The oldest revision in any filesystem is numbered zero.
01668  */
01669 svn_error_t *
01670 svn_fs_youngest_rev(svn_revnum_t *youngest_p,
01671                     svn_fs_t *fs,
01672                     apr_pool_t *pool);
01673 
01674 
01675 /** Deltify predecessors of paths modified in @a revision in
01676  * filesystem @a fs.  Use @a pool for all allocations.
01677  *
01678  * @note This can be a time-consuming process, depending the breadth
01679  * of the changes made in @a revision, and the depth of the history of
01680  * those changed paths.
01681  */
01682 svn_error_t *
01683 svn_fs_deltify_revision(svn_fs_t *fs,
01684                         svn_revnum_t revision,
01685                         apr_pool_t *pool);
01686 
01687 
01688 /** Set @a *value_p to the value of the property named @a propname on
01689  * revision @a rev in the filesystem @a fs.  If @a rev has no property by
01690  * that name, set @a *value_p to zero.  Allocate the result in @a pool.
01691  */
01692 svn_error_t *
01693 svn_fs_revision_prop(svn_string_t **value_p,
01694                      svn_fs_t *fs,
01695                      svn_revnum_t rev,
01696                      const char *propname,
01697                      apr_pool_t *pool);
01698 
01699 
01700 /** Set @a *table_p to the entire property list of revision @a rev in
01701  * filesystem @a fs, as an APR hash table allocated in @a pool.  The table
01702  * maps <tt>char *</tt> property names to @c svn_string_t * values; the names
01703  * and values are allocated in @a pool.
01704  */
01705 svn_error_t *
01706 svn_fs_revision_proplist(apr_hash_t **table_p,
01707                          svn_fs_t *fs,
01708                          svn_revnum_t rev,
01709                          apr_pool_t *pool);
01710 
01711 
01712 /** Change a revision's property's value, or add/delete a property.
01713  *
01714  * - @a fs is a filesystem, and @a rev is the revision in that filesystem
01715  *   whose property should change.
01716  * - @a name is the name of the property to change.
01717  * - @a value is the new value of the property, or zero if the property should
01718  *   be removed altogether.
01719  *
01720  * Note that revision properties are non-historied --- you can change
01721  * them after the revision has been committed.  They are not protected
01722  * via transactions.
01723  *
01724  * Do any necessary temporary allocation in @a pool.
01725  */
01726 svn_error_t *
01727 svn_fs_change_rev_prop(svn_fs_t *fs,
01728                        svn_revnum_t rev,
01729                        const char *name,
01730                        const svn_string_t *value,
01731                        apr_pool_t *pool);
01732 
01733 
01734 
01735 /* Computing deltas.  */
01736 
01737 
01738 /** Set @a *stream_p to a pointer to a delta stream that will turn the
01739  * contents of the file @a source into the contents of the file @a target.
01740  * If @a source_root is zero, use a file with zero length as the source.
01741  *
01742  * This function does not compare the two files' properties.
01743  *
01744  * Allocate @a *stream_p, and do any necessary temporary allocation, in
01745  * @a pool.
01746  */
01747 svn_error_t *
01748 svn_fs_get_file_delta_stream(svn_txdelta_stream_t **stream_p,
01749                              svn_fs_root_t *source_root,
01750                              const char *source_path,
01751                              svn_fs_root_t *target_root,
01752                              const char *target_path,
01753                              apr_pool_t *pool);
01754 
01755 
01756 
01757 /* UUID manipulation. */
01758 
01759 /** Populate @a *uuid with the UUID associated with @a fs.  Allocate
01760     @a *uuid in @a pool.  */
01761 svn_error_t *
01762 svn_fs_get_uuid(svn_fs_t *fs,
01763                 const char **uuid,
01764                 apr_pool_t *pool);
01765 
01766 
01767 /** If not @c NULL, associate @a *uuid with @a fs.  Otherwise (if @a
01768  * uuid is @c NULL), generate a new UUID for @a fs.  Use @a pool for
01769  * any scratchwork.
01770  */
01771 svn_error_t *
01772 svn_fs_set_uuid(svn_fs_t *fs,
01773                 const char *uuid,
01774                 apr_pool_t *pool);
01775 
01776 
01777 /* Non-historical properties.  */
01778 
01779 /* [[Yes, do tell.]] */
01780 
01781 
01782 
01783 /** @defgroup svn_fs_locks Filesystem locks
01784  * @{
01785  * @since New in 1.2. */
01786 
01787 /** A lock represents one user's exclusive right to modify a path in a
01788  * filesystem.  In order to create or destroy a lock, a username must
01789  * be associated with the filesystem's access context (see @c
01790  * svn_fs_access_t).
01791  *
01792  * When a lock is created, a 'lock-token' is returned.  The lock-token
01793  * is a unique URI that represents the lock (treated as an opaque
01794  * string by the client), and is required to make further use of the
01795  * lock (including removal of the lock.)  A lock-token can also be
01796  * queried to return a svn_lock_t structure that describes the details
01797  * of the lock.
01798  *
01799  * Locks are not secret; anyone can view existing locks in a
01800  * filesystem.  Locks are not omnipotent: they can broken and stolen
01801  * by people who don't "own" the lock.  (Though admins can tailor a
01802  * custom break/steal policy via libsvn_repos pre-lock hook script.)
01803  *
01804  * Locks can be created with an optional expiration date.  If a lock
01805  * has an expiration date, then the act of fetching/reading it might
01806  * cause it to automatically expire, returning either nothing or an
01807  * expiration error (depending on the API).
01808  */
01809 
01810 
01811 /** Lock @a path in @a fs, and set @a *lock to a lock
01812  * representing the new lock, allocated in @a pool.
01813  *
01814  * @warning You may prefer to use svn_repos_fs_lock() instead,
01815  * which see.
01816  *
01817  * @a fs must have a username associated with it (see @c
01818  * svn_fs_access_t), else return @c SVN_ERR_FS_NO_USER.  Set the
01819  * 'owner' field in the new lock to the fs username.
01820  *
01821  * @a comment is optional: it's either an xml-escapable UTF8 string
01822  * which describes the lock, or it is @c NULL.
01823  *
01824  * @a is_dav_comment describes whether the comment was created by a
01825  * generic DAV client; only mod_dav_svn's autoversioning feature needs
01826  * to use it.  If in doubt, pass 0.
01827  *
01828  * If path is already locked, then return @c SVN_ERR_FS_PATH_ALREADY_LOCKED,
01829  * unless @a steal_lock is TRUE, in which case "steal" the existing
01830  * lock, even if the FS access-context's username does not match the
01831  * current lock's owner: delete the existing lock on @a path, and
01832  * create a new one.
01833  *
01834  * @a token is a lock token such as can be generated using
01835  * svn_fs_generate_lock_token() (indicating that the caller wants to
01836  * dictate the lock token used), or it is @c NULL (indicating that the
01837  * caller wishes to have a new token generated by this function).  If
01838  * @a token is not @c NULL, and represents an existing lock, then @a
01839  * path must match the path associated with that existing lock.
01840  *
01841  * If @a expiration_date is zero, then create a non-expiring lock.
01842  * Else, the lock will expire at @a expiration_date.
01843  *
01844  * If @a current_rev is a valid revnum, then do an out-of-dateness
01845  * check.  If the revnum is less than the last-changed-revision of @a
01846  * path (or if @a path doesn't exist in HEAD), return @c
01847  * SVN_ERR_FS_OUT_OF_DATE.
01848  *
01849  * @note At this time, only files can be locked.
01850  */
01851 svn_error_t *
01852 svn_fs_lock(svn_lock_t **lock,
01853             svn_fs_t *fs,
01854             const char *path,
01855             const char *token,
01856             const char *comment,
01857             svn_boolean_t is_dav_comment,
01858             apr_time_t expiration_date,
01859             svn_revnum_t current_rev,
01860             svn_boolean_t steal_lock,
01861             apr_pool_t *pool);
01862 
01863 
01864 /** Generate a unique lock-token using @a fs. Return in @a *token,
01865  * allocated in @a pool.
01866  *
01867  * This can be used in to populate lock->token before calling
01868  * svn_fs_attach_lock().
01869  */
01870 svn_error_t *
01871 svn_fs_generate_lock_token(const char **token,
01872                            svn_fs_t *fs,
01873                            apr_pool_t *pool);
01874 
01875 
01876 /** Remove the lock on @a path represented by @a token in @a fs.
01877  *
01878  * If @a token doesn't point to a lock, return @c SVN_ERR_FS_BAD_LOCK_TOKEN.
01879  * If @a token points to an expired lock, return @c SVN_ERR_FS_LOCK_EXPIRED.
01880  * If @a fs has no username associated with it, return @c SVN_ERR_FS_NO_USER
01881  * unless @a break_lock is specified.
01882  *
01883  * If @a token points to a lock, but the username of @a fs's access
01884  * context doesn't match the lock's owner, return @c
01885  * SVN_ERR_FS_LOCK_OWNER_MISMATCH.  If @a break_lock is TRUE, however, don't
01886  * return error;  allow the lock to be "broken" in any case.  In the latter
01887  * case, @a token shall be @c NULL.
01888  *
01889  * Use @a pool for temporary allocations.
01890  */
01891 svn_error_t *
01892 svn_fs_unlock(svn_fs_t *fs,
01893               const char *path,
01894               const char *token,
01895               svn_boolean_t break_lock,
01896               apr_pool_t *pool);
01897 
01898 
01899 /** If @a path is locked in @a fs, set @a *lock to an svn_lock_t which
01900  *  represents the lock, allocated in @a pool.
01901  *
01902  * If @a path is not locked, set @a *lock to NULL.
01903  */
01904 svn_error_t *
01905 svn_fs_get_lock(svn_lock_t **lock,
01906                 svn_fs_t *fs,
01907                 const char *path,
01908                 apr_pool_t *pool);
01909 
01910 
01911 /** The type of a lock discovery callback function.  @a baton is the
01912  * value specified in the call to svn_fs_get_locks(); the filesystem
01913  * passes it through to the callback.  @a lock is a lock structure.
01914  * @a pool is a temporary subpool for use by the callback
01915  * implementation -- it is cleared after invocation of the callback.
01916  */
01917 typedef svn_error_t *(*svn_fs_get_locks_callback_t)(void *baton,
01918                                                     svn_lock_t *lock,
01919                                                     apr_pool_t *pool);
01920 
01921 
01922 /** Report locks on or below @a path in @a fs using the @a
01923  * get_locks_func / @a get_locks_baton.  Use @a pool for necessary
01924  * allocations.
01925  *
01926  * If the @a get_locks_func callback implementation returns an error,
01927  * lock iteration will terminate and that error will be returned by
01928  * this function.
01929  */
01930 svn_error_t *
01931 svn_fs_get_locks(svn_fs_t *fs,
01932                  const char *path,
01933                  svn_fs_get_locks_callback_t get_locks_func,
01934                  void *get_locks_baton,
01935                  apr_pool_t *pool);
01936 
01937 /** @} */
01938 
01939 /**
01940  * Append a textual list of all available FS modules to the stringbuf
01941  * @a output.
01942  *
01943  * @since New in 1.2.
01944  */
01945 svn_error_t *
01946 svn_fs_print_modules(svn_stringbuf_t *output,
01947                      apr_pool_t *pool);
01948 
01949 /** @} */
01950 
01951 #ifdef __cplusplus
01952 }
01953 #endif /* __cplusplus */
01954 
01955 #endif /* SVN_FS_H */

Generated on Sun Dec 14 02:22:43 2008 for Subversion by  doxygen 1.4.7