=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