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