diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/FileSystem.3 | 53 | ||||
| -rw-r--r-- | doc/SplitPath.3 | 5 | ||||
| -rw-r--r-- | doc/filename.n | 12 | ||||
| -rw-r--r-- | doc/glob.n | 21 |
4 files changed, 63 insertions, 28 deletions
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 1da96c5..7e49235 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.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: FileSystem.3,v 1.2 2001/08/07 02:59:14 hobbs Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.3 2001/08/23 17:37:07 vincentdarley Exp $ '\" .so man.macros .TH Tcl_FSCopyFile 3 8.4 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSReadlink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo \- procedures to interact with any filesystem +Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSReadlink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo \- procedures to interact with any filesystem .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -42,8 +42,8 @@ int int \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR) .sp -int -\fBTcl_FSListVolumes\fR(\fIinterp\fR) +Tcl_Obj* +\fBTcl_FSListVolumes\fR(\fIvoid\fR) .sp int \fBTcl_FSEvalFile\fR(\fIinterp, fileName\fR) @@ -55,7 +55,7 @@ int \fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR) .sp Tcl_Obj* -\fBTcl_FSReadlink\fR(\fIpathPtr\fR) +\fBTcl_FSLink\fR(\fIpathPtr, toPtr\fR) .sp int \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR) @@ -111,9 +111,12 @@ int ClientData \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR) .sp -char* +Tcl_Obj* \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR) .sp +char* +\fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR) +.sp Tcl_Obj* \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR) .sp @@ -230,7 +233,20 @@ native files in the native filesystem. If appropriate vfs's have been registered, the 'files' may, to give two examples, be remote (e.g. situated on a remote ftp server) or archived (e.g. lying inside a .zip archive). Such registered filesystems provide a lookup table of -functions to implement all or some of the functionality listed here. +functions to implement all or some of the functionality listed here. +.PP +The \fBTcl_FS...\fR are objectified and may cache internal +representations and other path-related strings (e.g. the current +working directory). One side-effect of this is that one must be +careful when passing in temporary objects with a refCount of zero. +Under some circumstances, the filesystem code may wish to retain a +reference to the passed in object, and so one must not assume that +after any of these calls return, the object still has a refCount of +zero - it may have been incremented. The practical lesson to learn +from this is that \fbTcl_Obj *path = Tcl_NewStringObj(...) ; +Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may +segfault. The 'path' must have its refCount incremented before +passing it in, or decrementing it. .PP \fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the path name given by destPathPtr. If the two paths given lie in the same @@ -267,8 +283,9 @@ sets Tcl's errno to the 'EXDEV' posix error code (which signifies a 'cross-domain link'). .PP \fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list -volumes' function and asks those to append their root volumes to -the list in the interpreters result. +volumes' function and asks them to return their list of root volumes. It +accumulates the return values in a list which is returned to the +caller (with a refCount of 0). .PP \fBTcl_FSEvalFile\fR reads the file given by \fIpathPtr\fR and evaluates its contents as a Tcl script. It returns the same information as @@ -305,14 +322,18 @@ matched using the logic of 'string match'. To handle recursion, Tcl will call this function frequently asking only for directories to be returned. .PP -\fBTcl_FSReadlink\fR replaces the library version of readlink(). +\fBTcl_FSLink\fR replaces the library version of readlink(), and may +also be used in the future to allow link creation. The appropriate function for the filesystem to which pathPtr belongs will be called. .PP +If the \fItoPtr\fR is NULL, a readlink action is performed. The result is a Tcl_Obj specifying the contents of the symbolic link -given by 'path', or NULL if the symbolic link could not be read. The +given by \fIpath\fR, or NULL if the symbolic link could not be read. The result is owned by the caller, which should call Tcl_DecrRefCount when -the result is no longer needed. +the result is no longer needed. If the \fItoPtr\fR is not NULL, Tcl +should create a link, but this option is not currently supported (it +is left available for future expansion). .PP \fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information about the specified file. You do not need any access rights to the @@ -487,13 +508,16 @@ Returns NULL or a valid internal path representation. This internal representation is cached, so that repeated calls to this function will not require additional conversions. .PP -\fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path string +\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. .PP +\fBTcl_FSGetTranslatedStringPath\fR does the same as +\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. +.PP \fBTcl_FSNewNativePath\fR performs the something like that reverse of the usual obj->path->nativerep conversions. If some code retrieves a path in native form (from, e.g. readlink or a native dialog), and that path @@ -915,8 +939,7 @@ Should be implemented only if the filesystem adds volumes at the head of the filesystem, so that they can be returned by 'file volumes'. .PP .CS -typedef int Tcl_FSListVolumesProc( - Tcl_Interp *\fIinterp\fR); +typedef Tcl_Obj* Tcl_FSListVolumesProc(void); .CE .PP The result should be TCL_OK, since there is no way this function can diff --git a/doc/SplitPath.3 b/doc/SplitPath.3 index b112b82..71ebe82 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.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: SplitPath.3,v 1.2 1998/09/14 18:39:50 stanton Exp $ +'\" RCS: @(#) $Id: SplitPath.3,v 1.3 2001/08/23 17:37:07 vincentdarley Exp $ '\" .so man.macros .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures" @@ -45,6 +45,9 @@ A pointer to an initialized \fBTcl_DString\fR to which the result of .SH DESCRIPTION .PP +These procedures have been superceded by the objectified procedures in +the \fBFileSystem\fR man page, which are more efficient. +.PP These procedures may be used to disassemble and reassemble file paths in a platform independent manner: they provide C-level access to the same functionality as the \fBfile split\fR, \fBfile join\fR, and diff --git a/doc/filename.n b/doc/filename.n index 42a9dce..34939c0 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.4 2000/09/07 14:27:47 poenitz Exp $ +'\" RCS: @(#) $Id: filename.n,v 1.5 2001/08/23 17:37:07 vincentdarley Exp $ '\" .so man.macros .TH filename n 7.5 Tcl "Tcl Built-In Commands" @@ -177,9 +177,13 @@ substitution. .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. File -names that have a tilde without a user name will be substituted using -the \fB$HOME\fR environment variable, just like for Unix. +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 @@ -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.9 2001/07/31 19:12:06 vincentdarley Exp $ +'\" RCS: @(#) $Id: glob.n,v 1.10 2001/08/23 17:37:07 vincentdarley Exp $ '\" .so man.macros .TH glob n 8.3 Tcl "Tcl Built-In Commands" @@ -33,7 +33,8 @@ Search for files which match the given patterns starting in the given \fIdirectory\fR. This allows searching of directories whose name contains glob-sensitive characters without the need to quote such characters explicitly. This option may not be used in conjunction with -\fB\-path\fR. +\fB\-path\fR, which is used to allow searching for complete file paths +whose names may contain glob-sensitive characters. .TP \fB\-join\fR The remaining pattern arguments are treated as a single pattern @@ -48,18 +49,22 @@ switch an error is returned if the result list would be empty. \fB\-path\fR \fIpathPrefix\fR Search for files with the given \fIpathPrefix\fR where the rest of the name matches the given patterns. This allows searching for files with names -similar to a given file even when the names contain glob-sensitive +similar to a given file (as opposed to a directory) even when the names +contain glob-sensitive characters. This option may not be used in conjunction with -\fB\-directory\fR. +\fB\-directory\fR. For example, to find all files with the same root name +as $path, but differing extensions, you should use \fBglob +-path [file rootname $path] .*\fR which will work even if $path contains +numerous glob-sensitive characters. .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 +Thus \fBglob -tails -directory $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. +path segment, so \fBglob -tails -path [file rootname ~/foo.tex] .*\fR +will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. .TP \fB\-types\fR \fItypeList\fR Only list files or directories which match \fItypeList\fR, where the items @@ -164,7 +169,7 @@ like ``.../'' and ``..../'' for successively higher up parent directories. .TP \fBMacintosh\fR . -When using the options, \fB\-dir\fR, \fB\-join\fR or \fB\-path\fR, glob +When using the options, \fB\-directory\fR, \fB\-join\fR or \fB\-path\fR, glob assumes the directory separator for the entire pattern is the standard ``:''. When not using these options, glob examines each pattern argument and uses ``/'' unless the pattern contains a ``:''. |