svn_dirent_uri.h File Reference

A library to manipulate URIs, relative paths and directory entries. More...

`#include <apr.h>`
`#include <apr_pools.h>`
`#include <apr_tables.h>`
`#include "svn_types.h"`

Go to the source code of this file.

## Functions

const char * | svn_dirent_internal_style (const char *dirent, apr_pool_t *result_pool)
| Convert dirent from the local style to the canonical internal style. More...
svn_error_t * | svn_dirent_internal_style_safe (const char **internal_style_dirent, const char **non_canonical_result, const char *dirent, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Convert dirent from the local style to the canonical internal style and return it in *internal_style_dirent. More...
const char * | svn_dirent_local_style (const char *dirent, apr_pool_t *result_pool)
| Convert dirent from the internal style to the local style. More...
char * | svn_dirent_join (const char *base, const char *component, apr_pool_t *result_pool)
| Join a base dirent (base) with a component (component). More...
char * | svn_dirent_join_many (apr_pool_t *result_pool, const char *base,...)
| Join multiple components onto a base dirent. More...
char * | svn_relpath_join (const char *base, const char *component, apr_pool_t *result_pool)
| Join a base relpath (base) with a component (component). More...
const char * | svn_dirent_basename (const char *dirent, apr_pool_t *result_pool)
| Gets the name of the specified canonicalized dirent as it is known within its parent directory. More...
char * | svn_dirent_dirname (const char *dirent, apr_pool_t *result_pool)
| Get the dirname of the specified canonicalized dirent, defined as the dirent with its basename removed. More...
void | svn_dirent_split (const char **dirpath, const char **base_name, const char *dirent, apr_pool_t *result_pool)
| Divide the canonicalized dirent into *dirpath and *base_name. More...
void | svn_relpath_split (const char **dirpath, const char **base_name, const char *relpath, apr_pool_t *result_pool)
| Divide the canonicalized relpath into *dirpath and *base_name. More...
const char * | svn_relpath_basename (const char *relpath, apr_pool_t *result_pool)
| Get the basename of the specified canonicalized relpath. More...
char * | svn_relpath_dirname (const char *relpath, apr_pool_t *result_pool)
| Get the dirname of the specified canonicalized relpath, defined as the relpath with its basename removed. More...
const char * | svn_relpath_prefix (const char *relpath, int max_components, apr_pool_t *result_pool)
| Return a maximum of max_components components of relpath. More...
void | svn_uri_split (const char **dirpath, const char **base_name, const char *uri, apr_pool_t *result_pool)
| Divide the canonicalized uri into a uri *dirpath and a (URI-decoded) relpath *base_name. More...
const char * | svn_uri_basename (const char *uri, apr_pool_t *result_pool)
| Get the (URI-decoded) basename of the specified canonicalized uri. More...
char * | svn_uri_dirname (const char *uri, apr_pool_t *result_pool)
| Get the dirname of the specified canonicalized uri, defined as the uri with its basename removed. More...
svn_boolean_t | svn_dirent_is_absolute (const char *dirent)
| Return TRUE if dirent is considered absolute on the platform at hand. More...
svn_boolean_t | svn_dirent_is_root (const char *dirent, apr_size_t len)
| Return TRUE if dirent is considered a root directory on the platform at hand. More...
svn_boolean_t | svn_uri_is_root (const char *uri, apr_size_t len)
| Return TRUE if uri is a root URL (e.g., "http://server"). More...
const char * | svn_dirent_canonicalize (const char *dirent, apr_pool_t *result_pool)
| Return a new dirent like dirent, but transformed such that some types of dirent specification redundancies are removed. More...
svn_error_t * | svn_dirent_canonicalize_safe (const char **canonical_dirent, const char **non_canonical_result, const char *dirent, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Return a new *canonical_dirent like dirent, but transformed such that some types of dirent specification redundancies are removed. More...
const char * | svn_relpath_canonicalize (const char *relpath, apr_pool_t *result_pool)
| Return a new relpath like relpath, but transformed such that some types of relpath specification redundancies are removed. More...
svn_error_t * | svn_relpath_canonicalize_safe (const char **canonical_relpath, const char **non_canonical_result, const char *relpath, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Return a new *canonical_relpath like relpath, but transformed such that some types of relpath specification redundancies are removed. More...
const char * | svn_uri_canonicalize (const char *uri, apr_pool_t *result_pool)
| Return a new uri like uri, but transformed such that some types of uri specification redundancies are removed. More...
svn_error_t * | svn_uri_canonicalize_safe (const char **canonical_uri, const char **non_canonical_result, const char *uri, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Return a new *canonical_uri like uri, but transformed such that some types of uri specification redundancies are removed. More...
svn_boolean_t | svn_dirent_is_canonical (const char *dirent, apr_pool_t *scratch_pool)
| Return `TRUE` iff dirent is canonical. More...
svn_boolean_t | svn_relpath_is_canonical (const char *relpath)
| Return `TRUE` iff relpath is canonical. More...
svn_boolean_t | svn_uri_is_canonical (const char *uri, apr_pool_t *scratch_pool)
| Return `TRUE` iff uri is canonical. More...
char * | svn_dirent_get_longest_ancestor (const char *dirent1, const char *dirent2, apr_pool_t *result_pool)
| Return the longest common dirent shared by two canonicalized dirents, dirent1 and dirent2. More...
char * | svn_relpath_get_longest_ancestor (const char *relpath1, const char *relpath2, apr_pool_t *result_pool)
| Return the longest common path shared by two relative paths, relpath1 and relpath2. More...
char * | svn_uri_get_longest_ancestor (const char *uri1, const char *uri2, apr_pool_t *result_pool)
| Return the longest common path shared by two canonicalized uris, uri1 and uri2. More...
svn_error_t * | svn_dirent_get_absolute (const char **pabsolute, const char *relative, apr_pool_t *result_pool)
| Convert relative canonicalized dirent to an absolute dirent and return the results in *pabsolute. More...
const char * | svn_dirent_is_child (const char *parent_dirent, const char *child_dirent, apr_pool_t *result_pool)
| Similar to svn_dirent_skip_ancestor(), except that if child_dirent is the same as parent_dirent, it is not considered a child, so the result is `NULL`; an empty string is never returned. More...
svn_boolean_t | svn_dirent_is_ancestor (const char *parent_dirent, const char *child_dirent)
| Return TRUE if parent_dirent is an ancestor of child_dirent or the dirents are equal, and FALSE otherwise. More...
svn_boolean_t | svn_uri__is_ancestor (const char *parent_uri, const char *child_uri)
| Return TRUE if parent_uri is an ancestor of child_uri or the uris are equal, and FALSE otherwise.
const char * | svn_dirent_skip_ancestor (const char *parent_dirent, const char *child_dirent)
| Return the relative path part of child_dirent that is below parent_dirent, or just "" if parent_dirent is equal to child_dirent. More...
const char * | svn_relpath_skip_ancestor (const char *parent_relpath, const char *child_relpath)
| Return the relative path part of child_relpath that is below parent_relpath, or just "" if parent_relpath is equal to child_relpath. More...
const char * | svn_uri_skip_ancestor (const char *parent_uri, const char *child_uri, apr_pool_t *result_pool)
| Return the URI-decoded relative path of child_uri that is below parent_uri, or just "" if parent_uri is equal to child_uri. More...
svn_error_t * | svn_dirent_condense_targets (const char **pcommon, apr_array_header_t **pcondensed_targets, const apr_array_header_t *targets, svn_boolean_t remove_redundancies, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Find the common prefix of the canonicalized dirents in targets (an array of `const char *`'s), and remove redundant dirents if remove_redundancies is TRUE. More...
svn_error_t * | svn_uri_condense_targets (const char **pcommon, apr_array_header_t **pcondensed_targets, const apr_array_header_t *targets, svn_boolean_t remove_redundancies, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| Find the common prefix of the canonicalized uris in targets (an array of `const char *`'s), and remove redundant uris if remove_redundancies is TRUE. More...
svn_error_t * | svn_dirent_is_under_root (svn_boolean_t *under_root, const char **result_path, const char *base_path, const char *path, apr_pool_t *result_pool)
| Join path onto base_path, checking that path does not attempt to traverse above base_path. More...
svn_error_t * | svn_uri_get_dirent_from_file_url (const char **dirent, const char *url, apr_pool_t *result_pool)
| Set *dirent to the path corresponding to the file:// URL url, using the platform-specific file:// rules. More...
svn_error_t * | svn_uri_get_file_url_from_dirent (const char **url, const char *dirent, apr_pool_t *result_pool)
| Set *url to a file:// URL, corresponding to dirent using the platform specific dirent and file:// rules. More...

## Detailed Description

A library to manipulate URIs, relative paths and directory entries.

# @if copyrights

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations

# under the License.

This library makes a clear distinction between several path formats:

- a dirent is a path on (local) disc or a UNC path (Windows) in either relative or absolute format. Examples: "/foo/bar", "X:/temp", "//server/share", "A:/" (Windows only), "" But not: "http://server"
- a uri, for our purposes, is a percent-encoded, absolute path (URI) that starts with a schema definition. In practice, these tend to look like URLs, but never carry query strings. Examples: "http://server", "file:///path/to/repos", "svn+ssh://user@host:123/My%20Stuff/file.doc" But not: "file", "dir/file", "A:/dir", "/My%20Stuff/file.doc", ""
- a relative path (relpath) is an unrooted path that can be joined to any other relative path, uri or dirent. A relative path is never rooted/prefixed by a '/'. Examples: "file", "dir/file", "dir/subdir/../file", "" But not: "/file", "http://server/file"

This distinction is needed because on Windows we have to handle some dirents and URIs differently. Since it's not possible to determine from the path string if it's a dirent or a URI, it's up to the API user to make this choice. See also issue #2028.

All incoming and outgoing paths are non-NULL unless otherwise documented.

All of these functions expect paths passed into them to be in canonical form, except:

- `svn_dirent_canonicalize()`
- `svn_dirent_canonicalize_safe()`
- `svn_dirent_is_canonical()`
- `svn_dirent_internal_style()`
- `svn_relpath_canonicalize()`
- `svn_relpath_canonicalize_safe()`
- `svn_relpath_is_canonical()`
- `svn_uri_canonicalize()`
- `svn_uri_canonicalize_safe()`
- `svn_uri_is_canonical()`

The Subversion codebase also recognizes some other classes of path:

- A Subversion filesystem path (fspath) – otherwise known as a path within a repository – is a path relative to the root of the repository filesystem, that starts with a slash ("/"). The rules for a fspath are the same as for a relpath except for the leading '/'. A fspath never ends with '/' except when the whole path is just '/'. The fspath API is private (see private/svn_fspath.h).
- A URL path (urlpath) is just the path part of a URL (the part that follows the schema, username, hostname, and port). These are also like relpaths, except that they have a leading slash (like fspaths) and are URI-encoded. The urlpath API is also private (see private/svn_fspath.h) Example: "/svn/repos/trunk/README", "/svn/repos/!svn/bc/45/file%20with%20spaces.txt"

So, which path API is appropriate for your use-case?

- If your path refers to a local file, directory, symlink, etc. of the sort that you can examine and operate on with other software on your computer, it's a dirent.
- If your path is a full URL – with a schema, hostname (maybe), and path portion – it's a uri.
- If your path is relative, and is somewhat ambiguous unless it's joined to some other more explicit (possible absolute) base (such as a dirent or URL), it's a relpath.
- If your path is the virtual path of a versioned object inside a Subversion repository, it could be one of two different types of paths. We'd prefer to use relpaths (relative to the root directory of the virtual repository filesystem) for that stuff, but some legacy code uses fspaths. You'll need to figure out if your code expects repository paths to have a leading '/' or not. If so, they are fspaths; otherwise they are relpaths.
- If your path refers only to the path part of URL – as if someone hacked off the initial schema and hostname portion – it's a urlpath. To date, the ra_dav modules are the only ones within Subversion that make use of urlpaths, and this is because WebDAV makes heavy use of that form of path specification.

When translating between local paths (dirents) and uris code should always go via the relative path format, perhaps by truncating a parent portion from a path with svn_*_skip_ancestor(), or by converting portions to basenames and then joining to existing paths.

SECURITY WARNING: If a path that is received from an untrusted source – such as from the network – is converted to a dirent it should be tested with svn_dirent_is_under_root() before you can assume the path to be a safe local path.

MEMORY ALLOCATION: A function documented as allocating the result in a pool may instead return a static string such as "." or "". If the result is equal to an input, it will duplicate the input.

Definition in file svn_dirent_uri.h.

## Function Documentation

## svn_dirent_basename()

const char* svn_dirent_basename | ( | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Gets the name of the specified canonicalized dirent as it is known within its parent directory.

If the dirent is root, return "". The returned value will not have slashes in it.

Example: svn_dirent_basename("/foo/bar") -> "bar"

If result_pool is NULL, return a pointer to the basename in dirent, otherwise allocate the result in result_pool.

Note
  If an empty string is passed, then an empty string will be returned.

Since
  New in 1.7.

## svn_dirent_canonicalize()

const char* svn_dirent_canonicalize | ( | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Return a new dirent like dirent, but transformed such that some types of dirent specification redundancies are removed.

This involves:

- collapsing redundant "/./" elements
- removing multiple adjacent separator characters
- removing trailing separator characters
- converting the server name of a UNC path to lower case (on Windows)
- converting a drive letter to upper case (on Windows)

and possibly other semantically inoperative transformations.

Allocate the result in result_pool.

Warning
  This function may call `abort()` if dirent can not be canonicalized. Use svn_dirent_canonicalize_safe() for tainted input.

Since
  New in 1.6.

## svn_dirent_canonicalize_safe()

svn_error_t* svn_dirent_canonicalize_safe | ( | const char ** | canonical_dirent,
|  | const char ** | non_canonical_result,
|  | const char * | dirent,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Return a new *canonical_dirent like dirent, but transformed such that some types of dirent specification redundancies are removed.

Similar to svn_dirent_canonicalize() (which see), but returns an error if the dirent can not be canonicalized or of the result does not pass the svn_dirent_is_canonical() test.

If the function fails and non_canonical_result is not `NULL`, the result of the failed canonicalization attempt (which may be `NULL`) will be returned in *non_canonical_result.

Allocates the results in result_pool. Uses scratch_pool for temporary allocations.

Since
  New in 1.12.

## svn_dirent_condense_targets()

svn_error_t* svn_dirent_condense_targets | ( | const char ** | pcommon,
|  | apr_array_header_t ** | pcondensed_targets,
|  | const apr_array_header_t * | targets,
|  | svn_boolean_t | remove_redundancies,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Find the common prefix of the canonicalized dirents in targets (an array of `const char *`'s), and remove redundant dirents if remove_redundancies is TRUE.

- Set *pcommon to the absolute dirent of the dirent common to all of the targets. If the targets have no common prefix (e.g. "C:/file" and "D:/file" on Windows), set *pcommon to the empty string.
- If pcondensed_targets is non-NULL, set *pcondensed_targets to an array of targets relative to *pcommon, and if remove_redundancies is TRUE, omit any dirents that are descendants of another dirent in targets. If *pcommon is empty, *pcondensed_targets will contain absolute dirents; redundancies can still be removed. If pcondensed_targets is NULL, leave it alone.

Else if there is exactly one target, then

- Set *pcommon to that target, and
- If pcondensed_targets is non-NULL, set *pcondensed_targets to an array containing zero elements. Else if pcondensed_targets is NULL, leave it alone.

If there are no items in targets, set *pcommon and (if applicable) *pcondensed_targets to `NULL`.

Allocate the results in result_pool. Use scratch_pool for temporary allocations.

Since
  New in 1.7.

## svn_dirent_dirname()

char* svn_dirent_dirname | ( | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Get the dirname of the specified canonicalized dirent, defined as the dirent with its basename removed.

If dirent is root ("/", "X:/", "//server/share/") or "", it is returned unchanged.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_get_absolute()

svn_error_t* svn_dirent_get_absolute | ( | const char ** | pabsolute,
|  | const char * | relative,
|  | apr_pool_t * | result_pool
| ) |  |

Convert relative canonicalized dirent to an absolute dirent and return the results in *pabsolute.

Raise SVN_ERR_BAD_FILENAME if the absolute dirent cannot be determined.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_get_longest_ancestor()

char* svn_dirent_get_longest_ancestor | ( | const char * | dirent1,
|  | const char * | dirent2,
|  | apr_pool_t * | result_pool
| ) |  |

Return the longest common dirent shared by two canonicalized dirents, dirent1 and dirent2.

If there's no common ancestor, return the empty path.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_internal_style()

const char* svn_dirent_internal_style | ( | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Convert dirent from the local style to the canonical internal style.

"Local style" means native path separators and "." for the empty path.

Allocate the result in result_pool.

Warning
  This function may call `abort()` if the dirent parameter is not a valid local-style path. Use svn_dirent_internal_style_safe() for tainted input.

Since
  New in 1.6.

## svn_dirent_internal_style_safe()

svn_error_t* svn_dirent_internal_style_safe | ( | const char ** | internal_style_dirent,
|  | const char ** | non_canonical_result,
|  | const char * | dirent,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Convert dirent from the local style to the canonical internal style and return it in *internal_style_dirent.

"Local style" means native path separators and "." for the empty path.

Similar to svn_dirent_internal_style() (which see), but returns an error if the dirent can not be canonicalized or of the result does not pass the svn_dirent_is_canonical() test.

If the function fails and non_canonical_result is not `NULL`, the result of the failed canonicalization attempt (which may be `NULL`) will be returned in *non_canonical_result.

Allocates the results in result_pool. Uses scratch_pool for temporary allocations.

Since
  New in 1.12.

## svn_dirent_is_absolute()

svn_boolean_t svn_dirent_is_absolute | ( | const char * | dirent | ) |

Return TRUE if dirent is considered absolute on the platform at hand.

E.g. '/foo' on Posix platforms or 'X:/foo', '//server/share/foo' on Windows.

Since
  New in 1.6.

## svn_dirent_is_ancestor()

svn_boolean_t svn_dirent_is_ancestor | ( | const char * | parent_dirent,
|  | const char * | child_dirent
| ) |  |

Return TRUE if parent_dirent is an ancestor of child_dirent or the dirents are equal, and FALSE otherwise.

### TODO: Deprecate, as the semantics are trivially

obtainable from *_skip_ancestor().

Since
  New in 1.6.

## svn_dirent_is_canonical()

svn_boolean_t svn_dirent_is_canonical | ( | const char * | dirent,
|  | apr_pool_t * | scratch_pool
| ) |  |

Return `TRUE` iff dirent is canonical.

Use scratch_pool for temporary allocations.

Note
  The test for canonicalization is currently defined as "looks exactly the same as @c svn_dirent_canonicalize() would make it look".

See also
  svn_dirent_canonicalize()

Since
  New in 1.6.

## svn_dirent_is_child()

const char* svn_dirent_is_child | ( | const char * | parent_dirent,
|  | const char * | child_dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Similar to svn_dirent_skip_ancestor(), except that if child_dirent is the same as parent_dirent, it is not considered a child, so the result is `NULL`; an empty string is never returned.

If result_pool is NULL, return a pointer into child_dirent, otherwise allocate the result in result_pool.

### TODO: Deprecate, as the semantics are trivially

obtainable from *_skip_ancestor().

Since
  New in 1.6.

## svn_dirent_is_root()

svn_boolean_t svn_dirent_is_root | ( | const char * | dirent,
|  | apr_size_t | len
| ) |  |

Return TRUE if dirent is considered a root directory on the platform at hand.

E.g.: On Posix: '/' On Windows: '/', 'X:/', '//server/share', 'X:'

Note that on Windows '/' and 'X:' are roots, but paths starting with this root are not absolute.

Since
  New in 1.5.

## svn_dirent_is_under_root()

svn_error_t* svn_dirent_is_under_root | ( | svn_boolean_t * | under_root,
|  | const char ** | result_path,
|  | const char * | base_path,
|  | const char * | path,
|  | apr_pool_t * | result_pool
| ) |  |

Join path onto base_path, checking that path does not attempt to traverse above base_path.

If path or any ".." component within it resolves to a path above base_path, or if path is an absolute path, then set *under_root to `FALSE`. Otherwise, set *under_root to `TRUE` and, if result_path is not `NULL`, set *result_path to the resulting path.

path need not be canonical. base_path must be canonical and *result_path will be canonical.

Allocate the result in result_pool.

Note
  Use of this function is strongly encouraged. Do not roll your own. (http://cve.mitre.org/cgi-bin/cvename.cgi?name=2007-3846)

Since
  New in 1.7.

## svn_dirent_join()

char* svn_dirent_join | ( | const char * | base,
|  | const char * | component,
|  | apr_pool_t * | result_pool
| ) |  |

Join a base dirent (base) with a component (component).

If either base or component is the empty string, then the other argument will be copied and returned. If both are the empty string then empty string is returned.

If the component is an absolute dirent, then it is copied and returned. The platform specific rules for joining paths are used to join the components.

This function is NOT appropriate for native (local) file dirents. Only for "internal" canonicalized dirents, since it uses '/' for the separator.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_join_many()

char* svn_dirent_join_many | ( | apr_pool_t * | result_pool,
|  | const char * | base,
|  |  | ...
| ) |  |

Join multiple components onto a base dirent.

The components are terminated by a `SVN_VA_NULL`.

If any component is the empty string, it will be ignored.

If any component is an absolute dirent, then it resets the base and further components will be appended to it.

See svn_dirent_join() for further notes about joining dirents.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_local_style()

const char* svn_dirent_local_style | ( | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Convert dirent from the internal style to the local style.

"Local style" means native path separators and "." for the empty path. If the input is not canonical, the output may not be canonical.

Allocate the result in result_pool.

Since
  New in 1.6.

## svn_dirent_skip_ancestor()

const char* svn_dirent_skip_ancestor | ( | const char * | parent_dirent,
|  | const char * | child_dirent
| ) |  |

Return the relative path part of child_dirent that is below parent_dirent, or just "" if parent_dirent is equal to child_dirent.

If child_dirent is not below or equal to parent_dirent, return NULL.

If one of parent_dirent and child_dirent is absolute and the other relative, return NULL.

Since
  New in 1.7.

## svn_dirent_split()

void svn_dirent_split | ( | const char ** | dirpath,
|  | const char ** | base_name,
|  | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Divide the canonicalized dirent into *dirpath and *base_name.

If dirpath or base_name is NULL, then don't set that one.

Either dirpath or base_name may be dirent's own address, but they may not both be the same address, or the results are undefined.

If dirent has two or more components, the separator between dirpath and base_name is not included in either of the new names.

Examples:

-     "/foo/bar/baz"  ==>  "/foo/bar" and "baz"

-     "/bar"          ==>  "/"  and "bar"

-     "/"             ==>  "/"  and ""

-     "bar"           ==>  ""   and "bar"

-     ""              ==>  ""   and ""

  Windows: -

      "X:/"           ==>  "X:/" and ""

-     "X:/foo"        ==>  "X:/" and "foo"

-     "X:foo"         ==>  "X:" and "foo"

  Posix: -

      "X:foo"         ==>  ""   and "X:foo"

Allocate the results in result_pool.

Since
  New in 1.7.

## svn_relpath_basename()

const char* svn_relpath_basename | ( | const char * | relpath,
|  | apr_pool_t * | result_pool
| ) |  |

Get the basename of the specified canonicalized relpath.

The basename is defined as the last component of the relpath. If the relpath has only one component then that is returned. The returned value will have no slashes in it.

Example: svn_relpath_basename("/trunk/foo/bar") -> "bar"

If result_pool is NULL, return a pointer to the basename in relpath, otherwise allocate the result in result_pool.

Note
  If an empty string is passed, then an empty string will be returned.

Since
  New in 1.7.

## svn_relpath_canonicalize()

const char* svn_relpath_canonicalize | ( | const char * | relpath,
|  | apr_pool_t * | result_pool
| ) |  |

Return a new relpath like relpath, but transformed such that some types of relpath specification redundancies are removed.

This involves:

- collapsing redundant "/./" elements
- removing multiple adjacent separator characters
- removing trailing separator characters

and possibly other semantically inoperative transformations.

Allocate the result in result_pool.

Warning
  This function may call `abort()` if relpath can not be canonicalized. Use svn_relpath_canonicalize_safe() for tainted input.

Since
  New in 1.7.

## svn_relpath_canonicalize_safe()

svn_error_t* svn_relpath_canonicalize_safe | ( | const char ** | canonical_relpath,
|  | const char ** | non_canonical_result,
|  | const char * | relpath,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Return a new *canonical_relpath like relpath, but transformed such that some types of relpath specification redundancies are removed.

Similar to svn_relpath_canonicalize() (which see), but returns an error if the relpath can not be canonicalized or of the result does not pass the svn_relpath_is_canonical() test.

If the function fails and non_canonical_result is not `NULL`, the result of the failed canonicalization attempt (which may be `NULL`) will be returned in *non_canonical_result.

Allocates the results in result_pool. Uses scratch_pool for temporary allocations.

Since
  New in 1.12.

## svn_relpath_dirname()

char* svn_relpath_dirname | ( | const char * | relpath,
|  | apr_pool_t * | result_pool
| ) |  |

Get the dirname of the specified canonicalized relpath, defined as the relpath with its basename removed.

If relpath is empty, "" is returned.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_relpath_get_longest_ancestor()

char* svn_relpath_get_longest_ancestor | ( | const char * | relpath1,
|  | const char * | relpath2,
|  | apr_pool_t * | result_pool
| ) |  |

Return the longest common path shared by two relative paths, relpath1 and relpath2.

If there's no common ancestor, return the empty path.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_relpath_is_canonical()

svn_boolean_t svn_relpath_is_canonical | ( | const char * | relpath | ) |

Return `TRUE` iff relpath is canonical.

See also
  svn_relpath_canonicalize()

Since
  New in 1.7.

## svn_relpath_join()

char* svn_relpath_join | ( | const char * | base,
|  | const char * | component,
|  | apr_pool_t * | result_pool
| ) |  |

Join a base relpath (base) with a component (component).

component need not be a single component.

If either base or component is the empty path, then the other argument will be copied and returned. If both are the empty path the empty path is returned.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_relpath_prefix()

const char* svn_relpath_prefix | ( | const char * | relpath,
|  | int | max_components,
|  | apr_pool_t * | result_pool
| ) |  |

Return a maximum of max_components components of relpath.

This is an efficient way of calling svn_relpath_dirname() multiple times until only a specific number of components is left.

Allocate the result in result_pool (or statically in case of 0)

Since
  New in 1.9.

## svn_relpath_skip_ancestor()

const char* svn_relpath_skip_ancestor | ( | const char * | parent_relpath,
|  | const char * | child_relpath
| ) |  |

Return the relative path part of child_relpath that is below parent_relpath, or just "" if parent_relpath is equal to child_relpath.

If child_relpath is not below parent_relpath, return NULL.

Since
  New in 1.7.

## svn_relpath_split()

void svn_relpath_split | ( | const char ** | dirpath,
|  | const char ** | base_name,
|  | const char * | relpath,
|  | apr_pool_t * | result_pool
| ) |  |

Divide the canonicalized relpath into *dirpath and *base_name.

If dirpath or base_name is NULL, then don't set that one.

Either dirpath or base_name may be relpaths's own address, but they may not both be the same address, or the results are undefined.

If relpath has two or more components, the separator between dirpath and base_name is not included in either of the new names.

examples:

-     "foo/bar/baz"  ==>  "foo/bar" and "baz"

-     "bar"          ==>  ""  and "bar"

-     ""              ==>  ""   and ""

Allocate the results in result_pool.

Since
  New in 1.7.

## svn_uri_basename()

const char* svn_uri_basename | ( | const char * | uri,
|  | apr_pool_t * | result_pool
| ) |  |

Get the (URI-decoded) basename of the specified canonicalized uri.

The basename is defined as the last component of the uri. If the uri is root, return "". The returned value will have no slashes in it.

Example: svn_uri_basename("http://server/foo/bar") -> "bar"

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_canonicalize()

const char* svn_uri_canonicalize | ( | const char * | uri,
|  | apr_pool_t * | result_pool
| ) |  |

Return a new uri like uri, but transformed such that some types of uri specification redundancies are removed.

This involves:

- collapsing redundant "/./" elements
- removing multiple adjacent separator characters
- removing trailing separator characters
- normalizing the escaping of the path component by unescaping characters that don't need escaping and escaping characters that do need escaping but weren't
- removing the port number if it is the default port number (80 for http, 443 for https, 3690 for svn)

and possibly other semantically inoperative transformations.

Allocate the result in result_pool.

Warning
  This function may call `abort()` if uri can not be canonicalized. Use svn_uri_canonicalize_safe() for tainted input.

Since
  New in 1.7.

## svn_uri_canonicalize_safe()

svn_error_t* svn_uri_canonicalize_safe | ( | const char ** | canonical_uri,
|  | const char ** | non_canonical_result,
|  | const char * | uri,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Return a new *canonical_uri like uri, but transformed such that some types of uri specification redundancies are removed.

Similar to svn_uri_canonicalize() (which see), but returns an error if the uri can not be canonicalized or of the result does not pass the svn_uri_is_canonical() test.

If the function fails and non_canonical_result is not `NULL`, the result of the failed canonicalization attempt (which may be `NULL`) will be returned in *non_canonical_result.

Allocates the results in result_pool. Uses scratch_pool for temporary allocations.

Since
  New in 1.12.

## svn_uri_condense_targets()

svn_error_t* svn_uri_condense_targets | ( | const char ** | pcommon,
|  | apr_array_header_t ** | pcondensed_targets,
|  | const apr_array_header_t * | targets,
|  | svn_boolean_t | remove_redundancies,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool
| ) |  |

Find the common prefix of the canonicalized uris in targets (an array of `const char *`'s), and remove redundant uris if remove_redundancies is TRUE.

- Set *pcommon to the common base uri of all of the targets. If the targets have no common prefix (e.g. "http://srv1/file" and "http://srv2/file"), set *pcommon to the empty string.
- If pcondensed_targets is non-NULL, set *pcondensed_targets to an array of URI-decoded targets relative to *pcommon, and if remove_redundancies is TRUE, omit any uris that are descendants of another uri in targets. If *pcommon is empty, *pcondensed_targets will contain absolute uris; redundancies can still be removed. If pcondensed_targets is NULL, leave it alone.

Else if there is exactly one target, then

- Set *pcommon to that target, and
- If pcondensed_targets is non-NULL, set *pcondensed_targets to an array containing zero elements. Else if pcondensed_targets is NULL, leave it alone.

If there are no items in targets, set *pcommon and (if applicable) *pcondensed_targets to `NULL`.

Allocate the results in result_pool. Use scratch_pool for temporary allocations.

Since
  New in 1.7.

## svn_uri_dirname()

char* svn_uri_dirname | ( | const char * | uri,
|  | apr_pool_t * | result_pool
| ) |  |

Get the dirname of the specified canonicalized uri, defined as the uri with its basename removed.

If uri is root (e.g. "http://server"), it is returned unchanged.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_get_dirent_from_file_url()

svn_error_t* svn_uri_get_dirent_from_file_url | ( | const char ** | dirent,
|  | const char * | url,
|  | apr_pool_t * | result_pool
| ) |  |

Set *dirent to the path corresponding to the file:// URL url, using the platform-specific file:// rules.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_get_file_url_from_dirent()

svn_error_t* svn_uri_get_file_url_from_dirent | ( | const char ** | url,
|  | const char * | dirent,
|  | apr_pool_t * | result_pool
| ) |  |

Set *url to a file:// URL, corresponding to dirent using the platform specific dirent and file:// rules.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_get_longest_ancestor()

char* svn_uri_get_longest_ancestor | ( | const char * | uri1,
|  | const char * | uri2,
|  | apr_pool_t * | result_pool
| ) |  |

Return the longest common path shared by two canonicalized uris, uri1 and uri2.

If there's no common ancestor, return the empty path. In order for two URLs to have a common ancestor, they must (a) have the same protocol (since two URLs with the same path but different protocols may point at completely different resources), and (b) share a common ancestor in their path component, i.e. 'protocol://' is not a sufficient ancestor.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_is_canonical()

svn_boolean_t svn_uri_is_canonical | ( | const char * | uri,
|  | apr_pool_t * | scratch_pool
| ) |  |

Return `TRUE` iff uri is canonical.

Use scratch_pool for temporary allocations.

See also
  svn_uri_canonicalize()

Since
  New in 1.7.

## svn_uri_is_root()

svn_boolean_t svn_uri_is_root | ( | const char * | uri,
|  | apr_size_t | len
| ) |  |

Return TRUE if uri is a root URL (e.g., "http://server").

Since
  New in 1.7

## svn_uri_skip_ancestor()

const char* svn_uri_skip_ancestor | ( | const char * | parent_uri,
|  | const char * | child_uri,
|  | apr_pool_t * | result_pool
| ) |  |

Return the URI-decoded relative path of child_uri that is below parent_uri, or just "" if parent_uri is equal to child_uri.

If child_uri is not below parent_uri, return NULL.

Allocate the result in result_pool.

Since
  New in 1.7.

## svn_uri_split()

void svn_uri_split | ( | const char ** | dirpath,
|  | const char ** | base_name,
|  | const char * | uri,
|  | apr_pool_t * | result_pool
| ) |  |

Divide the canonicalized uri into a uri *dirpath and a (URI-decoded) relpath *base_name.

If dirpath or base_name is NULL, then don't set that one.

Either dirpath or base_name may be uri's own address, but they may not both be the same address, or the results are undefined.

If uri has two or more components, the separator between dirpath and base_name is not included in either of the new names.

Examples:

-     "http://server/foo/bar"  ==>  "http://server/foo" and "bar"

Allocate the result in result_pool.

Since
  New in 1.7.