Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_fs.h

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

Generated on Sat Feb 3 13:51:29 2007 for Subversion by  doxygen 1.4.2