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

Generated on Sat Jun 4 16:24:10 2011 for Subversion by  doxygen 1.4.7