##
##  OSSP path - Filesystem Path Manipulation
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002-2003 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2003 Cable & Wireless Deutschland <http://www.cw.com/de/>
##
##  This file is part of OSSP path, a filesystem path manipulation library
##  which can be found at http://www.ossp.org/pkg/lib/path/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  path.pod: manual page
##

=pod

=head1 NAME

B<OSSP path> - Filesystem Path Manipulation

=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<OSSP path> is a filesystem path manipulation library. It allows one
to convert between absolute and relative paths and to resolve symbolic
links in a path.

=head1 APPLICATION PROGRAMMING INTERFACE (API)

The following Application Programming Interface (API) is provided by
B<OSSP path>:

=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

The code

 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
answer '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(3) and path_rel2abs(3) function was originally written
in December 1997 by I<Shigio Yamaguchi> for his I<PathConvert> project.
The path_resolve(3) 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<OSSP path> library as a whole was
written in January 2000 by I<Ralf S. Engelschall> for use in the B<OSSP>
project.

=cut