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
12 * http://www.apache.org/licenses/LICENSE-2.0
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
20 * ====================================================================
23 * @file svn_dirent_uri.h
24 * @brief A library to manipulate URIs, relative paths and directory entries.
26 * This library makes a clear distinction between several path formats:
28 * - a dirent is a path on (local) disc or a UNC path (Windows) in
29 * either relative or absolute format.
31 * "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only), ""
35 * - a uri, for our purposes, is a percent-encoded, absolute path
36 * (URI) that starts with a schema definition. In practice, these
37 * tend to look like URLs, but never carry query strings.
39 * "http://server", "file:///path/to/repos",
40 * "svn+ssh://user@host:123/My%20Stuff/file.doc"
42 * "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc", ""
44 * - a relative path (relpath) is an unrooted path that can be joined
45 * to any other relative path, uri or dirent. A relative path is
46 * never rooted/prefixed by a '/'.
48 * "file", "dir/file", "dir/subdir/../file", ""
50 * "/file", "http://server/file"
52 * This distinction is needed because on Windows we have to handle some
53 * dirents and URIs differently. Since it's not possible to determine from
54 * the path string if it's a dirent or a URI, it's up to the API user to
55 * make this choice. See also issue #2028.
57 * All incoming and outgoing paths are non-NULL unless otherwise documented.
59 * All of these functions expect paths passed into them to be in canonical
62 * - @c svn_dirent_canonicalize()
63 * - @c svn_dirent_canonicalize_safe()
64 * - @c svn_dirent_is_canonical()
65 * - @c svn_dirent_internal_style()
66 * - @c svn_relpath_canonicalize()
67 * - @c svn_relpath_canonicalize_safe()
68 * - @c svn_relpath_is_canonical()
69 * - @c svn_uri_canonicalize()
70 * - @c svn_uri_canonicalize_safe()
71 * - @c svn_uri_is_canonical()
73 * The Subversion codebase also recognizes some other classes of path:
75 * - A Subversion filesystem path (fspath) -- otherwise known as a
76 * path within a repository -- is a path relative to the root of
77 * the repository filesystem, that starts with a slash ("/"). The
78 * rules for a fspath are the same as for a relpath except for the
79 * leading '/'. A fspath never ends with '/' except when the whole
80 * path is just '/'. The fspath API is private (see
81 * private/svn_fspath.h).
83 * - A URL path (urlpath) is just the path part of a URL (the part
84 * that follows the schema, username, hostname, and port). These
85 * are also like relpaths, except that they have a leading slash
86 * (like fspaths) and are URI-encoded. The urlpath API is also
87 * private (see private/svn_fspath.h)
89 * "/svn/repos/trunk/README",
90 * "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"
92 * So, which path API is appropriate for your use-case?
94 * - If your path refers to a local file, directory, symlink, etc. of
95 * the sort that you can examine and operate on with other software
96 * on your computer, it's a dirent.
98 * - If your path is a full URL -- with a schema, hostname (maybe),
99 * and path portion -- it's a uri.
101 * - If your path is relative, and is somewhat ambiguous unless it's
102 * joined to some other more explicit (possible absolute) base
103 * (such as a dirent or URL), it's a relpath.
105 * - If your path is the virtual path of a versioned object inside a
106 * Subversion repository, it could be one of two different types of
107 * paths. We'd prefer to use relpaths (relative to the root
108 * directory of the virtual repository filesystem) for that stuff,
109 * but some legacy code uses fspaths. You'll need to figure out if
110 * your code expects repository paths to have a leading '/' or not.
111 * If so, they are fspaths; otherwise they are relpaths.
113 * - If your path refers only to the path part of URL -- as if
114 * someone hacked off the initial schema and hostname portion --
115 * it's a urlpath. To date, the ra_dav modules are the only ones
116 * within Subversion that make use of urlpaths, and this is because
117 * WebDAV makes heavy use of that form of path specification.
119 * When translating between local paths (dirents) and uris code should
120 * always go via the relative path format, perhaps by truncating a
121 * parent portion from a path with svn_*_skip_ancestor(), or by
122 * converting portions to basenames and then joining to existing
125 * SECURITY WARNING: If a path that is received from an untrusted
126 * source -- such as from the network -- is converted to a dirent it
127 * should be tested with svn_dirent_is_under_root() before you can
128 * assume the path to be a safe local path.
130 * MEMORY ALLOCATION: A function documented as allocating the result
131 * in a pool may instead return a static string such as "." or "". If
132 * the result is equal to an input, it will duplicate the input.
135 #ifndef SVN_DIRENT_URI_H
136 #define SVN_DIRENT_URI_H
139 #include <apr_pools.h>
140 #include <apr_tables.h>
142 #include "svn_types.h"
146 #endif /* __cplusplus */
150 * Convert @a dirent from the local style to the canonical internal style.
151 * "Local style" means native path separators and "." for the empty path.
153 * Allocate the result in @a result_pool.
155 * @warning This function may call @c abort() if the @a dirent parameter
156 * is not a valid local-style path.
157 * Use svn_dirent_internal_style_safe() for tainted input.
162 svn_dirent_internal_style(const char *dirent,
163 apr_pool_t *result_pool);
166 * Convert @a dirent from the local style to the canonical internal style
167 * and return it in @a *internal_style_dirent. "Local style" means native
168 * path separators and "." for the empty path.
170 * Similar to svn_dirent_internal_style() (which see), but returns an error
171 * if the @a dirent can not be canonicalized or of the result does not pass
172 * the svn_dirent_is_canonical() test.
174 * If the function fails and @a non_canonical_result is not @c NULL, the
175 * result of the failed canonicalization attempt (which may be @c NULL)
176 * will be returned in @a *non_canonical_result.
178 * Allocates the results in @a result_pool. Uses @a scratch_pool for
179 * temporary allocations.
181 * @since New in 1.12.
184 svn_dirent_internal_style_safe(const char **internal_style_dirent,
185 const char **non_canonical_result,
187 apr_pool_t *result_pool,
188 apr_pool_t *scratch_pool);
190 /** Convert @a dirent from the internal style to the local style.
191 * "Local style" means native path separators and "." for the empty path.
192 * If the input is not canonical, the output may not be canonical.
194 * Allocate the result in @a result_pool.
199 svn_dirent_local_style(const char *dirent,
200 apr_pool_t *result_pool);
202 /** Join a base dirent (@a base) with a component (@a component).
204 * If either @a base or @a component is the empty string, then the other
205 * argument will be copied and returned. If both are the empty string then
206 * empty string is returned.
208 * If the @a component is an absolute dirent, then it is copied and returned.
209 * The platform specific rules for joining paths are used to join the components.
211 * This function is NOT appropriate for native (local) file
212 * dirents. Only for "internal" canonicalized dirents, since it uses '/'
215 * Allocate the result in @a result_pool.
220 svn_dirent_join(const char *base,
221 const char *component,
222 apr_pool_t *result_pool);
224 /** Join multiple components onto a @a base dirent. The components are
225 * terminated by a @c SVN_VA_NULL.
227 * If any component is the empty string, it will be ignored.
229 * If any component is an absolute dirent, then it resets the base and
230 * further components will be appended to it.
232 * See svn_dirent_join() for further notes about joining dirents.
234 * Allocate the result in @a result_pool.
239 svn_dirent_join_many(apr_pool_t *result_pool,
241 ...) SVN_NEEDS_SENTINEL_NULL;
243 /** Join a base relpath (@a base) with a component (@a component).
244 * @a component need not be a single component.
246 * If either @a base or @a component is the empty path, then the other
247 * argument will be copied and returned. If both are the empty path the
248 * empty path is returned.
250 * Allocate the result in @a result_pool.
255 svn_relpath_join(const char *base,
256 const char *component,
257 apr_pool_t *result_pool);
259 /** Gets the name of the specified canonicalized @a dirent as it is known
260 * within its parent directory. If the @a dirent is root, return "". The
261 * returned value will not have slashes in it.
263 * Example: svn_dirent_basename("/foo/bar") -> "bar"
265 * If @a result_pool is NULL, return a pointer to the basename in @a dirent,
266 * otherwise allocate the result in @a result_pool.
268 * @note If an empty string is passed, then an empty string will be returned.
273 svn_dirent_basename(const char *dirent,
274 apr_pool_t *result_pool);
276 /** Get the dirname of the specified canonicalized @a dirent, defined as
277 * the dirent with its basename removed.
279 * If @a dirent is root ("/", "X:/", "//server/share/") or "", it is returned
282 * Allocate the result in @a result_pool.
287 svn_dirent_dirname(const char *dirent,
288 apr_pool_t *result_pool);
290 /** Divide the canonicalized @a dirent into @a *dirpath and @a *base_name.
292 * If @a dirpath or @a base_name is NULL, then don't set that one.
294 * Either @a dirpath or @a base_name may be @a dirent's own address, but they
295 * may not both be the same address, or the results are undefined.
297 * If @a dirent has two or more components, the separator between @a dirpath
298 * and @a base_name is not included in either of the new names.
301 * - <pre>"/foo/bar/baz" ==> "/foo/bar" and "baz"</pre>
302 * - <pre>"/bar" ==> "/" and "bar"</pre>
303 * - <pre>"/" ==> "/" and ""</pre>
304 * - <pre>"bar" ==> "" and "bar"</pre>
305 * - <pre>"" ==> "" and ""</pre>
306 * Windows: - <pre>"X:/" ==> "X:/" and ""</pre>
307 * - <pre>"X:/foo" ==> "X:/" and "foo"</pre>
308 * - <pre>"X:foo" ==> "X:" and "foo"</pre>
309 * Posix: - <pre>"X:foo" ==> "" and "X:foo"</pre>
311 * Allocate the results in @a result_pool.
316 svn_dirent_split(const char **dirpath,
317 const char **base_name,
319 apr_pool_t *result_pool);
321 /** Divide the canonicalized @a relpath into @a *dirpath and @a *base_name.
323 * If @a dirpath or @a base_name is NULL, then don't set that one.
325 * Either @a dirpath or @a base_name may be @a relpaths's own address, but
326 * they may not both be the same address, or the results are undefined.
328 * If @a relpath has two or more components, the separator between @a dirpath
329 * and @a base_name is not included in either of the new names.
332 * - <pre>"foo/bar/baz" ==> "foo/bar" and "baz"</pre>
333 * - <pre>"bar" ==> "" and "bar"</pre>
334 * - <pre>"" ==> "" and ""</pre>
336 * Allocate the results in @a result_pool.
341 svn_relpath_split(const char **dirpath,
342 const char **base_name,
344 apr_pool_t *result_pool);
346 /** Get the basename of the specified canonicalized @a relpath. The
347 * basename is defined as the last component of the relpath. If the @a
348 * relpath has only one component then that is returned. The returned
349 * value will have no slashes in it.
351 * Example: svn_relpath_basename("/trunk/foo/bar") -> "bar"
353 * If @a result_pool is NULL, return a pointer to the basename in @a relpath,
354 * otherwise allocate the result in @a result_pool.
356 * @note If an empty string is passed, then an empty string will be returned.
361 svn_relpath_basename(const char *relpath,
362 apr_pool_t *result_pool);
364 /** Get the dirname of the specified canonicalized @a relpath, defined as
365 * the relpath with its basename removed.
367 * If @a relpath is empty, "" is returned.
369 * Allocate the result in @a result_pool.
374 svn_relpath_dirname(const char *relpath,
375 apr_pool_t *result_pool);
377 /** Return a maximum of @a max_components components of @a relpath. This is
378 * an efficient way of calling svn_relpath_dirname() multiple times until only
379 * a specific number of components is left.
381 * Allocate the result in @a result_pool (or statically in case of 0)
386 svn_relpath_prefix(const char *relpath,
388 apr_pool_t *result_pool);
391 /** Divide the canonicalized @a uri into a uri @a *dirpath and a
392 * (URI-decoded) relpath @a *base_name.
394 * If @a dirpath or @a base_name is NULL, then don't set that one.
396 * Either @a dirpath or @a base_name may be @a uri's own address, but they
397 * may not both be the same address, or the results are undefined.
399 * If @a uri has two or more components, the separator between @a dirpath
400 * and @a base_name is not included in either of the new names.
403 * - <pre>"http://server/foo/bar" ==> "http://server/foo" and "bar"</pre>
405 * Allocate the result in @a result_pool.
410 svn_uri_split(const char **dirpath,
411 const char **base_name,
413 apr_pool_t *result_pool);
415 /** Get the (URI-decoded) basename of the specified canonicalized @a
416 * uri. The basename is defined as the last component of the uri. If
417 * the @a uri is root, return "". The returned value will have no
420 * Example: svn_uri_basename("http://server/foo/bar") -> "bar"
422 * Allocate the result in @a result_pool.
427 svn_uri_basename(const char *uri,
428 apr_pool_t *result_pool);
430 /** Get the dirname of the specified canonicalized @a uri, defined as
431 * the uri with its basename removed.
433 * If @a uri is root (e.g. "http://server"), it is returned
436 * Allocate the result in @a result_pool.
441 svn_uri_dirname(const char *uri,
442 apr_pool_t *result_pool);
444 /** Return TRUE if @a dirent is considered absolute on the platform at
445 * hand. E.g. '/foo' on Posix platforms or 'X:/foo', '//server/share/foo'
451 svn_dirent_is_absolute(const char *dirent);
453 /** Return TRUE if @a dirent is considered a root directory on the platform
457 * On Windows: '/', 'X:/', '//server/share', 'X:'
459 * Note that on Windows '/' and 'X:' are roots, but paths starting with this
460 * root are not absolute.
465 svn_dirent_is_root(const char *dirent,
468 /** Return TRUE if @a uri is a root URL (e.g., "http://server").
473 svn_uri_is_root(const char *uri,
477 * Return a new dirent like @a dirent, but transformed such that some types
478 * of dirent specification redundancies are removed.
481 * - collapsing redundant "/./" elements
482 * - removing multiple adjacent separator characters
483 * - removing trailing separator characters
484 * - converting the server name of a UNC path to lower case (on Windows)
485 * - converting a drive letter to upper case (on Windows)
487 * and possibly other semantically inoperative transformations.
489 * Allocate the result in @a result_pool.
491 * @warning This function may call @c abort() if @a dirent can not be
493 * Use svn_dirent_canonicalize_safe() for tainted input.
498 svn_dirent_canonicalize(const char *dirent,
499 apr_pool_t *result_pool);
502 * Return a new @a *canonical_dirent like @a dirent, but transformed such
503 * that some types of dirent specification redundancies are removed.
505 * Similar to svn_dirent_canonicalize() (which see), but returns an error
506 * if the @a dirent can not be canonicalized or of the result does not pass
507 * the svn_dirent_is_canonical() test.
509 * If the function fails and @a non_canonical_result is not @c NULL, the
510 * result of the failed canonicalization attempt (which may be @c NULL)
511 * will be returned in @a *non_canonical_result.
513 * Allocates the results in @a result_pool. Uses @a scratch_pool for
514 * temporary allocations.
516 * @since New in 1.12.
519 svn_dirent_canonicalize_safe(const char **canonical_dirent,
520 const char **non_canonical_result,
522 apr_pool_t *result_pool,
523 apr_pool_t *scratch_pool);
527 * Return a new relpath like @a relpath, but transformed such that some types
528 * of relpath specification redundancies are removed.
531 * - collapsing redundant "/./" elements
532 * - removing multiple adjacent separator characters
533 * - removing trailing separator characters
535 * and possibly other semantically inoperative transformations.
537 * Allocate the result in @a result_pool.
539 * @warning This function may call @c abort() if @a relpath can not be
541 * Use svn_relpath_canonicalize_safe() for tainted input.
546 svn_relpath_canonicalize(const char *relpath,
547 apr_pool_t *result_pool);
550 * Return a new @a *canonical_relpath like @a relpath, but transformed such
551 * that some types of relpath specification redundancies are removed.
553 * Similar to svn_relpath_canonicalize() (which see), but returns an error
554 * if the @a relpath can not be canonicalized or of the result does not
555 * pass the svn_relpath_is_canonical() test.
557 * If the function fails and @a non_canonical_result is not @c NULL, the
558 * result of the failed canonicalization attempt (which may be @c NULL)
559 * will be returned in @a *non_canonical_result.
561 * Allocates the results in @a result_pool. Uses @a scratch_pool for
562 * temporary allocations.
564 * @since New in 1.12.
568 svn_relpath_canonicalize_safe(const char **canonical_relpath,
569 const char **non_canonical_result,
571 apr_pool_t *result_pool,
572 apr_pool_t *scratch_pool);
576 * Return a new uri like @a uri, but transformed such that some types
577 * of uri specification redundancies are removed.
580 * - collapsing redundant "/./" elements
581 * - removing multiple adjacent separator characters
582 * - removing trailing separator characters
583 * - normalizing the escaping of the path component by unescaping
584 * characters that don't need escaping and escaping characters that do
585 * need escaping but weren't
586 * - removing the port number if it is the default port number (80 for
587 * http, 443 for https, 3690 for svn)
589 * and possibly other semantically inoperative transformations.
591 * Allocate the result in @a result_pool.
593 * @warning This function may call @c abort() if @a uri can not be
595 * Use svn_uri_canonicalize_safe() for tainted input.
600 svn_uri_canonicalize(const char *uri,
601 apr_pool_t *result_pool);
604 * Return a new @a *canonical_uri like @a uri, but transformed such that
605 * some types of uri specification redundancies are removed.
607 * Similar to svn_uri_canonicalize() (which see), but returns an error if
608 * the @a uri can not be canonicalized or of the result does not pass the
609 * svn_uri_is_canonical() test.
611 * If the function fails and @a non_canonical_result is not @c NULL, the
612 * result of the failed canonicalization attempt (which may be @c NULL)
613 * will be returned in @a *non_canonical_result.
615 * Allocates the results in @a result_pool. Uses @a scratch_pool for
616 * temporary allocations.
618 * @since New in 1.12.
621 svn_uri_canonicalize_safe(const char **canonical_uri,
622 const char **non_canonical_result,
624 apr_pool_t *result_pool,
625 apr_pool_t *scratch_pool);
628 /** Return @c TRUE iff @a dirent is canonical.
630 * Use @a scratch_pool for temporary allocations.
632 * @note The test for canonicalization is currently defined as
633 * "looks exactly the same as @c svn_dirent_canonicalize() would make
636 * @see svn_dirent_canonicalize()
640 svn_dirent_is_canonical(const char *dirent,
641 apr_pool_t *scratch_pool);
643 /** Return @c TRUE iff @a relpath is canonical.
645 * @see svn_relpath_canonicalize()
649 svn_relpath_is_canonical(const char *relpath);
651 /** Return @c TRUE iff @a uri is canonical.
653 * Use @a scratch_pool for temporary allocations.
655 * @see svn_uri_canonicalize()
659 svn_uri_is_canonical(const char *uri,
660 apr_pool_t *scratch_pool);
662 /** Return the longest common dirent shared by two canonicalized dirents,
663 * @a dirent1 and @a dirent2. If there's no common ancestor, return the
666 * Allocate the result in @a result_pool.
671 svn_dirent_get_longest_ancestor(const char *dirent1,
673 apr_pool_t *result_pool);
675 /** Return the longest common path shared by two relative paths,
676 * @a relpath1 and @a relpath2. If there's no common ancestor, return the
679 * Allocate the result in @a result_pool.
684 svn_relpath_get_longest_ancestor(const char *relpath1,
685 const char *relpath2,
686 apr_pool_t *result_pool);
688 /** Return the longest common path shared by two canonicalized uris,
689 * @a uri1 and @a uri2. If there's no common ancestor, return the
690 * empty path. In order for two URLs to have a common ancestor, they
691 * must (a) have the same protocol (since two URLs with the same path
692 * but different protocols may point at completely different
693 * resources), and (b) share a common ancestor in their path
694 * component, i.e. 'protocol://' is not a sufficient ancestor.
696 * Allocate the result in @a result_pool.
701 svn_uri_get_longest_ancestor(const char *uri1,
703 apr_pool_t *result_pool);
705 /** Convert @a relative canonicalized dirent to an absolute dirent and
706 * return the results in @a *pabsolute.
707 * Raise SVN_ERR_BAD_FILENAME if the absolute dirent cannot be determined.
709 * Allocate the result in @a result_pool.
714 svn_dirent_get_absolute(const char **pabsolute,
715 const char *relative,
716 apr_pool_t *result_pool);
718 /** Similar to svn_dirent_skip_ancestor(), except that if @a child_dirent is
719 * the same as @a parent_dirent, it is not considered a child, so the result
720 * is @c NULL; an empty string is never returned.
722 * If @a result_pool is NULL, return a pointer into @a child_dirent, otherwise
723 * allocate the result in @a result_pool.
725 * ### TODO: Deprecate, as the semantics are trivially
726 * obtainable from *_skip_ancestor().
731 svn_dirent_is_child(const char *parent_dirent,
732 const char *child_dirent,
733 apr_pool_t *result_pool);
735 /** Return TRUE if @a parent_dirent is an ancestor of @a child_dirent or
736 * the dirents are equal, and FALSE otherwise.
738 * ### TODO: Deprecate, as the semantics are trivially
739 * obtainable from *_skip_ancestor().
744 svn_dirent_is_ancestor(const char *parent_dirent,
745 const char *child_dirent);
747 /** Return TRUE if @a parent_uri is an ancestor of @a child_uri or
748 * the uris are equal, and FALSE otherwise.
751 svn_uri__is_ancestor(const char *parent_uri,
752 const char *child_uri);
755 /** Return the relative path part of @a child_dirent that is below
756 * @a parent_dirent, or just "" if @a parent_dirent is equal to
757 * @a child_dirent. If @a child_dirent is not below or equal to
758 * @a parent_dirent, return NULL.
760 * If one of @a parent_dirent and @a child_dirent is absolute and
761 * the other relative, return NULL.
766 svn_dirent_skip_ancestor(const char *parent_dirent,
767 const char *child_dirent);
769 /** Return the relative path part of @a child_relpath that is below
770 * @a parent_relpath, or just "" if @a parent_relpath is equal to
771 * @a child_relpath. If @a child_relpath is not below @a parent_relpath,
777 svn_relpath_skip_ancestor(const char *parent_relpath,
778 const char *child_relpath);
780 /** Return the URI-decoded relative path of @a child_uri that is below
781 * @a parent_uri, or just "" if @a parent_uri is equal to @a child_uri. If
782 * @a child_uri is not below @a parent_uri, return NULL.
784 * Allocate the result in @a result_pool.
789 svn_uri_skip_ancestor(const char *parent_uri,
790 const char *child_uri,
791 apr_pool_t *result_pool);
793 /** Find the common prefix of the canonicalized dirents in @a targets
794 * (an array of <tt>const char *</tt>'s), and remove redundant dirents if @a
795 * remove_redundancies is TRUE.
797 * - Set @a *pcommon to the absolute dirent of the dirent common to
798 * all of the targets. If the targets have no common prefix (e.g.
799 * "C:/file" and "D:/file" on Windows), set @a *pcommon to the empty
802 * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
803 * to an array of targets relative to @a *pcommon, and if
804 * @a remove_redundancies is TRUE, omit any dirents that are
805 * descendants of another dirent in @a targets. If *pcommon
806 * is empty, @a *pcondensed_targets will contain absolute dirents;
807 * redundancies can still be removed. If @a pcondensed_targets is NULL,
810 * Else if there is exactly one target, then
812 * - Set @a *pcommon to that target, and
814 * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
815 * to an array containing zero elements. Else if
816 * @a pcondensed_targets is NULL, leave it alone.
818 * If there are no items in @a targets, set @a *pcommon and (if
819 * applicable) @a *pcondensed_targets to @c NULL.
821 * Allocate the results in @a result_pool. Use @a scratch_pool for
822 * temporary allocations.
827 svn_dirent_condense_targets(const char **pcommon,
828 apr_array_header_t **pcondensed_targets,
829 const apr_array_header_t *targets,
830 svn_boolean_t remove_redundancies,
831 apr_pool_t *result_pool,
832 apr_pool_t *scratch_pool);
834 /** Find the common prefix of the canonicalized uris in @a targets
835 * (an array of <tt>const char *</tt>'s), and remove redundant uris if @a
836 * remove_redundancies is TRUE.
838 * - Set @a *pcommon to the common base uri of all of the targets.
839 * If the targets have no common prefix (e.g. "http://srv1/file"
840 * and "http://srv2/file"), set @a *pcommon to the empty
843 * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
844 * to an array of URI-decoded targets relative to @a *pcommon, and
845 * if @a remove_redundancies is TRUE, omit any uris that are
846 * descendants of another uri in @a targets. If *pcommon is
847 * empty, @a *pcondensed_targets will contain absolute uris;
848 * redundancies can still be removed. If @a pcondensed_targets is
849 * NULL, leave it alone.
851 * Else if there is exactly one target, then
853 * - Set @a *pcommon to that target, and
855 * - If @a pcondensed_targets is non-NULL, set @a *pcondensed_targets
856 * to an array containing zero elements. Else if
857 * @a pcondensed_targets is NULL, leave it alone.
859 * If there are no items in @a targets, set @a *pcommon and (if
860 * applicable) @a *pcondensed_targets to @c NULL.
862 * Allocate the results in @a result_pool. Use @a scratch_pool for
863 * temporary allocations.
868 svn_uri_condense_targets(const char **pcommon,
869 apr_array_header_t **pcondensed_targets,
870 const apr_array_header_t *targets,
871 svn_boolean_t remove_redundancies,
872 apr_pool_t *result_pool,
873 apr_pool_t *scratch_pool);
875 /** Join @a path onto @a base_path, checking that @a path does not attempt
876 * to traverse above @a base_path. If @a path or any ".." component within
877 * it resolves to a path above @a base_path, or if @a path is an absolute
878 * path, then set @a *under_root to @c FALSE. Otherwise, set @a *under_root
879 * to @c TRUE and, if @a result_path is not @c NULL, set @a *result_path to
880 * the resulting path.
882 * @a path need not be canonical. @a base_path must be canonical and
883 * @a *result_path will be canonical.
885 * Allocate the result in @a result_pool.
887 * @note Use of this function is strongly encouraged. Do not roll your own.
888 * (http://cve.mitre.org/cgi-bin/cvename.cgi?name=2007-3846)
893 svn_dirent_is_under_root(svn_boolean_t *under_root,
894 const char **result_path,
895 const char *base_path,
897 apr_pool_t *result_pool);
899 /** Set @a *dirent to the path corresponding to the file:// URL @a url, using
900 * the platform-specific file:// rules.
902 * Allocate the result in @a result_pool.
907 svn_uri_get_dirent_from_file_url(const char **dirent,
909 apr_pool_t *result_pool);
911 /** Set @a *url to a file:// URL, corresponding to @a dirent using the
912 * platform specific dirent and file:// rules.
914 * Allocate the result in @a result_pool.
919 svn_uri_get_file_url_from_dirent(const char **url,
921 apr_pool_t *result_pool);
925 #endif /* __cplusplus */
927 #endif /* SVN_DIRENT_URI_H */