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