pathutils(3x) — HP-UX C++ A.03.20

NAME

pathbase, pathdir, pathcollapse, pathrel − various file-path manipulation utilities

SYNOPSIS

#include <codelib/pathutils.h>
char *pathbase(char *src);
const char *pathbase(const char *src);
char *pathdir(const char *src, char *dst = NULL);
char *pathcollapse(const char *src, char *dst = NULL,
boolean show_dir = FALSE);
char *pathrel(const char *dir, const char *src, char *dst = NULL);
CC ... -lcodelibs

DESCRIPTION

These functions provide some convenient ways to manage file-path names. With the exception of pathbase, all of the functions accept both a src and a dst argument. Src should be a pointer to the source path, and dst should be one of the following three values:

NULL Indicates that the function should allocate space for the result using malloc(3C). The user should free the returned value using free(3C).

src Indicates that the source path should be modified in place. The results of all pathutils(3X) functions except pathrel(3X) will be shorter or the same length as the original value.

OTHER A pointer to a suitably sized buffer to hold the result.

pathbase

Pathbase returns a pointer into src which points to the base name (see basename(1)) of the path. The base name of a path is the portion of the string following the last ´/´ character. If the ´/´ character does not occur in src, then src will be returned. If src ends in a ´/´, a pointer to the trailing NULL (´\0´) character will be returned.

pathdir

Pathdir returns the directory portion of a path, which is the portion of a string up to the last ´/´ character (see dirname(1)). If there is no ´/´ in the path, then the string "." is returned for the current directory. If the path is ´/´, then the entire path is returned.

pathcollapse

Pathcollapse collapses src into its simplest form. This is done by removing redundant ´/´ characters and ´.´ components, as well as removing ´directory/..´ pairs, where possible. Trailing ´/´ characters are considered to be redundant.

This simplification is done without examining the filesystem, so removal of redundant HP−UX context-dependent file components is not done. Also, relative pathnames will remain relative, and absolute pathnames will remain absolute.

If the show_dir argument is TRUE, a redundant trailing ´/´ character will be appended to the resulting path if the original appeared to refer to a directory. Specifically, a trailing slash will be present if the original path ended in ´/´, or if it ended in a ´.´ or ´..´ component.

pathrel

Pathrel converts the path in src into a path that is relative to dir. The paths in src and dir must both be absolute or both be relative, otherwise NULL is returned.

NOTES

Supports ANSI-C multi-byte strings

Pathutils provides the following interface for C and ANSI C since overloading isn’t supported:

char *pathbase(const char *src);

WARNINGS

The result of pathrel may be longer that src path. If dst points to src, it is the caller’s responsibility to ensure that dst is large enough to hold the result.

Incorrect results may be returned if paths containing symbolic links are passed to pathcollapse or pathrel.

Since pathcollapse does not examine the filesystem, an invalid path may inadvertently be made valid. For example, “/tmp/xxx/..” would become “/tmp” even if the directory “/tmp/xxx” didn’t exist. If this condition needs to be detected, simply check the original path using access(2) before simplifying.

Museum

Related Articles