ossp-pkg/path/path.pod
1.1.1.1
=pod
=head1 NAME
B<path> - Filesystem Path Manipulation Library
=head1 SYNOPSIS
#include "path.h"
char *B<path_abs2rel>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>, const char *I<base>);
char *B<path_rel2abs>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>, const char *I<base>);
char *B<path_resolve>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
char *B<path_dirname>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
char *B<path_basename>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
=head1 DESCRIPTION
B<Path> is a filesystem path conversion library. It allows one to
convert between absolute and relative paths and to resolve symlinks in a
path. The following Application Programming Interface (API) is provided
for this:
=over 4
=item char *B<path_abs2rel>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>, const char *I<base>);
This function make a relative path name from an absolute path name
I<path> based on a reference directory I<base>. The generated relative
path name is stored into the caller supplied buffer at I<outbuf>, but
never more than I<outsize> bytes are written. The resulting path name
may include symbolic links. The function doesn't check whether or not
any path exists. The function returns a pointer to I<outbuf> (the
relative path name) on success, and C<NULL> on error.
The function may fail with the following errors and set the external
variable C<errno> to indicate the particular error: C<EINVAL> (the
I<base> directory isn't an absolute path name or the I<outsize> argument
is zero) or C<ERANGE> (the I<outsize> argument is greater than zero but
smaller than the length of the pathname plus 1).
=item char *B<path_rel2abs>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>, const char *I<base>);
This function make an absolute path name from a relative path name
I<path> based on a reference directory I<base>. The generated absolute
path name is stored into the caller supplied buffer at I<outbuf>, but
never more than I<outsize> bytes are written. The resulting path name
may include symbolic links. The function doesn't check whether or not
any path exists. The function returns a pointer to I<outbuf> (the
absolute path name) on success, and C<NULL> on error.
The function may fail with the following errors and set the external
variable C<errno> to indicate the particular error: C<EINVAL> (the
I<base> directory isn't an absolute path name or the I<outsize> argument
is zero) or C<ERANGE> (the I<outsize> argument is greater than zero but
smaller than the length of the pathname plus 1).
=item char *B<path_resolve>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
This function resolves a path name I<path> into the corresponding
canonicalized absolute pathname. The generated absolute path name is
stored into the caller supplied buffer at I<outbuf>, but never more
than I<outsize> bytes are written. The function is capable to resolve
symbolic links, extra "C</>" characters and references to "C</./>" and
"C</../>". The function returns a pointer to I<outbuf> (the resolved
path name) on success, and C<NULL> on error.
The function may fail with an error and set the external variable
C<errno> for any of the errors specified for the library functions
chdir(2), close(2), fchdir(2), lstat(2), open(2), readlink(2) and
getcwd(3).
=item char *B<path_dirname>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
This function extracts the directory filename part from I<path> and stores it
into the caller supplied buffer at I<outbuf>, but never more than I<outsize>
bytes are written. The function returns a pointer to I<outbuf> on success,
and C<NULL> on error.
=item char *B<path_basename>(char *I<outbuf>, const size_t I<outsize>, const char *I<path>);
This function extracts the base filename part from I<path> and stores it into
the caller supplied buffer at I<outbuf>, but never more than I<outsize> bytes
are written. The function returns a pointer to I<outbuf> on success, and
C<NULL> on error.
=back
=head1 EXAMPLE
char result[MAXPATHLEN];
char *path = path_abs2rel(result, sizeof(result), "/usr/src/sys", "/usr/local/lib");
yields:
path == "../../src/sys"
Similarly,
path1 = path_abs2rel(result, sizeof(result), "/usr/src/sys", "/usr");
path2 = path_abs2rel(result, sizeof(result), "/usr/src/sys", "/usr/src/sys");
yields:
path1 == "src/sys"
path2 == "."
And
char *path = path_rel2abs(result, sizeof(result), "../../src/sys", "/usr/local/lib");
yields:
path == "/usr/src/sys"
Similarly,
path1 = rel2abs(result, sizeof(result), "src/sys", "/usr");
path2 = rel2abs(result, sizeof(result), ".", "/usr/src/sys");
yields:
path1 == "/usr/src/sys"
path2 == "/usr/src/sys"
=head1 BUGS
If the base directory includes symbolic links, the abs2rel(3) function
produces the wrong path. For example, if 'C</sys>' is a symbolic link to
'C</usr/src/sys>',
char *path = path_abs2rel(result, sizeof(result), "/usr/local/lib", "/sys");
yields:
path == "../usr/local/lib" /* It's wrong!! */
You should convert the base directory into a real path in advance.
path = path_abs2rel(result, sizeof(result),
"/sys/kern",
path_resolve(result2, sizeof(result2), "/sys"));
This then yields:
path == "../../../sys/kern" /* It's correct but ... */
That is correct, but a little redundant. If you wish get the simple an-
swer 'C<kern>', do the following.
path = path_abs2rel(r0, sizeof(r0),
path_resolve(r1, sizeof(r1), "/sys/kern"),
path_resolve(r2, sizeof(r2), "/sys"));
The path_resolve(3) function assures correct result, but don't forget
that path_resolve(3) requires that all but the last component of the
path exist.
=head1 SEE ALSO
=head1 AUTHORS
The path_abs2rel() and path_rel2abs() function was originally written in
December 1997 by I<Shigio Yamaguchi> for his I<PathConvert> project. The
path_resolve() function is derived from FreeBSD's realpath(3) function
which was written in February 1994 by I<Jan-Simon Pendry>. The work off
of this code and the B<Path> library as a whole was written in January
2000 by I<Ralf S. Engelschall>.
=cut