1 /** 2 * @copyright 3 * ==================================================================== 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_fs.h 24 * @brief Interface to the Subversion filesystem. 25 */ 26 27 #ifndef SVN_FS_H 28 #define SVN_FS_H 29 30 #include <apr.h> 31 #include <apr_pools.h> 32 #include <apr_hash.h> 33 #include <apr_tables.h> 34 #include <apr_time.h> /* for apr_time_t */ 35 36 #include "svn_types.h" 37 #include "svn_string.h" 38 #include "svn_delta.h" 39 #include "svn_io.h" 40 #include "svn_mergeinfo.h" 41 #include "svn_checksum.h" 42 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif /* __cplusplus */ 47 48 49 /** 50 * Get libsvn_fs version information. 51 * 52 * @since New in 1.1. 53 */ 54 const svn_version_t * 55 svn_fs_version(void); 56 57 /** 58 * @defgroup fs_handling Filesystem interaction subsystem 59 * @{ 60 */ 61 62 /* Opening and creating filesystems. */ 63 64 65 /** An object representing a Subversion filesystem. */ 66 typedef struct svn_fs_t svn_fs_t; 67 68 69 /** 70 * @name Filesystem configuration options 71 * @{ 72 */ 73 #define SVN_FS_CONFIG_BDB_TXN_NOSYNC "bdb-txn-nosync" 74 #define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE "bdb-log-autoremove" 75 76 /** Enable / disable text delta caching for a FSFS repository. 77 * 78 * @since New in 1.7. 79 */ 80 #define SVN_FS_CONFIG_FSFS_CACHE_DELTAS "fsfs-cache-deltas" 81 82 /** Enable / disable full-text caching for a FSFS repository. 83 * 84 * @since New in 1.7. 85 */ 86 #define SVN_FS_CONFIG_FSFS_CACHE_FULLTEXTS "fsfs-cache-fulltexts" 87 88 /** Enable / disable revprop caching for a FSFS repository. 89 * 90 * "2" is allowed, too and means "enable if efficient", 91 * i.e. this will not create warning at runtime if there 92 * if no efficient support for revprop caching. 93 * 94 * @since New in 1.8. 95 */ 96 #define SVN_FS_CONFIG_FSFS_CACHE_REVPROPS "fsfs-cache-revprops" 97 98 /** Select the cache namespace. If you potentially share the cache with 99 * another FS object for the same repository, objects read through one FS 100 * will not need to be read again for the other. In most cases, that is 101 * a very desirable behavior and the default is, therefore, an empty 102 * namespace. 103 * 104 * If you want to be sure that your FS instance will actually read all 105 * requested data at least once, you need to specify a separate namespace 106 * for it. All repository verification code, for instance, should use 107 * some GUID here that is different each time you open an FS instance. 108 * 109 * @since New in 1.8. 110 */ 111 #define SVN_FS_CONFIG_FSFS_CACHE_NS "fsfs-cache-namespace" 112 113 /* Note to maintainers: if you add further SVN_FS_CONFIG_FSFS_CACHE_* knobs, 114 update fs_fs.c:verify_as_revision_before_current_plus_plus(). */ 115 116 /* See also svn_fs_type(). */ 117 /** @since New in 1.1. */ 118 #define SVN_FS_CONFIG_FS_TYPE "fs-type" 119 /** @since New in 1.1. */ 120 #define SVN_FS_TYPE_BDB "bdb" 121 /** @since New in 1.1. */ 122 #define SVN_FS_TYPE_FSFS "fsfs" 123 124 /** Create repository format compatible with Subversion versions 125 * earlier than 1.4. 126 * 127 * @since New in 1.4. 128 */ 129 #define SVN_FS_CONFIG_PRE_1_4_COMPATIBLE "pre-1.4-compatible" 130 131 /** Create repository format compatible with Subversion versions 132 * earlier than 1.5. 133 * 134 * @since New in 1.5. 135 */ 136 #define SVN_FS_CONFIG_PRE_1_5_COMPATIBLE "pre-1.5-compatible" 137 138 /** Create repository format compatible with Subversion versions 139 * earlier than 1.6. 140 * 141 * @since New in 1.6. 142 */ 143 #define SVN_FS_CONFIG_PRE_1_6_COMPATIBLE "pre-1.6-compatible" 144 145 /** Create repository format compatible with Subversion versions 146 * earlier than 1.8. 147 * 148 * @since New in 1.8. 149 */ 150 #define SVN_FS_CONFIG_PRE_1_8_COMPATIBLE "pre-1.8-compatible" 151 /** @} */ 152 153 154 /** 155 * Callers should invoke this function to initialize global state in 156 * the FS library before creating FS objects. If this function is 157 * invoked, no FS objects may be created in another thread at the same 158 * time as this invocation, and the provided @a pool must last longer 159 * than any FS object created subsequently. 160 * 161 * If this function is not called, the FS library will make a best 162 * effort to bootstrap a mutex for protecting data common to FS 163 * objects; however, there is a small window of failure. Also, a 164 * small amount of data will be leaked if the Subversion FS library is 165 * dynamically unloaded, and using the bdb FS can potentially segfault 166 * or invoke other undefined behavior if this function is not called 167 * with an appropriate pool (such as the pool the module was loaded into) 168 * when loaded dynamically. 169 * 170 * If this function is called multiple times before the pool passed to 171 * the first call is destroyed or cleared, the later calls will have 172 * no effect. 173 * 174 * @since New in 1.2. 175 */ 176 svn_error_t * 177 svn_fs_initialize(apr_pool_t *pool); 178 179 180 /** The type of a warning callback function. @a baton is the value specified 181 * in the call to svn_fs_set_warning_func(); the filesystem passes it through 182 * to the callback. @a err contains the warning message. 183 * 184 * The callback function should not clear the error that is passed to it; 185 * its caller should do that. 186 */ 187 typedef void (*svn_fs_warning_callback_t)(void *baton, svn_error_t *err); 188 189 190 /** Provide a callback function, @a warning, that @a fs should use to 191 * report (non-fatal) errors. To print an error, the filesystem will call 192 * @a warning, passing it @a warning_baton and the error. 193 * 194 * By default, this is set to a function that will crash the process. 195 * Dumping to @c stderr or <tt>/dev/tty</tt> is not acceptable default 196 * behavior for server processes, since those may both be equivalent to 197 * <tt>/dev/null</tt>. 198 */ 199 void 200 svn_fs_set_warning_func(svn_fs_t *fs, 201 svn_fs_warning_callback_t warning, 202 void *warning_baton); 203 204 205 206 /** 207 * Create a new, empty Subversion filesystem, stored in the directory 208 * @a path, and return a pointer to it in @a *fs_p. @a path must not 209 * currently exist, but its parent must exist. If @a fs_config is not 210 * @c NULL, the options it contains modify the behavior of the 211 * filesystem. The interpretation of @a fs_config is specific to the 212 * filesystem back-end. The new filesystem may be closed by 213 * destroying @a pool. 214 * 215 * @note The lifetime of @a fs_config must not be shorter than @a 216 * pool's. It's a good idea to allocate @a fs_config from @a pool or 217 * one of its ancestors. 218 * 219 * If @a fs_config contains a value for #SVN_FS_CONFIG_FS_TYPE, that 220 * value determines the filesystem type for the new filesystem. 221 * Currently defined values are: 222 * 223 * SVN_FS_TYPE_BDB Berkeley-DB implementation 224 * SVN_FS_TYPE_FSFS Native-filesystem implementation 225 * 226 * If @a fs_config is @c NULL or does not contain a value for 227 * #SVN_FS_CONFIG_FS_TYPE then the default filesystem type will be used. 228 * This will typically be BDB for version 1.1 and FSFS for later versions, 229 * though the caller should not rely upon any particular default if they 230 * wish to ensure that a filesystem of a specific type is created. 231 * 232 * @since New in 1.1. 233 */ 234 svn_error_t * 235 svn_fs_create(svn_fs_t **fs_p, 236 const char *path, 237 apr_hash_t *fs_config, 238 apr_pool_t *pool); 239 240 /** 241 * Open a Subversion filesystem located in the directory @a path, and 242 * return a pointer to it in @a *fs_p. If @a fs_config is not @c 243 * NULL, the options it contains modify the behavior of the 244 * filesystem. The interpretation of @a fs_config is specific to the 245 * filesystem back-end. The opened filesystem may be closed by 246 * destroying @a pool. 247 * 248 * @note The lifetime of @a fs_config must not be shorter than @a 249 * pool's. It's a good idea to allocate @a fs_config from @a pool or 250 * one of its ancestors. 251 * 252 * Only one thread may operate on any given filesystem object at once. 253 * Two threads may access the same filesystem simultaneously only if 254 * they open separate filesystem objects. 255 * 256 * @note You probably don't want to use this directly. Take a look at 257 * svn_repos_open2() instead. 258 * 259 * @since New in 1.1. 260 */ 261 svn_error_t * 262 svn_fs_open(svn_fs_t **fs_p, 263 const char *path, 264 apr_hash_t *fs_config, 265 apr_pool_t *pool); 266 267 /** 268 * Upgrade the Subversion filesystem located in the directory @a path 269 * to the latest version supported by this library. Return 270 * #SVN_ERR_FS_UNSUPPORTED_UPGRADE and make no changes to the 271 * filesystem if the requested upgrade is not supported. Use @a pool 272 * for necessary allocations. 273 * 274 * @note You probably don't want to use this directly. Take a look at 275 * svn_repos_upgrade() instead. 276 * 277 * @since New in 1.5. 278 */ 279 svn_error_t * 280 svn_fs_upgrade(const char *path, 281 apr_pool_t *pool); 282 283 /** 284 * Callback function type for progress notification. 285 * 286 * @a revision is the number of the revision currently begin processed, 287 * #SVN_INVALID_REVNUM if the current stage is not linked to any specific 288 * revision. @a baton is the callback baton. 289 * 290 * @since New in 1.8. 291 */ 292 typedef void (*svn_fs_progress_notify_func_t)(svn_revnum_t revision, 293 void *baton, 294 apr_pool_t *pool); 295 296 /** 297 * Return, in @a *fs_type, a string identifying the back-end type of 298 * the Subversion filesystem located in @a path. Allocate @a *fs_type 299 * in @a pool. 300 * 301 * The string should be equal to one of the @c SVN_FS_TYPE_* defined 302 * constants, unless the filesystem is a new back-end type added in 303 * a later version of Subversion. 304 * 305 * In general, the type should make no difference in the filesystem's 306 * semantics, but there are a few situations (such as backups) where 307 * it might matter. 308 * 309 * @since New in 1.3. 310 */ 311 svn_error_t * 312 svn_fs_type(const char **fs_type, 313 const char *path, 314 apr_pool_t *pool); 315 316 /** 317 * Return the path to @a fs's repository, allocated in @a pool. 318 * @note This is just what was passed to svn_fs_create() or 319 * svn_fs_open() -- might be absolute, might not. 320 * 321 * @since New in 1.1. 322 */ 323 const char * 324 svn_fs_path(svn_fs_t *fs, 325 apr_pool_t *pool); 326 327 /** 328 * Return a shallow copy of the configuration parameters used to open 329 * @a fs, allocated in @a pool. It may be @c NULL. The contents of the 330 * hash contents remains valid only for @a fs's lifetime. 331 * 332 * @note This is just what was passed to svn_fs_create() or svn_fs_open(). 333 * You may not modify it. 334 * 335 * @since New in 1.8. 336 */ 337 apr_hash_t * 338 svn_fs_config(svn_fs_t *fs, 339 apr_pool_t *pool); 340 341 /** 342 * Delete the filesystem at @a path. 343 * 344 * @note: Deleting a filesystem that has an open svn_fs_t is not 345 * supported. Clear/destroy all pools used to create/open @a path. 346 * See issue 4264. 347 * 348 * @since New in 1.1. 349 */ 350 svn_error_t * 351 svn_fs_delete_fs(const char *path, 352 apr_pool_t *pool); 353 354 /** 355 * Copy a possibly live Subversion filesystem from @a src_path to 356 * @a dest_path. If @a clean is @c TRUE, perform cleanup on the 357 * source filesystem as part of the copy operation; currently, this 358 * means deleting copied, unused logfiles for a Berkeley DB source 359 * filesystem. 360 * 361 * If @a incremental is TRUE, make an effort to avoid re-copying 362 * information already present in the destination where possible. If 363 * incremental hotcopy is not implemented, raise 364 * #SVN_ERR_UNSUPPORTED_FEATURE. 365 * 366 * Use @a scratch_pool for temporary allocations. 367 * 368 * @since New in 1.8. 369 */ 370 svn_error_t * 371 svn_fs_hotcopy2(const char *src_path, 372 const char *dest_path, 373 svn_boolean_t clean, 374 svn_boolean_t incremental, 375 svn_cancel_func_t cancel_func, 376 void *cancel_baton, 377 apr_pool_t *scratch_pool); 378 379 /** 380 * Like svn_fs_hotcopy2(), but with @a incremental always passed as @c 381 * TRUE and without cancellation support. 382 * 383 * @deprecated Provided for backward compatibility with the 1.7 API. 384 * @since New in 1.1. 385 */ 386 SVN_DEPRECATED 387 svn_error_t * 388 svn_fs_hotcopy(const char *src_path, 389 const char *dest_path, 390 svn_boolean_t clean, 391 apr_pool_t *pool); 392 393 /** Perform any necessary non-catastrophic recovery on the Subversion 394 * filesystem located at @a path. 395 * 396 * If @a cancel_func is not @c NULL, it is called periodically with 397 * @a cancel_baton as argument to see if the client wishes to cancel 398 * recovery. BDB filesystems do not currently support cancellation. 399 * 400 * Do any necessary allocation within @a pool. 401 * 402 * For FSFS filesystems, recovery is currently limited to recreating 403 * the db/current file, and does not require exclusive access. 404 * 405 * For BDB filesystems, recovery requires exclusive access, and is 406 * described in detail below. 407 * 408 * After an unexpected server exit, due to a server crash or a system 409 * crash, a Subversion filesystem based on Berkeley DB needs to run 410 * recovery procedures to bring the database back into a consistent 411 * state and release any locks that were held by the deceased process. 412 * The recovery procedures require exclusive access to the database 413 * --- while they execute, no other process or thread may access the 414 * database. 415 * 416 * In a server with multiple worker processes, like Apache, if a 417 * worker process accessing the filesystem dies, you must stop the 418 * other worker processes, and run recovery. Then, the other worker 419 * processes can re-open the database and resume work. 420 * 421 * If the server exited cleanly, there is no need to run recovery, but 422 * there is no harm in it, either, and it take very little time. So 423 * it's a fine idea to run recovery when the server process starts, 424 * before it begins handling any requests. 425 * 426 * @since New in 1.5. 427 */ 428 svn_error_t * 429 svn_fs_recover(const char *path, 430 svn_cancel_func_t cancel_func, 431 void *cancel_baton, 432 apr_pool_t *pool); 433 434 435 /** 436 * Callback for svn_fs_freeze(). 437 * 438 * @since New in 1.8. 439 */ 440 typedef svn_error_t *(*svn_fs_freeze_func_t)(void *baton, apr_pool_t *pool); 441 442 /** 443 * Take an exclusive lock on @a fs to prevent commits and then invoke 444 * @a freeze_func passing @a freeze_baton. 445 * 446 * @note The BDB backend doesn't implement this feature so most 447 * callers should not call this function directly but should use the 448 * higher level svn_repos_freeze() instead. 449 * 450 * @see svn_repos_freeze() 451 * 452 * @since New in 1.8. 453 */ 454 svn_error_t * 455 svn_fs_freeze(svn_fs_t *fs, 456 svn_fs_freeze_func_t freeze_func, 457 void *freeze_baton, 458 apr_pool_t *pool); 459 460 461 /** Subversion filesystems based on Berkeley DB. 462 * 463 * The following functions are specific to Berkeley DB filesystems. 464 * 465 * @defgroup svn_fs_bdb Berkeley DB filesystems 466 * @{ 467 */ 468 469 /** Register an error handling function for Berkeley DB error messages. 470 * 471 * @deprecated Provided for backward compatibility with the 1.2 API. 472 * 473 * Despite being first declared deprecated in Subversion 1.3, this API 474 * is redundant in versions 1.1 and 1.2 as well. 475 * 476 * Berkeley DB's error codes are seldom sufficiently informative to allow 477 * adequate troubleshooting. Berkeley DB provides extra messages through 478 * a callback function - if an error occurs, the @a handler will be called 479 * with two strings: an error message prefix, which will be zero, and 480 * an error message. @a handler might print it out, log it somewhere, 481 * etc. 482 * 483 * Subversion 1.1 and later install their own handler internally, and 484 * wrap the messages from Berkeley DB into the standard svn_error_t object, 485 * making any information gained through this interface redundant. 486 * 487 * It is only worth using this function if your program will be used 488 * with Subversion 1.0. 489 * 490 * This function connects to the Berkeley DB @c DBENV->set_errcall interface. 491 * Since that interface supports only a single callback, Subversion's internal 492 * callback is registered with Berkeley DB, and will forward notifications to 493 * a user provided callback after performing its own processing. 494 */ 495 SVN_DEPRECATED 496 svn_error_t * 497 svn_fs_set_berkeley_errcall(svn_fs_t *fs, 498 void (*handler)(const char *errpfx, 499 char *msg)); 500 501 /** Set @a *logfiles to an array of <tt>const char *</tt> log file names 502 * of Berkeley DB-based Subversion filesystem. 503 * 504 * If @a only_unused is @c TRUE, set @a *logfiles to an array which 505 * contains only the names of Berkeley DB log files no longer in use 506 * by the filesystem. Otherwise, all log files (used and unused) are 507 * returned. 508 509 * This function wraps the Berkeley DB 'log_archive' function 510 * called by the db_archive binary. Repository administrators may 511 * want to run this function periodically and delete the unused log 512 * files, as a way of reclaiming disk space. 513 */ 514 svn_error_t * 515 svn_fs_berkeley_logfiles(apr_array_header_t **logfiles, 516 const char *path, 517 svn_boolean_t only_unused, 518 apr_pool_t *pool); 519 520 521 /** 522 * The following functions are similar to their generic counterparts. 523 * 524 * In Subversion 1.2 and earlier, they only work on Berkeley DB filesystems. 525 * In Subversion 1.3 and later, they perform largely as aliases for their 526 * generic counterparts (with the exception of recover, which only gained 527 * a generic counterpart in 1.5). 528 * 529 * @defgroup svn_fs_bdb_deprecated Berkeley DB filesystem compatibility 530 * @{ 531 */ 532 533 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 534 SVN_DEPRECATED 535 svn_fs_t * 536 svn_fs_new(apr_hash_t *fs_config, 537 apr_pool_t *pool); 538 539 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 540 SVN_DEPRECATED 541 svn_error_t * 542 svn_fs_create_berkeley(svn_fs_t *fs, 543 const char *path); 544 545 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 546 SVN_DEPRECATED 547 svn_error_t * 548 svn_fs_open_berkeley(svn_fs_t *fs, 549 const char *path); 550 551 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 552 SVN_DEPRECATED 553 const char * 554 svn_fs_berkeley_path(svn_fs_t *fs, 555 apr_pool_t *pool); 556 557 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 558 SVN_DEPRECATED 559 svn_error_t * 560 svn_fs_delete_berkeley(const char *path, 561 apr_pool_t *pool); 562 563 /** @deprecated Provided for backward compatibility with the 1.0 API. */ 564 SVN_DEPRECATED 565 svn_error_t * 566 svn_fs_hotcopy_berkeley(const char *src_path, 567 const char *dest_path, 568 svn_boolean_t clean_logs, 569 apr_pool_t *pool); 570 571 /** @deprecated Provided for backward compatibility with the 1.4 API. */ 572 SVN_DEPRECATED 573 svn_error_t * 574 svn_fs_berkeley_recover(const char *path, 575 apr_pool_t *pool); 576 /** @} */ 577 578 /** @} */ 579 580 581 /** Filesystem Access Contexts. 582 * 583 * @since New in 1.2. 584 * 585 * At certain times, filesystem functions need access to temporary 586 * user data. For example, which user is changing a file? If the 587 * file is locked, has an appropriate lock-token been supplied? 588 * 589 * This temporary user data is stored in an "access context" object, 590 * and the access context is then connected to the filesystem object. 591 * Whenever a filesystem function requires information, it can pull 592 * things out of the context as needed. 593 * 594 * @defgroup svn_fs_access_ctx Filesystem access contexts 595 * @{ 596 */ 597 598 /** An opaque object representing temporary user data. */ 599 typedef struct svn_fs_access_t svn_fs_access_t; 600 601 602 /** Set @a *access_ctx to a new #svn_fs_access_t object representing 603 * @a username, allocated in @a pool. @a username is presumed to 604 * have been authenticated by the caller. 605 * 606 * Make a deep copy of @a username. 607 */ 608 svn_error_t * 609 svn_fs_create_access(svn_fs_access_t **access_ctx, 610 const char *username, 611 apr_pool_t *pool); 612 613 614 /** Associate @a access_ctx with an open @a fs. 615 * 616 * This function can be run multiple times on the same open 617 * filesystem, in order to change the filesystem access context for 618 * different filesystem operations. Pass a NULL value for @a 619 * access_ctx to disassociate the current access context from the 620 * filesystem. 621 */ 622 svn_error_t * 623 svn_fs_set_access(svn_fs_t *fs, 624 svn_fs_access_t *access_ctx); 625 626 627 /** Set @a *access_ctx to the current @a fs access context, or NULL if 628 * there is no current fs access context. 629 */ 630 svn_error_t * 631 svn_fs_get_access(svn_fs_access_t **access_ctx, 632 svn_fs_t *fs); 633 634 635 /** Accessors for the access context: */ 636 637 /** Set @a *username to the name represented by @a access_ctx. */ 638 svn_error_t * 639 svn_fs_access_get_username(const char **username, 640 svn_fs_access_t *access_ctx); 641 642 643 /** Push a lock-token @a token associated with path @a path into the 644 * context @a access_ctx. The context remembers all tokens it 645 * receives, and makes them available to fs functions. The token and 646 * path are not duplicated into @a access_ctx's pool; make sure the 647 * token's lifetime is at least as long as @a access_ctx. 648 * 649 * @since New in 1.6. */ 650 svn_error_t * 651 svn_fs_access_add_lock_token2(svn_fs_access_t *access_ctx, 652 const char *path, 653 const char *token); 654 655 /** 656 * Same as svn_fs_access_add_lock_token2(), but with @a path set to value 1. 657 * 658 * @deprecated Provided for backward compatibility with the 1.5 API. 659 */ 660 SVN_DEPRECATED 661 svn_error_t * 662 svn_fs_access_add_lock_token(svn_fs_access_t *access_ctx, 663 const char *token); 664 665 /** @} */ 666 667 668 /** Filesystem Nodes and Node-Revisions. 669 * 670 * In a Subversion filesystem, a `node' corresponds roughly to an 671 * `inode' in a Unix filesystem: 672 * - A node is either a file or a directory. 673 * - A node's contents change over time. 674 * - When you change a node's contents, it's still the same node; it's 675 * just been changed. So a node's identity isn't bound to a specific 676 * set of contents. 677 * - If you rename a node, it's still the same node, just under a 678 * different name. So a node's identity isn't bound to a particular 679 * filename. 680 * 681 * A `node revision' refers to one particular version of a node's contents, 682 * that existed over a specific period of time (one or more repository 683 * revisions). Changing a node's contents always creates a new revision of 684 * that node, which is to say creates a new `node revision'. Once created, 685 * a node revision's contents never change. 686 * 687 * When we create a node, its initial contents are the initial revision of 688 * the node. As users make changes to the node over time, we create new 689 * revisions of that same node. When a user commits a change that deletes 690 * a file from the filesystem, we don't delete the node, or any revision 691 * of it --- those stick around to allow us to recreate prior revisions of 692 * the filesystem. Instead, we just remove the reference to the node 693 * from the directory. 694 * 695 * Each node revision is a part of exactly one node, and appears only once 696 * in the history of that node. It is uniquely identified by a node 697 * revision id, #svn_fs_id_t. Its node revision id also identifies which 698 * node it is a part of. 699 * 700 * @note: Often when we talk about `the node' within the context of a single 701 * revision (or transaction), we implicitly mean `the node as it appears in 702 * this revision (or transaction)', or in other words `the node revision'. 703 * 704 * @note: Commonly, a node revision will have the same content as some other 705 * node revisions in the same node and in different nodes. The FS libraries 706 * allow different node revisions to share the same data without storing a 707 * separate copy of the data. 708 * 709 * @defgroup svn_fs_nodes Filesystem nodes 710 * @{ 711 */ 712 713 /** An object representing a node-revision id. */ 714 typedef struct svn_fs_id_t svn_fs_id_t; 715 716 717 /** Return -1, 0, or 1 if node revisions @a a and @a b are respectively 718 * unrelated, equivalent, or otherwise related (part of the same node). 719 */ 720 int 721 svn_fs_compare_ids(const svn_fs_id_t *a, 722 const svn_fs_id_t *b); 723 724 725 726 /** Return TRUE if node revisions @a id1 and @a id2 are related (part of the 727 * same node), else return FALSE. 728 */ 729 svn_boolean_t 730 svn_fs_check_related(const svn_fs_id_t *id1, 731 const svn_fs_id_t *id2); 732 733 734 /** 735 * @note This function is not guaranteed to work with all filesystem 736 * types. There is currently no un-deprecated equivalent; contact the 737 * Subversion developers if you have a need for it. 738 * 739 * @deprecated Provided for backward compatibility with the 1.0 API. 740 */ 741 SVN_DEPRECATED 742 svn_fs_id_t * 743 svn_fs_parse_id(const char *data, 744 apr_size_t len, 745 apr_pool_t *pool); 746 747 748 /** Return a Subversion string containing the unparsed form of the 749 * node revision id @a id. Allocate the string containing the 750 * unparsed form in @a pool. 751 */ 752 svn_string_t * 753 svn_fs_unparse_id(const svn_fs_id_t *id, 754 apr_pool_t *pool); 755 756 /** @} */ 757 758 759 /** Filesystem Transactions. 760 * 761 * To make a change to a Subversion filesystem: 762 * - Create a transaction object, using svn_fs_begin_txn(). 763 * - Call svn_fs_txn_root(), to get the transaction's root directory. 764 * - Make whatever changes you like in that tree. 765 * - Commit the transaction, using svn_fs_commit_txn(). 766 * 767 * The filesystem implementation guarantees that your commit will 768 * either: 769 * - succeed completely, so that all of the changes are committed to 770 * create a new revision of the filesystem, or 771 * - fail completely, leaving the filesystem unchanged. 772 * 773 * Until you commit the transaction, any changes you make are 774 * invisible. Only when your commit succeeds do they become visible 775 * to the outside world, as a new revision of the filesystem. 776 * 777 * If you begin a transaction, and then decide you don't want to make 778 * the change after all (say, because your net connection with the 779 * client disappeared before the change was complete), you can call 780 * svn_fs_abort_txn(), to cancel the entire transaction; this 781 * leaves the filesystem unchanged. 782 * 783 * The only way to change the contents of files or directories, or 784 * their properties, is by making a transaction and creating a new 785 * revision, as described above. Once a revision has been committed, it 786 * never changes again; the filesystem interface provides no means to 787 * go back and edit the contents of an old revision. Once history has 788 * been recorded, it is set in stone. Clients depend on this property 789 * to do updates and commits reliably; proxies depend on this property 790 * to cache changes accurately; and so on. 791 * 792 * There are two kinds of nodes in the filesystem: mutable, and 793 * immutable. Revisions in the filesystem consist entirely of 794 * immutable nodes, whose contents never change. A transaction in 795 * progress, which the user is still constructing, uses mutable nodes 796 * for those nodes which have been changed so far, and refers to 797 * immutable nodes from existing revisions for portions of the tree 798 * which haven't been changed yet in that transaction. 799 * 800 * Immutable nodes, as part of revisions, never refer to mutable 801 * nodes, which are part of uncommitted transactions. Mutable nodes 802 * may refer to immutable nodes, or other mutable nodes. 803 * 804 * Note that the terms "immutable" and "mutable" describe whether or 805 * not the nodes have been changed as part of a transaction --- not 806 * the permissions on the nodes they refer to. Even if you aren't 807 * authorized to modify the filesystem's root directory, you might be 808 * authorized to change some descendant of the root; doing so would 809 * create a new mutable copy of the root directory. Mutability refers 810 * to the role of the node: part of an existing revision, or part of a 811 * new one. This is independent of your authorization to make changes 812 * to a given node. 813 * 814 * Transactions are actually persistent objects, stored in the 815 * database. You can open a filesystem, begin a transaction, and 816 * close the filesystem, and then a separate process could open the 817 * filesystem, pick up the same transaction, and continue work on it. 818 * When a transaction is successfully committed, it is removed from 819 * the database. 820 * 821 * Every transaction is assigned a name. You can open a transaction 822 * by name, and resume work on it, or find out the name of a 823 * transaction you already have open. You can also list all the 824 * transactions currently present in the database. 825 * 826 * You may assign properties to transactions; these are name/value 827 * pairs. When you commit a transaction, all of its properties become 828 * unversioned revision properties of the new revision. (There is one 829 * exception: the svn:date property will be automatically set on new 830 * transactions to the date that the transaction was created, and will 831 * be overwritten when the transaction is committed by the current 832 * time; changes to a transaction's svn:date property will not affect 833 * its committed value.) 834 * 835 * Transaction names are guaranteed to contain only letters (upper- 836 * and lower-case), digits, `-', and `.', from the ASCII character 837 * set. 838 * 839 * The Subversion filesystem will make a best effort to not reuse 840 * transaction names. The Berkeley DB backend generates transaction 841 * names using a sequence, or a counter, which is stored in the BDB 842 * database. Each new transaction increments the counter. The 843 * current value of the counter is not serialized into a filesystem 844 * dump file, so dumping and restoring the repository will reset the 845 * sequence and reuse transaction names. The FSFS backend generates a 846 * transaction name using the hostname, process ID and current time in 847 * microseconds since 00:00:00 January 1, 1970 UTC. So it is 848 * extremely unlikely that a transaction name will be reused. 849 * 850 * @defgroup svn_fs_txns Filesystem transactions 851 * @{ 852 */ 853 854 /** The type of a Subversion transaction object. */ 855 typedef struct svn_fs_txn_t svn_fs_txn_t; 856 857 858 /** @defgroup svn_fs_begin_txn2_flags Bitmask flags for svn_fs_begin_txn2() 859 * @since New in 1.2. 860 * @{ */ 861 862 /** Do on-the-fly out-of-dateness checks. That is, an fs routine may 863 * throw error if a caller tries to edit an out-of-date item in the 864 * transaction. 865 * 866 * @warning ### Not yet implemented. 867 */ 868 #define SVN_FS_TXN_CHECK_OOD 0x00001 869 870 /** Do on-the-fly lock checks. That is, an fs routine may throw error 871 * if a caller tries to edit a locked item without having rights to the lock. 872 */ 873 #define SVN_FS_TXN_CHECK_LOCKS 0x00002 874 875 /** @} */ 876 877 /** 878 * Begin a new transaction on the filesystem @a fs, based on existing 879 * revision @a rev. Set @a *txn_p to a pointer to the new transaction. 880 * When committed, this transaction will create a new revision. 881 * 882 * Allocate the new transaction in @a pool; when @a pool is freed, the new 883 * transaction will be closed (neither committed nor aborted). 884 * 885 * @a flags determines transaction enforcement behaviors, and is composed 886 * from the constants SVN_FS_TXN_* (#SVN_FS_TXN_CHECK_OOD etc.). 887 * 888 * @note If you're building a txn for committing, you probably 889 * don't want to call this directly. Instead, call 890 * svn_repos_fs_begin_txn_for_commit(), which honors the 891 * repository's hook configurations. 892 * 893 * @since New in 1.2. 894 */ 895 svn_error_t * 896 svn_fs_begin_txn2(svn_fs_txn_t **txn_p, 897 svn_fs_t *fs, 898 svn_revnum_t rev, 899 apr_uint32_t flags, 900 apr_pool_t *pool); 901 902 903 /** 904 * Same as svn_fs_begin_txn2(), but with @a flags set to 0. 905 * 906 * @deprecated Provided for backward compatibility with the 1.1 API. 907 */ 908 SVN_DEPRECATED 909 svn_error_t * 910 svn_fs_begin_txn(svn_fs_txn_t **txn_p, 911 svn_fs_t *fs, 912 svn_revnum_t rev, 913 apr_pool_t *pool); 914 915 916 917 /** Commit @a txn. 918 * 919 * @note You usually don't want to call this directly. 920 * Instead, call svn_repos_fs_commit_txn(), which honors the 921 * repository's hook configurations. 922 * 923 * If the transaction conflicts with other changes committed to the 924 * repository, return an #SVN_ERR_FS_CONFLICT error. Otherwise, create 925 * a new filesystem revision containing the changes made in @a txn, 926 * storing that new revision number in @a *new_rev, and return zero. 927 * 928 * If @a conflict_p is non-zero, use it to provide details on any 929 * conflicts encountered merging @a txn with the most recent committed 930 * revisions. If a conflict occurs, set @a *conflict_p to the path of 931 * the conflict in @a txn, allocated within @a pool; 932 * otherwise, set @a *conflict_p to NULL. 933 * 934 * If the commit succeeds, @a txn is invalid. 935 * 936 * If the commit fails for any reason, @a *new_rev is an invalid 937 * revision number, an error other than #SVN_NO_ERROR is returned and 938 * @a txn is still valid; you can make more operations to resolve the 939 * conflict, or call svn_fs_abort_txn() to abort the transaction. 940 * 941 * @note Success or failure of the commit of @a txn is determined by 942 * examining the value of @a *new_rev upon this function's return. If 943 * the value is a valid revision number, the commit was successful, 944 * even though a non-@c NULL function return value may indicate that 945 * something else went wrong in post commit FS processing. 946 * 947 * @note See api-errata/1.8/fs001.txt for information on how this 948 * function was documented in versions prior to 1.8. 949 * 950 * ### need to document this better. there are four combinations of 951 * ### return values: 952 * ### 1) err=NULL. conflict=NULL. new_rev is valid 953 * ### 2) err=SVN_ERR_FS_CONFLICT. conflict is set. new_rev=SVN_INVALID_REVNUM 954 * ### 3) err=!NULL. conflict=NULL. new_rev is valid 955 * ### 4) err=!NULL. conflict=NULL. new_rev=SVN_INVALID_REVNUM 956 * ### 957 * ### some invariants: 958 * ### *conflict_p will be non-NULL IFF SVN_ERR_FS_CONFLICT 959 * ### if *conflict_p is set (and SVN_ERR_FS_CONFLICT), then new_rev 960 * ### will always be SVN_INVALID_REVNUM 961 * ### *conflict_p will always be initialized to NULL, or to a valid 962 * ### conflict string 963 * ### *new_rev will always be initialized to SVN_INVALID_REVNUM, or 964 * ### to a valid, committed revision number 965 */ 966 svn_error_t * 967 svn_fs_commit_txn(const char **conflict_p, 968 svn_revnum_t *new_rev, 969 svn_fs_txn_t *txn, 970 apr_pool_t *pool); 971 972 973 /** Abort the transaction @a txn. Any changes made in @a txn are 974 * discarded, and the filesystem is left unchanged. Use @a pool for 975 * any necessary allocations. 976 * 977 * @note This function first sets the state of @a txn to "dead", and 978 * then attempts to purge it and any related data from the filesystem. 979 * If some part of the cleanup process fails, @a txn and some portion 980 * of its data may remain in the database after this function returns. 981 * Use svn_fs_purge_txn() to retry the transaction cleanup. 982 */ 983 svn_error_t * 984 svn_fs_abort_txn(svn_fs_txn_t *txn, 985 apr_pool_t *pool); 986 987 988 /** Cleanup the dead transaction in @a fs whose ID is @a txn_id. Use 989 * @a pool for all allocations. If the transaction is not yet dead, 990 * the error #SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned. (The 991 * caller probably forgot to abort the transaction, or the cleanup 992 * step of that abort failed for some reason.) 993 */ 994 svn_error_t * 995 svn_fs_purge_txn(svn_fs_t *fs, 996 const char *txn_id, 997 apr_pool_t *pool); 998 999 1000 /** Set @a *name_p to the name of the transaction @a txn, as a 1001 * NULL-terminated string. Allocate the name in @a pool. 1002 */ 1003 svn_error_t * 1004 svn_fs_txn_name(const char **name_p, 1005 svn_fs_txn_t *txn, 1006 apr_pool_t *pool); 1007 1008 /** Return @a txn's base revision. */ 1009 svn_revnum_t 1010 svn_fs_txn_base_revision(svn_fs_txn_t *txn); 1011 1012 1013 1014 /** Open the transaction named @a name in the filesystem @a fs. Set @a *txn 1015 * to the transaction. 1016 * 1017 * If there is no such transaction, #SVN_ERR_FS_NO_SUCH_TRANSACTION is 1018 * the error returned. 1019 * 1020 * Allocate the new transaction in @a pool; when @a pool is freed, the new 1021 * transaction will be closed (neither committed nor aborted). 1022 */ 1023 svn_error_t * 1024 svn_fs_open_txn(svn_fs_txn_t **txn, 1025 svn_fs_t *fs, 1026 const char *name, 1027 apr_pool_t *pool); 1028 1029 1030 /** Set @a *names_p to an array of <tt>const char *</tt> ids which are the 1031 * names of all the currently active transactions in the filesystem @a fs. 1032 * Allocate the array in @a pool. 1033 */ 1034 svn_error_t * 1035 svn_fs_list_transactions(apr_array_header_t **names_p, 1036 svn_fs_t *fs, 1037 apr_pool_t *pool); 1038 1039 /* Transaction properties */ 1040 1041 /** Set @a *value_p to the value of the property named @a propname on 1042 * transaction @a txn. If @a txn has no property by that name, set 1043 * @a *value_p to zero. Allocate the result in @a pool. 1044 */ 1045 svn_error_t * 1046 svn_fs_txn_prop(svn_string_t **value_p, 1047 svn_fs_txn_t *txn, 1048 const char *propname, 1049 apr_pool_t *pool); 1050 1051 1052 /** Set @a *table_p to the entire property list of transaction @a txn, as 1053 * an APR hash table allocated in @a pool. The resulting table maps property 1054 * names to pointers to #svn_string_t objects containing the property value. 1055 */ 1056 svn_error_t * 1057 svn_fs_txn_proplist(apr_hash_t **table_p, 1058 svn_fs_txn_t *txn, 1059 apr_pool_t *pool); 1060 1061 1062 /** Change a transactions @a txn's property's value, or add/delete a 1063 * property. @a name is the name of the property to change, and @a value 1064 * is the new value of the property, or zero if the property should be 1065 * removed altogether. Do any necessary temporary allocation in @a pool. 1066 */ 1067 svn_error_t * 1068 svn_fs_change_txn_prop(svn_fs_txn_t *txn, 1069 const char *name, 1070 const svn_string_t *value, 1071 apr_pool_t *pool); 1072 1073 1074 /** Change, add, and/or delete transaction property values in 1075 * transaction @a txn. @a props is an array of <tt>svn_prop_t</tt> 1076 * elements. This is equivalent to calling svn_fs_change_txn_prop() 1077 * multiple times with the @c name and @c value fields of each 1078 * successive <tt>svn_prop_t</tt>, but may be more efficient. 1079 * (Properties not mentioned are left alone.) Do any necessary 1080 * temporary allocation in @a pool. 1081 * 1082 * @since New in 1.5. 1083 */ 1084 svn_error_t * 1085 svn_fs_change_txn_props(svn_fs_txn_t *txn, 1086 const apr_array_header_t *props, 1087 apr_pool_t *pool); 1088 1089 /** @} */ 1090 1091 1092 /** Roots. 1093 * 1094 * An #svn_fs_root_t object represents the root directory of some 1095 * revision or transaction in a filesystem. To refer to particular 1096 * node or node revision, you provide a root, and a directory path 1097 * relative to that root. 1098 * 1099 * @defgroup svn_fs_roots Filesystem roots 1100 * @{ 1101 */ 1102 1103 /** The Filesystem Root object. */ 1104 typedef struct svn_fs_root_t svn_fs_root_t; 1105 1106 1107 /** Set @a *root_p to the root directory of revision @a rev in filesystem @a fs. 1108 * Allocate @a *root_p in a private subpool of @a pool; the root can be 1109 * destroyed earlier than @a pool by calling #svn_fs_close_root. 1110 */ 1111 svn_error_t * 1112 svn_fs_revision_root(svn_fs_root_t **root_p, 1113 svn_fs_t *fs, 1114 svn_revnum_t rev, 1115 apr_pool_t *pool); 1116 1117 1118 /** Set @a *root_p to the root directory of @a txn. Allocate @a *root_p in a 1119 * private subpool of @a pool; the root can be destroyed earlier than @a pool by 1120 * calling #svn_fs_close_root. 1121 */ 1122 svn_error_t * 1123 svn_fs_txn_root(svn_fs_root_t **root_p, 1124 svn_fs_txn_t *txn, 1125 apr_pool_t *pool); 1126 1127 1128 /** Free the root directory @a root; this only needs to be used if you want to 1129 * free the memory associated with @a root earlier than the time you destroy 1130 * the pool passed to the function that created it (svn_fs_revision_root() or 1131 * svn_fs_txn_root()). 1132 */ 1133 void 1134 svn_fs_close_root(svn_fs_root_t *root); 1135 1136 1137 /** Return the filesystem to which @a root belongs. */ 1138 svn_fs_t * 1139 svn_fs_root_fs(svn_fs_root_t *root); 1140 1141 1142 /** Return @c TRUE iff @a root is a transaction root. */ 1143 svn_boolean_t 1144 svn_fs_is_txn_root(svn_fs_root_t *root); 1145 1146 /** Return @c TRUE iff @a root is a revision root. */ 1147 svn_boolean_t 1148 svn_fs_is_revision_root(svn_fs_root_t *root); 1149 1150 1151 /** If @a root is the root of a transaction, return the name of the 1152 * transaction, allocated in @a pool; otherwise, return NULL. 1153 */ 1154 const char * 1155 svn_fs_txn_root_name(svn_fs_root_t *root, 1156 apr_pool_t *pool); 1157 1158 /** If @a root is the root of a transaction, return the number of the 1159 * revision on which is was based when created. Otherwise, return 1160 * #SVN_INVALID_REVNUM. 1161 * 1162 * @since New in 1.5. 1163 */ 1164 svn_revnum_t 1165 svn_fs_txn_root_base_revision(svn_fs_root_t *root); 1166 1167 /** If @a root is the root of a revision, return the revision number. 1168 * Otherwise, return #SVN_INVALID_REVNUM. 1169 */ 1170 svn_revnum_t 1171 svn_fs_revision_root_revision(svn_fs_root_t *root); 1172 1173 /** @} */ 1174 1175 1176 /** Directory entry names and directory paths. 1177 * 1178 * Here are the rules for directory entry names, and directory paths: 1179 * 1180 * A directory entry name is a Unicode string encoded in UTF-8, and 1181 * may not contain the NULL character (U+0000). The name should be in 1182 * Unicode canonical decomposition and ordering. No directory entry 1183 * may be named '.', '..', or the empty string. Given a directory 1184 * entry name which fails to meet these requirements, a filesystem 1185 * function returns an SVN_ERR_FS_PATH_SYNTAX error. 1186 * 1187 * A directory path is a sequence of zero or more directory entry 1188 * names, separated by slash characters (U+002f), and possibly ending 1189 * with slash characters. Sequences of two or more consecutive slash 1190 * characters are treated as if they were a single slash. If a path 1191 * ends with a slash, it refers to the same node it would without the 1192 * slash, but that node must be a directory, or else the function 1193 * returns an SVN_ERR_FS_NOT_DIRECTORY error. 1194 * 1195 * A path consisting of the empty string, or a string containing only 1196 * slashes, refers to the root directory. 1197 * 1198 * @defgroup svn_fs_directories Filesystem directories 1199 * @{ 1200 */ 1201 1202 1203 1204 /** The kind of change that occurred on the path. */ 1205 typedef enum svn_fs_path_change_kind_t 1206 { 1207 /** path modified in txn */ 1208 svn_fs_path_change_modify = 0, 1209 1210 /** path added in txn */ 1211 svn_fs_path_change_add, 1212 1213 /** path removed in txn */ 1214 svn_fs_path_change_delete, 1215 1216 /** path removed and re-added in txn */ 1217 svn_fs_path_change_replace, 1218 1219 /** ignore all previous change items for path (internal-use only) */ 1220 svn_fs_path_change_reset 1221 1222 } svn_fs_path_change_kind_t; 1223 1224 /** Change descriptor. 1225 * 1226 * @note Fields may be added to the end of this structure in future 1227 * versions. Therefore, to preserve binary compatibility, users 1228 * should not directly allocate structures of this type. 1229 * 1230 * @since New in 1.6. */ 1231 typedef struct svn_fs_path_change2_t 1232 { 1233 /** node revision id of changed path */ 1234 const svn_fs_id_t *node_rev_id; 1235 1236 /** kind of change */ 1237 svn_fs_path_change_kind_t change_kind; 1238 1239 /** were there text mods? */ 1240 svn_boolean_t text_mod; 1241 1242 /** were there property mods? */ 1243 svn_boolean_t prop_mod; 1244 1245 /** what node kind is the path? 1246 (Note: it is legal for this to be #svn_node_unknown.) */ 1247 svn_node_kind_t node_kind; 1248 1249 /** Copyfrom revision and path; this is only valid if copyfrom_known 1250 * is true. */ 1251 svn_boolean_t copyfrom_known; 1252 svn_revnum_t copyfrom_rev; 1253 const char *copyfrom_path; 1254 1255 /* NOTE! Please update svn_fs_path_change2_create() when adding new 1256 fields here. */ 1257 } svn_fs_path_change2_t; 1258 1259 1260 /** Similar to #svn_fs_path_change2_t, but without kind and copyfrom 1261 * information. 1262 * 1263 * @deprecated Provided for backwards compatibility with the 1.5 API. 1264 */ 1265 1266 typedef struct svn_fs_path_change_t 1267 { 1268 /** node revision id of changed path */ 1269 const svn_fs_id_t *node_rev_id; 1270 1271 /** kind of change */ 1272 svn_fs_path_change_kind_t change_kind; 1273 1274 /** were there text mods? */ 1275 svn_boolean_t text_mod; 1276 1277 /** were there property mods? */ 1278 svn_boolean_t prop_mod; 1279 1280 } svn_fs_path_change_t; 1281 1282 /** 1283 * Allocate an #svn_fs_path_change2_t structure in @a pool, initialize and 1284 * return it. 1285 * 1286 * Set the @c node_rev_id field of the created struct to @a node_rev_id, and 1287 * @c change_kind to @a change_kind. Set all other fields to their 1288 * @c _unknown, @c NULL or invalid value, respectively. 1289 * 1290 * @since New in 1.6. 1291 */ 1292 svn_fs_path_change2_t * 1293 svn_fs_path_change2_create(const svn_fs_id_t *node_rev_id, 1294 svn_fs_path_change_kind_t change_kind, 1295 apr_pool_t *pool); 1296 1297 /** Determine what has changed under a @a root. 1298 * 1299 * Allocate and return a hash @a *changed_paths2_p containing descriptions 1300 * of the paths changed under @a root. The hash is keyed with 1301 * <tt>const char *</tt> paths, and has #svn_fs_path_change2_t * values. 1302 * 1303 * Callers can assume that this function takes time proportional to 1304 * the amount of data output, and does not need to do tree crawls; 1305 * however, it is possible that some of the @c node_kind fields in the 1306 * #svn_fs_path_change2_t * values will be #svn_node_unknown or 1307 * that and some of the @c copyfrom_known fields will be FALSE. 1308 * 1309 * Use @a pool for all allocations, including the hash and its values. 1310 * 1311 * @since New in 1.6. 1312 */ 1313 svn_error_t * 1314 svn_fs_paths_changed2(apr_hash_t **changed_paths2_p, 1315 svn_fs_root_t *root, 1316 apr_pool_t *pool); 1317 1318 1319 /** Same as svn_fs_paths_changed2(), only with #svn_fs_path_change_t * values 1320 * in the hash (and thus no kind or copyfrom data). 1321 * 1322 * @deprecated Provided for backward compatibility with the 1.5 API. 1323 */ 1324 SVN_DEPRECATED 1325 svn_error_t * 1326 svn_fs_paths_changed(apr_hash_t **changed_paths_p, 1327 svn_fs_root_t *root, 1328 apr_pool_t *pool); 1329 1330 /** @} */ 1331 1332 1333 /* Operations appropriate to all kinds of nodes. */ 1334 1335 /** Set @a *kind_p to the type of node present at @a path under @a 1336 * root. If @a path does not exist under @a root, set @a *kind_p to 1337 * #svn_node_none. Use @a pool for temporary allocation. 1338 */ 1339 svn_error_t * 1340 svn_fs_check_path(svn_node_kind_t *kind_p, 1341 svn_fs_root_t *root, 1342 const char *path, 1343 apr_pool_t *pool); 1344 1345 1346 /** An opaque node history object. */ 1347 typedef struct svn_fs_history_t svn_fs_history_t; 1348 1349 1350 /** Set @a *history_p to an opaque node history object which 1351 * represents @a path under @a root. @a root must be a revision root. 1352 * Use @a pool for all allocations. 1353 */ 1354 svn_error_t * 1355 svn_fs_node_history(svn_fs_history_t **history_p, 1356 svn_fs_root_t *root, 1357 const char *path, 1358 apr_pool_t *pool); 1359 1360 1361 /** Set @a *prev_history_p to an opaque node history object which 1362 * represents the previous (or "next oldest") interesting history 1363 * location for the filesystem node represented by @a history, or @c 1364 * NULL if no such previous history exists. If @a cross_copies is @c 1365 * FALSE, also return @c NULL if stepping backwards in history to @a 1366 * *prev_history_p would cross a filesystem copy operation. 1367 * 1368 * @note If this is the first call to svn_fs_history_prev() for the @a 1369 * history object, it could return a history object whose location is 1370 * the same as the original. This will happen if the original 1371 * location was an interesting one (where the node was modified, or 1372 * took place in a copy event). This behavior allows looping callers 1373 * to avoid the calling svn_fs_history_location() on the object 1374 * returned by svn_fs_node_history(), and instead go ahead and begin 1375 * calling svn_fs_history_prev(). 1376 * 1377 * @note This function uses node-id ancestry alone to determine 1378 * modifiedness, and therefore does NOT claim that in any of the 1379 * returned revisions file contents changed, properties changed, 1380 * directory entries lists changed, etc. 1381 * 1382 * @note The revisions returned for @a path will be older than or 1383 * the same age as the revision of that path in @a root. That is, if 1384 * @a root is a revision root based on revision X, and @a path was 1385 * modified in some revision(s) younger than X, those revisions 1386 * younger than X will not be included for @a path. */ 1387 svn_error_t * 1388 svn_fs_history_prev(svn_fs_history_t **prev_history_p, 1389 svn_fs_history_t *history, 1390 svn_boolean_t cross_copies, 1391 apr_pool_t *pool); 1392 1393 1394 /** Set @a *path and @a *revision to the path and revision, 1395 * respectively, of the @a history object. Use @a pool for all 1396 * allocations. 1397 */ 1398 svn_error_t * 1399 svn_fs_history_location(const char **path, 1400 svn_revnum_t *revision, 1401 svn_fs_history_t *history, 1402 apr_pool_t *pool); 1403 1404 1405 /** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory. 1406 * Do any necessary temporary allocation in @a pool. 1407 */ 1408 svn_error_t * 1409 svn_fs_is_dir(svn_boolean_t *is_dir, 1410 svn_fs_root_t *root, 1411 const char *path, 1412 apr_pool_t *pool); 1413 1414 1415 /** Set @a *is_file to @c TRUE iff @a path in @a root is a file. 1416 * Do any necessary temporary allocation in @a pool. 1417 */ 1418 svn_error_t * 1419 svn_fs_is_file(svn_boolean_t *is_file, 1420 svn_fs_root_t *root, 1421 const char *path, 1422 apr_pool_t *pool); 1423 1424 1425 /** Get the id of a node. 1426 * 1427 * Set @a *id_p to the node revision ID of @a path in @a root, allocated in 1428 * @a pool. 1429 * 1430 * If @a root is the root of a transaction, keep in mind that other 1431 * changes to the transaction can change which node @a path refers to, 1432 * and even whether the path exists at all. 1433 */ 1434 svn_error_t * 1435 svn_fs_node_id(const svn_fs_id_t **id_p, 1436 svn_fs_root_t *root, 1437 const char *path, 1438 apr_pool_t *pool); 1439 1440 /** Set @a *revision to the revision in which @a path under @a root was 1441 * created. Use @a pool for any temporary allocations. @a *revision will 1442 * be set to #SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes 1443 * under a transaction root). Note that the root of an unmodified transaction 1444 * is not itself considered to be modified; in that case, return the revision 1445 * upon which the transaction was based. 1446 */ 1447 svn_error_t * 1448 svn_fs_node_created_rev(svn_revnum_t *revision, 1449 svn_fs_root_t *root, 1450 const char *path, 1451 apr_pool_t *pool); 1452 1453 /** Set @a *revision to the revision in which the line of history 1454 * represented by @a path under @a root originated. Use @a pool for 1455 * any temporary allocations. If @a root is a transaction root, @a 1456 * *revision will be set to #SVN_INVALID_REVNUM for any nodes newly 1457 * added in that transaction (brand new files or directories created 1458 * using #svn_fs_make_dir or #svn_fs_make_file). 1459 * 1460 * @since New in 1.5. 1461 */ 1462 svn_error_t * 1463 svn_fs_node_origin_rev(svn_revnum_t *revision, 1464 svn_fs_root_t *root, 1465 const char *path, 1466 apr_pool_t *pool); 1467 1468 /** Set @a *created_path to the path at which @a path under @a root was 1469 * created. Use @a pool for all allocations. Callers may use this 1470 * function in conjunction with svn_fs_node_created_rev() to perform a 1471 * reverse lookup of the mapping of (path, revision) -> node-id that 1472 * svn_fs_node_id() performs. 1473 */ 1474 svn_error_t * 1475 svn_fs_node_created_path(const char **created_path, 1476 svn_fs_root_t *root, 1477 const char *path, 1478 apr_pool_t *pool); 1479 1480 1481 /** Set @a *value_p to the value of the property named @a propname of 1482 * @a path in @a root. If the node has no property by that name, set 1483 * @a *value_p to zero. Allocate the result in @a pool. 1484 */ 1485 svn_error_t * 1486 svn_fs_node_prop(svn_string_t **value_p, 1487 svn_fs_root_t *root, 1488 const char *path, 1489 const char *propname, 1490 apr_pool_t *pool); 1491 1492 1493 /** Set @a *table_p to the entire property list of @a path in @a root, 1494 * as an APR hash table allocated in @a pool. The resulting table maps 1495 * property names to pointers to #svn_string_t objects containing the 1496 * property value. 1497 */ 1498 svn_error_t * 1499 svn_fs_node_proplist(apr_hash_t **table_p, 1500 svn_fs_root_t *root, 1501 const char *path, 1502 apr_pool_t *pool); 1503 1504 1505 /** Change a node's property's value, or add/delete a property. 1506 * 1507 * - @a root and @a path indicate the node whose property should change. 1508 * @a root must be the root of a transaction, not the root of a revision. 1509 * - @a name is the name of the property to change. 1510 * - @a value is the new value of the property, or zero if the property should 1511 * be removed altogether. 1512 * Do any necessary temporary allocation in @a pool. 1513 */ 1514 svn_error_t * 1515 svn_fs_change_node_prop(svn_fs_root_t *root, 1516 const char *path, 1517 const char *name, 1518 const svn_string_t *value, 1519 apr_pool_t *pool); 1520 1521 1522 /** Determine if the properties of two path/root combinations are different. 1523 * 1524 * Set @a *changed_p to 1 if the properties at @a path1 under @a root1 differ 1525 * from those at @a path2 under @a root2, or set it to 0 if they are the 1526 * same. Both paths must exist under their respective roots, and both 1527 * roots must be in the same filesystem. 1528 */ 1529 svn_error_t * 1530 svn_fs_props_changed(svn_boolean_t *changed_p, 1531 svn_fs_root_t *root1, 1532 const char *path1, 1533 svn_fs_root_t *root2, 1534 const char *path2, 1535 apr_pool_t *pool); 1536 1537 1538 /** Discover a node's copy ancestry, if any. 1539 * 1540 * If the node at @a path in @a root was copied from some other node, set 1541 * @a *rev_p and @a *path_p to the revision and path (expressed as an 1542 * absolute filesystem path) of the other node, allocating @a *path_p 1543 * in @a pool. 1544 * 1545 * Else if there is no copy ancestry for the node, set @a *rev_p to 1546 * #SVN_INVALID_REVNUM and @a *path_p to NULL. 1547 * 1548 * If an error is returned, the values of @a *rev_p and @a *path_p are 1549 * undefined, but otherwise, if one of them is set as described above, 1550 * you may assume the other is set correspondingly. 1551 * 1552 * @a root may be a revision root or a transaction root. 1553 * 1554 * Notes: 1555 * - Copy ancestry does not descend. After copying directory D to 1556 * E, E will have copy ancestry referring to D, but E's children 1557 * may not. See also svn_fs_copy(). 1558 * 1559 * - Copy ancestry *under* a copy is preserved. That is, if you 1560 * copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then 1561 * /G/pi2 will still have copy ancestry pointing to /A/D/G/pi. 1562 * We don't know if this is a feature or a bug yet; if it turns 1563 * out to be a bug, then the fix is to make svn_fs_copied_from() 1564 * observe the following logic, which currently callers may 1565 * choose to follow themselves: if node X has copy history, but 1566 * its ancestor A also has copy history, then you may ignore X's 1567 * history if X's revision-of-origin is earlier than A's -- 1568 * because that would mean that X's copy history was preserved in 1569 * a copy-under-a-copy scenario. If X's revision-of-origin is 1570 * the same as A's, then it was copied under A during the same 1571 * transaction that created A. (X's revision-of-origin cannot be 1572 * greater than A's, if X has copy history.) @todo See how 1573 * people like this, it can always be hidden behind the curtain 1574 * if necessary. 1575 * 1576 * - Copy ancestry is not stored as a regular subversion property 1577 * because it is not inherited. Copying foo to bar results in a 1578 * revision of bar with copy ancestry; but committing a text 1579 * change to bar right after that results in a new revision of 1580 * bar without copy ancestry. 1581 */ 1582 svn_error_t * 1583 svn_fs_copied_from(svn_revnum_t *rev_p, 1584 const char **path_p, 1585 svn_fs_root_t *root, 1586 const char *path, 1587 apr_pool_t *pool); 1588 1589 1590 /** Set @a *root_p and @a *path_p to the revision root and path of the 1591 * destination of the most recent copy event that caused @a path to 1592 * exist where it does in @a root, or to NULL if no such copy exists. 1593 * 1594 * @a *path_p might be a parent of @a path, rather than @a path 1595 * itself. However, it will always be the deepest relevant path. 1596 * That is, if a copy occurs underneath another copy in the same txn, 1597 * this function makes sure to set @a *path_p to the longest copy 1598 * destination path that is still a parent of or equal to @a path. 1599 * 1600 * Values returned in @a *root_p and @a *path_p will be allocated 1601 * from @a pool. 1602 * 1603 * @since New in 1.3. 1604 */ 1605 svn_error_t * 1606 svn_fs_closest_copy(svn_fs_root_t **root_p, 1607 const char **path_p, 1608 svn_fs_root_t *root, 1609 const char *path, 1610 apr_pool_t *pool); 1611 1612 1613 /** Retrieve mergeinfo for multiple nodes. 1614 * 1615 * @a *catalog is a catalog for @a paths. It will never be @c NULL, 1616 * but may be empty. 1617 * 1618 * @a root is revision root to use when looking up paths. 1619 * 1620 * @a paths are the paths you are requesting information for. 1621 * 1622 * @a inherit indicates whether to retrieve explicit, 1623 * explicit-or-inherited, or only inherited mergeinfo. 1624 * 1625 * If @a adjust_inherited_mergeinfo is @c TRUE, then any inherited 1626 * mergeinfo returned in @a *catalog is normalized to represent the 1627 * inherited mergeinfo on the path which inherits it. If 1628 * @a adjust_inherited_mergeinfo is @c FALSE, then any inherited 1629 * mergeinfo is the raw explicit mergeinfo from the nearest parent 1630 * of the path with explicit mergeinfo, unadjusted for the path-wise 1631 * difference between the path and its parent. This may include 1632 * non-inheritable mergeinfo. 1633 * 1634 * If @a include_descendants is TRUE, then additionally return the 1635 * mergeinfo for any descendant of any element of @a paths which has 1636 * the #SVN_PROP_MERGEINFO property explicitly set on it. (Note 1637 * that inheritance is only taken into account for the elements in @a 1638 * paths; descendants of the elements in @a paths which get their 1639 * mergeinfo via inheritance are not included in @a *catalog.) 1640 * 1641 * Allocate @a *catalog in result_pool. Do any necessary temporary 1642 * allocations in @a scratch_pool. 1643 * 1644 * @since New in 1.8. 1645 */ 1646 svn_error_t * 1647 svn_fs_get_mergeinfo2(svn_mergeinfo_catalog_t *catalog, 1648 svn_fs_root_t *root, 1649 const apr_array_header_t *paths, 1650 svn_mergeinfo_inheritance_t inherit, 1651 svn_boolean_t include_descendants, 1652 svn_boolean_t adjust_inherited_mergeinfo, 1653 apr_pool_t *result_pool, 1654 apr_pool_t *scratch_pool); 1655 1656 /** 1657 * Same as svn_fs_get_mergeinfo2(), but with @a adjust_inherited_mergeinfo 1658 * set always set to @c TRUE and with only one pool. 1659 * 1660 * @deprecated Provided for backward compatibility with the 1.5 API. 1661 */ 1662 SVN_DEPRECATED 1663 svn_error_t * 1664 svn_fs_get_mergeinfo(svn_mergeinfo_catalog_t *catalog, 1665 svn_fs_root_t *root, 1666 const apr_array_header_t *paths, 1667 svn_mergeinfo_inheritance_t inherit, 1668 svn_boolean_t include_descendants, 1669 apr_pool_t *pool); 1670 1671 /** Merge changes between two nodes into a third node. 1672 * 1673 * Given nodes @a source and @a target, and a common ancestor @a ancestor, 1674 * modify @a target to contain all the changes made between @a ancestor and 1675 * @a source, as well as the changes made between @a ancestor and @a target. 1676 * @a target_root must be the root of a transaction, not a revision. 1677 * 1678 * @a source, @a target, and @a ancestor are generally directories; this 1679 * function recursively merges the directories' contents. If they are 1680 * files, this function simply returns an error whenever @a source, 1681 * @a target, and @a ancestor are all distinct node revisions. 1682 * 1683 * If there are differences between @a ancestor and @a source that conflict 1684 * with changes between @a ancestor and @a target, this function returns an 1685 * #SVN_ERR_FS_CONFLICT error. 1686 * 1687 * If the merge is successful, @a target is left in the merged state, and 1688 * the base root of @a target's txn is set to the root node of @a source. 1689 * If an error is returned (whether for conflict or otherwise), @a target 1690 * is left unaffected. 1691 * 1692 * If @a conflict_p is non-NULL, then: a conflict error sets @a *conflict_p 1693 * to the name of the node in @a target which couldn't be merged, 1694 * otherwise, success sets @a *conflict_p to NULL. 1695 * 1696 * Do any necessary temporary allocation in @a pool. 1697 */ 1698 svn_error_t * 1699 svn_fs_merge(const char **conflict_p, 1700 svn_fs_root_t *source_root, 1701 const char *source_path, 1702 svn_fs_root_t *target_root, 1703 const char *target_path, 1704 svn_fs_root_t *ancestor_root, 1705 const char *ancestor_path, 1706 apr_pool_t *pool); 1707 1708 1709 1710 /* Directories. */ 1711 1712 1713 /** The type of a Subversion directory entry. */ 1714 typedef struct svn_fs_dirent_t 1715 { 1716 1717 /** The name of this directory entry. */ 1718 const char *name; 1719 1720 /** The node revision ID it names. */ 1721 const svn_fs_id_t *id; 1722 1723 /** The node kind. */ 1724 svn_node_kind_t kind; 1725 1726 } svn_fs_dirent_t; 1727 1728 1729 /** Set @a *entries_p to a newly allocated APR hash table containing the 1730 * entries of the directory at @a path in @a root. The keys of the table 1731 * are entry names, as byte strings, excluding the final NULL 1732 * character; the table's values are pointers to #svn_fs_dirent_t 1733 * structures. Allocate the table and its contents in @a pool. 1734 */ 1735 svn_error_t * 1736 svn_fs_dir_entries(apr_hash_t **entries_p, 1737 svn_fs_root_t *root, 1738 const char *path, 1739 apr_pool_t *pool); 1740 1741 1742 /** Create a new directory named @a path in @a root. The new directory has 1743 * no entries, and no properties. @a root must be the root of a transaction, 1744 * not a revision. 1745 * 1746 * Do any necessary temporary allocation in @a pool. 1747 */ 1748 svn_error_t * 1749 svn_fs_make_dir(svn_fs_root_t *root, 1750 const char *path, 1751 apr_pool_t *pool); 1752 1753 1754 /** Delete the node named @a path in @a root. If the node being deleted is 1755 * a directory, its contents will be deleted recursively. @a root must be 1756 * the root of a transaction, not of a revision. Use @a pool for 1757 * temporary allocation. 1758 * 1759 * If return #SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is 1760 * missing from its parent, that is, the final target of the deletion 1761 * is missing. 1762 * 1763 * Attempting to remove the root dir also results in an error, 1764 * #SVN_ERR_FS_ROOT_DIR, even if the dir is empty. 1765 */ 1766 svn_error_t * 1767 svn_fs_delete(svn_fs_root_t *root, 1768 const char *path, 1769 apr_pool_t *pool); 1770 1771 1772 /** Create a copy of @a from_path in @a from_root named @a to_path in 1773 * @a to_root. If @a from_path in @a from_root is a directory, copy the 1774 * tree it refers to recursively. 1775 * 1776 * The copy will remember its source; use svn_fs_copied_from() to 1777 * access this information. 1778 * 1779 * @a to_root must be the root of a transaction; @a from_root must be the 1780 * root of a revision. (Requiring @a from_root to be the root of a 1781 * revision makes the implementation trivial: there is no detectable 1782 * difference (modulo node revision ID's) between copying @a from and 1783 * simply adding a reference to it. So the operation takes place in 1784 * constant time. However, there's no reason not to extend this to 1785 * mutable nodes --- it's just more code.) Further, @a to_root and @a 1786 * from_root must represent the same filesystem. 1787 * 1788 * @note To do a copy without preserving copy history, use 1789 * svn_fs_revision_link(). 1790 * 1791 * Do any necessary temporary allocation in @a pool. 1792 */ 1793 svn_error_t * 1794 svn_fs_copy(svn_fs_root_t *from_root, 1795 const char *from_path, 1796 svn_fs_root_t *to_root, 1797 const char *to_path, 1798 apr_pool_t *pool); 1799 1800 1801 /** Like svn_fs_copy(), but doesn't record copy history, and preserves 1802 * the PATH. You cannot use svn_fs_copied_from() later to find out 1803 * where this copy came from. 1804 * 1805 * Use svn_fs_revision_link() in situations where you don't care 1806 * about the copy history, and where @a to_path and @a from_path are 1807 * the same, because it is cheaper than svn_fs_copy(). 1808 */ 1809 svn_error_t * 1810 svn_fs_revision_link(svn_fs_root_t *from_root, 1811 svn_fs_root_t *to_root, 1812 const char *path, 1813 apr_pool_t *pool); 1814 1815 /* Files. */ 1816 1817 /** Set @a *length_p to the length of the file @a path in @a root, in bytes. 1818 * Do any necessary temporary allocation in @a pool. 1819 */ 1820 svn_error_t * 1821 svn_fs_file_length(svn_filesize_t *length_p, 1822 svn_fs_root_t *root, 1823 const char *path, 1824 apr_pool_t *pool); 1825 1826 1827 /** Set @a *checksum to the checksum of type @a kind for the file @a path. 1828 * @a *checksum will be allocated out of @a pool, which will also be used 1829 * for temporary allocations. 1830 * 1831 * If the filesystem does not have a prerecorded checksum of @a kind for 1832 * @a path, and @a force is not TRUE, do not calculate a checksum 1833 * dynamically, just put NULL into @a checksum. (By convention, the NULL 1834 * checksum is considered to match any checksum.) 1835 * 1836 * Notes: 1837 * 1838 * You might wonder, why do we only provide this interface for file 1839 * contents, and not for properties or directories? 1840 * 1841 * The answer is that property lists and directory entry lists are 1842 * essentially data structures, not text. We serialize them for 1843 * transmission, but there is no guarantee that the consumer will 1844 * parse them into the same form, or even the same order, as the 1845 * producer. It's difficult to find a checksumming method that 1846 * reaches the same result given such variation in input. (I suppose 1847 * we could calculate an independent MD5 sum for each propname and 1848 * value, and XOR them together; same with directory entry names. 1849 * Maybe that's the solution?) Anyway, for now we punt. The most 1850 * important data, and the only data that goes through svndiff 1851 * processing, is file contents, so that's what we provide 1852 * checksumming for. 1853 * 1854 * Internally, of course, the filesystem checksums everything, because 1855 * it has access to the lowest level storage forms: strings behind 1856 * representations. 1857 * 1858 * @since New in 1.6. 1859 */ 1860 svn_error_t * 1861 svn_fs_file_checksum(svn_checksum_t **checksum, 1862 svn_checksum_kind_t kind, 1863 svn_fs_root_t *root, 1864 const char *path, 1865 svn_boolean_t force, 1866 apr_pool_t *pool); 1867 1868 /** 1869 * Same as svn_fs_file_checksum(), only always put the MD5 checksum of file 1870 * @a path into @a digest, which should point to @c APR_MD5_DIGESTSIZE bytes 1871 * of storage. If the checksum doesn't exist, put all 0's into @a digest. 1872 * 1873 * @deprecated Provided for backward compatibility with the 1.5 API. 1874 */ 1875 SVN_DEPRECATED 1876 svn_error_t * 1877 svn_fs_file_md5_checksum(unsigned char digest[], 1878 svn_fs_root_t *root, 1879 const char *path, 1880 apr_pool_t *pool); 1881 1882 1883 /** Set @a *contents to a readable generic stream that will yield the 1884 * contents of the file @a path in @a root. Allocate the stream in 1885 * @a pool. You can only use @a *contents for as long as the underlying 1886 * filesystem is open. If @a path is not a file, return 1887 * #SVN_ERR_FS_NOT_FILE. 1888 * 1889 * If @a root is the root of a transaction, it is possible that the 1890 * contents of the file @a path will change between calls to 1891 * svn_fs_file_contents(). In that case, the result of reading from 1892 * @a *contents is undefined. 1893 * 1894 * ### @todo kff: I am worried about lifetime issues with this pool vs 1895 * the trail created farther down the call stack. Trace this function 1896 * to investigate... 1897 */ 1898 svn_error_t * 1899 svn_fs_file_contents(svn_stream_t **contents, 1900 svn_fs_root_t *root, 1901 const char *path, 1902 apr_pool_t *pool); 1903 1904 /** 1905 * Callback function type used with svn_fs_try_process_file_contents() 1906 * that delivers the immutable, non-NULL @a contents of @a len bytes. 1907 * @a baton is an implementation-specific closure. 1908 * 1909 * Use @a scratch_pool for allocations. 1910 * 1911 * @since New in 1.8. 1912 */ 1913 typedef svn_error_t * 1914 (*svn_fs_process_contents_func_t)(const unsigned char *contents, 1915 apr_size_t len, 1916 void *baton, 1917 apr_pool_t *scratch_pool); 1918 1919 /** Efficiently deliver the contents of the file @a path in @a root 1920 * via @a processor (with @a baton), setting @a *success to @c TRUE 1921 * upon doing so. Use @a pool for allocations. 1922 * 1923 * This function is intended to support zero copy data processing. It may 1924 * not be implemented for all data backends or not applicable for certain 1925 * content. In that case, @a *success will always be @c FALSE. Also, this 1926 * is a best-effort function which means that there is no guarantee that 1927 * @a processor gets called at all for some content. 1928 * 1929 * @note @a processor is expected to be relatively short function with 1930 * at most O(content size) runtime. 1931 * 1932 * @since New in 1.8. 1933 */ 1934 svn_error_t * 1935 svn_fs_try_process_file_contents(svn_boolean_t *success, 1936 svn_fs_root_t *root, 1937 const char *path, 1938 svn_fs_process_contents_func_t processor, 1939 void* baton, 1940 apr_pool_t *pool); 1941 1942 /** Create a new file named @a path in @a root. The file's initial contents 1943 * are the empty string, and it has no properties. @a root must be the 1944 * root of a transaction, not a revision. 1945 * 1946 * Do any necessary temporary allocation in @a pool. 1947 */ 1948 svn_error_t * 1949 svn_fs_make_file(svn_fs_root_t *root, 1950 const char *path, 1951 apr_pool_t *pool); 1952 1953 1954 /** Apply a text delta to the file @a path in @a root. @a root must be the 1955 * root of a transaction, not a revision. 1956 * 1957 * Set @a *contents_p to a function ready to receive text delta windows 1958 * describing how to change the file's contents, relative to its 1959 * current contents. Set @a *contents_baton_p to a baton to pass to 1960 * @a *contents_p. 1961 * 1962 * If @a path does not exist in @a root, return an error. (You cannot use 1963 * this routine to create new files; use svn_fs_make_file() to create 1964 * an empty file first.) 1965 * 1966 * @a base_checksum is the hex MD5 digest for the base text against 1967 * which the delta is to be applied; it is ignored if NULL, and may be 1968 * ignored even if not NULL. If it is not ignored, it must match the 1969 * checksum of the base text against which svndiff data is being 1970 * applied; if not, svn_fs_apply_textdelta() or the @a *contents_p call 1971 * which detects the mismatch will return the error 1972 * #SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may 1973 * still be an error if @a base_checksum is neither NULL nor the 1974 * checksum of the empty string). 1975 * 1976 * @a result_checksum is the hex MD5 digest for the fulltext that 1977 * results from this delta application. It is ignored if NULL, but if 1978 * not NULL, it must match the checksum of the result; if it does not, 1979 * then the @a *contents_p call which detects the mismatch will return 1980 * the error #SVN_ERR_CHECKSUM_MISMATCH. 1981 * 1982 * The caller must send all delta windows including the terminating 1983 * NULL window to @a *contents_p before making further changes to the 1984 * transaction. 1985 * 1986 * Do temporary allocation in @a pool. 1987 */ 1988 svn_error_t * 1989 svn_fs_apply_textdelta(svn_txdelta_window_handler_t *contents_p, 1990 void **contents_baton_p, 1991 svn_fs_root_t *root, 1992 const char *path, 1993 const char *base_checksum, 1994 const char *result_checksum, 1995 apr_pool_t *pool); 1996 1997 1998 /** Write data directly to the file @a path in @a root. @a root must be the 1999 * root of a transaction, not a revision. 2000 * 2001 * Set @a *contents_p to a stream ready to receive full textual data. 2002 * When the caller closes this stream, the data replaces the previous 2003 * contents of the file. The caller must write all file data and close 2004 * the stream before making further changes to the transaction. 2005 * 2006 * If @a path does not exist in @a root, return an error. (You cannot use 2007 * this routine to create new files; use svn_fs_make_file() to create 2008 * an empty file first.) 2009 * 2010 * @a result_checksum is the hex MD5 digest for the final fulltext 2011 * written to the stream. It is ignored if NULL, but if not null, it 2012 * must match the checksum of the result; if it does not, then the @a 2013 * *contents_p call which detects the mismatch will return the error 2014 * #SVN_ERR_CHECKSUM_MISMATCH. 2015 * 2016 * Do any necessary temporary allocation in @a pool. 2017 * 2018 * ### This is like svn_fs_apply_textdelta(), but takes the text 2019 * straight. It is currently used only by the loader, see 2020 * libsvn_repos/load.c. It should accept a checksum, of course, which 2021 * would come from an (optional) header in the dump file. See 2022 * http://subversion.tigris.org/issues/show_bug.cgi?id=1102 for more. 2023 */ 2024 svn_error_t * 2025 svn_fs_apply_text(svn_stream_t **contents_p, 2026 svn_fs_root_t *root, 2027 const char *path, 2028 const char *result_checksum, 2029 apr_pool_t *pool); 2030 2031 2032 /** Check if the contents of two root/path combos have changed. 2033 * 2034 * Set @a *changed_p to 1 if the contents at @a path1 under @a root1 differ 2035 * from those at @a path2 under @a root2, or set it to 0 if they are the 2036 * same. Both paths must exist under their respective roots, and both 2037 * roots must be in the same filesystem. 2038 */ 2039 svn_error_t * 2040 svn_fs_contents_changed(svn_boolean_t *changed_p, 2041 svn_fs_root_t *root1, 2042 const char *path1, 2043 svn_fs_root_t *root2, 2044 const char *path2, 2045 apr_pool_t *pool); 2046 2047 2048 2049 /* Filesystem revisions. */ 2050 2051 2052 /** Set @a *youngest_p to the number of the youngest revision in filesystem 2053 * @a fs. Use @a pool for all temporary allocation. 2054 * 2055 * The oldest revision in any filesystem is numbered zero. 2056 */ 2057 svn_error_t * 2058 svn_fs_youngest_rev(svn_revnum_t *youngest_p, 2059 svn_fs_t *fs, 2060 apr_pool_t *pool); 2061 2062 2063 /** Provide filesystem @a fs the opportunity to compress storage relating to 2064 * associated with @a revision in filesystem @a fs. Use @a pool for all 2065 * allocations. 2066 * 2067 * @note This can be a time-consuming process, depending the breadth 2068 * of the changes made in @a revision, and the depth of the history of 2069 * those changed paths. This may also be a no op. 2070 */ 2071 svn_error_t * 2072 svn_fs_deltify_revision(svn_fs_t *fs, 2073 svn_revnum_t revision, 2074 apr_pool_t *pool); 2075 2076 2077 /** Set @a *value_p to the value of the property named @a propname on 2078 * revision @a rev in the filesystem @a fs. If @a rev has no property by 2079 * that name, set @a *value_p to zero. Allocate the result in @a pool. 2080 */ 2081 svn_error_t * 2082 svn_fs_revision_prop(svn_string_t **value_p, 2083 svn_fs_t *fs, 2084 svn_revnum_t rev, 2085 const char *propname, 2086 apr_pool_t *pool); 2087 2088 2089 /** Set @a *table_p to the entire property list of revision @a rev in 2090 * filesystem @a fs, as an APR hash table allocated in @a pool. The table 2091 * maps <tt>char *</tt> property names to #svn_string_t * values; the names 2092 * and values are allocated in @a pool. 2093 */ 2094 svn_error_t * 2095 svn_fs_revision_proplist(apr_hash_t **table_p, 2096 svn_fs_t *fs, 2097 svn_revnum_t rev, 2098 apr_pool_t *pool); 2099 2100 2101 /** Change a revision's property's value, or add/delete a property. 2102 * 2103 * - @a fs is a filesystem, and @a rev is the revision in that filesystem 2104 * whose property should change. 2105 * - @a name is the name of the property to change. 2106 * - if @a old_value_p is not @c NULL, then changing the property will fail with 2107 * error #SVN_ERR_FS_PROP_BASEVALUE_MISMATCH if the present value of the 2108 * property is not @a *old_value_p. (This is an atomic test-and-set). 2109 * @a *old_value_p may be @c NULL, representing that the property must be not 2110 * already set. 2111 * - @a value is the new value of the property, or zero if the property should 2112 * be removed altogether. 2113 * 2114 * Note that revision properties are non-historied --- you can change 2115 * them after the revision has been committed. They are not protected 2116 * via transactions. 2117 * 2118 * Do any necessary temporary allocation in @a pool. 2119 * 2120 * @since New in 1.7. 2121 */ 2122 svn_error_t * 2123 svn_fs_change_rev_prop2(svn_fs_t *fs, 2124 svn_revnum_t rev, 2125 const char *name, 2126 const svn_string_t *const *old_value_p, 2127 const svn_string_t *value, 2128 apr_pool_t *pool); 2129 2130 2131 /** 2132 * Similar to svn_fs_change_rev_prop2(), but with @a old_value_p passed as 2133 * @c NULL. 2134 * 2135 * @deprecated Provided for backward compatibility with the 1.6 API. 2136 */ 2137 SVN_DEPRECATED 2138 svn_error_t * 2139 svn_fs_change_rev_prop(svn_fs_t *fs, 2140 svn_revnum_t rev, 2141 const char *name, 2142 const svn_string_t *value, 2143 apr_pool_t *pool); 2144 2145 2146 2147 /* Computing deltas. */ 2148 2149 2150 /** Set @a *stream_p to a pointer to a delta stream that will turn the 2151 * contents of the file @a source into the contents of the file @a target. 2152 * If @a source_root is zero, use a file with zero length as the source. 2153 * 2154 * This function does not compare the two files' properties. 2155 * 2156 * Allocate @a *stream_p, and do any necessary temporary allocation, in 2157 * @a pool. 2158 */ 2159 svn_error_t * 2160 svn_fs_get_file_delta_stream(svn_txdelta_stream_t **stream_p, 2161 svn_fs_root_t *source_root, 2162 const char *source_path, 2163 svn_fs_root_t *target_root, 2164 const char *target_path, 2165 apr_pool_t *pool); 2166 2167 2168 2169 /* UUID manipulation. */ 2170 2171 /** Populate @a *uuid with the UUID associated with @a fs. Allocate 2172 @a *uuid in @a pool. */ 2173 svn_error_t * 2174 svn_fs_get_uuid(svn_fs_t *fs, 2175 const char **uuid, 2176 apr_pool_t *pool); 2177 2178 2179 /** If not @c NULL, associate @a *uuid with @a fs. Otherwise (if @a 2180 * uuid is @c NULL), generate a new UUID for @a fs. Use @a pool for 2181 * any scratch work. 2182 */ 2183 svn_error_t * 2184 svn_fs_set_uuid(svn_fs_t *fs, 2185 const char *uuid, 2186 apr_pool_t *pool); 2187 2188 2189 /* Non-historical properties. */ 2190 2191 /* [[Yes, do tell.]] */ 2192 2193 2194 2195 /** @defgroup svn_fs_locks Filesystem locks 2196 * @{ 2197 * @since New in 1.2. */ 2198 2199 /** A lock represents one user's exclusive right to modify a path in a 2200 * filesystem. In order to create or destroy a lock, a username must 2201 * be associated with the filesystem's access context (see 2202 * #svn_fs_access_t). 2203 * 2204 * When a lock is created, a 'lock-token' is returned. The lock-token 2205 * is a unique URI that represents the lock (treated as an opaque 2206 * string by the client), and is required to make further use of the 2207 * lock (including removal of the lock.) A lock-token can also be 2208 * queried to return a svn_lock_t structure that describes the details 2209 * of the lock. lock-tokens must not contain any newline character, 2210 * mainly due to the serialization for tokens for pre-commit hook. 2211 * 2212 * Locks are not secret; anyone can view existing locks in a 2213 * filesystem. Locks are not omnipotent: they can broken and stolen 2214 * by people who don't "own" the lock. (Though admins can tailor a 2215 * custom break/steal policy via libsvn_repos pre-lock hook script.) 2216 * 2217 * Locks can be created with an optional expiration date. If a lock 2218 * has an expiration date, then the act of fetching/reading it might 2219 * cause it to automatically expire, returning either nothing or an 2220 * expiration error (depending on the API). 2221 */ 2222 2223 2224 /** Lock @a path in @a fs, and set @a *lock to a lock 2225 * representing the new lock, allocated in @a pool. 2226 * 2227 * @warning You may prefer to use svn_repos_fs_lock() instead, 2228 * which see. 2229 * 2230 * @a fs must have a username associated with it (see 2231 * #svn_fs_access_t), else return #SVN_ERR_FS_NO_USER. Set the 2232 * 'owner' field in the new lock to the fs username. 2233 * 2234 * @a comment is optional: it's either an xml-escapable UTF8 string 2235 * which describes the lock, or it is @c NULL. 2236 * 2237 * @a is_dav_comment describes whether the comment was created by a 2238 * generic DAV client; only mod_dav_svn's autoversioning feature needs 2239 * to use it. If in doubt, pass 0. 2240 * 2241 * If path is already locked, then return #SVN_ERR_FS_PATH_ALREADY_LOCKED, 2242 * unless @a steal_lock is TRUE, in which case "steal" the existing 2243 * lock, even if the FS access-context's username does not match the 2244 * current lock's owner: delete the existing lock on @a path, and 2245 * create a new one. 2246 * 2247 * @a token is a lock token such as can be generated using 2248 * svn_fs_generate_lock_token() (indicating that the caller wants to 2249 * dictate the lock token used), or it is @c NULL (indicating that the 2250 * caller wishes to have a new token generated by this function). If 2251 * @a token is not @c NULL, and represents an existing lock, then @a 2252 * path must match the path associated with that existing lock. 2253 * 2254 * If @a expiration_date is zero, then create a non-expiring lock. 2255 * Else, the lock will expire at @a expiration_date. 2256 * 2257 * If @a current_rev is a valid revnum, then do an out-of-dateness 2258 * check. If the revnum is less than the last-changed-revision of @a 2259 * path (or if @a path doesn't exist in HEAD), return 2260 * #SVN_ERR_FS_OUT_OF_DATE. 2261 * 2262 * @note At this time, only files can be locked. 2263 */ 2264 svn_error_t * 2265 svn_fs_lock(svn_lock_t **lock, 2266 svn_fs_t *fs, 2267 const char *path, 2268 const char *token, 2269 const char *comment, 2270 svn_boolean_t is_dav_comment, 2271 apr_time_t expiration_date, 2272 svn_revnum_t current_rev, 2273 svn_boolean_t steal_lock, 2274 apr_pool_t *pool); 2275 2276 2277 /** Generate a unique lock-token using @a fs. Return in @a *token, 2278 * allocated in @a pool. 2279 * 2280 * This can be used in to populate lock->token before calling 2281 * svn_fs_attach_lock(). 2282 */ 2283 svn_error_t * 2284 svn_fs_generate_lock_token(const char **token, 2285 svn_fs_t *fs, 2286 apr_pool_t *pool); 2287 2288 2289 /** Remove the lock on @a path represented by @a token in @a fs. 2290 * 2291 * If @a token doesn't point to a lock, return #SVN_ERR_FS_BAD_LOCK_TOKEN. 2292 * If @a token points to an expired lock, return #SVN_ERR_FS_LOCK_EXPIRED. 2293 * If @a fs has no username associated with it, return #SVN_ERR_FS_NO_USER 2294 * unless @a break_lock is specified. 2295 * 2296 * If @a token points to a lock, but the username of @a fs's access 2297 * context doesn't match the lock's owner, return 2298 * #SVN_ERR_FS_LOCK_OWNER_MISMATCH. If @a break_lock is TRUE, however, don't 2299 * return error; allow the lock to be "broken" in any case. In the latter 2300 * case, @a token shall be @c NULL. 2301 * 2302 * Use @a pool for temporary allocations. 2303 */ 2304 svn_error_t * 2305 svn_fs_unlock(svn_fs_t *fs, 2306 const char *path, 2307 const char *token, 2308 svn_boolean_t break_lock, 2309 apr_pool_t *pool); 2310 2311 2312 /** If @a path is locked in @a fs, set @a *lock to an svn_lock_t which 2313 * represents the lock, allocated in @a pool. 2314 * 2315 * If @a path is not locked, set @a *lock to NULL. 2316 */ 2317 svn_error_t * 2318 svn_fs_get_lock(svn_lock_t **lock, 2319 svn_fs_t *fs, 2320 const char *path, 2321 apr_pool_t *pool); 2322 2323 2324 /** The type of a lock discovery callback function. @a baton is the 2325 * value specified in the call to svn_fs_get_locks(); the filesystem 2326 * passes it through to the callback. @a lock is a lock structure. 2327 * @a pool is a temporary subpool for use by the callback 2328 * implementation -- it is cleared after invocation of the callback. 2329 */ 2330 typedef svn_error_t *(*svn_fs_get_locks_callback_t)(void *baton, 2331 svn_lock_t *lock, 2332 apr_pool_t *pool); 2333 2334 2335 /** Report locks on or below @a path in @a fs using the @a 2336 * get_locks_func / @a get_locks_baton. Use @a pool for necessary 2337 * allocations. 2338 * 2339 * @a depth limits the reported locks to those associated with paths 2340 * within the specified depth of @a path, and must be one of the 2341 * following values: #svn_depth_empty, #svn_depth_files, 2342 * #svn_depth_immediates, or #svn_depth_infinity. 2343 * 2344 * If the @a get_locks_func callback implementation returns an error, 2345 * lock iteration will terminate and that error will be returned by 2346 * this function. 2347 * 2348 * @note Over the course of this function's invocation, locks might be 2349 * added, removed, or modified by concurrent processes. Callers need 2350 * to anticipate and gracefully handle the transience of this 2351 * information. 2352 * 2353 * @since New in 1.7. 2354 */ 2355 svn_error_t * 2356 svn_fs_get_locks2(svn_fs_t *fs, 2357 const char *path, 2358 svn_depth_t depth, 2359 svn_fs_get_locks_callback_t get_locks_func, 2360 void *get_locks_baton, 2361 apr_pool_t *pool); 2362 2363 /** Similar to svn_fs_get_locks2(), but with @a depth always passed as 2364 * svn_depth_infinity, and with the following known problem (which is 2365 * not present in svn_fs_get_locks2()): 2366 * 2367 * @note On Berkeley-DB-backed filesystems in Subversion 1.6 and 2368 * prior, the @a get_locks_func callback will be invoked from within a 2369 * Berkeley-DB transaction trail. Implementors of the callback are, 2370 * as a result, forbidden from calling any svn_fs API functions which 2371 * might themselves attempt to start a new Berkeley DB transaction 2372 * (which is most of this svn_fs API). Yes, this is a nasty 2373 * implementation detail to have to be aware of. 2374 * 2375 * @deprecated Provided for backward compatibility with the 1.6 API. 2376 */ 2377 SVN_DEPRECATED 2378 svn_error_t * 2379 svn_fs_get_locks(svn_fs_t *fs, 2380 const char *path, 2381 svn_fs_get_locks_callback_t get_locks_func, 2382 void *get_locks_baton, 2383 apr_pool_t *pool); 2384 2385 /** @} */ 2386 2387 /** 2388 * Append a textual list of all available FS modules to the stringbuf 2389 * @a output. Third-party modules are only included if repository 2390 * access has caused them to be loaded. 2391 * 2392 * @since New in 1.2. 2393 */ 2394 svn_error_t * 2395 svn_fs_print_modules(svn_stringbuf_t *output, 2396 apr_pool_t *pool); 2397 2398 2399 /** The kind of action being taken by 'pack'. */ 2400 typedef enum svn_fs_pack_notify_action_t 2401 { 2402 /** packing of the shard has commenced */ 2403 svn_fs_pack_notify_start = 0, 2404 2405 /** packing of the shard is completed */ 2406 svn_fs_pack_notify_end, 2407 2408 /** packing of the shard revprops has commenced 2409 @since New in 1.7. */ 2410 svn_fs_pack_notify_start_revprop, 2411 2412 /** packing of the shard revprops has completed 2413 @since New in 1.7. */ 2414 svn_fs_pack_notify_end_revprop 2415 2416 } svn_fs_pack_notify_action_t; 2417 2418 /** The type of a pack notification function. @a shard is the shard being 2419 * acted upon; @a action is the type of action being performed. @a baton is 2420 * the corresponding baton for the notification function, and @a pool can 2421 * be used for temporary allocations, but will be cleared between invocations. 2422 */ 2423 typedef svn_error_t *(*svn_fs_pack_notify_t)(void *baton, 2424 apr_int64_t shard, 2425 svn_fs_pack_notify_action_t action, 2426 apr_pool_t *pool); 2427 2428 /** 2429 * Possibly update the filesystem located in the directory @a path 2430 * to use disk space more efficiently. 2431 * 2432 * @since New in 1.6. 2433 */ 2434 svn_error_t * 2435 svn_fs_pack(const char *db_path, 2436 svn_fs_pack_notify_t notify_func, 2437 void *notify_baton, 2438 svn_cancel_func_t cancel_func, 2439 void *cancel_baton, 2440 apr_pool_t *pool); 2441 2442 2443 /** 2444 * Perform backend-specific data consistency and correctness validations 2445 * to the Subversion filesystem (mainly the meta-data) located in the 2446 * directory @a path. Use the backend-specific configuration @a fs_config 2447 * when opening the filesystem. @a NULL is valid for all backends. 2448 * Use @a scratch_pool for temporary allocations. 2449 * 2450 * @a start and @a end define the (minimum) range of revisions to check. 2451 * If @a start is #SVN_INVALID_REVNUM, it defaults to @c r0. Likewise, 2452 * @a end will default to the current youngest repository revision when 2453 * given as #SVN_INVALID_REVNUM. Since meta data checks may have to touch 2454 * other revisions as well, you may receive notifications for revisions 2455 * outside the specified range. In fact, it is perfectly legal for a FS 2456 * implementation to always check all revisions. 2457 * 2458 * Global invariants are only guaranteed to get verified when @a r0 has 2459 * been included in the range of revisions to check. 2460 * 2461 * The optional @a notify_func callback is only a general feedback that 2462 * the operation is still in process but may be called in random revisions 2463 * order and more than once for the same revision, i.e. r2, r1, r2 would 2464 * be a valid sequence. 2465 * 2466 * The optional @a cancel_func callback will be invoked as usual to allow 2467 * the user to preempt this potentially lengthy operation. 2468 * 2469 * @note You probably don't want to use this directly. Take a look at 2470 * svn_repos_verify_fs2() instead, which does non-backend-specific 2471 * verifications as well. 2472 * 2473 * @note To ensure a full verification using all tests and covering all 2474 * revisions, you must call this function *and* #svn_fs_verify_root. 2475 * 2476 * @note Implementors, please do tests that can be done efficiently for 2477 * a single revision in #svn_fs_verify_root. This function is meant for 2478 * global checks or tests that require an expensive context setup. 2479 * 2480 * @see svn_repos_verify_fs2() 2481 * @see svn_fs_verify_root() 2482 * 2483 * @since New in 1.8. 2484 */ 2485 svn_error_t * 2486 svn_fs_verify(const char *path, 2487 apr_hash_t *fs_config, 2488 svn_revnum_t start, 2489 svn_revnum_t end, 2490 svn_fs_progress_notify_func_t notify_func, 2491 void *notify_baton, 2492 svn_cancel_func_t cancel_func, 2493 void *cancel_baton, 2494 apr_pool_t *scratch_pool); 2495 2496 /** 2497 * Perform backend-specific data consistency and correctness validations 2498 * of @a root in the Subversion filesystem @a fs. @a root is typically 2499 * a revision root (see svn_fs_revision_root()), but may be a 2500 * transaction root. Use @a scratch_pool for temporary allocations. 2501 * 2502 * @note You probably don't want to use this directly. Take a look at 2503 * svn_repos_verify_fs2() instead, which does non-backend-specific 2504 * verifications as well. 2505 * 2506 * @note To ensure a full verification using all available tests and 2507 * covering all revisions, you must call both this function and 2508 * #svn_fs_verify. 2509 * 2510 * @note Implementors, please perform tests that cannot be done 2511 * efficiently for a single revision in #svn_fs_verify. This function 2512 * is intended for local checks that don't require an expensive context 2513 * setup. 2514 * 2515 * @see svn_repos_verify_fs2() 2516 * @see svn_fs_verify() 2517 * 2518 * @since New in 1.8. 2519 */ 2520 svn_error_t * 2521 svn_fs_verify_root(svn_fs_root_t *root, 2522 apr_pool_t *scratch_pool); 2523 2524 /** @} */ 2525 2526 #ifdef __cplusplus 2527 } 2528 #endif /* __cplusplus */ 2529 2530 #endif /* SVN_FS_H */ 2531