ossp-pkg/path/path.pod
##
## 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
