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 45extern "C" { 46#endif /* __cplusplus */ 47 48 49/** 50 * Get libsvn_fs version information. 51 * 52 * @since New in 1.1. 53 */ 54const svn_version_t * 55svn_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. */ 66typedef struct svn_fs_t svn_fs_t; 67 68/** 69 * @defgroup svn_fs_backend_names Built-in back-ends 70 * Constants defining the currently supported built-in filesystem backends. 71 * 72 * @see svn_fs_type 73 * @{ 74 */ 75/** @since New in 1.1. */ 76#define SVN_FS_TYPE_BDB "bdb" 77/** @since New in 1.1. */ 78#define SVN_FS_TYPE_FSFS "fsfs" 79 80/** 81 * EXPERIMENTAL filesystem backend. 82 * 83 * It is not ready for general production use. Please consult the 84 * respective release notes on suggested usage scenarios. 85 * 86 * @since New in 1.9. 87 */ 88#define SVN_FS_TYPE_FSX "fsx" 89 90/** @} */ 91 92 93/** 94 * @name Filesystem configuration options 95 * @{ 96 */ 97#define SVN_FS_CONFIG_BDB_TXN_NOSYNC "bdb-txn-nosync" 98#define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE "bdb-log-autoremove" 99 100/** Enable / disable text delta caching for a FSFS repository. 101 * 102 * @since New in 1.7. 103 */ 104#define SVN_FS_CONFIG_FSFS_CACHE_DELTAS "fsfs-cache-deltas" 105 106/** Enable / disable full-text caching for a FSFS repository. 107 * 108 * @since New in 1.7. 109 */ 110#define SVN_FS_CONFIG_FSFS_CACHE_FULLTEXTS "fsfs-cache-fulltexts" 111 112/** Enable / disable revprop caching for a FSFS repository. 113 * 114 * "2" is allowed, too and means "enable if efficient", 115 * i.e. this will not create warning at runtime if there 116 * is no efficient support for revprop caching. 117 * 118 * @since New in 1.8. 119 */ 120#define SVN_FS_CONFIG_FSFS_CACHE_REVPROPS "fsfs-cache-revprops" 121 122/** Select the cache namespace. If you potentially share the cache with 123 * another FS object for the same repository, objects read through one FS 124 * will not need to be read again for the other. In most cases, that is 125 * a very desirable behavior and the default is, therefore, an empty 126 * namespace. 127 * 128 * If you want to be sure that your FS instance will actually read all 129 * requested data at least once, you need to specify a separate namespace 130 * for it. All repository verification code, for instance, should use 131 * some GUID here that is different each time you open an FS instance. 132 * 133 * @since New in 1.8. 134 */ 135#define SVN_FS_CONFIG_FSFS_CACHE_NS "fsfs-cache-namespace" 136 137/** Enable / disable caching of node properties for a FSFS repository. 138 * 139 * @since New in 1.10. 140 */ 141#define SVN_FS_CONFIG_FSFS_CACHE_NODEPROPS "fsfs-cache-nodeprops" 142 143/** Enable / disable the FSFS format 7 "block read" feature. 144 * 145 * @since New in 1.9. 146 */ 147#define SVN_FS_CONFIG_FSFS_BLOCK_READ "fsfs-block-read" 148 149/** String with a decimal representation of the FSFS format shard size. 150 * Zero ("0") means that a repository with linear layout should be created. 151 * 152 * This option will only be used during the creation of new repositories 153 * and is otherwise ignored. 154 * 155 * @since New in 1.9. 156 */ 157#define SVN_FS_CONFIG_FSFS_SHARD_SIZE "fsfs-shard-size" 158 159/** Enable / disable the FSFS format 7 logical addressing feature for a 160 * newly created repository. 161 * 162 * This option will only be used during the creation of new repositories 163 * and is otherwise ignored. 164 * 165 * @since New in 1.9. 166 */ 167#define SVN_FS_CONFIG_FSFS_LOG_ADDRESSING "fsfs-log-addressing" 168 169/* Note to maintainers: if you add further SVN_FS_CONFIG_FSFS_CACHE_* knobs, 170 update fs_fs.c:verify_as_revision_before_current_plus_plus(). */ 171 172/** Select the filesystem type. See also #svn_fs_type(). 173 * 174 * @since New in 1.1. */ 175#define SVN_FS_CONFIG_FS_TYPE "fs-type" 176 177/** Create repository format compatible with Subversion versions 178 * earlier than 1.4. 179 * 180 * @since New in 1.4. 181 */ 182#define SVN_FS_CONFIG_PRE_1_4_COMPATIBLE "pre-1.4-compatible" 183 184/** Create repository format compatible with Subversion versions 185 * earlier than 1.5. 186 * 187 * @since New in 1.5. 188 */ 189#define SVN_FS_CONFIG_PRE_1_5_COMPATIBLE "pre-1.5-compatible" 190 191/** Create repository format compatible with Subversion versions 192 * earlier than 1.6. 193 * 194 * @since New in 1.6. 195 */ 196#define SVN_FS_CONFIG_PRE_1_6_COMPATIBLE "pre-1.6-compatible" 197 198/** Create repository format compatible with Subversion versions 199 * earlier than 1.8. 200 * 201 * @since New in 1.8. 202 */ 203#define SVN_FS_CONFIG_PRE_1_8_COMPATIBLE "pre-1.8-compatible" 204 205/** Create repository format compatible with the specified Subversion 206 * release. The value must be a version in the same format as 207 * #SVN_VER_NUMBER and cannot exceed the current version. 208 * 209 * @note The @c patch component would often be ignored, due to our forward 210 * compatibility promises within minor release lines. It should therefore 211 * usually be set to @c 0. 212 * 213 * @since New in 1.9. 214 */ 215#define SVN_FS_CONFIG_COMPATIBLE_VERSION "compatible-version" 216 217/** Specifies whether the filesystem should be forcing a physical write of 218 * the data to disk. Enabling the option allows the filesystem to return 219 * from the API calls without forcing the write to disk. If this option 220 * is disabled, the changes are always written to disk. 221 * 222 * @note Avoiding the forced write to disk usually is more efficient, but 223 * doesn't guarantee data integrity after a system crash or power failure 224 * and should be used with caution. 225 * 226 * @since New in 1.10. 227 */ 228#define SVN_FS_CONFIG_NO_FLUSH_TO_DISK "no-flush-to-disk" 229 230/** @} */ 231 232 233/** 234 * Callers should invoke this function to initialize global state in 235 * the FS library before creating FS objects. If this function is 236 * invoked, no FS objects may be created in another thread at the same 237 * time as this invocation, and the provided @a pool must last longer 238 * than any FS object created subsequently. 239 * 240 * If this function is not called, the FS library will make a best 241 * effort to bootstrap a mutex for protecting data common to FS 242 * objects; however, there is a small window of failure. Also, a 243 * small amount of data will be leaked if the Subversion FS library is 244 * dynamically unloaded, and using the bdb FS can potentially segfault 245 * or invoke other undefined behavior if this function is not called 246 * with an appropriate pool (such as the pool the module was loaded into) 247 * when loaded dynamically. 248 * 249 * If this function is called multiple times before the pool passed to 250 * the first call is destroyed or cleared, the later calls will have 251 * no effect. 252 * 253 * @since New in 1.2. 254 */ 255svn_error_t * 256svn_fs_initialize(apr_pool_t *pool); 257 258 259/** The type of a warning callback function. @a baton is the value specified 260 * in the call to svn_fs_set_warning_func(); the filesystem passes it through 261 * to the callback. @a err contains the warning message. 262 * 263 * The callback function should not clear the error that is passed to it; 264 * its caller should do that. 265 */ 266typedef void (*svn_fs_warning_callback_t)(void *baton, svn_error_t *err); 267 268 269/** Provide a callback function, @a warning, that @a fs should use to 270 * report (non-fatal) errors. To print an error, the filesystem will call 271 * @a warning, passing it @a warning_baton and the error. 272 * 273 * By default, this is set to a function that will crash the process. 274 * Dumping to @c stderr or <tt>/dev/tty</tt> is not acceptable default 275 * behavior for server processes, since those may both be equivalent to 276 * <tt>/dev/null</tt>. 277 */ 278void 279svn_fs_set_warning_func(svn_fs_t *fs, 280 svn_fs_warning_callback_t warning, 281 void *warning_baton); 282 283 284 285/** 286 * Create a new, empty Subversion filesystem, stored in the directory 287 * @a path, and return a pointer to it in @a *fs_p. @a path must not 288 * currently exist, but its parent must exist. If @a fs_config is not 289 * @c NULL, the options it contains modify the behavior of the 290 * filesystem. The interpretation of @a fs_config is specific to the 291 * filesystem back-end. The new filesystem may be closed by 292 * destroying @a result_pool. 293 * 294 * Use @a scratch_pool for temporary allocations. 295 * 296 * @note The lifetime of @a fs_config must not be shorter than @a 297 * result_pool's. It's a good idea to allocate @a fs_config from 298 * @a result_pool or one of its ancestors. 299 * 300 * If @a fs_config contains a value for #SVN_FS_CONFIG_FS_TYPE, that 301 * value determines the filesystem type for the new filesystem. 302 * Currently defined values are: 303 * 304 * SVN_FS_TYPE_BDB Berkeley-DB implementation 305 * SVN_FS_TYPE_FSFS Native-filesystem implementation 306 * SVN_FS_TYPE_FSX Experimental filesystem implementation 307 * 308 * If @a fs_config is @c NULL or does not contain a value for 309 * #SVN_FS_CONFIG_FS_TYPE then the default filesystem type will be used. 310 * This will typically be BDB for version 1.1 and FSFS for later versions, 311 * though the caller should not rely upon any particular default if they 312 * wish to ensure that a filesystem of a specific type is created. 313 * 314 * @since New in 1.10. 315 */ 316svn_error_t * 317svn_fs_create2(svn_fs_t **fs_p, 318 const char *path, 319 apr_hash_t *fs_config, 320 apr_pool_t *result_pool, 321 apr_pool_t *scratch_pool); 322 323/** 324 * Like svn_fs_create2(), but without @a scratch_pool. 325 * 326 * @deprecated Provided for backward compatibility with the 1.9 API. 327 * @since New in 1.1. 328 */ 329SVN_DEPRECATED 330svn_error_t * 331svn_fs_create(svn_fs_t **fs_p, 332 const char *path, 333 apr_hash_t *fs_config, 334 apr_pool_t *pool); 335 336/** 337 * Open a Subversion filesystem located in the directory @a path, and 338 * return a pointer to it in @a *fs_p. If @a fs_config is not @c 339 * NULL, the options it contains modify the behavior of the 340 * filesystem. The interpretation of @a fs_config is specific to the 341 * filesystem back-end. The opened filesystem will be allocated in 342 * @a result_pool may be closed by clearing or destroying that pool. 343 * Use @a scratch_pool for temporary allocations. 344 * 345 * @note The lifetime of @a fs_config must not be shorter than @a 346 * result_pool's. It's a good idea to allocate @a fs_config from 347 * @a result_pool or one of its ancestors. 348 * 349 * Only one thread may operate on any given filesystem object at once. 350 * Two threads may access the same filesystem simultaneously only if 351 * they open separate filesystem objects. 352 * 353 * @note You probably don't want to use this directly. Take a look at 354 * svn_repos_open3() instead. 355 * 356 * @since New in 1.9. 357 */ 358svn_error_t * 359svn_fs_open2(svn_fs_t **fs_p, 360 const char *path, 361 apr_hash_t *fs_config, 362 apr_pool_t *result_pool, 363 apr_pool_t *scratch_pool); 364 365/** 366 * Like svn_fs_open2(), but without @a scratch_pool. 367 * 368 * @deprecated Provided for backward compatibility with the 1.8 API. 369 * @since New in 1.1. 370 */ 371SVN_DEPRECATED 372svn_error_t * 373svn_fs_open(svn_fs_t **fs_p, 374 const char *path, 375 apr_hash_t *fs_config, 376 apr_pool_t *pool); 377 378/** The kind of action being taken by 'upgrade'. 379 * 380 * @since New in 1.9. 381 */ 382typedef enum svn_fs_upgrade_notify_action_t 383{ 384 /** Packing of the revprop shard has completed. 385 * The number parameter is the shard being processed. */ 386 svn_fs_upgrade_pack_revprops = 0, 387 388 /** Removal of the non-packed revprop shard is completed. 389 * The number parameter is the shard being processed */ 390 svn_fs_upgrade_cleanup_revprops, 391 392 /** DB format has been set to the new value. 393 * The number parameter is the new format number. */ 394 svn_fs_upgrade_format_bumped 395} svn_fs_upgrade_notify_action_t; 396 397/** The type of an upgrade notification function. @a number is specifc 398 * to @a action (see #svn_fs_upgrade_notify_action_t); @a action is the 399 * type of action being performed. @a baton is the corresponding baton 400 * for the notification function, and @a scratch_pool can be used for 401 * temporary allocations, but will be cleared between invocations. 402 * 403 * @since New in 1.9. 404 */ 405typedef svn_error_t *(*svn_fs_upgrade_notify_t)(void *baton, 406 apr_uint64_t number, 407 svn_fs_upgrade_notify_action_t action, 408 apr_pool_t *scratch_pool); 409 410/** 411 * Upgrade the Subversion filesystem located in the directory @a path 412 * to the latest version supported by this library. Return 413 * #SVN_ERR_FS_UNSUPPORTED_UPGRADE and make no changes to the 414 * filesystem if the requested upgrade is not supported. Use 415 * @a scratch_pool for temporary allocations. 416 * 417 * The optional @a notify_func callback is only a general feedback that 418 * the operation is still in process but may be called in e.g. random shard 419 * order and more than once for the same shard. 420 * 421 * The optional @a cancel_func callback will be invoked as usual to allow 422 * the user to preempt this potentially lengthy operation. 423 * 424 * @note You probably don't want to use this directly. Take a look at 425 * svn_repos_upgrade2() instead. 426 * 427 * @note Canceling an upgrade is legal but may leave remnants of previous 428 * format data that may not be cleaned up automatically by later calls. 429 * 430 * @since New in 1.9. 431 */ 432svn_error_t * 433svn_fs_upgrade2(const char *path, 434 svn_fs_upgrade_notify_t notify_func, 435 void *notify_baton, 436 svn_cancel_func_t cancel_func, 437 void *cancel_baton, 438 apr_pool_t *scratch_pool); 439 440/** 441 * Like svn_fs_upgrade2 but with notify_func, notify_baton, cancel_func 442 * and cancel_baton being set to NULL. 443 * 444 * @deprecated Provided for backward compatibility with the 1.8 API. 445 * @since New in 1.5. 446 */ 447SVN_DEPRECATED 448svn_error_t * 449svn_fs_upgrade(const char *path, 450 apr_pool_t *pool); 451 452/** 453 * Callback function type for progress notification. 454 * 455 * @a revision is the number of the revision currently being processed, 456 * #SVN_INVALID_REVNUM if the current stage is not linked to any specific 457 * revision. @a baton is the callback baton. 458 * 459 * @since New in 1.8. 460 */ 461typedef void (*svn_fs_progress_notify_func_t)(svn_revnum_t revision, 462 void *baton, 463 apr_pool_t *pool); 464 465/** 466 * Return, in @a *fs_type, a string identifying the back-end type of 467 * the Subversion filesystem located in @a path. Allocate @a *fs_type 468 * in @a pool. 469 * 470 * The string should be equal to one of the @c SVN_FS_TYPE_* defined 471 * constants, unless the filesystem is a new back-end type added in 472 * a later version of Subversion. 473 * 474 * In general, the type should make no difference in the filesystem's 475 * semantics, but there are a few situations (such as backups) where 476 * it might matter. 477 * 478 * @since New in 1.3. 479 */ 480svn_error_t * 481svn_fs_type(const char **fs_type, 482 const char *path, 483 apr_pool_t *pool); 484 485/** 486 * Return the path to @a fs's repository, allocated in @a pool. 487 * @note This is just what was passed to svn_fs_create() or 488 * svn_fs_open() -- might be absolute, might not. 489 * 490 * @since New in 1.1. 491 */ 492const char * 493svn_fs_path(svn_fs_t *fs, 494 apr_pool_t *pool); 495 496/** 497 * Return a shallow copy of the configuration parameters used to open 498 * @a fs, allocated in @a pool. It may be @c NULL. The contents of the 499 * hash contents remains valid only for @a fs's lifetime. 500 * 501 * @note This is just what was passed to svn_fs_create() or svn_fs_open(). 502 * You may not modify it. 503 * 504 * @since New in 1.8. 505 */ 506apr_hash_t * 507svn_fs_config(svn_fs_t *fs, 508 apr_pool_t *pool); 509 510/** 511 * Delete the filesystem at @a path. 512 * 513 * @note: Deleting a filesystem that has an open svn_fs_t is not 514 * supported. Clear/destroy all pools used to create/open @a path. 515 * See issue 4264. 516 * 517 * @since New in 1.1. 518 */ 519svn_error_t * 520svn_fs_delete_fs(const char *path, 521 apr_pool_t *pool); 522 523/** The type of a hotcopy notification function. @a start_revision and 524 * @a end_revision indicate the copied revision range. @a baton is the 525 * corresponding baton for the notification function, and @a scratch_pool 526 * can be used for temporary allocations, but will be cleared between 527 * invocations. 528 */ 529typedef void (*svn_fs_hotcopy_notify_t)(void *baton, 530 svn_revnum_t start_revision, 531 svn_revnum_t end_revision, 532 apr_pool_t *scratch_pool); 533 534/** 535 * Copy a possibly live Subversion filesystem from @a src_path to 536 * @a dest_path. If @a clean is @c TRUE, perform cleanup on the 537 * source filesystem as part of the copy operation; currently, this 538 * means deleting copied, unused logfiles for a Berkeley DB source 539 * filesystem. 540 * 541 * If @a incremental is TRUE, make an effort to avoid re-copying 542 * information already present in the destination where possible. If 543 * incremental hotcopy is not implemented, raise 544 * #SVN_ERR_UNSUPPORTED_FEATURE. 545 * 546 * For each revision range copied, @a notify_func will be called with 547 * staring and ending revision numbers (both inclusive and not necessarily 548 * different) and with the @a notify_baton. Currently, this notification 549 * is not triggered by the BDB backend. @a notify_func may be @c NULL 550 * if this notification is not required. 551 * 552 * The optional @a cancel_func callback will be invoked with 553 * @a cancel_baton as usual to allow the user to preempt this potentially 554 * lengthy operation. 555 * 556 * Use @a scratch_pool for temporary allocations. 557 * 558 * @since New in 1.9. 559 */ 560svn_error_t * 561svn_fs_hotcopy3(const char *src_path, 562 const char *dest_path, 563 svn_boolean_t clean, 564 svn_boolean_t incremental, 565 svn_fs_hotcopy_notify_t notify_func, 566 void *notify_baton, 567 svn_cancel_func_t cancel_func, 568 void *cancel_baton, 569 apr_pool_t *scratch_pool); 570 571/** 572 * Like svn_fs_hotcopy3(), but with @a notify_func and @a notify_baton 573 * always passed as @c NULL. 574 * 575 * @deprecated Provided for backward compatibility with the 1.8 API. 576 * @since New in 1.8. 577 */ 578SVN_DEPRECATED 579svn_error_t * 580svn_fs_hotcopy2(const char *src_path, 581 const char *dest_path, 582 svn_boolean_t clean, 583 svn_boolean_t incremental, 584 svn_cancel_func_t cancel_func, 585 void *cancel_baton, 586 apr_pool_t *scratch_pool); 587 588/** 589 * Like svn_fs_hotcopy2(), but with @a incremental always passed as @c 590 * TRUE and without cancellation support. 591 * 592 * @deprecated Provided for backward compatibility with the 1.7 API. 593 * @since New in 1.1. 594 */ 595SVN_DEPRECATED 596svn_error_t * 597svn_fs_hotcopy(const char *src_path, 598 const char *dest_path, 599 svn_boolean_t clean, 600 apr_pool_t *pool); 601 602/** Perform any necessary non-catastrophic recovery on the Subversion 603 * filesystem located at @a path. 604 * 605 * If @a cancel_func is not @c NULL, it is called periodically with 606 * @a cancel_baton as argument to see if the client wishes to cancel 607 * recovery. BDB filesystems do not currently support cancellation. 608 * 609 * Do any necessary allocation within @a pool. 610 * 611 * For FSFS filesystems, recovery is currently limited to recreating 612 * the db/current file, and does not require exclusive access. 613 * 614 * For BDB filesystems, recovery requires exclusive access, and is 615 * described in detail below. 616 * 617 * After an unexpected server exit, due to a server crash or a system 618 * crash, a Subversion filesystem based on Berkeley DB needs to run 619 * recovery procedures to bring the database back into a consistent 620 * state and release any locks that were held by the deceased process. 621 * The recovery procedures require exclusive access to the database 622 * --- while they execute, no other process or thread may access the 623 * database. 624 * 625 * In a server with multiple worker processes, like Apache, if a 626 * worker process accessing the filesystem dies, you must stop the 627 * other worker processes, and run recovery. Then, the other worker 628 * processes can re-open the database and resume work. 629 * 630 * If the server exited cleanly, there is no need to run recovery, but 631 * there is no harm in it, either, and it take very little time. So 632 * it's a fine idea to run recovery when the server process starts, 633 * before it begins handling any requests. 634 * 635 * @since New in 1.5. 636 */ 637svn_error_t * 638svn_fs_recover(const char *path, 639 svn_cancel_func_t cancel_func, 640 void *cancel_baton, 641 apr_pool_t *pool); 642 643 644/** 645 * Callback for svn_fs_freeze(). 646 * 647 * @since New in 1.8. 648 */ 649typedef svn_error_t *(*svn_fs_freeze_func_t)(void *baton, apr_pool_t *pool); 650 651/** 652 * Take an exclusive lock on @a fs to prevent commits and then invoke 653 * @a freeze_func passing @a freeze_baton. 654 * 655 * @note @a freeze_func must not, directly or indirectly, call any function 656 * that attempts to take out a lock on the underlying repository. These 657 * include functions for packing, hotcopying, setting revprops and commits. 658 * Attempts to do so may result in a deadlock. 659 * 660 * @note The BDB backend doesn't implement this feature so most 661 * callers should not call this function directly but should use the 662 * higher level svn_repos_freeze() instead. 663 * 664 * @see svn_repos_freeze() 665 * 666 * @since New in 1.8. 667 */ 668svn_error_t * 669svn_fs_freeze(svn_fs_t *fs, 670 svn_fs_freeze_func_t freeze_func, 671 void *freeze_baton, 672 apr_pool_t *pool); 673 674 675/** Subversion filesystems based on Berkeley DB. 676 * 677 * The following functions are specific to Berkeley DB filesystems. 678 * 679 * @defgroup svn_fs_bdb Berkeley DB filesystems 680 * @{ 681 */ 682 683/** Register an error handling function for Berkeley DB error messages. 684 * 685 * @deprecated Provided for backward compatibility with the 1.2 API. 686 * 687 * Despite being first declared deprecated in Subversion 1.3, this API 688 * is redundant in versions 1.1 and 1.2 as well. 689 * 690 * Berkeley DB's error codes are seldom sufficiently informative to allow 691 * adequate troubleshooting. Berkeley DB provides extra messages through 692 * a callback function - if an error occurs, the @a handler will be called 693 * with two strings: an error message prefix, which will be zero, and 694 * an error message. @a handler might print it out, log it somewhere, 695 * etc. 696 * 697 * Subversion 1.1 and later install their own handler internally, and 698 * wrap the messages from Berkeley DB into the standard svn_error_t object, 699 * making any information gained through this interface redundant. 700 * 701 * It is only worth using this function if your program will be used 702 * with Subversion 1.0. 703 * 704 * This function connects to the Berkeley DB @c DBENV->set_errcall interface. 705 * Since that interface supports only a single callback, Subversion's internal 706 * callback is registered with Berkeley DB, and will forward notifications to 707 * a user provided callback after performing its own processing. 708 */ 709SVN_DEPRECATED 710svn_error_t * 711svn_fs_set_berkeley_errcall(svn_fs_t *fs, 712 void (*handler)(const char *errpfx, 713 char *msg)); 714 715/** Set @a *logfiles to an array of <tt>const char *</tt> log file names 716 * of Berkeley DB-based Subversion filesystem. 717 * 718 * If @a only_unused is @c TRUE, set @a *logfiles to an array which 719 * contains only the names of Berkeley DB log files no longer in use 720 * by the filesystem. Otherwise, all log files (used and unused) are 721 * returned. 722 723 * This function wraps the Berkeley DB 'log_archive' function 724 * called by the db_archive binary. Repository administrators may 725 * want to run this function periodically and delete the unused log 726 * files, as a way of reclaiming disk space. 727 */ 728svn_error_t * 729svn_fs_berkeley_logfiles(apr_array_header_t **logfiles, 730 const char *path, 731 svn_boolean_t only_unused, 732 apr_pool_t *pool); 733 734 735/** 736 * The following functions are similar to their generic counterparts. 737 * 738 * In Subversion 1.2 and earlier, they only work on Berkeley DB filesystems. 739 * In Subversion 1.3 and later, they perform largely as aliases for their 740 * generic counterparts (with the exception of recover, which only gained 741 * a generic counterpart in 1.5). 742 * 743 * @defgroup svn_fs_bdb_deprecated Berkeley DB filesystem compatibility 744 * @{ 745 */ 746 747/** @deprecated Provided for backward compatibility with the 1.0 API. */ 748SVN_DEPRECATED 749svn_fs_t * 750svn_fs_new(apr_hash_t *fs_config, 751 apr_pool_t *pool); 752 753/** @deprecated Provided for backward compatibility with the 1.0 API. */ 754SVN_DEPRECATED 755svn_error_t * 756svn_fs_create_berkeley(svn_fs_t *fs, 757 const char *path); 758 759/** @deprecated Provided for backward compatibility with the 1.0 API. */ 760SVN_DEPRECATED 761svn_error_t * 762svn_fs_open_berkeley(svn_fs_t *fs, 763 const char *path); 764 765/** @deprecated Provided for backward compatibility with the 1.0 API. */ 766SVN_DEPRECATED 767const char * 768svn_fs_berkeley_path(svn_fs_t *fs, 769 apr_pool_t *pool); 770 771/** @deprecated Provided for backward compatibility with the 1.0 API. */ 772SVN_DEPRECATED 773svn_error_t * 774svn_fs_delete_berkeley(const char *path, 775 apr_pool_t *pool); 776 777/** @deprecated Provided for backward compatibility with the 1.0 API. */ 778SVN_DEPRECATED 779svn_error_t * 780svn_fs_hotcopy_berkeley(const char *src_path, 781 const char *dest_path, 782 svn_boolean_t clean_logs, 783 apr_pool_t *pool); 784 785/** @deprecated Provided for backward compatibility with the 1.4 API. */ 786SVN_DEPRECATED 787svn_error_t * 788svn_fs_berkeley_recover(const char *path, 789 apr_pool_t *pool); 790/** @} */ 791 792/** @} */ 793 794 795/** Filesystem Access Contexts. 796 * 797 * @since New in 1.2. 798 * 799 * At certain times, filesystem functions need access to temporary 800 * user data. For example, which user is changing a file? If the 801 * file is locked, has an appropriate lock-token been supplied? 802 * 803 * This temporary user data is stored in an "access context" object, 804 * and the access context is then connected to the filesystem object. 805 * Whenever a filesystem function requires information, it can pull 806 * things out of the context as needed. 807 * 808 * @defgroup svn_fs_access_ctx Filesystem access contexts 809 * @{ 810 */ 811 812/** An opaque object representing temporary user data. */ 813typedef struct svn_fs_access_t svn_fs_access_t; 814 815 816/** Set @a *access_ctx to a new #svn_fs_access_t object representing 817 * @a username, allocated in @a pool. @a username is presumed to 818 * have been authenticated by the caller. 819 * 820 * Make a deep copy of @a username. 821 */ 822svn_error_t * 823svn_fs_create_access(svn_fs_access_t **access_ctx, 824 const char *username, 825 apr_pool_t *pool); 826 827 828/** Associate @a access_ctx with an open @a fs. 829 * 830 * This function can be run multiple times on the same open 831 * filesystem, in order to change the filesystem access context for 832 * different filesystem operations. Pass a NULL value for @a 833 * access_ctx to disassociate the current access context from the 834 * filesystem. 835 */ 836svn_error_t * 837svn_fs_set_access(svn_fs_t *fs, 838 svn_fs_access_t *access_ctx); 839 840 841/** Set @a *access_ctx to the current @a fs access context, or NULL if 842 * there is no current fs access context. 843 */ 844svn_error_t * 845svn_fs_get_access(svn_fs_access_t **access_ctx, 846 svn_fs_t *fs); 847 848 849/** Accessors for the access context: */ 850 851/** Set @a *username to the name represented by @a access_ctx. */ 852svn_error_t * 853svn_fs_access_get_username(const char **username, 854 svn_fs_access_t *access_ctx); 855 856 857/** Push a lock-token @a token associated with path @a path into the 858 * context @a access_ctx. The context remembers all tokens it 859 * receives, and makes them available to fs functions. The token and 860 * path are not duplicated into @a access_ctx's pool; make sure the 861 * token's lifetime is at least as long as @a access_ctx. 862 * 863 * @since New in 1.6. */ 864svn_error_t * 865svn_fs_access_add_lock_token2(svn_fs_access_t *access_ctx, 866 const char *path, 867 const char *token); 868 869/** 870 * Same as svn_fs_access_add_lock_token2(), but with @a path set to value 1. 871 * 872 * @deprecated Provided for backward compatibility with the 1.5 API. 873 */ 874SVN_DEPRECATED 875svn_error_t * 876svn_fs_access_add_lock_token(svn_fs_access_t *access_ctx, 877 const char *token); 878 879/** @} */ 880 881 882/** Filesystem Nodes and Node-Revisions. 883 * 884 * In a Subversion filesystem, a `node' corresponds roughly to an 885 * `inode' in a Unix filesystem: 886 * - A node is either a file or a directory. 887 * - A node's contents change over time. 888 * - When you change a node's contents, it's still the same node; it's 889 * just been changed. So a node's identity isn't bound to a specific 890 * set of contents. 891 * - If you rename a node, it's still the same node, just under a 892 * different name. So a node's identity isn't bound to a particular 893 * filename. 894 * 895 * A `node revision' refers to one particular version of a node's contents, 896 * that existed over a specific period of time (one or more repository 897 * revisions). Changing a node's contents always creates a new revision of 898 * that node, which is to say creates a new `node revision'. Once created, 899 * a node revision's contents never change. 900 * 901 * When we create a node, its initial contents are the initial revision of 902 * the node. As users make changes to the node over time, we create new 903 * revisions of that same node. When a user commits a change that deletes 904 * a file from the filesystem, we don't delete the node, or any revision 905 * of it --- those stick around to allow us to recreate prior revisions of 906 * the filesystem. Instead, we just remove the reference to the node 907 * from the directory. 908 * 909 * Each node revision is a part of exactly one node, and appears only once 910 * in the history of that node. It is uniquely identified by a node 911 * revision id, #svn_fs_id_t. Its node revision id also identifies which 912 * node it is a part of. 913 * 914 * @note: Often when we talk about `the node' within the context of a single 915 * revision (or transaction), we implicitly mean `the node as it appears in 916 * this revision (or transaction)', or in other words `the node revision'. 917 * 918 * @note: Commonly, a node revision will have the same content as some other 919 * node revisions in the same node and in different nodes. The FS libraries 920 * allow different node revisions to share the same data without storing a 921 * separate copy of the data. 922 * 923 * @defgroup svn_fs_nodes Filesystem nodes 924 * @{ 925 */ 926 927/** Defines the possible ways two arbitrary (root, path)-pairs may be 928 * related. 929 * 930 * @since New in 1.9. 931 */ 932typedef enum svn_fs_node_relation_t 933{ 934 /** The (root, path)-pairs are not related, i.e. none of the other cases 935 * apply. If the roots refer to different @c svn_fs_t instances, then 936 * they are always considered unrelated - even if the underlying 937 * repository is the same. 938 */ 939 svn_fs_node_unrelated = 0, 940 941 /** No changes have been made between the (root, path)-pairs, i.e. they 942 * have the same (relative) nodes in their sub-trees, corresponding sub- 943 * tree nodes have the same contents as well as properties and report the 944 * same "created-path" and "created-rev" data. This implies having a 945 * common ancestor. 946 * 947 * However, due to efficiency considerations, the FS implementation may 948 * report some combinations as merely having a common ancestor 949 * (@a svn_fs_node_common_ancestor) instead of actually being unchanged. 950 */ 951 svn_fs_node_unchanged, 952 953 /** The (root, path)-pairs have a common ancestor (which may be one of 954 * them) but there are changes between them, i.e. they don't fall into 955 * the @c svn_fs_node_unchanged category. 956 * 957 * Due to efficiency considerations, the FS implementation may falsely 958 * classify some combinations as merely having a common ancestor that 959 * are, in fact, unchanged (@a svn_fs_node_unchanged). 960 */ 961 svn_fs_node_common_ancestor 962 963} svn_fs_node_relation_t; 964 965/** An object representing a node-revision id. */ 966typedef struct svn_fs_id_t svn_fs_id_t; 967 968 969/** Return -1, 0, or 1 if node revisions @a a and @a b are respectively 970 * unrelated, equivalent, or otherwise related (part of the same node). 971 * 972 * @note Consider using the more expressive #svn_fs_node_relation() instead. 973 * 974 * @see #svn_fs_node_relation 975 */ 976int 977svn_fs_compare_ids(const svn_fs_id_t *a, 978 const svn_fs_id_t *b); 979 980 981 982/** Return TRUE if node revisions @a id1 and @a id2 are related (part of the 983 * same node), else return FALSE. 984 * 985 * @note Consider using the more expressive #svn_fs_node_relation() instead. 986 * 987 * @see #svn_fs_node_relation 988 */ 989svn_boolean_t 990svn_fs_check_related(const svn_fs_id_t *id1, 991 const svn_fs_id_t *id2); 992 993 994/** 995 * @note This function is not guaranteed to work with all filesystem 996 * types. There is currently no un-deprecated equivalent; contact the 997 * Subversion developers if you have a need for it. 998 * 999 * @deprecated Provided for backward compatibility with the 1.0 API. 1000 */ 1001SVN_DEPRECATED 1002svn_fs_id_t * 1003svn_fs_parse_id(const char *data, 1004 apr_size_t len, 1005 apr_pool_t *pool); 1006 1007 1008/** Return a Subversion string containing the unparsed form of the 1009 * node revision id @a id. Allocate the string containing the 1010 * unparsed form in @a pool. 1011 */ 1012svn_string_t * 1013svn_fs_unparse_id(const svn_fs_id_t *id, 1014 apr_pool_t *pool); 1015 1016/** @} */ 1017 1018 1019/** Filesystem Transactions. 1020 * 1021 * To make a change to a Subversion filesystem: 1022 * - Create a transaction object, using svn_fs_begin_txn(). 1023 * - Call svn_fs_txn_root(), to get the transaction's root directory. 1024 * - Make whatever changes you like in that tree. 1025 * - Commit the transaction, using svn_fs_commit_txn(). 1026 * 1027 * The filesystem implementation guarantees that your commit will 1028 * either: 1029 * - succeed completely, so that all of the changes are committed to 1030 * create a new revision of the filesystem, or 1031 * - fail completely, leaving the filesystem unchanged. 1032 * 1033 * Until you commit the transaction, any changes you make are 1034 * invisible. Only when your commit succeeds do they become visible 1035 * to the outside world, as a new revision of the filesystem. 1036 * 1037 * If you begin a transaction, and then decide you don't want to make 1038 * the change after all (say, because your net connection with the 1039 * client disappeared before the change was complete), you can call 1040 * svn_fs_abort_txn(), to cancel the entire transaction; this 1041 * leaves the filesystem unchanged. 1042 * 1043 * The only way to change the contents of files or directories, or 1044 * their properties, is by making a transaction and creating a new 1045 * revision, as described above. Once a revision has been committed, it 1046 * never changes again; the filesystem interface provides no means to 1047 * go back and edit the contents of an old revision. Once history has 1048 * been recorded, it is set in stone. Clients depend on this property 1049 * to do updates and commits reliably; proxies depend on this property 1050 * to cache changes accurately; and so on. 1051 * 1052 * There are two kinds of nodes in the filesystem: mutable, and 1053 * immutable. Revisions in the filesystem consist entirely of 1054 * immutable nodes, whose contents never change. A transaction in 1055 * progress, which the user is still constructing, uses mutable nodes 1056 * for those nodes which have been changed so far, and refers to 1057 * immutable nodes from existing revisions for portions of the tree 1058 * which haven't been changed yet in that transaction. 1059 * 1060 * Immutable nodes, as part of revisions, never refer to mutable 1061 * nodes, which are part of uncommitted transactions. Mutable nodes 1062 * may refer to immutable nodes, or other mutable nodes. 1063 * 1064 * Note that the terms "immutable" and "mutable" describe whether or 1065 * not the nodes have been changed as part of a transaction --- not 1066 * the permissions on the nodes they refer to. Even if you aren't 1067 * authorized to modify the filesystem's root directory, you might be 1068 * authorized to change some descendant of the root; doing so would 1069 * create a new mutable copy of the root directory. Mutability refers 1070 * to the role of the node: part of an existing revision, or part of a 1071 * new one. This is independent of your authorization to make changes 1072 * to a given node. 1073 * 1074 * Transactions are actually persistent objects, stored in the 1075 * database. You can open a filesystem, begin a transaction, and 1076 * close the filesystem, and then a separate process could open the 1077 * filesystem, pick up the same transaction, and continue work on it. 1078 * When a transaction is successfully committed, it is removed from 1079 * the database. 1080 * 1081 * Every transaction is assigned a name. You can open a transaction 1082 * by name, and resume work on it, or find out the name of a 1083 * transaction you already have open. You can also list all the 1084 * transactions currently present in the database. 1085 * 1086 * You may assign properties to transactions; these are name/value 1087 * pairs. When you commit a transaction, all of its properties become 1088 * unversioned revision properties of the new revision. (There is one 1089 * exception: the svn:date property will be automatically set on new 1090 * transactions to the date that the transaction was created, and can 1091 * be overwritten when the transaction is committed by the current 1092 * time; see svn_fs_commit_txn.) 1093 * 1094 * Transaction names are guaranteed to contain only letters (upper- 1095 * and lower-case), digits, `-', and `.', from the ASCII character 1096 * set. 1097 * 1098 * The Subversion filesystem will make a best effort to not reuse 1099 * transaction names. The BDB and FSFS backends generate transaction 1100 * names using a sequence, or a counter, which is stored in the 1101 * database. Each new transaction increments the counter. The 1102 * current value of the counter is not serialized into a filesystem 1103 * dump file, so dumping and restoring the repository will reset the 1104 * sequence and so may reuse transaction names. 1105 * 1106 * @defgroup svn_fs_txns Filesystem transactions 1107 * @{ 1108 */ 1109 1110/** The type of a Subversion transaction object. */ 1111typedef struct svn_fs_txn_t svn_fs_txn_t; 1112 1113 1114/** @defgroup svn_fs_begin_txn2_flags Bitmask flags for svn_fs_begin_txn2() 1115 * @since New in 1.2. 1116 * @{ */ 1117 1118/** Do on-the-fly out-of-dateness checks. That is, an fs routine may 1119 * throw error if a caller tries to edit an out-of-date item in the 1120 * transaction. 1121 * 1122 * @warning ### Not yet implemented. 1123 */ 1124#define SVN_FS_TXN_CHECK_OOD 0x00001 1125 1126/** Do on-the-fly lock checks. That is, an fs routine may throw error 1127 * if a caller tries to edit a locked item without having rights to the lock. 1128 */ 1129#define SVN_FS_TXN_CHECK_LOCKS 0x00002 1130 1131/** Allow the client to specify the final svn:date of the revision by 1132 * setting or deleting the corresponding transaction property rather 1133 * than have it set automatically when the transaction is committed. 1134 * 1135 * @since New in 1.9. 1136 */ 1137#define SVN_FS_TXN_CLIENT_DATE 0x00004 1138 1139/** @} */ 1140 1141/** 1142 * Begin a new transaction on the filesystem @a fs, based on existing 1143 * revision @a rev. Set @a *txn_p to a pointer to the new transaction. 1144 * When committed, this transaction will create a new revision. 1145 * 1146 * Allocate the new transaction in @a pool; when @a pool is freed, the new 1147 * transaction will be closed (neither committed nor aborted). 1148 * 1149 * @a flags determines transaction enforcement behaviors, and is composed 1150 * from the constants SVN_FS_TXN_* (#SVN_FS_TXN_CHECK_OOD etc.). 1151 * 1152 * @note If you're building a txn for committing, you probably 1153 * don't want to call this directly. Instead, call 1154 * svn_repos_fs_begin_txn_for_commit(), which honors the 1155 * repository's hook configurations. 1156 * 1157 * @since New in 1.2. 1158 */ 1159svn_error_t * 1160svn_fs_begin_txn2(svn_fs_txn_t **txn_p, 1161 svn_fs_t *fs, 1162 svn_revnum_t rev, 1163 apr_uint32_t flags, 1164 apr_pool_t *pool); 1165 1166 1167/** 1168 * Same as svn_fs_begin_txn2(), but with @a flags set to 0. 1169 * 1170 * @deprecated Provided for backward compatibility with the 1.1 API. 1171 */ 1172SVN_DEPRECATED 1173svn_error_t * 1174svn_fs_begin_txn(svn_fs_txn_t **txn_p, 1175 svn_fs_t *fs, 1176 svn_revnum_t rev, 1177 apr_pool_t *pool); 1178 1179 1180 1181/** Commit @a txn. 1182 * 1183 * @note You usually don't want to call this directly. 1184 * Instead, call svn_repos_fs_commit_txn(), which honors the 1185 * repository's hook configurations. 1186 * 1187 * If the transaction conflicts with other changes committed to the 1188 * repository, return an #SVN_ERR_FS_CONFLICT error. Otherwise, create 1189 * a new filesystem revision containing the changes made in @a txn, 1190 * storing that new revision number in @a *new_rev, and return zero. 1191 * 1192 * If #SVN_FS_TXN_CLIENT_DATE was passed to #svn_fs_begin_txn2 any 1193 * svn:date on the transaction will be become the unversioned property 1194 * svn:date on the revision. svn:date can have any value, it does not 1195 * have to be a timestamp. If the transaction has no svn:date the 1196 * revision will have no svn:date. 1197 * 1198 * If #SVN_FS_TXN_CLIENT_DATE was not passed to #svn_fs_begin_txn2 the 1199 * new revision will have svn:date set to the current time at some 1200 * point during the commit and any svn:date on the transaction will be 1201 * lost. 1202 * 1203 * If @a conflict_p is non-zero, use it to provide details on any 1204 * conflicts encountered merging @a txn with the most recent committed 1205 * revisions. If a conflict occurs, set @a *conflict_p to the path of 1206 * the conflict in @a txn, allocated within @a pool; 1207 * otherwise, set @a *conflict_p to NULL. 1208 * 1209 * If the commit succeeds, @a txn is invalid. 1210 * 1211 * If the commit fails for any reason, @a *new_rev is an invalid 1212 * revision number, an error other than #SVN_NO_ERROR is returned and 1213 * @a txn is still valid; you can make more operations to resolve the 1214 * conflict, or call svn_fs_abort_txn() to abort the transaction. 1215 * 1216 * @note Success or failure of the commit of @a txn is determined by 1217 * examining the value of @a *new_rev upon this function's return. If 1218 * the value is a valid revision number, the commit was successful, 1219 * even though a non-@c NULL function return value may indicate that 1220 * something else went wrong in post commit FS processing. 1221 * 1222 * @note See api-errata/1.8/fs001.txt for information on how this 1223 * function was documented in versions prior to 1.8. 1224 * 1225 * ### need to document this better. there are four combinations of 1226 * ### return values: 1227 * ### 1) err=NULL. conflict=NULL. new_rev is valid 1228 * ### 2) err=SVN_ERR_FS_CONFLICT. conflict is set. new_rev=SVN_INVALID_REVNUM 1229 * ### 3) err=!NULL. conflict=NULL. new_rev is valid 1230 * ### 4) err=!NULL. conflict=NULL. new_rev=SVN_INVALID_REVNUM 1231 * ### 1232 * ### some invariants: 1233 * ### *conflict_p will be non-NULL IFF SVN_ERR_FS_CONFLICT 1234 * ### if *conflict_p is set (and SVN_ERR_FS_CONFLICT), then new_rev 1235 * ### will always be SVN_INVALID_REVNUM 1236 * ### *conflict_p will always be initialized to NULL, or to a valid 1237 * ### conflict string 1238 * ### *new_rev will always be initialized to SVN_INVALID_REVNUM, or 1239 * ### to a valid, committed revision number 1240 * 1241 */ 1242svn_error_t * 1243svn_fs_commit_txn(const char **conflict_p, 1244 svn_revnum_t *new_rev, 1245 svn_fs_txn_t *txn, 1246 apr_pool_t *pool); 1247 1248 1249/** Abort the transaction @a txn. Any changes made in @a txn are 1250 * discarded, and the filesystem is left unchanged. Use @a pool for 1251 * any necessary allocations. 1252 * 1253 * @note This function first sets the state of @a txn to "dead", and 1254 * then attempts to purge it and any related data from the filesystem. 1255 * If some part of the cleanup process fails, @a txn and some portion 1256 * of its data may remain in the database after this function returns. 1257 * Use svn_fs_purge_txn() to retry the transaction cleanup. 1258 */ 1259svn_error_t * 1260svn_fs_abort_txn(svn_fs_txn_t *txn, 1261 apr_pool_t *pool); 1262 1263 1264/** Cleanup the dead transaction in @a fs whose ID is @a txn_id. Use 1265 * @a pool for all allocations. If the transaction is not yet dead, 1266 * the error #SVN_ERR_FS_TRANSACTION_NOT_DEAD is returned. (The 1267 * caller probably forgot to abort the transaction, or the cleanup 1268 * step of that abort failed for some reason.) 1269 */ 1270svn_error_t * 1271svn_fs_purge_txn(svn_fs_t *fs, 1272 const char *txn_id, 1273 apr_pool_t *pool); 1274 1275 1276/** Set @a *name_p to the name of the transaction @a txn, as a 1277 * NULL-terminated string. Allocate the name in @a pool. 1278 */ 1279svn_error_t * 1280svn_fs_txn_name(const char **name_p, 1281 svn_fs_txn_t *txn, 1282 apr_pool_t *pool); 1283 1284/** Return @a txn's base revision. */ 1285svn_revnum_t 1286svn_fs_txn_base_revision(svn_fs_txn_t *txn); 1287 1288 1289 1290/** Open the transaction named @a name in the filesystem @a fs. Set @a *txn 1291 * to the transaction. 1292 * 1293 * If there is no such transaction, #SVN_ERR_FS_NO_SUCH_TRANSACTION is 1294 * the error returned. 1295 * 1296 * Allocate the new transaction in @a pool; when @a pool is freed, the new 1297 * transaction will be closed (neither committed nor aborted). 1298 */ 1299svn_error_t * 1300svn_fs_open_txn(svn_fs_txn_t **txn, 1301 svn_fs_t *fs, 1302 const char *name, 1303 apr_pool_t *pool); 1304 1305 1306/** Set @a *names_p to an array of <tt>const char *</tt> ids which are the 1307 * names of all the currently active transactions in the filesystem @a fs. 1308 * Allocate the array in @a pool. 1309 */ 1310svn_error_t * 1311svn_fs_list_transactions(apr_array_header_t **names_p, 1312 svn_fs_t *fs, 1313 apr_pool_t *pool); 1314 1315/* Transaction properties */ 1316 1317/** Set @a *value_p to the value of the property named @a propname on 1318 * transaction @a txn. If @a txn has no property by that name, set 1319 * @a *value_p to zero. Allocate the result in @a pool. 1320 */ 1321svn_error_t * 1322svn_fs_txn_prop(svn_string_t **value_p, 1323 svn_fs_txn_t *txn, 1324 const char *propname, 1325 apr_pool_t *pool); 1326 1327 1328/** Set @a *table_p to the entire property list of transaction @a txn, as 1329 * an APR hash table allocated in @a pool. The resulting table maps property 1330 * names to pointers to #svn_string_t objects containing the property value. 1331 */ 1332svn_error_t * 1333svn_fs_txn_proplist(apr_hash_t **table_p, 1334 svn_fs_txn_t *txn, 1335 apr_pool_t *pool); 1336 1337 1338/** Change a transactions @a txn's property's value, or add/delete a 1339 * property. @a name is the name of the property to change, and @a value 1340 * is the new value of the property, or zero if the property should be 1341 * removed altogether. Do any necessary temporary allocation in @a pool. 1342 */ 1343svn_error_t * 1344svn_fs_change_txn_prop(svn_fs_txn_t *txn, 1345 const char *name, 1346 const svn_string_t *value, 1347 apr_pool_t *pool); 1348 1349 1350/** Change, add, and/or delete transaction property values in 1351 * transaction @a txn. @a props is an array of <tt>svn_prop_t</tt> 1352 * elements. This is equivalent to calling svn_fs_change_txn_prop() 1353 * multiple times with the @c name and @c value fields of each 1354 * successive <tt>svn_prop_t</tt>, but may be more efficient. 1355 * (Properties not mentioned are left alone.) Do any necessary 1356 * temporary allocation in @a pool. 1357 * 1358 * @since New in 1.5. 1359 */ 1360svn_error_t * 1361svn_fs_change_txn_props(svn_fs_txn_t *txn, 1362 const apr_array_header_t *props, 1363 apr_pool_t *pool); 1364 1365/** @} */ 1366 1367 1368/** Roots. 1369 * 1370 * An #svn_fs_root_t object represents the root directory of some 1371 * revision or transaction in a filesystem. To refer to particular 1372 * node or node revision, you provide a root, and a directory path 1373 * relative to that root. 1374 * 1375 * @defgroup svn_fs_roots Filesystem roots 1376 * @{ 1377 */ 1378 1379/** The Filesystem Root object. */ 1380typedef struct svn_fs_root_t svn_fs_root_t; 1381 1382 1383/** Set @a *root_p to the root directory of revision @a rev in filesystem @a fs. 1384 * Allocate @a *root_p in a private subpool of @a pool; the root can be 1385 * destroyed earlier than @a pool by calling #svn_fs_close_root. 1386 */ 1387svn_error_t * 1388svn_fs_revision_root(svn_fs_root_t **root_p, 1389 svn_fs_t *fs, 1390 svn_revnum_t rev, 1391 apr_pool_t *pool); 1392 1393 1394/** Set @a *root_p to the root directory of @a txn. Allocate @a *root_p in a 1395 * private subpool of @a pool; the root can be destroyed earlier than @a pool by 1396 * calling #svn_fs_close_root. 1397 */ 1398svn_error_t * 1399svn_fs_txn_root(svn_fs_root_t **root_p, 1400 svn_fs_txn_t *txn, 1401 apr_pool_t *pool); 1402 1403 1404/** Free the root directory @a root; this only needs to be used if you want to 1405 * free the memory associated with @a root earlier than the time you destroy 1406 * the pool passed to the function that created it (svn_fs_revision_root() or 1407 * svn_fs_txn_root()). 1408 */ 1409void 1410svn_fs_close_root(svn_fs_root_t *root); 1411 1412 1413/** Return the filesystem to which @a root belongs. */ 1414svn_fs_t * 1415svn_fs_root_fs(svn_fs_root_t *root); 1416 1417 1418/** Return @c TRUE iff @a root is a transaction root. */ 1419svn_boolean_t 1420svn_fs_is_txn_root(svn_fs_root_t *root); 1421 1422/** Return @c TRUE iff @a root is a revision root. */ 1423svn_boolean_t 1424svn_fs_is_revision_root(svn_fs_root_t *root); 1425 1426 1427/** If @a root is the root of a transaction, return the name of the 1428 * transaction, allocated in @a pool; otherwise, return NULL. 1429 */ 1430const char * 1431svn_fs_txn_root_name(svn_fs_root_t *root, 1432 apr_pool_t *pool); 1433 1434/** If @a root is the root of a transaction, return the number of the 1435 * revision on which is was based when created. Otherwise, return 1436 * #SVN_INVALID_REVNUM. 1437 * 1438 * @since New in 1.5. 1439 */ 1440svn_revnum_t 1441svn_fs_txn_root_base_revision(svn_fs_root_t *root); 1442 1443/** If @a root is the root of a revision, return the revision number. 1444 * Otherwise, return #SVN_INVALID_REVNUM. 1445 */ 1446svn_revnum_t 1447svn_fs_revision_root_revision(svn_fs_root_t *root); 1448 1449/** @} */ 1450 1451 1452/** Directory entry names and directory paths. 1453 * 1454 * Here are the rules for directory entry names, and directory paths: 1455 * 1456 * A directory entry name is a Unicode string encoded in UTF-8, and 1457 * may not contain the NULL character (U+0000). The name should be in 1458 * Unicode canonical decomposition and ordering. No directory entry 1459 * may be named '.', '..', or the empty string. Given a directory 1460 * entry name which fails to meet these requirements, a filesystem 1461 * function returns an #SVN_ERR_FS_PATH_SYNTAX error. 1462 * 1463 * A directory path is a sequence of zero or more directory entry 1464 * names, separated by slash characters (U+002f), and possibly ending 1465 * with slash characters. Sequences of two or more consecutive slash 1466 * characters are treated as if they were a single slash. If a path 1467 * ends with a slash, it refers to the same node it would without the 1468 * slash, but that node must be a directory, or else the function 1469 * may return an #SVN_ERR_FS_NOT_DIRECTORY error. 1470 * 1471 * A path consisting of the empty string, or a string containing only 1472 * slashes, refers to the root directory. 1473 * 1474 * @defgroup svn_fs_directories Filesystem directories 1475 * @{ 1476 */ 1477 1478 1479 1480/** The kind of change that occurred on the path. */ 1481typedef enum svn_fs_path_change_kind_t 1482{ 1483 /** path modified in txn */ 1484 svn_fs_path_change_modify = 0, 1485 1486 /** path added in txn */ 1487 svn_fs_path_change_add, 1488 1489 /** path removed in txn */ 1490 svn_fs_path_change_delete, 1491 1492 /** path removed and re-added in txn */ 1493 svn_fs_path_change_replace, 1494 1495 /** ignore all previous change items for path (internal-use only) */ 1496 svn_fs_path_change_reset 1497} svn_fs_path_change_kind_t; 1498 1499/** Change descriptor. 1500 * 1501 * @note Fields may be added to the end of this structure in future 1502 * versions. Therefore, to preserve binary compatibility, users 1503 * should not directly allocate structures of this type. 1504 * 1505 * @note The @c text_mod, @c prop_mod and @c mergeinfo_mod flags mean the 1506 * text, properties and mergeinfo property (respectively) were "touched" 1507 * by the commit API; this does not mean the new value is different from 1508 * the old value. 1509 * 1510 * @since New in 1.10. */ 1511typedef struct svn_fs_path_change3_t 1512{ 1513 /** path of the node that got changed. */ 1514 svn_string_t path; 1515 1516 /** kind of change */ 1517 svn_fs_path_change_kind_t change_kind; 1518 1519 /** what node kind is the path? 1520 (Note: it is legal for this to be #svn_node_unknown.) */ 1521 svn_node_kind_t node_kind; 1522 1523 /** was the text touched? 1524 * For node_kind=dir: always false. For node_kind=file: 1525 * modify: true iff text touched. 1526 * add (copy): true iff text touched. 1527 * add (plain): always true. 1528 * delete: always false. 1529 * replace: as for the add/copy part of the replacement. 1530 */ 1531 svn_boolean_t text_mod; 1532 1533 /** were the properties touched? 1534 * modify: true iff props touched. 1535 * add (copy): true iff props touched. 1536 * add (plain): true iff props touched. 1537 * delete: always false. 1538 * replace: as for the add/copy part of the replacement. 1539 */ 1540 svn_boolean_t prop_mod; 1541 1542 /** was the mergeinfo property touched? 1543 * modify: } true iff svn:mergeinfo property add/del/mod 1544 * add (copy): } and fs format supports this flag. 1545 * add (plain): } 1546 * delete: always false. 1547 * replace: as for the add/copy part of the replacement. 1548 * (Note: Pre-1.9 repositories will report #svn_tristate_unknown.) 1549 */ 1550 svn_tristate_t mergeinfo_mod; 1551 1552 /** Copyfrom revision and path; this is only valid if copyfrom_known 1553 * is true. */ 1554 svn_boolean_t copyfrom_known; 1555 svn_revnum_t copyfrom_rev; 1556 const char *copyfrom_path; 1557 1558 /* NOTE! Please update svn_fs_path_change3_create() when adding new 1559 fields here. */ 1560} svn_fs_path_change3_t; 1561 1562 1563/** Similar to #svn_fs_path_change3_t, but with @a node_rev_id and without 1564 * path information. 1565 * 1566 * @note Fields may be added to the end of this structure in future 1567 * versions. Therefore, to preserve binary compatibility, users 1568 * should not directly allocate structures of this type. 1569 * 1570 * @note The @c text_mod, @c prop_mod and @c mergeinfo_mod flags mean the 1571 * text, properties and mergeinfo property (respectively) were "touched" 1572 * by the commit API; this does not mean the new value is different from 1573 * the old value. 1574 * 1575 * @since New in 1.6. 1576 * 1577 * @deprecated Provided for backwards compatibility with the 1.9 API. 1578 */ 1579typedef struct svn_fs_path_change2_t 1580{ 1581 /** node revision id of changed path */ 1582 const svn_fs_id_t *node_rev_id; 1583 1584 /** kind of change */ 1585 svn_fs_path_change_kind_t change_kind; 1586 1587 /** was the text touched? 1588 * For node_kind=dir: always false. For node_kind=file: 1589 * modify: true iff text touched. 1590 * add (copy): true iff text touched. 1591 * add (plain): always true. 1592 * delete: always false. 1593 * replace: as for the add/copy part of the replacement. 1594 */ 1595 svn_boolean_t text_mod; 1596 1597 /** were the properties touched? 1598 * modify: true iff props touched. 1599 * add (copy): true iff props touched. 1600 * add (plain): true iff props touched. 1601 * delete: always false. 1602 * replace: as for the add/copy part of the replacement. 1603 */ 1604 svn_boolean_t prop_mod; 1605 1606 /** what node kind is the path? 1607 (Note: it is legal for this to be #svn_node_unknown.) */ 1608 svn_node_kind_t node_kind; 1609 1610 /** Copyfrom revision and path; this is only valid if copyfrom_known 1611 * is true. */ 1612 svn_boolean_t copyfrom_known; 1613 svn_revnum_t copyfrom_rev; 1614 const char *copyfrom_path; 1615 1616 /** was the mergeinfo property touched? 1617 * modify: } true iff svn:mergeinfo property add/del/mod 1618 * add (copy): } and fs format supports this flag. 1619 * add (plain): } 1620 * delete: always false. 1621 * replace: as for the add/copy part of the replacement. 1622 * (Note: Pre-1.9 repositories will report #svn_tristate_unknown.) 1623 * @since New in 1.9. */ 1624 svn_tristate_t mergeinfo_mod; 1625 /* NOTE! Please update svn_fs_path_change2_create() when adding new 1626 fields here. */ 1627} svn_fs_path_change2_t; 1628 1629 1630/** Similar to #svn_fs_path_change2_t, but without kind and copyfrom 1631 * information. 1632 * 1633 * @deprecated Provided for backwards compatibility with the 1.5 API. 1634 */ 1635 1636typedef struct svn_fs_path_change_t 1637{ 1638 /** node revision id of changed path */ 1639 const svn_fs_id_t *node_rev_id; 1640 1641 /** kind of change */ 1642 svn_fs_path_change_kind_t change_kind; 1643 1644 /** were there text mods? */ 1645 svn_boolean_t text_mod; 1646 1647 /** were there property mods? */ 1648 svn_boolean_t prop_mod; 1649 1650} svn_fs_path_change_t; 1651 1652/** 1653 * Allocate an #svn_fs_path_change2_t structure in @a pool, initialize and 1654 * return it. 1655 * 1656 * Set the @c node_rev_id field of the created struct to @a node_rev_id, and 1657 * @c change_kind to @a change_kind. Set all other fields to their 1658 * @c _unknown, @c NULL or invalid value, respectively. 1659 * 1660 * @since New in 1.6. 1661 */ 1662svn_fs_path_change2_t * 1663svn_fs_path_change2_create(const svn_fs_id_t *node_rev_id, 1664 svn_fs_path_change_kind_t change_kind, 1665 apr_pool_t *pool); 1666 1667/** 1668 * Allocate an #svn_fs_path_change3_t structure in @a result_pool, 1669 * initialize and return it. 1670 * 1671 * Set the @c change_kind field to @a change_kind. Set all other fields 1672 * to their @c _unknown, @c NULL or invalid value, respectively. 1673 * 1674 * @since New in 1.10. 1675 */ 1676svn_fs_path_change3_t * 1677svn_fs_path_change3_create(svn_fs_path_change_kind_t change_kind, 1678 apr_pool_t *result_pool); 1679 1680/** 1681 * Return a deep copy of @a *change, allocated in @a result_pool. 1682 * 1683 * @since New in 1.10. 1684 */ 1685svn_fs_path_change3_t * 1686svn_fs_path_change3_dup(svn_fs_path_change3_t *change, 1687 apr_pool_t *result_pool); 1688 1689/** 1690 * Opaque iterator object type for a changed paths list. 1691 * 1692 * @since New in 1.10. 1693 */ 1694typedef struct svn_fs_path_change_iterator_t svn_fs_path_change_iterator_t; 1695 1696/** 1697 * Set @a *change to the path change that @a iterator currently points to 1698 * and advance the @a iterator. If the change list has been exhausted, 1699 * @a change will be set to @c NULL. 1700 * 1701 * You may modify @a **change but its content becomes invalid as soon as 1702 * either @a iterator becomes invalid or you call this function again. 1703 * 1704 * @note The @c node_kind field in @a change may be #svn_node_unknown and 1705 * the @c copyfrom_known fields may be FALSE. 1706 * 1707 * @since New in 1.10. 1708 */ 1709svn_error_t * 1710svn_fs_path_change_get(svn_fs_path_change3_t **change, 1711 svn_fs_path_change_iterator_t *iterator); 1712 1713 1714/** Determine what has changed under a @a root. 1715 * 1716 * Set @a *iterator to an iterator object, allocated in @a result_pool, 1717 * which will give access to the full list of changed paths under @a root. 1718 * Each call to @a svn_fs_path_change_get will return a new unique path 1719 * change and has amortized O(1) runtime. The iteration order is undefined 1720 * and may change even for the same @a root. 1721 * 1722 * If @a root becomes invalid, @a *iterator becomes invalid, too. 1723 * 1724 * Use @a scratch_pool for temporary allocations. 1725 * 1726 * @note The @a *iterator may be a large object and bind limited system 1727 * resources such as file handles. Be sure to clear the owning 1728 * pool once you don't need that iterator anymore. 1729 * 1730 * @since New in 1.10. 1731 */ 1732svn_error_t * 1733svn_fs_paths_changed3(svn_fs_path_change_iterator_t **iterator, 1734 svn_fs_root_t *root, 1735 apr_pool_t *result_pool, 1736 apr_pool_t *scratch_pool); 1737 1738/** Same as svn_fs_paths_changed3() but returning all changes in a single, 1739 * large data structure and using a single pool for all allocations. 1740 * 1741 * Allocate and return a hash @a *changed_paths2_p containing descriptions 1742 * of the paths changed under @a root. The hash is keyed with 1743 * <tt>const char *</tt> paths, and has #svn_fs_path_change2_t * values. 1744 * 1745 * Use @a pool for all allocations, including the hash and its values. 1746 * 1747 * @note Retrieving the #svn_fs_path_change2_t.node_rev_id element may 1748 * be expensive in some FS backends. 1749 * 1750 * @since New in 1.6. 1751 * 1752 * @deprecated Provided for backward compatibility with the 1.9 API. 1753 */ 1754SVN_DEPRECATED 1755svn_error_t * 1756svn_fs_paths_changed2(apr_hash_t **changed_paths2_p, 1757 svn_fs_root_t *root, 1758 apr_pool_t *pool); 1759 1760 1761/** Same as svn_fs_paths_changed2(), only with #svn_fs_path_change_t * values 1762 * in the hash (and thus no kind or copyfrom data). 1763 * 1764 * @deprecated Provided for backward compatibility with the 1.5 API. 1765 */ 1766SVN_DEPRECATED 1767svn_error_t * 1768svn_fs_paths_changed(apr_hash_t **changed_paths_p, 1769 svn_fs_root_t *root, 1770 apr_pool_t *pool); 1771 1772/** @} */ 1773 1774 1775/* Operations appropriate to all kinds of nodes. */ 1776 1777/** Set @a *kind_p to the type of node present at @a path under @a 1778 * root. If @a path does not exist under @a root, set @a *kind_p to 1779 * #svn_node_none. Use @a pool for temporary allocation. 1780 */ 1781svn_error_t * 1782svn_fs_check_path(svn_node_kind_t *kind_p, 1783 svn_fs_root_t *root, 1784 const char *path, 1785 apr_pool_t *pool); 1786 1787 1788/** An opaque node history object. */ 1789typedef struct svn_fs_history_t svn_fs_history_t; 1790 1791 1792/** Set @a *history_p to an opaque node history object which 1793 * represents @a path under @a root. @a root must be a revision root. 1794 * Allocate the result in @a result_pool and use @a scratch_pool for 1795 * temporary allocations. 1796 * 1797 * @since New in 1.9. 1798 */ 1799svn_error_t * 1800svn_fs_node_history2(svn_fs_history_t **history_p, 1801 svn_fs_root_t *root, 1802 const char *path, 1803 apr_pool_t *result_pool, 1804 apr_pool_t *scratch_pool); 1805 1806/** Same as svn_fs_node_history2() but using a single @a pool for all 1807 * allocations. 1808 * 1809 * @deprecated Provided for backward compatibility with the 1.8 API. 1810 */ 1811SVN_DEPRECATED 1812svn_error_t * 1813svn_fs_node_history(svn_fs_history_t **history_p, 1814 svn_fs_root_t *root, 1815 const char *path, 1816 apr_pool_t *pool); 1817 1818 1819/** Set @a *prev_history_p to an opaque node history object which 1820 * represents the previous (or "next oldest") interesting history 1821 * location for the filesystem node represented by @a history, or @c 1822 * NULL if no such previous history exists. If @a cross_copies is @c 1823 * FALSE, also return @c NULL if stepping backwards in history to @a 1824 * *prev_history_p would cross a filesystem copy operation. 1825 * 1826 * @note If this is the first call to svn_fs_history_prev() for the @a 1827 * history object, it could return a history object whose location is 1828 * the same as the original. This will happen if the original 1829 * location was an interesting one (where the node was modified, or 1830 * took place in a copy event). This behavior allows looping callers 1831 * to avoid calling svn_fs_history_location() on the object returned 1832 * by svn_fs_node_history(), and instead go ahead and begin calling 1833 * svn_fs_history_prev(). 1834 * 1835 * @note This function uses node-id ancestry alone to determine 1836 * modifiedness, and therefore does NOT claim that in any of the 1837 * returned revisions file contents changed, properties changed, 1838 * directory entries lists changed, etc. 1839 * 1840 * @note The revisions returned for @a path will be older than or 1841 * the same age as the revision of that path in @a root. That is, if 1842 * @a root is a revision root based on revision X, and @a path was 1843 * modified in some revision(s) younger than X, those revisions 1844 * younger than X will not be included for @a path. 1845 * 1846 * Allocate the result in @a result_pool and use @a scratch_pool for 1847 * temporary allocations. 1848 * 1849 * @since New in 1.9. */ 1850svn_error_t * 1851svn_fs_history_prev2(svn_fs_history_t **prev_history_p, 1852 svn_fs_history_t *history, 1853 svn_boolean_t cross_copies, 1854 apr_pool_t *result_pool, 1855 apr_pool_t *scratch_pool); 1856 1857/** Same as svn_fs_history_prev2() but using a single @a pool for all 1858 * allocations. 1859 * 1860 * @deprecated Provided for backward compatibility with the 1.8 API. 1861 */ 1862SVN_DEPRECATED 1863svn_error_t * 1864svn_fs_history_prev(svn_fs_history_t **prev_history_p, 1865 svn_fs_history_t *history, 1866 svn_boolean_t cross_copies, 1867 apr_pool_t *pool); 1868 1869 1870/** Set @a *path and @a *revision to the path and revision, 1871 * respectively, of the @a history object. Use @a pool for all 1872 * allocations. 1873 */ 1874svn_error_t * 1875svn_fs_history_location(const char **path, 1876 svn_revnum_t *revision, 1877 svn_fs_history_t *history, 1878 apr_pool_t *pool); 1879 1880 1881/** Set @a *is_dir to @c TRUE iff @a path in @a root is a directory. 1882 * Do any necessary temporary allocation in @a pool. 1883 */ 1884svn_error_t * 1885svn_fs_is_dir(svn_boolean_t *is_dir, 1886 svn_fs_root_t *root, 1887 const char *path, 1888 apr_pool_t *pool); 1889 1890 1891/** Set @a *is_file to @c TRUE iff @a path in @a root is a file. 1892 * Do any necessary temporary allocation in @a pool. 1893 */ 1894svn_error_t * 1895svn_fs_is_file(svn_boolean_t *is_file, 1896 svn_fs_root_t *root, 1897 const char *path, 1898 apr_pool_t *pool); 1899 1900 1901/** Get the id of a node. 1902 * 1903 * Set @a *id_p to the node revision ID of @a path in @a root, allocated in 1904 * @a pool. 1905 * 1906 * If @a root is the root of a transaction, keep in mind that other 1907 * changes to the transaction can change which node @a path refers to, 1908 * and even whether the path exists at all. 1909 */ 1910svn_error_t * 1911svn_fs_node_id(const svn_fs_id_t **id_p, 1912 svn_fs_root_t *root, 1913 const char *path, 1914 apr_pool_t *pool); 1915 1916/** Determine how @a path_a under @a root_a and @a path_b under @a root_b 1917 * are related and return the result in @a relation. There is no restriction 1918 * concerning the roots: They may refer to different repositories, be in 1919 * arbitrary revision order and any of them may pertain to a transaction. 1920 * @a scratch_pool is used for temporary allocations. 1921 * 1922 * @note Paths from different svn_fs_t will be reported as unrelated even 1923 * if the underlying physical repository is the same. 1924 * 1925 * @since New in 1.9. 1926 */ 1927svn_error_t * 1928svn_fs_node_relation(svn_fs_node_relation_t *relation, 1929 svn_fs_root_t *root_a, 1930 const char *path_a, 1931 svn_fs_root_t *root_b, 1932 const char *path_b, 1933 apr_pool_t *scratch_pool); 1934 1935/** Set @a *revision to the revision in which the node-revision identified 1936 * by @a path under @a root was created; that is, to the revision in which 1937 * @a path under @a root was last modified. @a *revision will 1938 * be set to #SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes 1939 * under a transaction root). Note that the root of an unmodified transaction 1940 * is not itself considered to be modified; in that case, return the revision 1941 * upon which the transaction was based. 1942 * 1943 * Use @a pool for any temporary allocations. 1944 */ 1945svn_error_t * 1946svn_fs_node_created_rev(svn_revnum_t *revision, 1947 svn_fs_root_t *root, 1948 const char *path, 1949 apr_pool_t *pool); 1950 1951/** Set @a *revision to the revision in which the line of history 1952 * represented by @a path under @a root originated. Use @a pool for 1953 * any temporary allocations. If @a root is a transaction root, @a 1954 * *revision will be set to #SVN_INVALID_REVNUM for any nodes newly 1955 * added in that transaction (brand new files or directories created 1956 * using #svn_fs_make_dir or #svn_fs_make_file). 1957 * 1958 * @since New in 1.5. 1959 */ 1960svn_error_t * 1961svn_fs_node_origin_rev(svn_revnum_t *revision, 1962 svn_fs_root_t *root, 1963 const char *path, 1964 apr_pool_t *pool); 1965 1966/** Set @a *created_path to the path at which @a path under @a root was 1967 * created. Use @a pool for all allocations. Callers may use this 1968 * function in conjunction with svn_fs_node_created_rev() to perform a 1969 * reverse lookup of the mapping of (path, revision) -> node-id that 1970 * svn_fs_node_id() performs. 1971 */ 1972svn_error_t * 1973svn_fs_node_created_path(const char **created_path, 1974 svn_fs_root_t *root, 1975 const char *path, 1976 apr_pool_t *pool); 1977 1978 1979/** Set @a *value_p to the value of the property named @a propname of 1980 * @a path in @a root. If the node has no property by that name, set 1981 * @a *value_p to zero. Allocate the result in @a pool. 1982 */ 1983svn_error_t * 1984svn_fs_node_prop(svn_string_t **value_p, 1985 svn_fs_root_t *root, 1986 const char *path, 1987 const char *propname, 1988 apr_pool_t *pool); 1989 1990 1991/** Set @a *table_p to the entire property list of @a path in @a root, 1992 * as an APR hash table allocated in @a pool. The resulting table maps 1993 * property names to pointers to #svn_string_t objects containing the 1994 * property value. 1995 */ 1996svn_error_t * 1997svn_fs_node_proplist(apr_hash_t **table_p, 1998 svn_fs_root_t *root, 1999 const char *path, 2000 apr_pool_t *pool); 2001 2002/** Set @a *has_props to TRUE if the node @a path in @a root has properties 2003 * and to FALSE if it doesn't have properties. Perform temporary allocations 2004 * in @a scratch_pool. 2005 * 2006 * @since New in 1.9. 2007 */ 2008svn_error_t * 2009svn_fs_node_has_props(svn_boolean_t *has_props, 2010 svn_fs_root_t *root, 2011 const char *path, 2012 apr_pool_t *scratch_pool); 2013 2014 2015/** Change a node's property's value, or add/delete a property. 2016 * 2017 * - @a root and @a path indicate the node whose property should change. 2018 * @a root must be the root of a transaction, not the root of a revision. 2019 * - @a name is the name of the property to change. 2020 * - @a value is the new value of the property, or zero if the property should 2021 * be removed altogether. 2022 * Do any necessary temporary allocation in @a pool. 2023 */ 2024svn_error_t * 2025svn_fs_change_node_prop(svn_fs_root_t *root, 2026 const char *path, 2027 const char *name, 2028 const svn_string_t *value, 2029 apr_pool_t *pool); 2030 2031 2032/** Determine if the properties of two path/root combinations are different. 2033 * 2034 * Set @a *different_p to #TRUE if the properties at @a path1 under @a root1 2035 * differ from those at @a path2 under @a root2, or set it to #FALSE if they 2036 * are the same. Both paths must exist under their respective roots, and 2037 * both roots must be in the same filesystem. 2038 * Do any necessary temporary allocation in @a scratch_pool. 2039 * 2040 * @note For the purposes of preserving accurate history, certain bits of 2041 * code (such as the repository dump code) need to care about the distinction 2042 * between situations when the properties are "different" and "have changed 2043 * across two points in history". We have a pair of functions that can 2044 * answer both of these questions, svn_fs_props_different() and 2045 * svn_fs_props_changed(). See issue 4598 for more details. 2046 * 2047 * @see svn_fs_props_changed 2048 * 2049 * @since New in 1.9. 2050 */ 2051svn_error_t * 2052svn_fs_props_different(svn_boolean_t *different_p, 2053 svn_fs_root_t *root1, 2054 const char *path1, 2055 svn_fs_root_t *root2, 2056 const char *path2, 2057 apr_pool_t *scratch_pool); 2058 2059 2060/** Determine if the properties of two path/root combinations have changed. 2061 * 2062 * Set @a *changed_p to #TRUE if the properties at @a path1 under @a root1 2063 * differ from those at @a path2 under @a root2, or set it to #FALSE if they 2064 * are the same. Both paths must exist under their respective roots, and 2065 * both roots must be in the same filesystem. 2066 * Do any necessary temporary allocation in @a pool. 2067 * 2068 * @note For the purposes of preserving accurate history, certain bits of 2069 * code (such as the repository dump code) need to care about the distinction 2070 * between situations when the properties are "different" and "have changed 2071 * across two points in history". We have a pair of functions that can 2072 * answer both of these questions, svn_fs_props_different() and 2073 * svn_fs_props_changed(). See issue 4598 for more details. 2074 * 2075 * @note This function can currently return false negatives for FSFS: 2076 * If @a root1 and @a root2 were both transaction roots and the proplists 2077 * of both paths had been changed in their respective transactions, 2078 * @a changed_p would be set to #FALSE. 2079 * 2080 * @see svn_fs_props_different 2081 */ 2082svn_error_t * 2083svn_fs_props_changed(svn_boolean_t *changed_p, 2084 svn_fs_root_t *root1, 2085 const char *path1, 2086 svn_fs_root_t *root2, 2087 const char *path2, 2088 apr_pool_t *pool); 2089 2090 2091/** Discover a node's copy ancestry, if any. 2092 * 2093 * If the node at @a path in @a root was copied from some other node, set 2094 * @a *rev_p and @a *path_p to the revision and path (expressed as an 2095 * absolute filesystem path) of the other node, allocating @a *path_p 2096 * in @a pool. 2097 * 2098 * Else if there is no copy ancestry for the node, set @a *rev_p to 2099 * #SVN_INVALID_REVNUM and @a *path_p to NULL. 2100 * 2101 * If an error is returned, the values of @a *rev_p and @a *path_p are 2102 * undefined, but otherwise, if one of them is set as described above, 2103 * you may assume the other is set correspondingly. 2104 * 2105 * @a root may be a revision root or a transaction root. 2106 * 2107 * Notes: 2108 * - Copy ancestry does not descend. After copying directory D to 2109 * E, E will have copy ancestry referring to D, but E's children 2110 * may not. See also svn_fs_copy(). 2111 * 2112 * - Copy ancestry *under* a copy is preserved. That is, if you 2113 * copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then 2114 * /G/pi2 will still have copy ancestry pointing to /A/D/G/pi. 2115 * We don't know if this is a feature or a bug yet; if it turns 2116 * out to be a bug, then the fix is to make svn_fs_copied_from() 2117 * observe the following logic, which currently callers may 2118 * choose to follow themselves: if node X has copy history, but 2119 * its ancestor A also has copy history, then you may ignore X's 2120 * history if X's revision-of-origin is earlier than A's -- 2121 * because that would mean that X's copy history was preserved in 2122 * a copy-under-a-copy scenario. If X's revision-of-origin is 2123 * the same as A's, then it was copied under A during the same 2124 * transaction that created A. (X's revision-of-origin cannot be 2125 * greater than A's, if X has copy history.) @todo See how 2126 * people like this, it can always be hidden behind the curtain 2127 * if necessary. 2128 * 2129 * - Copy ancestry is not stored as a regular subversion property 2130 * because it is not inherited. Copying foo to bar results in a 2131 * revision of bar with copy ancestry; but committing a text 2132 * change to bar right after that results in a new revision of 2133 * bar without copy ancestry. 2134 */ 2135svn_error_t * 2136svn_fs_copied_from(svn_revnum_t *rev_p, 2137 const char **path_p, 2138 svn_fs_root_t *root, 2139 const char *path, 2140 apr_pool_t *pool); 2141 2142 2143/** Set @a *root_p and @a *path_p to the revision root and path of the 2144 * destination of the most recent copy event that caused @a path to 2145 * exist where it does in @a root, or to NULL if no such copy exists. 2146 * 2147 * @a *path_p might be a parent of @a path, rather than @a path 2148 * itself. However, it will always be the deepest relevant path. 2149 * That is, if a copy occurs underneath another copy in the same txn, 2150 * this function makes sure to set @a *path_p to the longest copy 2151 * destination path that is still a parent of or equal to @a path. 2152 * 2153 * Values returned in @a *root_p and @a *path_p will be allocated 2154 * from @a pool. 2155 * 2156 * @since New in 1.3. 2157 */ 2158svn_error_t * 2159svn_fs_closest_copy(svn_fs_root_t **root_p, 2160 const char **path_p, 2161 svn_fs_root_t *root, 2162 const char *path, 2163 apr_pool_t *pool); 2164 2165/** Receives parsed @a mergeinfo for the file system path @a path. 2166 * 2167 * The user-provided @a baton is being passed through by the retrieval 2168 * function and @a scratch_pool will be cleared between invocations. 2169 * 2170 * @since New in 1.10. 2171 */ 2172typedef svn_error_t * 2173(*svn_fs_mergeinfo_receiver_t)(const char *path, 2174 svn_mergeinfo_t mergeinfo, 2175 void *baton, 2176 apr_pool_t *scratch_pool); 2177 2178/** Retrieve mergeinfo for multiple nodes. 2179 * 2180 * For each node found with mergeinfo on it, invoke @a receiver with 2181 * the provided @a baton. 2182 * 2183 * @a root is revision root to use when looking up paths. 2184 * 2185 * @a paths are the paths you are requesting information for. 2186 * 2187 * @a inherit indicates whether to retrieve explicit, 2188 * explicit-or-inherited, or only inherited mergeinfo. 2189 * 2190 * If @a adjust_inherited_mergeinfo is @c TRUE, then any inherited 2191 * mergeinfo reported to @a *receiver is normalized to represent the 2192 * inherited mergeinfo on the path which inherits it. This adjusted 2193 * mergeinfo is keyed by the path which inherits it. If 2194 * @a adjust_inherited_mergeinfo is @c FALSE, then any inherited 2195 * mergeinfo is the raw explicit mergeinfo from the nearest parent 2196 * of the path with explicit mergeinfo, unadjusted for the path-wise 2197 * difference between the path and its parent. This may include 2198 * non-inheritable mergeinfo. This unadjusted mergeinfo is keyed by 2199 * the path at which it was found. 2200 * 2201 * If @a include_descendants is TRUE, then additionally return the 2202 * mergeinfo for any descendant of any element of @a paths which has 2203 * the #SVN_PROP_MERGEINFO property explicitly set on it. (Note 2204 * that inheritance is only taken into account for the elements in @a 2205 * paths; descendants of the elements in @a paths which get their 2206 * mergeinfo via inheritance are not reported to @a receiver.) 2207 * 2208 * Do any necessary temporary allocations in @a scratch_pool. 2209 * 2210 * @since New in 1.10. 2211 */ 2212svn_error_t * 2213svn_fs_get_mergeinfo3(svn_fs_root_t *root, 2214 const apr_array_header_t *paths, 2215 svn_mergeinfo_inheritance_t inherit, 2216 svn_boolean_t include_descendants, 2217 svn_boolean_t adjust_inherited_mergeinfo, 2218 svn_fs_mergeinfo_receiver_t receiver, 2219 void *baton, 2220 apr_pool_t *scratch_pool); 2221 2222/** 2223 * Same as svn_fs_get_mergeinfo3(), but all mergeinfo is being collected 2224 * and returned in @a *catalog. It will never be @c NULL, but may be empty. 2225 * 2226 * @since New in 1.8. 2227 * 2228 * @deprecated Provided for backward compatibility with the 1.9 API. 2229 */ 2230SVN_DEPRECATED 2231svn_error_t * 2232svn_fs_get_mergeinfo2(svn_mergeinfo_catalog_t *catalog, 2233 svn_fs_root_t *root, 2234 const apr_array_header_t *paths, 2235 svn_mergeinfo_inheritance_t inherit, 2236 svn_boolean_t include_descendants, 2237 svn_boolean_t adjust_inherited_mergeinfo, 2238 apr_pool_t *result_pool, 2239 apr_pool_t *scratch_pool); 2240 2241/** 2242 * Same as svn_fs_get_mergeinfo2(), but with @a adjust_inherited_mergeinfo 2243 * set always set to @c TRUE and with only one pool. 2244 * 2245 * @deprecated Provided for backward compatibility with the 1.5 API. 2246 */ 2247SVN_DEPRECATED 2248svn_error_t * 2249svn_fs_get_mergeinfo(svn_mergeinfo_catalog_t *catalog, 2250 svn_fs_root_t *root, 2251 const apr_array_header_t *paths, 2252 svn_mergeinfo_inheritance_t inherit, 2253 svn_boolean_t include_descendants, 2254 apr_pool_t *pool); 2255 2256/** Merge changes between two nodes into a third node. 2257 * 2258 * Given nodes @a source and @a target, and a common ancestor @a ancestor, 2259 * modify @a target to contain all the changes made between @a ancestor and 2260 * @a source, as well as the changes made between @a ancestor and @a target. 2261 * @a target_root must be the root of a transaction, not a revision. 2262 * 2263 * @a source, @a target, and @a ancestor are generally directories; this 2264 * function recursively merges the directories' contents. If they are 2265 * files, this function simply returns an error whenever @a source, 2266 * @a target, and @a ancestor are all distinct node revisions. 2267 * 2268 * If there are differences between @a ancestor and @a source that conflict 2269 * with changes between @a ancestor and @a target, this function returns an 2270 * #SVN_ERR_FS_CONFLICT error. 2271 * 2272 * If the merge is successful, @a target is left in the merged state, and 2273 * the base root of @a target's txn is set to the root node of @a source. 2274 * If an error is returned (whether for conflict or otherwise), @a target 2275 * is left unaffected. 2276 * 2277 * If @a conflict_p is non-NULL, then: a conflict error sets @a *conflict_p 2278 * to the name of the node in @a target which couldn't be merged, 2279 * otherwise, success sets @a *conflict_p to NULL. 2280 * 2281 * Do any necessary temporary allocation in @a pool. 2282 */ 2283svn_error_t * 2284svn_fs_merge(const char **conflict_p, 2285 svn_fs_root_t *source_root, 2286 const char *source_path, 2287 svn_fs_root_t *target_root, 2288 const char *target_path, 2289 svn_fs_root_t *ancestor_root, 2290 const char *ancestor_path, 2291 apr_pool_t *pool); 2292 2293 2294 2295/* Directories. */ 2296 2297 2298/** The type of a Subversion directory entry. */ 2299typedef struct svn_fs_dirent_t 2300{ 2301 2302 /** The name of this directory entry. */ 2303 const char *name; 2304 2305 /** The node revision ID it names. */ 2306 const svn_fs_id_t *id; 2307 2308 /** The node kind. */ 2309 svn_node_kind_t kind; 2310 2311} svn_fs_dirent_t; 2312 2313 2314/** Set @a *entries_p to a newly allocated APR hash table containing the 2315 * entries of the directory at @a path in @a root. The keys of the table 2316 * are entry names, as byte strings, excluding the final NULL 2317 * character; the table's values are pointers to #svn_fs_dirent_t 2318 * structures. Allocate the table and its contents in @a pool. 2319 */ 2320svn_error_t * 2321svn_fs_dir_entries(apr_hash_t **entries_p, 2322 svn_fs_root_t *root, 2323 const char *path, 2324 apr_pool_t *pool); 2325 2326/** Take the #svn_fs_dirent_t structures in @a entries as returned by 2327 * #svn_fs_dir_entries for @a root and determine an optimized ordering 2328 * in which data access would most likely be efficient. Set @a *ordered_p 2329 * to a newly allocated APR array of pointers to these #svn_fs_dirent_t 2330 * structures. Allocate the array (but not its contents) in @a result_pool 2331 * and use @a scratch_pool for temporaries. 2332 * 2333 * @since New in 1.9. 2334 */ 2335svn_error_t * 2336svn_fs_dir_optimal_order(apr_array_header_t **ordered_p, 2337 svn_fs_root_t *root, 2338 apr_hash_t *entries, 2339 apr_pool_t *result_pool, 2340 apr_pool_t *scratch_pool); 2341 2342/** Create a new directory named @a path in @a root. The new directory has 2343 * no entries, and no properties. @a root must be the root of a transaction, 2344 * not a revision. 2345 * 2346 * Do any necessary temporary allocation in @a pool. 2347 */ 2348svn_error_t * 2349svn_fs_make_dir(svn_fs_root_t *root, 2350 const char *path, 2351 apr_pool_t *pool); 2352 2353 2354/** Delete the node named @a path in @a root. If the node being deleted is 2355 * a directory, its contents will be deleted recursively. @a root must be 2356 * the root of a transaction, not of a revision. Use @a pool for 2357 * temporary allocation. 2358 * 2359 * If return #SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of @a path is 2360 * missing from its parent, that is, the final target of the deletion 2361 * is missing. 2362 * 2363 * Attempting to remove the root dir also results in an error, 2364 * #SVN_ERR_FS_ROOT_DIR, even if the dir is empty. 2365 */ 2366svn_error_t * 2367svn_fs_delete(svn_fs_root_t *root, 2368 const char *path, 2369 apr_pool_t *pool); 2370 2371 2372/** Create a copy of @a from_path in @a from_root named @a to_path in 2373 * @a to_root. If @a from_path in @a from_root is a directory, copy the 2374 * tree it refers to recursively. 2375 * 2376 * The copy will remember its source; use svn_fs_copied_from() to 2377 * access this information. 2378 * 2379 * @a to_root must be the root of a transaction; @a from_root must be the 2380 * root of a revision. (Requiring @a from_root to be the root of a 2381 * revision makes the implementation trivial: there is no detectable 2382 * difference (modulo node revision ID's) between copying @a from and 2383 * simply adding a reference to it. So the operation takes place in 2384 * constant time. However, there's no reason not to extend this to 2385 * mutable nodes --- it's just more code.) Further, @a to_root and @a 2386 * from_root must represent the same filesystem. 2387 * 2388 * @note To do a copy without preserving copy history, use 2389 * svn_fs_revision_link(). 2390 * 2391 * Do any necessary temporary allocation in @a pool. 2392 */ 2393svn_error_t * 2394svn_fs_copy(svn_fs_root_t *from_root, 2395 const char *from_path, 2396 svn_fs_root_t *to_root, 2397 const char *to_path, 2398 apr_pool_t *pool); 2399 2400 2401/** Like svn_fs_copy(), but doesn't record copy history, and preserves 2402 * the PATH. You cannot use svn_fs_copied_from() later to find out 2403 * where this copy came from. 2404 * 2405 * Use svn_fs_revision_link() in situations where you don't care 2406 * about the copy history, and where @a to_path and @a from_path are 2407 * the same, because it is cheaper than svn_fs_copy(). 2408 */ 2409svn_error_t * 2410svn_fs_revision_link(svn_fs_root_t *from_root, 2411 svn_fs_root_t *to_root, 2412 const char *path, 2413 apr_pool_t *pool); 2414 2415 2416/* Files. */ 2417 2418/** Set @a *length_p to the length of the file @a path in @a root, in bytes. 2419 * Do any necessary temporary allocation in @a pool. 2420 */ 2421svn_error_t * 2422svn_fs_file_length(svn_filesize_t *length_p, 2423 svn_fs_root_t *root, 2424 const char *path, 2425 apr_pool_t *pool); 2426 2427 2428/** Set @a *checksum to the checksum of type @a kind for the file @a path. 2429 * @a *checksum will be allocated out of @a pool, which will also be used 2430 * for temporary allocations. 2431 * 2432 * If the filesystem does not have a prerecorded checksum of @a kind for 2433 * @a path, and @a force is not TRUE, do not calculate a checksum 2434 * dynamically, just put NULL into @a checksum. (By convention, the NULL 2435 * checksum is considered to match any checksum.) 2436 * 2437 * Notes: 2438 * 2439 * You might wonder, why do we only provide this interface for file 2440 * contents, and not for properties or directories? 2441 * 2442 * The answer is that property lists and directory entry lists are 2443 * essentially data structures, not text. We serialize them for 2444 * transmission, but there is no guarantee that the consumer will 2445 * parse them into the same form, or even the same order, as the 2446 * producer. It's difficult to find a checksumming method that 2447 * reaches the same result given such variation in input. (I suppose 2448 * we could calculate an independent MD5 sum for each propname and 2449 * value, and XOR them together; same with directory entry names. 2450 * Maybe that's the solution?) Anyway, for now we punt. The most 2451 * important data, and the only data that goes through svndiff 2452 * processing, is file contents, so that's what we provide 2453 * checksumming for. 2454 * 2455 * Internally, of course, the filesystem checksums everything, because 2456 * it has access to the lowest level storage forms: strings behind 2457 * representations. 2458 * 2459 * @since New in 1.6. 2460 */ 2461svn_error_t * 2462svn_fs_file_checksum(svn_checksum_t **checksum, 2463 svn_checksum_kind_t kind, 2464 svn_fs_root_t *root, 2465 const char *path, 2466 svn_boolean_t force, 2467 apr_pool_t *pool); 2468 2469/** 2470 * Same as svn_fs_file_checksum(), only always put the MD5 checksum of file 2471 * @a path into @a digest, which should point to @c APR_MD5_DIGESTSIZE bytes 2472 * of storage. If the checksum doesn't exist, put all 0's into @a digest. 2473 * 2474 * @deprecated Provided for backward compatibility with the 1.5 API. 2475 */ 2476SVN_DEPRECATED 2477svn_error_t * 2478svn_fs_file_md5_checksum(unsigned char digest[], 2479 svn_fs_root_t *root, 2480 const char *path, 2481 apr_pool_t *pool); 2482 2483 2484/** Set @a *contents to a readable generic stream that will yield the 2485 * contents of the file @a path in @a root. Allocate the stream in 2486 * @a pool. You can only use @a *contents for as long as the underlying 2487 * filesystem is open. If @a path is not a file, return 2488 * #SVN_ERR_FS_NOT_FILE. 2489 * 2490 * If @a root is the root of a transaction, it is possible that the 2491 * contents of the file @a path will change between calls to 2492 * svn_fs_file_contents(). In that case, the result of reading from 2493 * @a *contents is undefined. 2494 * 2495 * @todo kff: I am worried about lifetime issues with this pool vs 2496 * the trail created farther down the call stack. Trace this function 2497 * to investigate... 2498 */ 2499svn_error_t * 2500svn_fs_file_contents(svn_stream_t **contents, 2501 svn_fs_root_t *root, 2502 const char *path, 2503 apr_pool_t *pool); 2504 2505/** 2506 * Callback function type used with svn_fs_try_process_file_contents() 2507 * that delivers the immutable, non-NULL @a contents of @a len bytes. 2508 * @a baton is an implementation-specific closure. 2509 * 2510 * Use @a scratch_pool for allocations. 2511 * 2512 * @since New in 1.8. 2513 */ 2514typedef svn_error_t * 2515(*svn_fs_process_contents_func_t)(const unsigned char *contents, 2516 apr_size_t len, 2517 void *baton, 2518 apr_pool_t *scratch_pool); 2519 2520/** Efficiently deliver the contents of the file @a path in @a root 2521 * via @a processor (with @a baton), setting @a *success to @c TRUE 2522 * upon doing so. Use @a pool for allocations. 2523 * 2524 * This function is intended to support zero copy data processing. It may 2525 * not be implemented for all data backends or not be applicable for certain 2526 * content. In those cases, @a *success will always be @c FALSE. Also, 2527 * this is a best-effort function which means that there is no guarantee 2528 * that @a processor gets called at all. 2529 * 2530 * @note @a processor is expected to be a relatively simple function with 2531 * a runtime of O(content size) or less. 2532 * 2533 * @since New in 1.8. 2534 */ 2535svn_error_t * 2536svn_fs_try_process_file_contents(svn_boolean_t *success, 2537 svn_fs_root_t *root, 2538 const char *path, 2539 svn_fs_process_contents_func_t processor, 2540 void* baton, 2541 apr_pool_t *pool); 2542 2543/** Create a new file named @a path in @a root. The file's initial contents 2544 * are the empty string, and it has no properties. @a root must be the 2545 * root of a transaction, not a revision. 2546 * 2547 * Do any necessary temporary allocation in @a pool. 2548 */ 2549svn_error_t * 2550svn_fs_make_file(svn_fs_root_t *root, 2551 const char *path, 2552 apr_pool_t *pool); 2553 2554 2555/** Apply a text delta to the file @a path in @a root. @a root must be the 2556 * root of a transaction, not a revision. 2557 * 2558 * Set @a *contents_p to a function ready to receive text delta windows 2559 * describing how to change the file's contents, relative to its 2560 * current contents. Set @a *contents_baton_p to a baton to pass to 2561 * @a *contents_p. 2562 * 2563 * If @a path does not exist in @a root, return an error. (You cannot use 2564 * this routine to create new files; use svn_fs_make_file() to create 2565 * an empty file first.) 2566 * 2567 * @a base_checksum is the hex MD5 digest for the base text against 2568 * which the delta is to be applied; it is ignored if NULL, and may be 2569 * ignored even if not NULL. If it is not ignored, it must match the 2570 * checksum of the base text against which svndiff data is being 2571 * applied; if not, svn_fs_apply_textdelta() or the @a *contents_p call 2572 * which detects the mismatch will return the error 2573 * #SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may 2574 * still be an error if @a base_checksum is neither NULL nor the 2575 * checksum of the empty string). 2576 * 2577 * @a result_checksum is the hex MD5 digest for the fulltext that 2578 * results from this delta application. It is ignored if NULL, but if 2579 * not NULL, it must match the checksum of the result; if it does not, 2580 * then the @a *contents_p call which detects the mismatch will return 2581 * the error #SVN_ERR_CHECKSUM_MISMATCH. 2582 * 2583 * The caller must send all delta windows including the terminating 2584 * NULL window to @a *contents_p before making further changes to the 2585 * transaction. 2586 * 2587 * Do temporary allocation in @a pool. 2588 */ 2589svn_error_t * 2590svn_fs_apply_textdelta(svn_txdelta_window_handler_t *contents_p, 2591 void **contents_baton_p, 2592 svn_fs_root_t *root, 2593 const char *path, 2594 const char *base_checksum, 2595 const char *result_checksum, 2596 apr_pool_t *pool); 2597 2598 2599/** Write data directly to the file @a path in @a root. @a root must be the 2600 * root of a transaction, not a revision. 2601 * 2602 * Set @a *contents_p to a stream ready to receive full textual data. 2603 * When the caller closes this stream, the data replaces the previous 2604 * contents of the file. The caller must write all file data and close 2605 * the stream before making further changes to the transaction. 2606 * 2607 * If @a path does not exist in @a root, return an error. (You cannot use 2608 * this routine to create new files; use svn_fs_make_file() to create 2609 * an empty file first.) 2610 * 2611 * @a result_checksum is the hex MD5 digest for the final fulltext 2612 * written to the stream. It is ignored if NULL, but if not null, it 2613 * must match the checksum of the result; if it does not, then the @a 2614 * *contents_p call which detects the mismatch will return the error 2615 * #SVN_ERR_CHECKSUM_MISMATCH. 2616 * 2617 * Do any necessary temporary allocation in @a pool. 2618 * 2619 * @note This is like svn_fs_apply_textdelta(), but takes the text 2620 * straight. 2621 */ 2622svn_error_t * 2623svn_fs_apply_text(svn_stream_t **contents_p, 2624 svn_fs_root_t *root, 2625 const char *path, 2626 const char *result_checksum, 2627 apr_pool_t *pool); 2628 2629 2630/** Check if the contents of two root/path combos are different. 2631 * 2632 * Set @a *different_p to #TRUE if the file contents at @a path1 under 2633 * @a root1 differ from those at @a path2 under @a root2, or set it to 2634 * #FALSE if they are the same. Both paths must exist under their 2635 * respective roots, and both roots must be in the same filesystem. 2636 * Do any necessary temporary allocation in @a scratch_pool. 2637 * 2638 * @note For the purposes of preserving accurate history, certain bits of 2639 * code (such as the repository dump code) need to care about the distinction 2640 * between situations when two files have "different" content and when the 2641 * contents of a given file "have changed" across two points in its history. 2642 * We have a pair of functions that can answer both of these questions, 2643 * svn_fs_contents_different() and svn_fs_contents_changed(). See issue 2644 * 4598 for more details. 2645 * 2646 * @see svn_fs_contents_changed 2647 * 2648 * @since New in 1.9. 2649 */ 2650svn_error_t * 2651svn_fs_contents_different(svn_boolean_t *different_p, 2652 svn_fs_root_t *root1, 2653 const char *path1, 2654 svn_fs_root_t *root2, 2655 const char *path2, 2656 apr_pool_t *scratch_pool); 2657 2658/** Check if the contents of two root/path combos have changed. 2659 * 2660 * Set @a *changed_p to #TRUE if the file contents at @a path1 under 2661 * @a root1 differ from those at @a path2 under @a root2, or set it to 2662 * #FALSE if they are the same. Both paths must exist under their 2663 * respective roots, and both roots must be in the same filesystem. 2664 * Do any necessary temporary allocation in @a pool. 2665 * 2666 * @note svn_fs_contents_changed() was not designed to be used to detect 2667 * when two files have different content, but really to detect when the 2668 * contents of a given file have changed across two points in its history. 2669 * For the purposes of preserving accurate history, certain bits of code 2670 * (such as the repository dump code) need to care about this distinction. 2671 * For example, it's not an error from the FS API point of view to call 2672 * svn_fs_apply_textdelta() and explicitly set a file's contents to exactly 2673 * what they were before the edit was made. We have a pair of functions 2674 * that can answer both of these questions, svn_fs_contents_changed() and 2675 * svn_fs_contents_different(). See issue 4598 for more details. 2676 * 2677 * @see svn_fs_contents_different 2678 */ 2679svn_error_t * 2680svn_fs_contents_changed(svn_boolean_t *changed_p, 2681 svn_fs_root_t *root1, 2682 const char *path1, 2683 svn_fs_root_t *root2, 2684 const char *path2, 2685 apr_pool_t *pool); 2686 2687 2688 2689/* Filesystem revisions. */ 2690 2691 2692/** Set @a *youngest_p to the number of the youngest revision in filesystem 2693 * @a fs. Use @a pool for all temporary allocation. 2694 * 2695 * The oldest revision in any filesystem is numbered zero. 2696 */ 2697svn_error_t * 2698svn_fs_youngest_rev(svn_revnum_t *youngest_p, 2699 svn_fs_t *fs, 2700 apr_pool_t *pool); 2701 2702 2703/** 2704 * Return filesystem format information for @a fs. 2705 * 2706 * Set @a *fs_format to the filesystem format number of @a fs, which is 2707 * an integer that increases when incompatible changes are made (such as 2708 * by #svn_fs_upgrade). 2709 * 2710 * Set @a *supports_version to the version number of the minimum Subversion GA 2711 * release that can read and write @a fs. 2712 * 2713 * @see svn_repos_info_format 2714 * 2715 * @since New in 1.9. 2716 */ 2717svn_error_t * 2718svn_fs_info_format(int *fs_format, 2719 svn_version_t **supports_version, 2720 svn_fs_t *fs, 2721 apr_pool_t *result_pool, 2722 apr_pool_t *scratch_pool); 2723 2724/** 2725 * Return a list of admin-serviceable config files for @a fs. @a *files 2726 * will be set to an array containing paths as C strings. 2727 * 2728 * @since New in 1.9. 2729 */ 2730svn_error_t * 2731svn_fs_info_config_files(apr_array_header_t **files, 2732 svn_fs_t *fs, 2733 apr_pool_t *result_pool, 2734 apr_pool_t *scratch_pool); 2735 2736 2737 2738/** Provide filesystem @a fs the opportunity to compress storage relating to 2739 * associated with @a revision in filesystem @a fs. Use @a pool for all 2740 * allocations. 2741 * 2742 * @note This can be a time-consuming process, depending the breadth 2743 * of the changes made in @a revision, and the depth of the history of 2744 * those changed paths. This may also be a no op. 2745 */ 2746svn_error_t * 2747svn_fs_deltify_revision(svn_fs_t *fs, 2748 svn_revnum_t revision, 2749 apr_pool_t *pool); 2750 2751/** Make sure that all completed revision property changes to the filesystem 2752 * underlying @a fs are actually visible through @a fs. Use @a scratch_pool 2753 * for temporary allocations. 2754 * 2755 * This is an explicit synchronization barrier for revprop changes made 2756 * through different #svn_fs_t for the same underlying filesystem. Any 2757 * revprop change through @a fs acts as an implicit barrier, i.e. that 2758 * object will see all completed revprop changes up to an including its own. 2759 * Only #svn_fs_revision_prop2 and #svn_fs_revision_proplist2 have an option 2760 * to not synchronize with on-disk data and potentially return outdated data 2761 * as old as the last barrier. 2762 * 2763 * The intended use of this is implementing efficient queries in upper layers 2764 * where the result only needs to include all changes up to the start of 2765 * that query but does not need to pick up on changes while the query is 2766 * running: 2767 * 2768 * @code 2769 SVN_ERR(svn_fs_deltify_revision(fs, pool); 2770 for (i = 0; i < n; i++) 2771 SVN_ERR(svn_fs_revision_prop2(&authors[i], fs, revs[i], "svn:author", 2772 FALSE, pool, pool)); @endcode 2773 * 2774 * @see svn_fs_revision_prop2, svn_fs_revision_proplist2 2775 * 2776 * @since New in 1.10. 2777 */ 2778svn_error_t * 2779svn_fs_refresh_revision_props(svn_fs_t *fs, 2780 apr_pool_t *scratch_pool); 2781 2782/** Set @a *value_p to the value of the property named @a propname on 2783 * revision @a rev in the filesystem @a fs. If @a rev has no property by 2784 * that name, set @a *value_p to zero. 2785 * 2786 * If @a refresh is set, this call acts as a read barrier and is guaranteed 2787 * to return the latest value. Otherwise, it may return data as old as the 2788 * last synchronization point but can be much faster to access - in 2789 * particular for packed repositories. 2790 * 2791 * Allocate the result in @a result_pool and use @a scratch_pool for 2792 * temporary allocations. 2793 * 2794 * @see svn_fs_refresh_revision_props 2795 * 2796 * @since New in 1.10. 2797 */ 2798svn_error_t * 2799svn_fs_revision_prop2(svn_string_t **value_p, 2800 svn_fs_t *fs, 2801 svn_revnum_t rev, 2802 const char *propname, 2803 svn_boolean_t refresh, 2804 apr_pool_t *result_pool, 2805 apr_pool_t *scratch_pool); 2806 2807/** Like #svn_fs_revision_prop2 but using @a pool for @a scratch_pool as 2808 * well as @a result_pool and setting @a refresh to #TRUE. 2809 * 2810 * @see svn_fs_refresh_revision_props 2811 * 2812 * @deprecated For backward compatibility with 1.9. 2813 */ 2814SVN_DEPRECATED 2815svn_error_t * 2816svn_fs_revision_prop(svn_string_t **value_p, 2817 svn_fs_t *fs, 2818 svn_revnum_t rev, 2819 const char *propname, 2820 apr_pool_t *pool); 2821 2822 2823/** Set @a *table_p to the entire property list of revision @a rev in 2824 * filesystem @a fs, as an APR hash table allocated in @a pool. The table 2825 * maps <tt>char *</tt> property names to #svn_string_t * values; the names 2826 * and values are allocated in @a result_pool. Use @a scratch_pool for 2827 * temporary allocations. 2828 * 2829 * If @a refresh is set, this call acts as a read barrier and is guaranteed 2830 * to return the latest value. Otherwise, it may return data as old as the 2831 * last synchronization point but can be much faster to access - in 2832 * particular for packed repositories. 2833 * 2834 * @see svn_fs_refresh_revision_props 2835 * 2836 * @since New in 1.10. 2837 * 2838 */ 2839svn_error_t * 2840svn_fs_revision_proplist2(apr_hash_t **table_p, 2841 svn_fs_t *fs, 2842 svn_revnum_t rev, 2843 svn_boolean_t refresh, 2844 apr_pool_t *result_pool, 2845 apr_pool_t *scratch_pool); 2846 2847/** Like svn_fs_revision_proplist2 but using @a pool for @a scratch_pool as 2848 * well as @a result_pool and setting @a refresh to #TRUE. 2849 * 2850 * @see svn_fs_refresh_revision_props 2851 * 2852 * @deprecated For backward compatibility with 1.9. 2853 */ 2854SVN_DEPRECATED 2855svn_error_t * 2856svn_fs_revision_proplist(apr_hash_t **table_p, 2857 svn_fs_t *fs, 2858 svn_revnum_t rev, 2859 apr_pool_t *pool); 2860 2861/** Change a revision's property's value, or add/delete a property. 2862 * 2863 * - @a fs is a filesystem, and @a rev is the revision in that filesystem 2864 * whose property should change. 2865 * - @a name is the name of the property to change. 2866 * - if @a old_value_p is not @c NULL, then changing the property will fail with 2867 * error #SVN_ERR_FS_PROP_BASEVALUE_MISMATCH if the present value of the 2868 * property is not @a *old_value_p. (This is an atomic test-and-set). 2869 * @a *old_value_p may be @c NULL, representing that the property must be not 2870 * already set. 2871 * - @a value is the new value of the property, or zero if the property should 2872 * be removed altogether. 2873 * 2874 * Note that revision properties are non-historied --- you can change 2875 * them after the revision has been committed. They are not protected 2876 * via transactions. 2877 * 2878 * Do any necessary temporary allocation in @a pool. 2879 * 2880 * @since New in 1.7. 2881 */ 2882svn_error_t * 2883svn_fs_change_rev_prop2(svn_fs_t *fs, 2884 svn_revnum_t rev, 2885 const char *name, 2886 const svn_string_t *const *old_value_p, 2887 const svn_string_t *value, 2888 apr_pool_t *pool); 2889 2890 2891/** 2892 * Similar to svn_fs_change_rev_prop2(), but with @a old_value_p passed as 2893 * @c NULL. 2894 * 2895 * @deprecated Provided for backward compatibility with the 1.6 API. 2896 */ 2897SVN_DEPRECATED 2898svn_error_t * 2899svn_fs_change_rev_prop(svn_fs_t *fs, 2900 svn_revnum_t rev, 2901 const char *name, 2902 const svn_string_t *value, 2903 apr_pool_t *pool); 2904 2905 2906 2907/* Computing deltas. */ 2908 2909 2910/** Set @a *stream_p to a pointer to a delta stream that will turn the 2911 * contents of the file @a source into the contents of the file @a target. 2912 * If @a source_root is zero, use a file with zero length as the source. 2913 * 2914 * This function does not compare the two files' properties. 2915 * 2916 * Allocate @a *stream_p, and do any necessary temporary allocation, in 2917 * @a pool. 2918 */ 2919svn_error_t * 2920svn_fs_get_file_delta_stream(svn_txdelta_stream_t **stream_p, 2921 svn_fs_root_t *source_root, 2922 const char *source_path, 2923 svn_fs_root_t *target_root, 2924 const char *target_path, 2925 apr_pool_t *pool); 2926 2927 2928 2929/* UUID manipulation. */ 2930 2931/** Populate @a *uuid with the UUID associated with @a fs. Allocate 2932 @a *uuid in @a pool. */ 2933svn_error_t * 2934svn_fs_get_uuid(svn_fs_t *fs, 2935 const char **uuid, 2936 apr_pool_t *pool); 2937 2938 2939/** If not @c NULL, associate @a *uuid with @a fs. Otherwise (if @a 2940 * uuid is @c NULL), generate a new UUID for @a fs. Use @a pool for 2941 * any scratch work. 2942 */ 2943svn_error_t * 2944svn_fs_set_uuid(svn_fs_t *fs, 2945 const char *uuid, 2946 apr_pool_t *pool); 2947 2948 2949/** @defgroup svn_fs_locks Filesystem locks 2950 * @{ 2951 * @since New in 1.2. */ 2952 2953/** A lock represents one user's exclusive right to modify a path in a 2954 * filesystem. In order to create or destroy a lock, a username must 2955 * be associated with the filesystem's access context (see 2956 * #svn_fs_access_t). 2957 * 2958 * When a lock is created, a 'lock-token' is returned. The lock-token 2959 * is a unique URI that represents the lock (treated as an opaque 2960 * string by the client), and is required to make further use of the 2961 * lock (including removal of the lock.) A lock-token can also be 2962 * queried to return a svn_lock_t structure that describes the details 2963 * of the lock. lock-tokens must not contain any newline character, 2964 * mainly due to the serialization for tokens for pre-commit hook. 2965 * 2966 * Locks are not secret; anyone can view existing locks in a 2967 * filesystem. Locks are not omnipotent: they can be broken and stolen 2968 * by people who don't "own" the lock. (Though admins can tailor a 2969 * custom break/steal policy via libsvn_repos pre-lock hook script.) 2970 * 2971 * Locks can be created with an optional expiration date. If a lock 2972 * has an expiration date, then the act of fetching/reading it might 2973 * cause it to automatically expire, returning either nothing or an 2974 * expiration error (depending on the API). 2975 */ 2976 2977/** Lock information for use with svn_fs_lock_many() [and svn_repos_fs_...]. 2978 * 2979 * @see svn_fs_lock_target_create 2980 * 2981 * @since New in 1.9. 2982 */ 2983typedef struct svn_fs_lock_target_t svn_fs_lock_target_t; 2984 2985/** Create an <tt>svn_fs_lock_target_t</tt> allocated in @a result_pool. 2986 * @a token can be NULL and @a current_rev can be SVN_INVALID_REVNUM. 2987 * 2988 * The @a token is not duplicated and so must have a lifetime at least as 2989 * long as the returned target object. 2990 * 2991 * @since New in 1.9. 2992 */ 2993svn_fs_lock_target_t *svn_fs_lock_target_create(const char *token, 2994 svn_revnum_t current_rev, 2995 apr_pool_t *result_pool); 2996 2997/** Update @a target changing the token to @a token, @a token can be NULL. 2998 * 2999 * The @a token is not duplicated and so must have a lifetime at least as 3000 * long as @a target. 3001 * 3002 * @since New in 1.9. 3003 */ 3004void svn_fs_lock_target_set_token(svn_fs_lock_target_t *target, 3005 const char *token); 3006 3007/** The callback invoked by svn_fs_lock_many() and svn_fs_unlock_many(). 3008 * 3009 * @a path and @a lock are allocated in the result_pool passed to 3010 * svn_fs_lock_many/svn_fs_unlock_many and so will persist beyond the 3011 * callback invocation. @a fs_err will be cleared after the callback 3012 * returns, use svn_error_dup() to preserve the error. 3013 * 3014 * If the callback returns an error no further callbacks will be made 3015 * and svn_fs_lock_many/svn_fs_unlock_many will return an error. The 3016 * caller cannot rely on any particular order for these callbacks and 3017 * cannot rely on interrupting the underlying operation by returning 3018 * an error. Returning an error stops the callbacks but any locks 3019 * that would have been reported in further callbacks may, or may not, 3020 * still be created/released. 3021 * 3022 * @since New in 1.9. 3023 */ 3024typedef svn_error_t *(*svn_fs_lock_callback_t)(void *baton, 3025 const char *path, 3026 const svn_lock_t *lock, 3027 svn_error_t *fs_err, 3028 apr_pool_t *scratch_pool); 3029 3030/** Lock the paths in @a lock_targets in @a fs. 3031 * 3032 * @a fs must have a username associated with it (see 3033 * #svn_fs_access_t), else return #SVN_ERR_FS_NO_USER. Set the 3034 * 'owner' field in each new lock to the fs username. 3035 * 3036 * @a comment is optional: it's either an xml-escapable UTF8 string 3037 * which describes the lock, or it is @c NULL. 3038 * 3039 * @a is_dav_comment describes whether the comment was created by a 3040 * generic DAV client; only mod_dav_svn's autoversioning feature needs 3041 * to use it. If in doubt, pass 0. 3042 * 3043 * The paths to be locked are passed as the <tt>const char *</tt> keys 3044 * of the @a lock_targets hash. The hash values are 3045 * <tt>svn_fs_lock_target_t *</tt> and provide the token and 3046 * @a current_rev for each path. The token is a lock token such as can 3047 * be generated using svn_fs_generate_lock_token() (indicating that 3048 * the caller wants to dictate the lock token used), or it is @c NULL 3049 * (indicating that the caller wishes to have a new token generated by 3050 * this function). If the token is not @c NULL, and represents an 3051 * existing lock, then the path must match the path associated with 3052 * that existing lock. If @a current_rev is a valid revnum, then do an 3053 * out-of-dateness check. If the revnum is less than the 3054 * last-changed-revision of the path (or if the path doesn't exist in 3055 * HEAD), yield an #SVN_ERR_FS_OUT_OF_DATE error for this path. 3056 * 3057 * If a path is already locked, then yield #SVN_ERR_FS_PATH_ALREADY_LOCKED, 3058 * unless @a steal_lock is TRUE, in which case "steal" the existing 3059 * lock, even if the FS access-context's username does not match the 3060 * current lock's owner: delete the existing lock on the path, and 3061 * create a new one. 3062 * 3063 * If @a expiration_date is zero, then create a non-expiring lock. 3064 * Else, the lock will expire at @a expiration_date. 3065 * 3066 * For each path in @a lock_targets @a lock_callback will be invoked 3067 * passing @a lock_baton and the lock and error that apply to path. 3068 * @a lock_callback can be NULL in which case it is not called and any 3069 * errors that would have been passed to the callback are not reported. 3070 * 3071 * The lock and path passed to @a lock_callback will be allocated in 3072 * @a result_pool. Use @a scratch_pool for temporary allocations. 3073 * 3074 * @note At this time, only files can be locked. 3075 * 3076 * @note This function is not atomic. If it returns an error, some targets 3077 * may remain unlocked while others may have been locked. 3078 * 3079 * @note You probably don't want to use this directly. Take a look at 3080 * svn_repos_fs_lock_many() instead. 3081 * 3082 * @since New in 1.9. 3083 */ 3084svn_error_t * 3085svn_fs_lock_many(svn_fs_t *fs, 3086 apr_hash_t *lock_targets, 3087 const char *comment, 3088 svn_boolean_t is_dav_comment, 3089 apr_time_t expiration_date, 3090 svn_boolean_t steal_lock, 3091 svn_fs_lock_callback_t lock_callback, 3092 void *lock_baton, 3093 apr_pool_t *result_pool, 3094 apr_pool_t *scratch_pool); 3095 3096/** Similar to svn_fs_lock_many() but locks only a single @a path and 3097 * returns the lock in @a *lock, allocated in @a pool, or an error. 3098 * 3099 * @since New in 1.2. 3100 */ 3101svn_error_t * 3102svn_fs_lock(svn_lock_t **lock, 3103 svn_fs_t *fs, 3104 const char *path, 3105 const char *token, 3106 const char *comment, 3107 svn_boolean_t is_dav_comment, 3108 apr_time_t expiration_date, 3109 svn_revnum_t current_rev, 3110 svn_boolean_t steal_lock, 3111 apr_pool_t *pool); 3112 3113 3114/** Generate a unique lock-token using @a fs. Return in @a *token, 3115 * allocated in @a pool. 3116 * 3117 * This can be used in to populate lock->token before calling 3118 * svn_fs_attach_lock(). 3119 */ 3120svn_error_t * 3121svn_fs_generate_lock_token(const char **token, 3122 svn_fs_t *fs, 3123 apr_pool_t *pool); 3124 3125 3126/** Remove the locks on the paths in @a unlock_targets in @a fs. 3127 * 3128 * The paths to be unlocked are passed as <tt>const char *</tt> keys 3129 * of the @a unlock_targets hash with the corresponding lock tokens as 3130 * <tt>const char *</tt> values. If the token doesn't point to a 3131 * lock, yield an #SVN_ERR_FS_BAD_LOCK_TOKEN error for this path. If 3132 * the token points to an expired lock, yield an 3133 * #SVN_ERR_FS_LOCK_EXPIRED error for this path. If @a fs has no 3134 * username associated with it, yield an #SVN_ERR_FS_NO_USER unless @a 3135 * break_lock is specified. 3136 * 3137 * If the token points to a lock, but the username of @a fs's access 3138 * context doesn't match the lock's owner, yield an 3139 * #SVN_ERR_FS_LOCK_OWNER_MISMATCH. If @a break_lock is TRUE, 3140 * however, don't return error; allow the lock to be "broken" in any 3141 * case. In the latter case, the token shall be @c NULL. 3142 * 3143 * For each path in @a unlock_targets @a lock_callback will be invoked 3144 * passing @a lock_baton and error that apply to path. The @a lock 3145 * passed to the callback will be NULL. @a lock_callback can be NULL 3146 * in which case it is not called and any errors that would have been 3147 * passed to the callback are not reported. 3148 * 3149 * The path passed to lock_callback will be allocated in @a result_pool. 3150 * Use @a scratch_pool for temporary allocations. 3151 * 3152 * @note This function is not atomic. If it returns an error, some targets 3153 * may remain locked while others may have been unlocked. 3154 * 3155 * @note You probably don't want to use this directly. Take a look at 3156 * svn_repos_fs_unlock_many() instead. 3157 * 3158 * @since New in 1.9. 3159 */ 3160svn_error_t * 3161svn_fs_unlock_many(svn_fs_t *fs, 3162 apr_hash_t *unlock_targets, 3163 svn_boolean_t break_lock, 3164 svn_fs_lock_callback_t lock_callback, 3165 void *lock_baton, 3166 apr_pool_t *result_pool, 3167 apr_pool_t *scratch_pool); 3168 3169/** Similar to svn_fs_unlock_many() but only unlocks a single path. 3170 * 3171 * @since New in 1.2. 3172 */ 3173svn_error_t * 3174svn_fs_unlock(svn_fs_t *fs, 3175 const char *path, 3176 const char *token, 3177 svn_boolean_t break_lock, 3178 apr_pool_t *pool); 3179 3180 3181/** If @a path is locked in @a fs, set @a *lock to an svn_lock_t which 3182 * represents the lock, allocated in @a pool. 3183 * 3184 * If @a path is not locked or does not exist in HEAD, set @a *lock to NULL. 3185 */ 3186svn_error_t * 3187svn_fs_get_lock(svn_lock_t **lock, 3188 svn_fs_t *fs, 3189 const char *path, 3190 apr_pool_t *pool); 3191 3192 3193/** The type of a lock discovery callback function. @a baton is the 3194 * value specified in the call to svn_fs_get_locks(); the filesystem 3195 * passes it through to the callback. @a lock is a lock structure. 3196 * @a pool is a temporary subpool for use by the callback 3197 * implementation -- it is cleared after invocation of the callback. 3198 */ 3199typedef svn_error_t *(*svn_fs_get_locks_callback_t)(void *baton, 3200 svn_lock_t *lock, 3201 apr_pool_t *pool); 3202 3203 3204/** Report locks on or below @a path in @a fs using the @a 3205 * get_locks_func / @a get_locks_baton. Use @a pool for necessary 3206 * allocations. 3207 * 3208 * @a depth limits the reported locks to those associated with paths 3209 * within the specified depth of @a path, and must be one of the 3210 * following values: #svn_depth_empty, #svn_depth_files, 3211 * #svn_depth_immediates, or #svn_depth_infinity. 3212 * 3213 * If the @a get_locks_func callback implementation returns an error, 3214 * lock iteration will terminate and that error will be returned by 3215 * this function. 3216 * 3217 * @note Over the course of this function's invocation, locks might be 3218 * added, removed, or modified by concurrent processes. Callers need 3219 * to anticipate and gracefully handle the transience of this 3220 * information. 3221 * 3222 * @since New in 1.7. 3223 */ 3224svn_error_t * 3225svn_fs_get_locks2(svn_fs_t *fs, 3226 const char *path, 3227 svn_depth_t depth, 3228 svn_fs_get_locks_callback_t get_locks_func, 3229 void *get_locks_baton, 3230 apr_pool_t *pool); 3231 3232/** Similar to svn_fs_get_locks2(), but with @a depth always passed as 3233 * svn_depth_infinity, and with the following known problem (which is 3234 * not present in svn_fs_get_locks2()): 3235 * 3236 * @note On Berkeley-DB-backed filesystems in Subversion 1.6 and 3237 * prior, the @a get_locks_func callback will be invoked from within a 3238 * Berkeley-DB transaction trail. Implementors of the callback are, 3239 * as a result, forbidden from calling any svn_fs API functions which 3240 * might themselves attempt to start a new Berkeley DB transaction 3241 * (which is most of this svn_fs API). Yes, this is a nasty 3242 * implementation detail to have to be aware of. 3243 * 3244 * @deprecated Provided for backward compatibility with the 1.6 API. 3245 */ 3246SVN_DEPRECATED 3247svn_error_t * 3248svn_fs_get_locks(svn_fs_t *fs, 3249 const char *path, 3250 svn_fs_get_locks_callback_t get_locks_func, 3251 void *get_locks_baton, 3252 apr_pool_t *pool); 3253 3254/** @} */ 3255 3256/** 3257 * Append a textual list of all available FS modules to the stringbuf 3258 * @a output. Third-party modules are only included if repository 3259 * access has caused them to be loaded. 3260 * 3261 * @since New in 1.2. 3262 */ 3263svn_error_t * 3264svn_fs_print_modules(svn_stringbuf_t *output, 3265 apr_pool_t *pool); 3266 3267 3268/** The kind of action being taken by 'pack'. */ 3269typedef enum svn_fs_pack_notify_action_t 3270{ 3271 /** packing of the shard has commenced */ 3272 svn_fs_pack_notify_start = 0, 3273 3274 /** packing of the shard is completed */ 3275 svn_fs_pack_notify_end, 3276 3277 /** packing of the shard revprops has commenced 3278 @since New in 1.7. */ 3279 svn_fs_pack_notify_start_revprop, 3280 3281 /** packing of the shard revprops has completed 3282 @since New in 1.7. */ 3283 svn_fs_pack_notify_end_revprop, 3284 3285 /** pack has been a no-op for this repository. The next / future packable 3286 shard will be given. If the shard is -1, then the repository does not 3287 support packing at all. 3288 @since New in 1.10. */ 3289 svn_fs_pack_notify_noop 3290 3291} svn_fs_pack_notify_action_t; 3292 3293/** The type of a pack notification function. @a shard is the shard being 3294 * acted upon; @a action is the type of action being performed. @a baton is 3295 * the corresponding baton for the notification function, and @a pool can 3296 * be used for temporary allocations, but will be cleared between invocations. 3297 */ 3298typedef svn_error_t *(*svn_fs_pack_notify_t)(void *baton, 3299 apr_int64_t shard, 3300 svn_fs_pack_notify_action_t action, 3301 apr_pool_t *pool); 3302 3303/** 3304 * Possibly update the filesystem located in the directory @a path 3305 * to use disk space more efficiently. 3306 * 3307 * @since New in 1.6. 3308 */ 3309svn_error_t * 3310svn_fs_pack(const char *db_path, 3311 svn_fs_pack_notify_t notify_func, 3312 void *notify_baton, 3313 svn_cancel_func_t cancel_func, 3314 void *cancel_baton, 3315 apr_pool_t *pool); 3316 3317 3318/** 3319 * Perform backend-specific data consistency and correctness validations 3320 * to the Subversion filesystem (mainly the meta-data) located in the 3321 * directory @a path. Use the backend-specific configuration @a fs_config 3322 * when opening the filesystem. @a NULL is valid for all backends. 3323 * Use @a scratch_pool for temporary allocations. 3324 * 3325 * @a start and @a end define the (minimum) range of revisions to check. 3326 * If @a start is #SVN_INVALID_REVNUM, it defaults to @c r0. Likewise, 3327 * @a end will default to the current youngest repository revision when 3328 * given as #SVN_INVALID_REVNUM. Since meta data checks may have to touch 3329 * other revisions as well, you may receive notifications for revisions 3330 * outside the specified range. In fact, it is perfectly legal for a FS 3331 * implementation to always check all revisions. 3332 * 3333 * Global invariants are only guaranteed to get verified when @a r0 has 3334 * been included in the range of revisions to check. 3335 * 3336 * The optional @a notify_func callback is only a general feedback that 3337 * the operation is still in process but may be called in random revisions 3338 * order and more than once for the same revision, i.e. r2, r1, r2 would 3339 * be a valid sequence. 3340 * 3341 * The optional @a cancel_func callback will be invoked as usual to allow 3342 * the user to preempt this potentially lengthy operation. 3343 * 3344 * @note You probably don't want to use this directly. Take a look at 3345 * svn_repos_verify_fs2() instead, which does non-backend-specific 3346 * verifications as well. 3347 * 3348 * @note To ensure a full verification using all tests and covering all 3349 * revisions, you must call this function *and* #svn_fs_verify_root. 3350 * 3351 * @note Implementors, please do tests that can be done efficiently for 3352 * a single revision in #svn_fs_verify_root. This function is meant for 3353 * global checks or tests that require an expensive context setup. 3354 * 3355 * @see svn_repos_verify_fs2() 3356 * @see svn_fs_verify_root() 3357 * 3358 * @since New in 1.8. 3359 */ 3360svn_error_t * 3361svn_fs_verify(const char *path, 3362 apr_hash_t *fs_config, 3363 svn_revnum_t start, 3364 svn_revnum_t end, 3365 svn_fs_progress_notify_func_t notify_func, 3366 void *notify_baton, 3367 svn_cancel_func_t cancel_func, 3368 void *cancel_baton, 3369 apr_pool_t *scratch_pool); 3370 3371/** 3372 * Perform backend-specific data consistency and correctness validations 3373 * of @a root in the Subversion filesystem @a fs. @a root is typically 3374 * a revision root (see svn_fs_revision_root()), but may be a 3375 * transaction root. Use @a scratch_pool for temporary allocations. 3376 * 3377 * @note You probably don't want to use this directly. Take a look at 3378 * svn_repos_verify_fs2() instead, which does non-backend-specific 3379 * verifications as well. 3380 * 3381 * @note To ensure a full verification using all available tests and 3382 * covering all revisions, you must call both this function and 3383 * #svn_fs_verify. 3384 * 3385 * @note Implementors, please perform tests that cannot be done 3386 * efficiently for a single revision in #svn_fs_verify. This function 3387 * is intended for local checks that don't require an expensive context 3388 * setup. 3389 * 3390 * @see svn_repos_verify_fs2() 3391 * @see svn_fs_verify() 3392 * 3393 * @since New in 1.8. 3394 */ 3395svn_error_t * 3396svn_fs_verify_root(svn_fs_root_t *root, 3397 apr_pool_t *scratch_pool); 3398 3399/** @} */ 3400 3401/** 3402 * @defgroup fs_info Filesystem information subsystem 3403 * @{ 3404 */ 3405 3406/** 3407 * A structure that provides some information about a filesystem. 3408 * Returned by svn_fs_info() for #SVN_FS_TYPE_FSFS filesystems. 3409 * 3410 * @note Fields may be added to the end of this structure in future 3411 * versions. Therefore, users shouldn't allocate structures of this 3412 * type, to preserve binary compatibility. 3413 * 3414 * @since New in 1.9. 3415 */ 3416typedef struct svn_fs_fsfs_info_t { 3417 3418 /** Filesystem backend (#fs_type), i.e., the string #SVN_FS_TYPE_FSFS. */ 3419 const char *fs_type; 3420 3421 /** Shard size, or 0 if the filesystem is not currently sharded. */ 3422 int shard_size; 3423 3424 /** The smallest revision (as #svn_revnum_t) which is not in a pack file. 3425 * @note Zero (0) if (but not iff) the format does not support packing. */ 3426 svn_revnum_t min_unpacked_rev; 3427 3428 /** TRUE if logical addressing is enabled for this repository. 3429 * FALSE if repository uses physical addressing. */ 3430 svn_boolean_t log_addressing; 3431 /* ### TODO: information about fsfs.conf? rep-cache.db? write locks? */ 3432 3433 /* If you add fields here, check whether you need to extend svn_fs_info() 3434 or svn_fs_info_dup(). */ 3435} svn_fs_fsfs_info_t; 3436 3437/** 3438 * A structure that provides some information about a filesystem. 3439 * Returned by svn_fs_info() for #SVN_FS_TYPE_FSX filesystems. 3440 * 3441 * @note Fields may be added to the end of this structure in future 3442 * versions. Therefore, users shouldn't allocate structures of this 3443 * type, to preserve binary compatibility. 3444 * 3445 * @since New in 1.9. 3446 */ 3447typedef struct svn_fs_fsx_info_t { 3448 3449 /** Filesystem backend (#fs_type), i.e., the string #SVN_FS_TYPE_FSX. */ 3450 const char *fs_type; 3451 3452 /** Shard size, always > 0. */ 3453 int shard_size; 3454 3455 /** The smallest revision which is not in a pack file. */ 3456 svn_revnum_t min_unpacked_rev; 3457 3458 /* If you add fields here, check whether you need to extend svn_fs_info() 3459 or svn_fs_info_dup(). */ 3460 3461} svn_fs_fsx_info_t; 3462 3463/** @see svn_fs_info 3464 * @since New in 1.9. */ 3465typedef struct svn_fs_info_placeholder_t { 3466 /** @see svn_fs_type */ 3467 const char *fs_type; 3468 3469 /* Do not add new fields here, to maintain compatibility with the first 3470 released version of svn_fs_fsfs_info_t. */ 3471} svn_fs_info_placeholder_t; 3472 3473/** 3474 * Set @a *fs_info to a struct describing @a fs. The type of the 3475 * struct depends on the backend: for #SVN_FS_TYPE_FSFS, the struct will be 3476 * of type #svn_fs_fsfs_info_t; for #SVN_FS_TYPE_FSX, it will be of type 3477 * #svn_fs_fsx_info_t; otherwise, the struct is guaranteed to be 3478 * (compatible with) #svn_fs_info_placeholder_t. 3479 * 3480 * @see #svn_fs_fsfs_info_t, #svn_fs_fsx_info_t 3481 * 3482 * @since New in 1.9. 3483 */ 3484svn_error_t * 3485svn_fs_info(const svn_fs_info_placeholder_t **fs_info, 3486 svn_fs_t *fs, 3487 apr_pool_t *result_pool, 3488 apr_pool_t *scratch_pool); 3489 3490/** 3491 * Return a duplicate of @a info, allocated in @a result_pool. The returned 3492 * struct will be of the same type as the passed-in struct, which itself 3493 * must have been returned from svn_fs_info() or svn_fs_info_dup(). No part 3494 * of the new structure will be shared with @a info (except static string 3495 * constants). Use @a scratch_pool for temporary allocations. 3496 * 3497 * @see #svn_fs_info_placeholder_t, #svn_fs_fsfs_info_t 3498 * 3499 * @since New in 1.9. 3500 */ 3501void * 3502svn_fs_info_dup(const void *info, 3503 apr_pool_t *result_pool, 3504 apr_pool_t *scratch_pool); 3505 3506/** 3507 * A structure specifying the filesystem-specific input/output operation. 3508 * 3509 * @see svn_fs_ioctl() 3510 * 3511 * @since New in 1.13. 3512 */ 3513typedef struct svn_fs_ioctl_code_t 3514{ 3515 const char *fs_type; 3516 int code; 3517} svn_fs_ioctl_code_t; 3518 3519/** 3520 * A convenience macro to declare #svn_fs_ioctl_code_t codes. 3521 * 3522 * @since New in 1.13. 3523 */ 3524#define SVN_FS_DECLARE_IOCTL_CODE(name, fs_type, code) \ 3525 static const svn_fs_ioctl_code_t name = { fs_type, code } 3526 3527/** 3528 * Issue a filesystem-specific input/output operation defined by @a ctlcode 3529 * (usually, a low-level operation which cannot be expressed by other 3530 * filesystem APIs). If @a fs is @c NULL, issue a global operation. 3531 * If @a fs is not @c NULL, issue an operation that is specific to this 3532 * filesystem instance. 3533 * 3534 * If the filesystem cannot handle this ioctl code, return the 3535 * #SVN_ERR_FS_UNRECOGNIZED_IOCTL_CODE error. 3536 * 3537 * Allocate the result in @a result_pool, use @a scratch_pool for temporary 3538 * allocations. 3539 * 3540 * @see #svn_fs_ioctl_code_t 3541 * 3542 * @since New in 1.13. 3543 */ 3544svn_error_t * 3545svn_fs_ioctl(svn_fs_t *fs, 3546 svn_fs_ioctl_code_t ctlcode, 3547 void *input, 3548 void **output_p, 3549 svn_cancel_func_t cancel_func, 3550 void *cancel_baton, 3551 apr_pool_t *result_pool, 3552 apr_pool_t *scratch_pool); 3553 3554/** @} */ 3555 3556#ifdef __cplusplus 3557} 3558#endif /* __cplusplus */ 3559 3560#endif /* SVN_FS_H */ 3561