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