home-etc: doc/path_canonize.3 (NEW), doc/get_home_etc.3, doc/home_...
siefca
siefca at pld-linux.org
Wed May 17 23:30:37 CEST 2006
Author: siefca Date: Wed May 17 21:30:37 2006 GMT
Module: home-etc Tag: HEAD
---- Log message:
- documentation updated
- path_canonize improved
---- Files affected:
home-etc/doc:
path_canonize.3 (NONE -> 1.1) (NEW), get_home_etc.3 (1.6 -> 1.7) , home_etc_expand_tilde.3 (1.2 -> 1.3) , home_etc_path.3 (1.8 -> 1.9)
home-etc/src:
core.c (1.20 -> 1.21) , realpath.c (1.1 -> 1.2)
---- Diffs:
================================================================
Index: home-etc/doc/path_canonize.3
diff -u /dev/null home-etc/doc/path_canonize.3:1.1
--- /dev/null Wed May 17 23:30:37 2006
+++ home-etc/doc/path_canonize.3 Wed May 17 23:30:32 2006
@@ -0,0 +1,87 @@
+.\" Copyright (c) 2006 by Paweł Wilk <siefca at gnu.org>
+.\"
+.\" Permission is granted to copy, distribute and/or modify this document
+.\" under the terms of the GNU Free Documentation License, Version 1.2
+.\" or any later version published by the Free Software Foundation;
+.\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+.\" A copy of the license is included in the section entitled "GNU
+.\" Free Documentation License"; if it's not, contact Free Software Foundation, Inc.
+.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain one.
+.\"
+.TH path_canonize "3" "PLD Linux/GNU" "May 2006" "HOME-ETC"
+.SH NAME
+path_canonize \- pathname canonizer
+.SH SYNOPSIS
+.nf
+.B #include <home_etc.h>
+.sp
+.BI "const char *path_canonize(const char *" pathname ", char " use_env );
+.fi
+.SH DESCRIPTION
+This function tries to make the given \fIpathname\fP absolute.
+It tries to canonize as much parts of the found subdirectories as
+it is possible.
+
+If \fBhome_etc_expand_tile(3)\fP has been used before to enable
+tilde-slash pair parsing, the function treats \fI~/\fP as if it
+was user's home directory path (in fact it internally replaces it first
+and then goes to re-parse it, to make sure that the home directory is ok).
+Additionally, the \fI~\fP character is also translated into user's home
+directory name, but only if the whole parsed path contains only that
+one character. The \fIuse_env\fP is a swich which determines the method
+to obtain user's home directory. If it's set to 1 home directory is
+obtained using \fIHOME\fP environment variable. If it is set to 0,
+then the home directory is taken from system by calling \fBgetpwuid(3)\fP.
+
+It uses filesystem calls \fBchdir(2)\fP and \fBgetcwd(3)\fP to canonize
+accessible parts of the given pathname. It also tries to use simple
+string substitution to canonize parts of the given pathname, which
+are unseen or unaccessible for a current process. It does it by
+parsing strings such as \fI..\fP and \fI.\fP and multiple \fI/\fP
+and replaces parts of the pathname according to known logic.
+
+If it is possible this function checks the last part of the given
+pathname and removes trailing slash when the last part is a file,
+not a directory. For directories in fact, it does not removes the
+trailer when it was found in the pathname nor adds it.
+
+.SH "RETURN VALUE"
+This function returns the pointer to a static buffer containing
+the newly generated pathname or NULL if something went bad.
+
+.SH EXAMPLES
+for HOME=\fI/home/users/siefca\fP
+.sp
+this function call:
+.sp
+.BI "_HE_LIKE_TILDE;
+.BI "home_etc_path("""~/././../siefca/.muttrc/ """, " 1 );
+.sp
+will return:
+.I /home/users/siefca/.muttrc
+
+.SH WARNINGS
+Be ware of setting \fBuse_env\fP to non-zero for deamons
+which can inherit the environment variables at start and
+are not setting it again when changing the UID/EUID. These
+are daemons, that (so-called) aren't touching users' environment.
+In such cases you may get false results.
+
+The static buffer has a length of a MAXPATHLEN bytes. In case of
+a larger strings the NULL is generated while parsing.
+
+.SH "SEE ALSO"
+.BR home_etc_expand_tile(3),
+.BR chdir(2),
+.BR getcwd(3),
+.BR getpwuid(3)
+
+.SH LICENSE
+The HOME-ETC library is distributed under the terms of GNU LGPL.
+This documentation is distributed under the terms of GNU FDL.
+
+.SH AUTHOR
+Pawel Wilk <siefca at gnu.org>
+There was also a lot of other people, who have contributed to this code
+and/or helped with patching applications. See the AUTHORS and the CONTRIBUTORS files.
+
================================================================
Index: home-etc/doc/get_home_etc.3
diff -u home-etc/doc/get_home_etc.3:1.6 home-etc/doc/get_home_etc.3:1.7
--- home-etc/doc/get_home_etc.3:1.6 Wed May 17 03:50:04 2006
+++ home-etc/doc/get_home_etc.3 Wed May 17 23:30:32 2006
@@ -113,11 +113,12 @@
a larger strings the NULL is generated while parsing.
.SH "SEE ALSO"
-.BR getenv(3),
-.BR getpwnam(3),
.BR home_etc(3),
.BR home_etc_path(3),
-.BR home_etc_reset(3)
+.BR home_etc_reset(3),
+.BR getenv(3),
+.BR getpwuid(3)
+
.SH LICENSE
The HOME-ETC library is distributed under the terms of GNU LGPL.
================================================================
Index: home-etc/doc/home_etc_expand_tilde.3
diff -u home-etc/doc/home_etc_expand_tilde.3:1.2 home-etc/doc/home_etc_expand_tilde.3:1.3
--- home-etc/doc/home_etc_expand_tilde.3:1.2 Wed May 17 16:41:17 2006
+++ home-etc/doc/home_etc_expand_tilde.3 Wed May 17 23:30:32 2006
@@ -31,8 +31,11 @@
path contains only that one character.
The way to obtain user's home directory depends on method choosen while
-invoking \fBhome_etc_path(3)\fP (see \fIuse_env\fP description in the
-manual).
+invoking \fBhome_etc_path(3)\fP. The \fIuse_env\fP is a swich which
+determines the method to obtain user's home directory. If it's set
+to 1 home directory is obtained using \fIHOME\fP environment variable.
+If it is set to 0, then the home directory is taken from system
+by calling \fBgetpwuid(3)\fP.
Once invoked this function keeps last setting memorized. The parsing
by default is in state DISABLED.
@@ -62,6 +65,7 @@
.BR home_etc_path(3),
.BR get_home_etc(3),
.BR get_home_etc_static(3)
+.BR getpwuid(3)
.SH LICENSE
The HOME-ETC library is distributed under the terms of GNU LGPL.
================================================================
Index: home-etc/doc/home_etc_path.3
diff -u home-etc/doc/home_etc_path.3:1.8 home-etc/doc/home_etc_path.3:1.9
--- home-etc/doc/home_etc_path.3:1.8 Wed May 17 16:41:17 2006
+++ home-etc/doc/home_etc_path.3 Wed May 17 23:30:32 2006
@@ -81,7 +81,7 @@
.sp
.BI "home_etc_path("""/home/users/siefca/.muttrc """, " 1 );
.sp
-or a pair:
+or:
.sp
.BI "home_etc_expand_tilde(" 1 );
.BI "home_etc_path("""~/.muttrc """, " 1 );
@@ -224,14 +224,22 @@
which can inherit the environment variables at start and
are not setting it again when changing the UID/EUID. These
are daemons, that (so-called) aren't touching users' environment.
-In such cases you may get a false results.
+In such cases you may get false results.
The static buffer has a length of a MAXPATHLEN bytes. In case of
a larger strings the NULL is generated while parsing.
-If you want the very current informations and need to refresh
-the cache used to store the \fBHOME_ETC\fP pathname use \fBhome_etc_reset(3)\fP function
-just before \fBhome_etc_path(3)\fP or its wrappers.
+If you want to get the very current informations
+and need to refresh the cache used to store the \fBHOME_ETC\fP
+pathname use \fBhome_etc_reset(3)\fP function just before
+\fBhome_etc_path(3)\fP or its wrappers.
+
+The resulting path may be canonized (absolutized), but may be not,
+or may be canonized partially. It depends on how big portion
+of the given pathname the function was able to resolve by accessing
+the filesystem. If you want your resulting path to be fully canonized
+you will probably have to use the \fBpath_canonize(3)\fP function
+to postprocess the result.
.SH "SEE ALSO"
.BR home_etc(3),
@@ -239,6 +247,7 @@
.BR home_etc_reset(3),
.BR get_home_etc(3),
.BR get_home_etc_static(3),
+.BR path_canonize(3),
.BR chdir(2),
.BR getcwd(3)
================================================================
Index: home-etc/src/core.c
diff -u home-etc/src/core.c:1.20 home-etc/src/core.c:1.21
--- home-etc/src/core.c:1.20 Wed May 17 16:28:45 2006
+++ home-etc/src/core.c Wed May 17 23:30:32 2006
@@ -180,7 +180,7 @@
/* and unresolvable part of the pathname */
/* rebirth our paths by eliminating zeroes from prev. oper. */
- p = pbuff;
+ p = q;
while(p < pbuff+s)
{
if(*p == '\0')
================================================================
Index: home-etc/src/realpath.c
diff -u home-etc/src/realpath.c:1.1 home-etc/src/realpath.c:1.2
--- home-etc/src/realpath.c:1.1 Wed May 17 18:14:28 2006
+++ home-etc/src/realpath.c Wed May 17 23:30:32 2006
@@ -18,13 +18,13 @@
{
int er = 0;
const char *r = NULL;
- const char **p = NULL;
+ char **p = NULL;
_HE_LIKE_TILDE;
if (argc < 2)
{
- fprintf(stderr, "usage: realpath path [...]\n");
+ fprintf(stderr, "usage: realpath pathname [pathname ...]\n");
exit(1);
}
================================================================
---- CVS-web:
http://cvs.pld-linux.org/home-etc/doc/get_home_etc.3?r1=1.6&r2=1.7&f=u
http://cvs.pld-linux.org/home-etc/doc/home_etc_expand_tilde.3?r1=1.2&r2=1.3&f=u
http://cvs.pld-linux.org/home-etc/doc/home_etc_path.3?r1=1.8&r2=1.9&f=u
http://cvs.pld-linux.org/home-etc/src/core.c?r1=1.20&r2=1.21&f=u
http://cvs.pld-linux.org/home-etc/src/realpath.c?r1=1.1&r2=1.2&f=u
More information about the pld-cvs-commit
mailing list