*** /dev/null Sun Apr 28 16:52:11 2024
--- - Sun Apr 28 16:54:50 2024
***************
*** 0 ****
--- 1,176 ----
+
+ =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
+
|
