diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/FileSystem.3 | 42 | ||||
| -rw-r--r-- | doc/file.n | 33 |
2 files changed, 56 insertions, 19 deletions
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index c38bcf4..747f5c4 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.25 2002/06/13 09:39:59 vincentdarley Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.26 2002/06/21 14:22:28 vincentdarley Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -64,7 +64,7 @@ int \fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR) .sp Tcl_Obj* -\fBTcl_FSLink\fR(\fIpathPtr, toPtr, linkType\fR) +\fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR) .sp int \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR) @@ -343,18 +343,22 @@ 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_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 \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. If the \fItoPtr\fR is not NULL, Tcl -should create a link, but this option is not currently supported (it -and the \fIlinkType\fR field are left available for future expansion). +\fBTcl_FSLink\fR replaces the library version of readlink(), and +extends it to support the creation of links. The appropriate function +for the filesystem to which linkNamePtr 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 +\fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned +by the caller, which should call Tcl_DecrRefCount when the result is no +longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link +of one of the types passed in in the \fIlinkAction\fR flag. This flag is +an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK. +Where a choice exists (i.e. more than one flag is passed in), the Tcl +convention is to prefer symbolic links. When a link is successfully +created, the return value should be \fItoPtr\fR (which is therefore +already owned by the caller). If unsuccessful, NULL should be +returned. .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 @@ -1030,19 +1034,21 @@ only if the filesystem supports links, and may otherwise be NULL. .PP .CS typedef Tcl_Obj* Tcl_FSLinkProc( - Tcl_Obj *\fIpathPtr\fR, + Tcl_Obj *\fIlinkNamePtr\fR, Tcl_Obj *\fItoPtr\fR, - int \fIlinkType\fR); + int \fIlinkAction\fR); .CE .PP If \fItoPtr\fR is NULL, the function is being asked to read the contents of a link. The result is a Tcl_Obj specifying the contents of -the symbolic link given by 'path', or NULL if the symbolic link could +the link given by \fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned by the caller, which should call Tcl_DecrRefCount when the result is no longer needed. If \fItoPtr\fR is not NULL, the function should attempt to create a link. The result in this case should be \fItoPtr\fR if the link was successful and NULL -otherwise. In this case the result is not owned by the caller. +otherwise. In this case the result is not owned by the caller. See +the documentation for \fBTcl_FSLink\fR for the correct interpretation +of the \fIlinkAction\fR flags. .SH LISTVOLUMESPROC .PP Function to list any filesystem volumes added by this filesystem. @@ -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.19 2002/06/20 00:50:48 jenglish Exp $ +'\" RCS: @(#) $Id: file.n,v 1.20 2002/06/21 14:22:28 vincentdarley Exp $ '\" .so man.macros .TH file n 8.3 Tcl "Tcl Built-In Commands" @@ -191,6 +191,37 @@ is always canonical for the current platform: \fB/\fR for Unix and Windows, and \fB:\fR for Macintosh. .RE .TP +\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR? +. +If only one argument is given, that argument is assumed to be +\fIlinkName\fR, and this command returns the value of the link given by +\fIlinkName\fR (i.e. the name of the file it points to). If +\fIlinkName\fR isn't a link or its value cannot be read (as, for example, +seems to be the case with hard links, which look just like ordinary +files), then an error is returned. +. +If 2 arguments are given, then these are assumed to be \fIlinkName\fR and +\fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR +doesn't exist, an error will be returned. Otherwise, Tcl creates a new +link called \fIlinkName\fR which points to the existing filesystem object +at \fItarget\fR, where the type of the link is platform-specific (on Unix +a symbolic link will be the default). This is useful for the case where +the user wishes to create a link in a cross-platform way, and doesn't +care what type of link is created. +. +If the user wishes to make a link of a specific type only, (and signal an +error if for some reason that is not possible), then the optional +\fI-linktype\fR argument should be given. Accepted values for +\fI-linktype\fR are "-symbolic" and "-hard". +. +When creating links on filesystems that either do not support any links, +or do not support the specific type requested, an error message will be +returned. In particular Windows 95, 98 and ME do not support any links +at present, but most Unix platforms support both symbolic and hard links +(the latter for files only), MacOS supports symbolic links and Windows +NT/2000/XP (on NTFS drives) support symbolic directory links and hard +file links. +.TP \fBfile lstat \fIname varName\fR . Same as \fBstat\fR option (see below) except uses the \fIlstat\fR |