diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Access.3 | 6 | ||||
| -rw-r--r-- | doc/OpenFileChnl.3 | 44 | ||||
| -rw-r--r-- | doc/file.n | 33 | ||||
| -rw-r--r-- | doc/glob.n | 21 |
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 @@ -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 @@ -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 |