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


Generated on Mon Nov 26 11:23:52 2007 for Apache Portable Runtime by  doxygen 1.5.2