- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# svn_fs.h

Go to the documentation of this file.

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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines