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