Filepath Manipulation Functions
[File Information]

Defines
#define	APR_FILEPATH_NOTABOVEROOT   0x01
#define	APR_FILEPATH_SECUREROOTTEST   0x02
#define	APR_FILEPATH_SECUREROOT   0x03
#define	APR_FILEPATH_NOTRELATIVE   0x04
#define	APR_FILEPATH_NOTABSOLUTE   0x08
#define	APR_FILEPATH_NATIVE   0x10
#define	APR_FILEPATH_TRUENAME   0x20
#define	APR_FILEPATH_ENCODING_UNKNOWN   0
#define	APR_FILEPATH_ENCODING_LOCALE   1
#define	APR_FILEPATH_ENCODING_UTF8   2
Functions
apr_status_t	apr_filepath_root (const char **rootpath, const char **filepath, apr_int32_t flags, apr_pool_t *p)
apr_status_t	apr_filepath_merge (char **newpath, const char *rootpath, const char *addpath, apr_int32_t flags, apr_pool_t *p)
apr_status_t	apr_filepath_list_split (apr_array_header_t **pathelts, const char *liststr, apr_pool_t *p)
apr_status_t	apr_filepath_list_merge (char **liststr, apr_array_header_t *pathelts, apr_pool_t *p)
apr_status_t	apr_filepath_get (char **path, apr_int32_t flags, apr_pool_t *p)
apr_status_t	apr_filepath_set (const char *path, apr_pool_t *p)
apr_status_t	apr_filepath_encoding (int *style, apr_pool_t *p)

---

Define Documentation

#define APR_FILEPATH_ENCODING_LOCALE   1

The FilePath character encoding is locale-dependent

#define APR_FILEPATH_ENCODING_UNKNOWN   0

The FilePath character encoding is unknown

#define APR_FILEPATH_ENCODING_UTF8   2

The FilePath character encoding is UTF-8

#define APR_FILEPATH_NATIVE   0x10

Return the file system's native path format (e.g. path delimiters of ':' on MacOS9, '\' on Win32, etc.)

#define APR_FILEPATH_NOTABOVEROOT   0x01

Cause apr_filepath_merge to fail if addpath is above rootpath

#define APR_FILEPATH_NOTABSOLUTE   0x08

Fail apr_filepath_merge if the merged path is absolute

#define APR_FILEPATH_NOTRELATIVE   0x04

Fail apr_filepath_merge if the merged path is relative

#define APR_FILEPATH_SECUREROOT   0x03

Cause apr_filepath_merge to fail if addpath is above rootpath, even given a rootpath /foo/bar and an addpath ../bar/bash

#define APR_FILEPATH_SECUREROOTTEST   0x02

internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT

#define APR_FILEPATH_TRUENAME   0x20

Resolve the true case of existing directories and file elements of addpath, (resolving any aliases on Win32) and append a proper trailing slash if a directory

---

Function Documentation

apr_status_t apr_filepath_encoding	(	int *	style,
		apr_pool_t *	p
	)

Determine the encoding used internally by the FilePath functions

Parameters:

	style	points to a variable which receives the encoding style flag
	p	the pool to allocate any working storage

Remarks:

Use apr_os_locale_encoding and/or apr_os_default_encoding to get the name of the path encoding if it's not UTF-8.

apr_status_t apr_filepath_get	(	char **	path,
		apr_int32_t	flags,
		apr_pool_t *	p
	)

Return the default file path (for relative file names)

Parameters:

	path	the default path string returned
	flags	optional flag APR_FILEPATH_NATIVE to retrieve the default file path in os-native format.
	p	the pool to allocate the default path string from

apr_status_t apr_filepath_list_merge	(	char **	liststr,
		apr_array_header_t *	pathelts,
		apr_pool_t *	p
	)

Merge a list of search path components into a single search path

Parameters:

	liststr	the returned search path; may be NULL if pathelts is empty
	pathelts	the components of the search path
	p	the pool to allocate the search path from

Remarks:

emtpy strings in the source array are ignored.

the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

apr_status_t apr_filepath_list_split	(	apr_array_header_t **	pathelts,
		const char *	liststr,
		apr_pool_t *	p
	)

Split a search path into separate components

Parameters:

	pathelts	the returned components of the search path
	liststr	the search path (e.g., getenv("PATH"))
	p	the pool to allocate the array and path components from

Remarks:

empty path componenta do not become part of pathelts.

the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

apr_status_t apr_filepath_merge	(	char **	newpath,
		const char *	rootpath,
		const char *	addpath,
		apr_int32_t	flags,
		apr_pool_t *	p
	)

Merge additional file path onto the previously processed rootpath

Parameters:

	newpath	the merged paths returned
	rootpath	the root file path (NULL uses the current working path)
	addpath	the path to add to the root path
	flags	the desired APR_FILEPATH_ rules to apply when merging
	p	the pool to allocate the new path string from

Remarks:

if the flag APR_FILEPATH_TRUENAME is given, and the addpath contains wildcard characters ('*', '?') on platforms that don't support such characters within filenames, the paths will be merged, but the result code will be APR_EPATHWILD, and all further segments will not reflect the true filenames including the wildcard and following segments.

apr_status_t apr_filepath_root	(	const char **	rootpath,
		const char **	filepath,
		apr_int32_t	flags,
		apr_pool_t *	p
	)

Extract the rootpath from the given filepath

Parameters:

	rootpath	the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
	filepath	the pathname to parse for its root component
	flags	the desired rules to apply, from APR_FILEPATH_NATIVE Use native path seperators (e.g. '\' on Win32) APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper
	p	the pool to allocate the new path string from

Remarks:

on return, filepath points to the first non-root character in the given filepath. In the simplest example, given a filepath of "/foo", returns the rootpath of "/" and filepath points at "foo". This is far more complex on other platforms, which will canonicalize the root form to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also test for the validity of that root (e.g., that a drive d:/ or network share //machine/foovol/). The function returns APR_ERELATIVE if filepath isn't rooted (an error), APR_EINCOMPLETE if the root path is ambigious (but potentially legitimate, e.g. "/" on Windows is incomplete because it doesn't specify the drive letter), or APR_EBADPATH if the root is simply invalid. APR_SUCCESS is returned if filepath is an absolute path.

apr_status_t apr_filepath_set	(	const char *	path,
		apr_pool_t *	p
	)

Set the default file path (for relative file names)

Parameters:

	path	the default path returned
	p	the pool to allocate any working storage

---