From 7874bbbf7780a2d50f99f77b4d0590e5b4e6fcbf Mon Sep 17 00:00:00 2001
From: vincentdarley <vincentdarley>
Date: Fri, 3 Oct 2003 17:24:34 +0000
Subject: FileSystem.3

---
 doc/FileSystem.3 | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 010c408..8cc70b0 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.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: FileSystem.3,v 1.32.2.1 2003/06/23 10:49:14 vincentdarley Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.32.2.2 2003/10/03 17:24:34 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -546,14 +546,22 @@ not require additional conversions.
 \fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
 from the given Tcl_Obj.  
 .PP
-If the translation succeeds (i.e. the object is a valid path), then it
-is returned.  Otherwise NULL will be returned, and an error message may
-be left in the interpreter.  A "translated" path is one which
-contains no "~" or "~user" sequences (these have been expanded to
-their current representation in the filesystem).
-.PP
-\fBTcl_FSGetTranslatedStringPath\fR does the same as 
+If the translation succeeds (i.e. the object is a valid path), then it is
+returned.  Otherwise NULL will be returned, and an error message may be
+left in the interpreter.  A "translated" path is one which contains no
+"~" or "~user" sequences (these have been expanded to their current
+representation in the filesystem).  The object returned is owned by the
+caller, which must store it or call Tcl_DecrRefCount to ensure memory is
+freed.  This function is of little practical use, and
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+better functions to use for most purposes.
+.PP
+\fBTcl_FSGetTranslatedStringPath\fR does the same as
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
+The string returned is dynamically allocated and owned by the caller,
+which must store it or call ckfree to ensure it is freed.  Again,
+\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
+better functions to use for most purposes.
 .PP
 \fBTcl_FSNewNativePath\fR performs something like that reverse of the
 usual obj->path->nativerep conversions.  If some code retrieves a path
-- 
cgit v0.12