From 40b6f0c8bf1edab6618ea5c61cea14cf3a5c5443 Mon Sep 17 00:00:00 2001 From: vincentdarley Date: Fri, 12 Dec 2003 17:02:13 +0000 Subject: improved filesystem documentation --- doc/file.n | 19 +++++++++------- doc/filename.n | 71 +++++++++++++++++++++++++++++----------------------------- doc/glob.n | 9 +++++++- 3 files changed, 55 insertions(+), 44 deletions(-) diff --git a/doc/file.n b/doc/file.n index ce699aa..0658009 100644 --- a/doc/file.n +++ b/doc/file.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: file.n,v 1.25 2003/07/07 08:57:58 vincentdarley Exp $ +'\" RCS: @(#) $Id: file.n,v 1.26 2003/12/12 17:02:13 vincentdarley Exp $ '\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" @@ -220,13 +220,16 @@ error if for some reason that is not possible), then the optional \fI-linktype\fR argument should be given. Accepted values for \fI-linktype\fR are "-symbolic" and "-hard". . -When creating links on filesystems that either do not support any links, -or do not support the specific type requested, an error message will be -returned. In particular Windows 95, 98 and ME do not support any links -at present, but most Unix platforms support both symbolic and hard links -(the latter for files only), MacOS supports symbolic links and Windows -NT/2000/XP (on NTFS drives) support symbolic directory links and hard -file links. +On Unix, symbolic links can be made to relative paths, but on all other +platforms target paths will be converted to absolute, normalized form +before the link is created (and "~user" paths are always expanded to +absolute form). When creating links on filesystems that +either do not support any links, or do not support the specific type +requested, an error message will be returned. In particular Windows 95, +98 and ME do not support any links at present, but most Unix platforms +support both symbolic and hard links (the latter for files only), MacOS +supports symbolic links and Windows NT/2000/XP (on NTFS drives) support +symbolic directory links and hard file links. .TP \fBfile lstat \fIname varName\fR . diff --git a/doc/filename.n b/doc/filename.n index de77d8c..5427c1d 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: filename.n,v 1.8 2003/09/16 14:56:08 vincentdarley Exp $ +'\" RCS: @(#) $Id: filename.n,v 1.9 2003/12/12 17:02:13 vincentdarley Exp $ '\" .so man.macros .TH filename n 7.5 Tcl "Tcl Built-In Commands" @@ -45,16 +45,16 @@ The rules for native names depend on the value reported in the Tcl array element \fBtcl_platform(platform)\fR: .TP 10 \fBmac\fR -On Apple Macintosh systems, Tcl supports two forms of path names. The -normal Mac style names use colons as path separators. Paths may be -relative or absolute, and file names may contain any character other -than colon. A leading colon causes the rest of the path to be -interpreted relative to the current directory. If a path contains a -colon that is not at the beginning, then the path is interpreted as an -absolute path. Sequences of two or more colons anywhere in the path -are used to construct relative paths where \fB::\fR refers to the -parent of the current directory, \fB:::\fR refers to the parent of the -parent, and so forth. +On Apple Macintosh Classic systems (i.e. with MacOS 9.x or older), Tcl +supports two forms of path names. The normal Mac style names use colons +as path separators. Paths may be relative or absolute, and file names +may contain any character other than colon. A leading colon causes the +rest of the path to be interpreted relative to the current directory. +If a path contains a colon that is not at the beginning, then the path +is interpreted as an absolute path. Sequences of two or more colons +anywhere in the path are used to construct relative paths where \fB::\fR +refers to the parent of the current directory, \fB:::\fR refers to the +parent of the parent, and so forth. .RS .PP In addition to Macintosh style names, Tcl also supports a subset of @@ -100,13 +100,14 @@ current folder. .RE .TP \fBunix\fR -On Unix platforms, Tcl uses path names where the components are -separated by slashes. Path names may be relative or absolute, and -file names may contain any character other than slash. The file names -\fB\&.\fR and \fB\&..\fR are special and refer to the current directory -and the parent of the current directory respectively. Multiple -adjacent slash characters are interpreted as a single separator. -The following examples illustrate various forms of path names: +On Unix and Apple MacOS X platforms, Tcl uses path names where the +components are separated by slashes. Path names may be relative or +absolute, and file names may contain any character other than slash. +The file names \fB\&.\fR and \fB\&..\fR are special and refer to the +current directory and the parent of the current directory respectively. +Multiple adjacent slash characters are interpreted as a single +separator. The following examples illustrate various forms of path +names: .RS .TP 15 \fB/\fR @@ -175,24 +176,24 @@ extra backslashes are superfluous. .SH "TILDE SUBSTITUTION" .PP In addition to the file name rules described above, Tcl also supports -\fIcsh\fR-style tilde substitution. If a file name starts with a -tilde, then the file name will be interpreted as if the first element -is replaced with the location of the home directory for the given -user. If the tilde is followed immediately by a separator, then the -\fB$HOME\fR environment variable is substituted. Otherwise the -characters between the tilde and the next separator are taken as a -user name, which is used to retrieve the user's home directory for -substitution. +\fIcsh\fR-style tilde substitution. If a file name starts with a tilde, +then the file name will be interpreted as if the first element is +replaced with the location of the home directory for the given user. If +the tilde is followed immediately by a separator, then the \fB$HOME\fR +environment variable is substituted. Otherwise the characters between +the tilde and the next separator are taken as a user name, which is used +to retrieve the user's home directory for substitution. This works on +Unix, MacOS X and Windows (except very old releases). .PP -The Macintosh and Windows platforms do not support tilde substitution -when a user name follows the tilde. On these platforms, attempts to -use a tilde followed by a user name will generate an error that the -user does not exist when Tcl attempts to interpret that part of the -path or otherwise access the file. The behaviour of these paths -when not trying to interpret them is the same as on Unix. File -names that have a tilde without a user name will be correctly -substituted using the \fB$HOME\fR environment variable, just like -for Unix. +The Classic Macintosh (OS 9 and older) platform and old Windows +platforms do not support tilde substitution when a user name follows the +tilde. On these platforms, attempts to use a tilde followed by a user +name will generate an error that the user does not exist when Tcl +attempts to interpret that part of the path or otherwise access the +file. The behaviour of these paths when not trying to interpret them is +the same as on Unix. File names that have a tilde without a user name +will be correctly substituted using the \fB$HOME\fR environment +variable, just like for Unix. .SH "PORTABILITY ISSUES" .PP diff --git a/doc/glob.n b/doc/glob.n index 15ae60c..e4df23d 100644 --- a/doc/glob.n +++ b/doc/glob.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: glob.n,v 1.12 2002/07/01 18:24:39 jenglish Exp $ +'\" RCS: @(#) $Id: glob.n,v 1.13 2003/12/12 17:02:13 vincentdarley Exp $ '\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" @@ -149,6 +149,13 @@ command if you want the list sorted). Second, \fBglob\fR only returns the names of files that actually exist; in csh no check for existence is made unless a pattern contains a ?, *, or [] construct. +.LP +When the \fBglob\fR command returns relative paths whose filenames +start with a tilde ``~'' (for example through \fBglob *\fR or +\fBglob -tails\fR, the returned list will not quote the tilde with +``./''. This means care must be taken if those names are later to +be used with \fBfile join\fR, to avoid them being interpreted as +absolute paths pointing to a given user's home directory. .SH "PORTABILITY ISSUES" .PP -- cgit v0.12