file copy soft link docs

3 files changed, 34 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index b7d6c92..7812c0a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2001-11-02  Vince Darley  <vincentdarley@users.sourceforge.net>
+
+	* doc/file.n:
+	* generic/tclIOUtil.c: updated documentation and comments
+	to clarify behaviour of 'file copy' wrt soft links.
+	
 2001-10-29  Vince Darley  <vincentdarley@users.sourceforge.net>
 
 	* win/tclWinFile.c: fix to '-types {f r}' bug in
diff --git a/doc/file.n b/doc/file.n
index df71bd5..55df079 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.8 2001/09/04 18:06:34 vincentdarley Exp $
+'\" RCS: @(#) $Id: file.n,v 1.9 2001/11/02 12:06:27 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -92,18 +92,20 @@ is determined using the same rules as for \fBstring match\fR.
 \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
 .RS
 The first form makes a copy of the file or directory \fIsource\fR under
-the pathname \fItarget\fR.  If \fItarget\fR is an existing directory,
+the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
 then the second form is used.  The second form makes a copy inside
 \fItargetDir\fR of each \fIsource\fR file listed.  If a directory is
 specified as a \fIsource\fR, then the contents of the directory will be
-recursively copied into \fItargetDir\fR.  Existing files will not be
-overwritten unless the \fB\-force\fR option is specified.  Trying to
-overwrite a non-empty directory, overwrite a directory with a file, or a
-file with a directory will all result in errors even if \fI\-force\fR was
-specified.  Arguments are processed in the order specified, halting at the
-first error, if any.  A \fB\-\|\-\fR marks the end of switches; the argument
-following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it
-starts with a \fB\-\fR.
+recursively copied into \fItargetDir\fR. Existing files will not be
+overwritten unless the \fB\-force\fR option is specified.  When copying
+within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
+the links themselves are copied, not the things they point to).  Trying
+to overwrite a non-empty directory, overwrite a directory with a file,
+or a file with a directory will all result in errors even if
+\fI\-force\fR was specified.  Arguments are processed in the order
+specified, halting at the first error, if any.  A \fB\-\|\-\fR marks
+the end of switches; the argument following the \fB\-\|\-\fR will be
+treated as a \fIsource\fR even if it starts with a \fB\-\fR.
 .RE
 .TP
 \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
diff --git a/generic/tclIOUtil.c b/generic/tclIOUtil.c
index dc91066..b9bfbe1 100644
--- a/generic/tclIOUtil.c
+++ b/generic/tclIOUtil.c
@@ -17,7 +17,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclIOUtil.c,v 1.24 2001/10/29 15:02:44 vincentdarley Exp $
+ * RCS: @(#) $Id: tclIOUtil.c,v 1.25 2001/11/02 12:06:27 vincentdarley Exp $
  */
 
 #include "tclInt.h"
@@ -2861,8 +2861,13 @@ GetPathType(pathObjPtr, filesystemPtrPtr, driveNameLengthPtr, driveNameRef)
 	 * certain absolute Windows paths starting '//' and those tests
 	 * will go wrong.
 	 * 
-	 * Besides these test-suite issues, there is actually no
-	 * reason to skip the native filesystem.
+	 * Besides these test-suite issues, there is one other reason
+	 * to skip the native filesystem --- since the tclFilename.c
+	 * code has nice fast 'absolute path' checkers, we don't want
+	 * to waste time repeating that effort here, and this 
+	 * function is actually called quite often, so if we can
+	 * save the overhead of the native filesystem returning us
+	 * a list of volumes all the time, it is better.
 	 */
 	if ((fsRecPtr->fsPtr != &nativeFilesystem) && (proc != NULL)) {
 	    int numVolumes;
@@ -2871,10 +2876,10 @@ GetPathType(pathObjPtr, filesystemPtrPtr, driveNameLengthPtr, driveNameRef)
 		if (Tcl_ListObjLength(NULL, thisFsVolumes, 
 				      &numVolumes) != TCL_OK) {
 		    /* 
-		     * This is VERY bad; Tcl_FSListVolumes didn't 
-		     * return a valid list.  Set numVolumes to -1
-		     * so that we skip the while loop below and
-		     * just return with the current value of 'type'.
+		     * This is VERY bad; the Tcl_FSListVolumesProc
+		     * didn't return a valid list.  Set numVolumes to
+		     * -1 so that we skip the while loop below and just
+		     * return with the current value of 'type'.
 		     * 
 		     * It would be better if we could signal an error
 		     * here (but panic seems a bit excessive).
@@ -2978,6 +2983,10 @@ Tcl_FSRenameFile(srcPathPtr, destPathPtr)
  *	If the two paths given belong to the same filesystem, we call
  *	that filesystem's copy function.  Otherwise we simply
  *	return the posix error 'EXDEV', and -1.
+ *	
+ *	Note that in the native filesystems, 'copyFileProc' is defined
+ *	to copy soft links (i.e. it copies the links themselves, not
+ *	the things they point to).
  *
  * Results:
  *      Standard Tcl error code if a function was called.