GME  13
Functions
svn_dirent_uri.h File Reference

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

Go to the source code of this file.

Functions

const char * svn_dirent_internal_style (const char *dirent, apr_pool_t *result_pool)
const char * svn_dirent_local_style (const char *dirent, apr_pool_t *result_pool)
const char * svn_relpath__internal_style (const char *relpath, apr_pool_t *result_pool)
char * svn_dirent_join (const char *base, const char *component, apr_pool_t *result_pool)
char * svn_dirent_join_many (apr_pool_t *result_pool, const char *base,...)
char * svn_relpath_join (const char *base, const char *component, apr_pool_t *result_pool)
const char * svn_dirent_basename (const char *dirent, apr_pool_t *result_pool)
char * svn_dirent_dirname (const char *dirent, apr_pool_t *result_pool)
void svn_dirent_split (const char **dirpath, const char **base_name, const char *dirent, apr_pool_t *result_pool)
void svn_relpath_split (const char **dirpath, const char **base_name, const char *relpath, apr_pool_t *result_pool)
const char * svn_relpath_basename (const char *relpath, apr_pool_t *result_pool)
char * svn_relpath_dirname (const char *relpath, apr_pool_t *result_pool)
void svn_uri_split (const char **dirpath, const char **base_name, const char *uri, apr_pool_t *result_pool)
const char * svn_uri_basename (const char *uri, apr_pool_t *result_pool)
char * svn_uri_dirname (const char *uri, apr_pool_t *result_pool)
svn_boolean_t svn_dirent_is_absolute (const char *dirent)
svn_boolean_t svn_dirent_is_root (const char *dirent, apr_size_t len)
svn_boolean_t svn_uri_is_root (const char *uri, apr_size_t len)
const char * svn_dirent_canonicalize (const char *dirent, apr_pool_t *result_pool)
const char * svn_relpath_canonicalize (const char *relpath, apr_pool_t *result_pool)
const char * svn_uri_canonicalize (const char *uri, apr_pool_t *result_pool)
svn_boolean_t svn_dirent_is_canonical (const char *dirent, apr_pool_t *scratch_pool)
svn_boolean_t svn_relpath_is_canonical (const char *relpath)
svn_boolean_t svn_uri_is_canonical (const char *uri, apr_pool_t *scratch_pool)
char * svn_dirent_get_longest_ancestor (const char *dirent1, const char *dirent2, apr_pool_t *result_pool)
char * svn_relpath_get_longest_ancestor (const char *relpath1, const char *relpath2, apr_pool_t *result_pool)
char * svn_uri_get_longest_ancestor (const char *uri1, const char *uri2, apr_pool_t *result_pool)
svn_error_tsvn_dirent_get_absolute (const char **pabsolute, const char *relative, apr_pool_t *result_pool)
const char * svn_dirent_is_child (const char *parent_dirent, const char *child_dirent, apr_pool_t *result_pool)
svn_boolean_t svn_dirent_is_ancestor (const char *parent_dirent, const char *child_dirent)
svn_boolean_t svn_uri__is_ancestor (const char *parent_uri, const char *child_uri)
const char * svn_dirent_skip_ancestor (const char *parent_dirent, const char *child_dirent)
const char * svn_relpath_skip_ancestor (const char *parent_relpath, const char *child_relpath)
const char * svn_uri_skip_ancestor (const char *parent_uri, const char *child_uri, apr_pool_t *result_pool)
svn_error_tsvn_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)
svn_error_tsvn_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)
svn_error_tsvn_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)
svn_error_tsvn_uri_get_dirent_from_file_url (const char **dirent, const char *url, apr_pool_t *result_pool)
svn_error_tsvn_uri_get_file_url_from_dirent (const char **url, const char *dirent, apr_pool_t *result_pool)

Detailed Description

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

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:

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:

The Subversion codebase also recognizes some other classes of path:

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

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

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.
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.

Since:
New in 1.6.
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.
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_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.
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.
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.

Since:
New in 1.6.
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_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_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.
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_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_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.
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.
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 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.
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.
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.
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.
const char* svn_relpath__internal_style ( const char *  relpath,
apr_pool_t result_pool 
)

Convert relpath 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.

Since:
New in 1.7.
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.
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.

Since:
New in 1.7.
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.
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_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.
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.
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 or equal to parent_relpath, return NULL.

Since:
New in 1.7.
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_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_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.
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.

Since:
New in 1.7.
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.
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_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_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.
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_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_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
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 or equal to parent_uri, return NULL.

Allocate the result in result_pool.

Since:
New in 1.7.
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.