Path Processing

Routines for manipulating path strings. More...

Collaboration diagram for Path Processing:

Files
file	path.h

Macros
#define	BU_PATH_MATCH_NOMATCH   1
#define	BU_PATH_MATCH_NOESCAPE   0x01
#define	BU_PATH_MATCH_PATHNAME   0x02
#define	BU_PATH_MATCH_PERIOD   0x04
#define	BU_PATH_MATCH_LEADING_DIR   0x08
#define	BU_PATH_MATCH_CASEFOLD   0x10

Enumerations
enum	bu_path_component_t {   BU_PATH_DIRNAME , BU_PATH_BASENAME , BU_PATH_BASENAME_EXTLESS , BU_PATH_EXT ,   BU_PATH_EXTLESS , BU_PATH_UNKNOWN }

Functions
char *	bu_path_dirname (const char *path)
char *	bu_path_basename (const char *path, char *basename)
const char *	bu_path_normalize (const char *path)
int	bu_path_component (struct bu_vls *component, const char *path, bu_path_component_t type)
char **	bu_path_to_argv (const char *path, int *ac)
int	bu_path_match (const char *pattern, const char *pathname, int flags)

Detailed Description

Routines for manipulating path strings.

operating system and geometry database path strings.

Typically being used for operating system and geometry database path strings, routines in this header do NOT have knowledge of or access the filesystem. They will not check for the presence or absence of objects on disk or in a geometry database - they operate only on the the path string itself. Any validation of the path is the responsibility of the caller or other routines.

Macro Definition Documentation

BU_PATH_MATCH_NOMATCH

#define BU_PATH_MATCH_NOMATCH   1

Definition at line 189 of file path.h.

BU_PATH_MATCH_NOESCAPE

#define BU_PATH_MATCH_NOESCAPE   0x01

bu_path_match() flag: Backslash is ordinary character, not an escape character.

Definition at line 195 of file path.h.

BU_PATH_MATCH_PATHNAME

#define BU_PATH_MATCH_PATHNAME   0x02

bu_path_match() flag: Match a slash in pathname only with a slash in pattern and not by an asterisk or a question mark metacharacter, nor by a bracket expression containing a slash.

Definition at line 203 of file path.h.

BU_PATH_MATCH_PERIOD

#define BU_PATH_MATCH_PERIOD   0x04

bu_path_match() flag: Leading period in pathname has to be matched exactly by a period in pattern.

Definition at line 208 of file path.h.

BU_PATH_MATCH_LEADING_DIR

#define BU_PATH_MATCH_LEADING_DIR   0x08

bu_path_match() flag: Ignore /[tail] after Imatch.

Definition at line 212 of file path.h.

BU_PATH_MATCH_CASEFOLD

#define BU_PATH_MATCH_CASEFOLD   0x10

bu_path_match() flag: Case-insensitive matching.

Definition at line 217 of file path.h.

Enumeration Type Documentation

bu_path_component_t

enum bu_path_component_t

Components of a path recognized by bu_path_component(), identified below in the context of the example path:

/dir1/dir2/file.ext

Enumerator
BU_PATH_DIRNAME	/dir1/dir2
BU_PATH_BASENAME	file.ext
BU_PATH_BASENAME_EXTLESS	file
BU_PATH_EXT	ext
BU_PATH_EXTLESS	/dir1/dir2/file
BU_PATH_UNKNOWN	marks end of bu_path_component_t enums

Definition at line 157 of file path.h.

Function Documentation

bu_path_dirname()

char * bu_path_dirname

(

const char *

path

)

Given a string containing a hierarchical path, return a dynamic string to the parent path.

This function is similar if not identical to most dirname() BSD system function implementations; but that system function cannot be used due to significantly inconsistent behavior across platforms.

This function always recognizes paths separated by a '/' (i.e., geometry paths) as well as whatever the native platform directory separator may be. It is assumed that all file and directory names in the path will not contain a path separator, even if escaped.

It is the caller's responsibility to bu_free() the pointer returned from this routine.

Examples of strings returned:

Input String	Output String
/usr/dir/file	/usr/dir
/usr/dir/	/usr
/usr/file	/usr
/usr/	/
/usr	/
/	/
.	.
..	.
usr	.
a/b	a
a/	.
../a/b	../a

This routine will return "." if other valid results are not available but should never return NULL.

bu_path_basename()

char * bu_path_basename	(	const char *	path,
		char *	basename
	)

A libbu re-implementation of basename() for cross-platform compatibility.

Given a string containing a hierarchically delimited path (e.g., /path/to/file), determine the file name portion after the last path separator.

This function is similar to most basename() BSD system function implementations; but that system function cannot be used due to significantly inconsistent behavior across platforms, particularly with respect to memory allocation and threading behavior.

This function always recognizes paths separated by a '/' (i.e., geometry paths) as well as whatever the native platform directory separator may be. It is assumed that all file and directory names in the path do not contain a path separator. That is, there is currently no support for escaped characters.

It is the caller's responsibility to provide a basename buffer with enough memory for a string with length at least strlen(path) + 1 (for terminating nul) characters as that is the maximum possible basename size. If the basename output argument is NULL, then dynamic memory will be returned and the caller is responsible for releasing memory (via bu_free()), otherwise the caller-provided basename pointer is returned and managed by the caller accordingly.

Examples of strings returned:

Input String	Output String
/usr/dir/file	file
/usr/dir/	dir
/usr/	usr
/usr	usr
/	/
.	.
..	..
usr	usr
a/b	b
a/	a
///	/

bu_path_normalize()

const char * bu_path_normalize

(

const char *

path

)

Normalize a path according to rules used for realpath, but without filesystem (or database object) validation.

Returns

A STATIC buffer is returned. It is the caller's responsibility to call bu_strdup() or make other provisions to save the returned string, before calling again.

bu_path_component()

int bu_path_component	(	struct bu_vls *	component,
		const char *	path,
		bu_path_component_t	type
	)

Identify components of a file path such as the filename (basename), file extension, directory path (dirname) and more.

Returns truthfully (non-zero) if the specified component type was found in the provided path. A copy of the component will be written to the 'component' vls if non-NULL.

bu_path_to_argv()

char ** bu_path_to_argv	(	const char *	path,
		int *	ac
	)

Generate an argv array from a path

Given a path string, separate the path elements into a dynamically allocated argv array with the path separators removed. It is the caller's responsibility to free the array that is returned as well as all elements in the array using bu_argv_free() or manually calling bu_free().

bu_path_match()

int bu_path_match	(	const char *	pattern,
		const char *	pathname,
		int	flags
	)

Compares a string filename or pathname to a pattern.

This is a portable implementation of the fnmatch() function as specified in POSIX 1003.2-1992, section B.6.

Returns 0 if a match is found or 1 otherwise.