Changes from TIP#17 "Redo Tcl's filesystem"

The following files were impacted.

   * doc/Access.3:
   * doc/FileSystem.3:
   * doc/OpenFileChnl.3:
   * doc/file.n:
   * doc/glob.n:
   * generic/tcl.decls:
   * generic/tcl.h:
   * generic/tclCmdAH.c:
   * generic/tclCmdIL.c:
   * generic/tclCmdMZ.c:
   * generic/tclDate.c:
   * generic/tclDecls.h:
   * generic/tclEncoding.c:
   * generic/tclFCmd.c:
   * generic/tclFileName.c:
   * generic/tclGetDate.y:
   * generic/tclIO.c:
   * generic/tclIOCmd.c:
   * generic/tclIOUtil.c:
   * generic/tclInt.decls:
   * generic/tclInt.h:
   * generic/tclIntDecls.h:
   * generic/tclLoad.c:
   * generic/tclStubInit.c:
   * generic/tclTest.c:
   * generic/tclUtil.c:
   * library/init.tcl:
   * mac/tclMacFCmd.c:
   * mac/tclMacFile.c:
   * mac/tclMacInit.c:
   * mac/tclMacPort.h:
   * mac/tclMacResource.c:
   * mac/tclMacTime.c:
   * tests/cmdAH.test:
   * tests/event.test:
   * tests/fCmd.test:
   * tests/fileName.test:
   * tests/io.test:
   * tests/ioCmd.test:
   * tests/proc-old.test:
   * tests/registry.test:
   * tests/unixFCmd.test:
   * tests/winDde.test:
   * tests/winFCmd.test:
   * unix/mkLinks:
   * unix/tclUnixFCmd.c:
   * unix/tclUnixFile.c:
   * unix/tclUnixInit.c:
   * unix/tclUnixPipe.c:
   * win/tclWinFCmd.c:
   * win/tclWinFile.c:
   * win/tclWinInit.c:
   * win/tclWinPipe.c

4 files changed, 95 insertions, 9 deletions

diff --git a/doc/Access.3 b/doc/Access.3
index c81cf10..daa4f53 100644
--- a/doc/Access.3
+++ b/doc/Access.3
@@ -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: Access.3,v 1.3 1999/05/06 19:14:39 stanton Exp $
+'\" RCS: @(#) $Id: Access.3,v 1.4 2001/07/31 19:12:05 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures"
@@ -35,6 +35,10 @@ The structure that contains the result.
 
 .SH DESCRIPTION
 .PP
+As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and
+\fBTcl_FSStat\fR should be used in preference to \fBTcl_Access\fR and
+\fBTcl_Stat\fR, wherever possible.
+.PP
 There are two reasons for calling \fBTcl_Access\fR and \fBTcl_Stat\fR
 rather than calling system level functions \fBaccess\fR and \fBstat\fR
 directly.  First, the Windows implementation of both functions fixes
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 45d1410..eeafd08 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,13 +4,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.9 2000/04/25 00:54:53 ericm Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.10 2001/07/31 19:12:05 vincentdarley Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_Ungets \- buffered I/O facilities using channels
+Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_Ungets \- buffered I/O facilities using channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -46,6 +46,12 @@ int
 \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
 .sp
 int
+\fBTcl_DetachChannel\fR(\fIinterp, channel\fR)
+.sp
+int
+\fBTcl_IsStandardChannel\fR(\fIchannel\fR)
+.sp
+int
 \fBTcl_Close\fR(\fIinterp, channel\fR)
 .sp
 .VS 8.1
@@ -236,7 +242,11 @@ If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
 returns NULL and records a POSIX error code that can be
 retrieved with \fBTcl_GetErrno\fR.
 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
-leaves an error message in \fIinterp\fR's result after any error.
+leaves an error message in \fIinterp\fR's result after any error.  
+As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should 
+be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
+.PP
+
 .PP
 The newly created channel is not registered in the supplied interpreter; to
 register it, use \fBTcl_RegisterChannel\fR, described below.
@@ -339,7 +349,33 @@ interpreter, the channel is also closed and destroyed.
 Code not associated with a Tcl interpreter can call
 \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
 that it no longer holds a reference to that channel. If this is the last
-reference to the channel, it will now be closed.
+reference to the channel, it will now be closed.  \fBTcl_UnregisterChannel\fR
+is very similar to \fBTcl_DetachChannel\fR except that it will also
+close the channel if no further references to it exist.
+
+.SH TCL_DETACHCHANNEL
+.PP
+\fBTcl_DetachChannel\fR removes a channel from the set of channels
+accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
+able to use the channel's name to refer to the channel in that interpreter.
+Beyond that, this command has no further effect.  It cannot be used on
+the standard channels (stdout, stderr, stdin), and will return
+TCL_ERROR if passed one of those channels.
+.PP
+Code not associated with a Tcl interpreter can call
+\fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
+that it no longer holds a reference to that channel. If this is the last
+reference to the channel, unlike \fBTcl_UnregisterChannel\fR, 
+it will not be closed.
+
+.SH TCL_ISSTANDARDCHANNEL
+.PP
+\fBTcl_IsStandardChannel\fR tests whether a channel is one of the
+three standard channels, stdin, stdout or stderr.  If so, it returns
+1, otherwise 0.
+.PP
+No attempt is made to check whether the given channel or the standard 
+channels are initialized or otherwise valid.
 
 .SH TCL_CLOSE
 .PP
diff --git a/doc/file.n b/doc/file.n
index 7a2f9c6..681207f 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.6 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: file.n,v 1.7 2001/07/31 19:12:06 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -216,6 +216,16 @@ Returns the platform-specific name of the file. This is useful if the
 filename is needed to pass to a platform-specific call, such as exec
 under Windows or AppleScript on the Macintosh.
 .TP
+\fBfile normalize \fIname\fR
+.
+Returns a unique normalised path representation for the file, whose string
+value can be used as a unique identifier for the it.  A normalized path is
+one which has all '../', './' removed.  Also it is one which is in the
+'standard' format for the native platform.  On MacOS, Unix, this means the
+path must be free of symbolic links/aliases, and on Windows it means we want
+the long form, with the long form's case-dependence (which gives us a
+unique, case-dependent path).
+.TP
 \fBfile owned \fIname\fR 
 .
 Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
@@ -267,6 +277,14 @@ Returns all of the characters in \fIname\fR up to but not including the
 last ``.'' character in the last component of name.  If the last
 component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
 .TP
+\fBfile separator ?\fIname\fR?
+.
+If no argument is given, returns the character which is used to separate 
+path segments for native files on this platform.  If a path is given,
+the filesystem responsible for that path is asked to return its
+separator character.  If no file system accepts \fIname\fR, an error
+is generated.
+.TP
 \fBfile size \fIname\fR
 .
 Returns a decimal string giving the size of file \fIname\fR in bytes.  If
@@ -303,6 +321,19 @@ values.  The \fBtype\fR element gives the type of the file in the same
 form returned by the command \fBfile type\fR.  This command returns an
 empty string.
 .TP
+\fBfile system \fIname\fR
+.
+Returns a list of two elements, the first of which is the name of the
+filesystem to use for the file, and the second the type of the file
+within that filesystem.  If a filesystem only supports one type of
+file, the second element may be null.  For example the native files
+have a first element 'native', and a second element which is a
+platform-specific type name for the file (e.g. 'networked'), or
+possibly the empty string.  A generic virtual file system might return
+the list 'vfs ftp' to represent a file on a remote ftp site mounted as
+a virtual filesystem through an extension called 'vfs'.  If the file
+does not belong to any filesystem, an error is generated.
+.TP
 \fBfile tail \fIname\fR
 .
 Returns all of the characters in \fIname\fR after the last directory
diff --git a/doc/glob.n b/doc/glob.n
index 8331bd3..38a96df 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.8 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: glob.n,v 1.9 2001/07/31 19:12:06 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
@@ -52,6 +52,15 @@ similar to a given file even when the names contain glob-sensitive
 characters.  This option may not be used in conjunction with
 \fB\-directory\fR.
 .TP
+\fB\-tails\fR
+Only return the part of each file found which follows the last directory
+named in any \fB\-directory\fR or \fB\-path\fR path specification.  
+Thus \fBglob -tails -dir $dir *\fR is equivalent to 
+\fBset pwd [pwd] ; cd $dir ; glob *; cd $pwd\fR.  For 
+\fB\-path\fR specifications, the returned names will include the last
+path segment, so \fBglob -tails -path /usr/loc */*\fR will return paths
+like \fBlocal/bin local/lib\fR etc.
+.TP
 \fB\-types\fR \fItypeList\fR
 Only list files or directories which match \fItypeList\fR, where the items
 in the list have two forms.  The first form is like the \-type option of
@@ -114,8 +123,14 @@ Matches the character \fIx\fR.
 \fB{\fIa\fB,\fIb\fB,\fI...\fR}
 Matches any of the strings \fIa\fR, \fIb\fR, etc.
 .LP
-As with csh, a  ``.'' at the beginning of a file's name or just
-after a ``/'' must be matched explicitly or with a {} construct.
+On Unix, as with csh, a ``.'' at the beginning of a file's name or just
+after a ``/'' must be matched explicitly or with a {} construct,
+unless the ``-types hidden'' flag is given (since ``.'' at the beginning 
+of a file's name indicates that it is hidden).  On other platforms,
+files beginning with a ``.'' are handled no differently to any others,
+except the special directories ``.'' and ``..'' which must be matched
+explicitly (this is to avoid a recursive pattern like ``glob -join * *
+* *'' from recursing up the directory hierarchy as well as down).
 In addition, all ``/'' characters must be matched explicitly.
 .LP
 If the first character in a \fIpattern\fR is ``~'' then it refers