From ecd460f0cf5fb2d5ba832332353c4c610e8684fb Mon Sep 17 00:00:00 2001 From: dkf Date: Sat, 2 Dec 2006 16:14:30 +0000 Subject: Bug 1606454 fixed --- ChangeLog | 37 +-- doc/file.n | 950 ++++++++++++++++++++++++++++++------------------------------- 2 files changed, 495 insertions(+), 492 deletions(-) diff --git a/ChangeLog b/ChangeLog index c5d9229..bab903d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2006-12-02 Donal K. Fellows + + * doc/file.n: Clarification of [file pathtype] docs. [Bug 1606454] + 2006-12-01 Kevin Kenny * libtommath/bn_mp_add.c: Corrected the effects of a @@ -10,13 +14,12 @@ * doc/mathfunc.n: Added isqrt() function to docs * generic/tclBasic.c: Added isqrt() math function (ExprIsqrtFunc) * tests/expr.test (expr-47.*): Added tests for isqrt() - * tests/info.test (info-20.2): Added isqrt() to expected math - funcs. - + * tests/info.test (info-20.2): Added isqrt() to expected math funcs. + 2006-12-01 Don Porter - * tests/chan.test: Correct timing sensitivity in new test - [Bug 1606860] + * tests/chan.test: Correct timing sensitivity in new test. [Bug + 1606860] TIP#287 IMPLEMENTATION @@ -42,15 +45,15 @@ 2006-11-30 Kevin Kenny * library/tzdata: Olson's tzdata2006p. - * libtommath/bn_mp_sqrt.c: Fixed a bug where the initial - approximation to the square root could be on the wrong side, - causing failure of convergence. - + * libtommath/bn_mp_sqrt.c: Fixed a bug where the initial approximation + to the square root could be on the wrong side, causing failure of + convergence. + 2006-11-29 Don Porter * generic/tclBasic.c (Tcl_AppendObjToErrorInfo): Added - Tcl_DecrRefCount() on the objPtr argument to plug memory leaks. - This makes the routine a consumer, which makes it easiest to use. + Tcl_DecrRefCount() on the objPtr argument to plug memory leaks. This + makes the routine a consumer, which makes it easiest to use. 2006-11-28 Andreas Kupries @@ -78,14 +81,14 @@ * unix/tclUnixChan.c (TclUnixWaitForFile): * tests/event.test (event-14.*): Corrected a bug where - TclUnixWaitForFile would present select() with the wrong mask - on an LP64 machine if a fd number exceeds 32. Thanks to - Jean-Luc Fontaine for reporting and diagnosing [Bug 1602208]. - + TclUnixWaitForFile would present select() with the wrong mask on an + LP64 machine if a fd number exceeds 32. Thanks to Jean-Luc Fontaine + for reporting and diagnosing [Bug 1602208]. + 2006-11-27 Don Porter * generic/tclExecute.c (TclIncrObj): Correct failure to detect - floating-point increment values. Thanks to William Coleda [Bug 1602991] + floating-point increment values. Thanks to William Coleda [Bug 1602991] 2006-11-26 Donal K. Fellows @@ -134,7 +137,7 @@ 2006-11-20 Donal K. Fellows - * generic/tclBasic.c (Tcl_CreateInterp, TclHideUnsafeCommands): + * generic/tclBasic.c (Tcl_CreateInterp, TclHideUnsafeCommands): * library/init.tcl: Refactored the [chan] command's guts so that it does not use aliases to global commands, making the code more robust. diff --git a/doc/file.n b/doc/file.n index c3c975a..8584468 100644 --- a/doc/file.n +++ b/doc/file.n @@ -1,475 +1,475 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" 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.40 2005/05/10 18:33:59 kennykb Exp $ -'\" -.so man.macros -.TH file n 8.3 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -file \- Manipulate file names and attributes -.SH SYNOPSIS -\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command provides several operations on a file's name or attributes. -\fIName\fR is the name of a file; if it starts with a tilde, then tilde -substitution is done before executing the command (see the manual entry for -\fBfilename\fR for details). \fIOption\fR indicates what to do with the -file name. Any unique abbreviation for \fIoption\fR is acceptable. The -valid options are: -.TP -\fBfile atime \fIname\fR ?\fBtime\fR? -. -Returns a decimal string giving the time at which file \fIname\fR was last -accessed. If \fItime\fR is specified, it is an access time to set -for the file. The time is measured in the standard POSIX fashion as -seconds from a fixed starting time (often January 1, 1970). If the file -doesn't exist or its access time cannot be queried or set then an error is -generated. On Windows, FAT file systems do not support access time. -.TP -\fBfile attributes \fIname\fR -.TP -\fBfile attributes \fIname\fR ?\fBoption\fR? -.TP -\fBfile attributes \fIname\fR ?\fBoption value option value...\fR? -.RS -This subcommand returns or sets platform specific values associated -with a file. The first form returns a list of the platform specific -flags and their values. The second form returns the value for the -specific option. The third form sets one or more of the values. The -values are as follows: -.PP -On Unix, \fB-group\fR gets or sets the group name for the file. A group id -can be given to the command, but it returns a group name. \fB-owner\fR gets -or sets the user name of the owner of the file. The command returns the -owner name, but the numerical id can be passed when setting the -owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) -uses. This command does also has limited support for setting using the -symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], -where multiple symbolic attributes can be separated by commas (example: -\fBu+s,go\-rw\fR add sticky bit for user, remove read and write -permissions for group and other). A simplified \fBls\fR style string, -of the form rwxrwxrwx (must be 9 characters), is also supported -(example: \fBrwxr\-xr\-t\fR is equivalent to 01755). -On versions of Unix supporting file flags, \fB-readonly\fR gives the -value or sets or clears the readonly attribute of the file, -i.e. the user immutable flag \fBuchg\fR to chflags(1). -.PP -On Windows, \fB-archive\fR gives the value or sets or clears the -archive attribute of the file. \fB-hidden\fR gives the value or sets -or clears the hidden attribute of the file. \fB-longname\fR will -expand each path element to its long version. This attribute cannot be -set. \fB-readonly\fR gives the value or sets or clears the readonly -attribute of the file. \fB-shortname\fR gives a string where every -path element is replaced with its short (8.3) version of the -name. This attribute cannot be set. \fB-system\fR gives or sets or -clears the value of the system attribute of the file. -.PP -On Mac OS X and Darwin, \fB-creator\fR gives or sets the -Finder creator type of the file. \fB-hidden\fR gives or sets or clears -the hidden attribute of the file. \fB-readonly\fR gives or sets or -clears the readonly attribute of the file. \fB-rsrclength\fR gives -the length of the resource fork of the file, this attribute can only be -set to the value 0, which results in the resource fork being stripped -off the file. -.RE -.TP -\fBfile channels ?\fIpattern\fR? -. -If \fIpattern\fR isn't specified, returns a list of names of all -registered open channels in this interpreter. If \fIpattern\fR is -specified, only those names matching \fIpattern\fR are returned. Matching -is determined using the same rules as for \fBstring match\fR. -.TP -\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR -.TP -\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, -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 (when Tcl will -also attempt to adjust permissions on the destination file or directory -if that is necessary to allow the copy to proceed). 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 overwrite 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 ... ? -. -Removes the file or directory specified by each \fIpathname\fR -argument. Non-empty directories will be removed only if the -\fB\-force\fR option is specified. When operating on symbolic links, -the links themselves will be deleted, not the objects they point to. -Trying to delete a non-existent file is not considered an error. -Trying to delete a read-only file will cause the file to be deleted, -even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR -option is specified on a directory, Tcl will attempt both to change -permissions and move the current directory 'pwd' out of the given path -if that is necessary to allow the deletion to proceed. 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 \fIpathname\fR even if it starts with -a \fB\-\fR. -.TP -\fBfile dirname \fIname\fR -Returns a name comprised of all of the path components in \fIname\fR -excluding the last element. If \fIname\fR is a relative file name and -only contains one path element, then returns ``\fB.\fR''. If \fIname\fR -refers to a root directory, then the root directory is returned. For -example, -.RS -.CS -\fBfile dirname c:/\fR -.CE -returns \fBc:/\fR. -.PP -Note that tilde substitution will only be -performed if it is necessary to complete the command. For example, -.CS -\fBfile dirname ~/src/foo.c\fR -.CE -returns \fB~/src\fR, whereas -.CS -\fBfile dirname ~\fR -.CE -returns \fB/home\fR (or something similar). -.RE -.TP -\fBfile executable \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is executable by the current user, -\fB0\fR otherwise. -.TP -\fBfile exists \fIname\fR -. -Returns \fB1\fR if file \fIname\fR exists and the current user has -search privileges for the directories leading to it, \fB0\fR otherwise. -.TP -\fBfile extension \fIname\fR -. -Returns all of the characters in \fIname\fR after and including the last -dot in the last element of \fIname\fR. If there is no dot in the last -element of \fIname\fR then returns the empty string. -.TP -\fBfile isdirectory \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. -.TP -\fBfile isfile \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. -.TP -\fBfile join \fIname\fR ?\fIname ...\fR? -. -Takes one or more file names and combines them, using the correct path -separator for the current platform. If a particular \fIname\fR is -relative, then it will be joined to the previous file name argument. -Otherwise, any earlier arguments will be discarded, and joining will -proceed from the current argument. For example, -.RS -.CS -\fBfile join a b /foo bar\fR -.CE -returns \fB/foo/bar\fR. -.PP -Note that any of the names can contain separators, and that the result -is always canonical for the current platform: \fB/\fR for Unix and -Windows. -.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 (which is also the returned value), 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". -. -On Unix, symbolic links can be made to relative paths, and those paths -must be relative to the actual \fIlinkName\fR's location (not to the -cwd), but on all other platforms where relative links are not supported, -target paths will always be converted to absolute, normalized form -before the link is created (and therefore relative paths are interpreted -as relative to the cwd). Furthermore, "~user" paths are always expanded -to absolute form. 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) 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 -kernel call instead of \fIstat\fR. This means that if \fIname\fR -refers to a symbolic link the information returned in \fIvarName\fR -is for the link rather than the file it refers to. On systems that -don't support symbolic links this option behaves exactly the same -as the \fBstat\fR option. -.TP -\fBfile mkdir \fIdir\fR ?\fIdir\fR ...? -. -Creates each directory specified. For each pathname \fIdir\fR specified, -this command will create all non-existing parent directories as -well as \fIdir\fR itself. If an existing directory is specified, then -no action is taken and no error is returned. Trying to overwrite an existing -file with a directory will result in an error. Arguments are processed in -the order specified, halting at the first error, if any. -.TP -\fBfile mtime \fIname\fR ?\fItime\fR? -. -Returns a decimal string giving the time at which file \fIname\fR was last -modified. If \fItime\fR is specified, it is a modification time to set for -the file (equivalent to Unix \fBtouch\fR). The time is measured in the -standard POSIX fashion as seconds from a fixed starting time (often January -1, 1970). If the file doesn't exist or its modified time cannot be queried -or set then an error is generated. -.TP -\fBfile nativename \fIname\fR -. -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. -.TP -\fBfile normalize \fIname\fR -. -.RS -Returns a unique normalized path representation for the file-system -object (file, directory, link, etc), whose string value can be used as a -unique identifier for it. A normalized path is an absolute path which has -all '../', './' removed. Also it is one which is in the ``standard'' -format for the native platform. On Unix, this means the segments -leading up to the path must be free of symbolic links/aliases (but the -very last path component may be a symbolic link), and on Windows it also -means we want the long form with that form's case-dependence (which -gives us a unique, case-dependent path). The one exception concerning the -last link in the path is necessary, because Tcl or the user may wish to -operate on the actual symbolic link itself (for example 'file delete', 'file -rename', 'file copy' are defined to operate on symbolic links, not on the -things that they point to). -.RE -.TP -\fBfile owned \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR -otherwise. -.TP -\fBfile pathtype \fIname\fR -. -Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If -\fIname\fR refers to a specific file on a specific volume, the path type -will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the -current working directory, then the path type will be \fBrelative\fR. If -\fIname\fR refers to a file relative to the current working directory on -a specified volume, or to a specific file on the current working volume, then -the file type is \fBvolumerelative\fR. -.TP -\fBfile readable \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is readable by the current user, -\fB0\fR otherwise. -.TP -\fBfile readlink \fIname\fR -. -Returns the value of the symbolic link given by \fIname\fR (i.e. the name -of the file it points to). If \fIname\fR isn't a symbolic link or its -value cannot be read, then an error is returned. On systems that don't -support symbolic links this option is undefined. -.TP -\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR -.TP -\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR -.RS -The first form takes the file or directory specified by pathname -\fIsource\fR and renames it to \fItarget\fR, moving the file if the -pathname \fItarget\fR specifies a name in a different directory. If -\fItarget\fR is an existing directory, then the second form is used. -The second form moves each \fIsource\fR file or directory into the -directory \fItargetDir\fR. Existing files will not be overwritten -unless the \fB\-force\fR option is specified. When operating inside a -single filesystem, Tcl will rename symbolic links rather than the -things that 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. 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 rootname \fIname\fR -. -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\fR ?\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 -the file doesn't exist or its size cannot be queried then an error is -generated. -.TP -\fBfile split \fIname\fR -. -Returns a list whose elements are the path components in \fIname\fR. The -first element of the list will have the same path type as \fIname\fR. -All other elements will be relative. Path separators will be discarded -unless they are needed ensure that an element is unambiguously relative. -For example, under Unix -.RS -.CS -file split /foo/~bar/baz -.CE -returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands -that use the third component do not attempt to perform tilde -substitution. -.RE -.TP -\fBfile stat \fIname varName\fR -. -Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable -given by \fIvarName\fR to hold information returned from the kernel call. -\fIVarName\fR is treated as an array variable, and the following elements -of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, -\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, -\fBuid\fR. Each element except \fBtype\fR is a decimal string with the -value of the corresponding field from the \fBstat\fR return structure; -see the manual entry for \fBstat\fR for details on the meanings of the -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 one or two elements, the first of which is the name of -the filesystem to use for the file, and the second, if given, an -arbitrary string representing the filesystem-specific nature or type of -the location within that filesystem. If a filesystem only supports one -type of file, the second element may not be supplied. For example the -native files have a first element 'native', and a second element which -when given is a platform-specific type name for the file's system -(e.g. 'NTFS', 'FAT', on Windows). 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 the last filesystem component of -\fIname\fR. Any trailing directory separator in \fIname\fR is ignored. -If \fIname\fR contains no separators then returns \fIname\fR. So, -\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all -return \fBb\fR. -.TP -\fBfile type \fIname\fR -. -Returns a string giving the type of file \fIname\fR, which will be one of -\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, -\fBfifo\fR, \fBlink\fR, or \fBsocket\fR. -.TP -\fBfile volumes\fR -. -Returns the absolute paths to the volumes mounted on the system, as a -proper Tcl list. Without any virtual filesystems mounted as root -volumes, on UNIX, the command will always return "/", since all -filesystems are locally mounted. -On Windows, it will return a list of the available local drives -(e.g. {a:/ c:/}). If any virtual filesystem has mounted additional -volumes, they will be in the returned list. -.TP -\fBfile writable \fIname\fR -. -Returns \fB1\fR if file \fIname\fR is writable by the current user, -\fB0\fR otherwise. -.SH "PORTABILITY ISSUES" -.TP -\fBUnix\fR\0\0\0\0\0\0\0 -. -These commands always operate using the real user and group identifiers, -not the effective ones. -.SH EXAMPLES -This procedure shows how to search for C files in a given directory -that have a correspondingly-named object file in the current -directory: -.CS -proc findMatchingCFiles {dir} { - set files {} - switch $::tcl_platform(platform) { - windows { - set ext .obj - } - unix { - set ext .o - } - } - foreach file [glob -nocomplain -directory $dir *.c] { - set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext - if {[\fBfile exists\fR $objectFile]} { - lappend files $file - } - } - return $files -} -.CE -.PP -Rename a file and leave a symbolic link pointing from the old location -to the new place: -.CS -set oldName foobar.txt -set newName foo/bar.txt -# Make sure that where we're going to move to exists... -if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { - \fBfile mkdir\fR [\fBfile dirname\fR $newName] -} -\fBfile rename\fR $oldName $newName -\fBfile link\fR -symbolic $oldName $newName -.CE - -.SH "SEE ALSO" -filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), -fblocked(n), flush(n) - -.SH KEYWORDS -attributes, copy files, delete files, directory, file, move files, name, rename files, stat +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" 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.41 2006/12/02 16:14:30 dkf Exp $ +'\" +.so man.macros +.TH file n 8.3 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +file \- Manipulate file names and attributes +.SH SYNOPSIS +\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command provides several operations on a file's name or attributes. +\fIName\fR is the name of a file; if it starts with a tilde, then tilde +substitution is done before executing the command (see the manual entry for +\fBfilename\fR for details). \fIOption\fR indicates what to do with the +file name. Any unique abbreviation for \fIoption\fR is acceptable. The +valid options are: +.TP +\fBfile atime \fIname\fR ?\fBtime\fR? +. +Returns a decimal string giving the time at which file \fIname\fR was last +accessed. If \fItime\fR is specified, it is an access time to set +for the file. The time is measured in the standard POSIX fashion as +seconds from a fixed starting time (often January 1, 1970). If the file +doesn't exist or its access time cannot be queried or set then an error is +generated. On Windows, FAT file systems do not support access time. +.TP +\fBfile attributes \fIname\fR +.TP +\fBfile attributes \fIname\fR ?\fBoption\fR? +.TP +\fBfile attributes \fIname\fR ?\fBoption value option value...\fR? +.RS +This subcommand returns or sets platform specific values associated +with a file. The first form returns a list of the platform specific +flags and their values. The second form returns the value for the +specific option. The third form sets one or more of the values. The +values are as follows: +.PP +On Unix, \fB-group\fR gets or sets the group name for the file. A group id +can be given to the command, but it returns a group name. \fB-owner\fR gets +or sets the user name of the owner of the file. The command returns the +owner name, but the numerical id can be passed when setting the +owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) +uses. This command does also has limited support for setting using the +symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], +where multiple symbolic attributes can be separated by commas (example: +\fBu+s,go\-rw\fR add sticky bit for user, remove read and write +permissions for group and other). A simplified \fBls\fR style string, +of the form rwxrwxrwx (must be 9 characters), is also supported +(example: \fBrwxr\-xr\-t\fR is equivalent to 01755). +On versions of Unix supporting file flags, \fB-readonly\fR gives the +value or sets or clears the readonly attribute of the file, +i.e. the user immutable flag \fBuchg\fR to chflags(1). +.PP +On Windows, \fB-archive\fR gives the value or sets or clears the +archive attribute of the file. \fB-hidden\fR gives the value or sets +or clears the hidden attribute of the file. \fB-longname\fR will +expand each path element to its long version. This attribute cannot be +set. \fB-readonly\fR gives the value or sets or clears the readonly +attribute of the file. \fB-shortname\fR gives a string where every +path element is replaced with its short (8.3) version of the +name. This attribute cannot be set. \fB-system\fR gives or sets or +clears the value of the system attribute of the file. +.PP +On Mac OS X and Darwin, \fB-creator\fR gives or sets the +Finder creator type of the file. \fB-hidden\fR gives or sets or clears +the hidden attribute of the file. \fB-readonly\fR gives or sets or +clears the readonly attribute of the file. \fB-rsrclength\fR gives +the length of the resource fork of the file, this attribute can only be +set to the value 0, which results in the resource fork being stripped +off the file. +.RE +.TP +\fBfile channels ?\fIpattern\fR? +. +If \fIpattern\fR isn't specified, returns a list of names of all +registered open channels in this interpreter. If \fIpattern\fR is +specified, only those names matching \fIpattern\fR are returned. Matching +is determined using the same rules as for \fBstring match\fR. +.TP +\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +.TP +\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, +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 (when Tcl will +also attempt to adjust permissions on the destination file or directory +if that is necessary to allow the copy to proceed). 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 overwrite 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 ... ? +. +Removes the file or directory specified by each \fIpathname\fR +argument. Non-empty directories will be removed only if the +\fB\-force\fR option is specified. When operating on symbolic links, +the links themselves will be deleted, not the objects they point to. +Trying to delete a non-existent file is not considered an error. +Trying to delete a read-only file will cause the file to be deleted, +even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR +option is specified on a directory, Tcl will attempt both to change +permissions and move the current directory 'pwd' out of the given path +if that is necessary to allow the deletion to proceed. 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 \fIpathname\fR even if it starts with +a \fB\-\fR. +.TP +\fBfile dirname \fIname\fR +Returns a name comprised of all of the path components in \fIname\fR +excluding the last element. If \fIname\fR is a relative file name and +only contains one path element, then returns ``\fB.\fR''. If \fIname\fR +refers to a root directory, then the root directory is returned. For +example, +.RS +.CS +\fBfile dirname c:/\fR +.CE +returns \fBc:/\fR. +.PP +Note that tilde substitution will only be +performed if it is necessary to complete the command. For example, +.CS +\fBfile dirname ~/src/foo.c\fR +.CE +returns \fB~/src\fR, whereas +.CS +\fBfile dirname ~\fR +.CE +returns \fB/home\fR (or something similar). +.RE +.TP +\fBfile executable \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is executable by the current user, +\fB0\fR otherwise. +.TP +\fBfile exists \fIname\fR +. +Returns \fB1\fR if file \fIname\fR exists and the current user has +search privileges for the directories leading to it, \fB0\fR otherwise. +.TP +\fBfile extension \fIname\fR +. +Returns all of the characters in \fIname\fR after and including the last +dot in the last element of \fIname\fR. If there is no dot in the last +element of \fIname\fR then returns the empty string. +.TP +\fBfile isdirectory \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. +.TP +\fBfile isfile \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. +.TP +\fBfile join \fIname\fR ?\fIname ...\fR? +. +Takes one or more file names and combines them, using the correct path +separator for the current platform. If a particular \fIname\fR is +relative, then it will be joined to the previous file name argument. +Otherwise, any earlier arguments will be discarded, and joining will +proceed from the current argument. For example, +.RS +.CS +\fBfile join a b /foo bar\fR +.CE +returns \fB/foo/bar\fR. +.PP +Note that any of the names can contain separators, and that the result +is always canonical for the current platform: \fB/\fR for Unix and +Windows. +.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 (which is also the returned value), 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". +. +On Unix, symbolic links can be made to relative paths, and those paths +must be relative to the actual \fIlinkName\fR's location (not to the +cwd), but on all other platforms where relative links are not supported, +target paths will always be converted to absolute, normalized form +before the link is created (and therefore relative paths are interpreted +as relative to the cwd). Furthermore, "~user" paths are always expanded +to absolute form. 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) 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 +kernel call instead of \fIstat\fR. This means that if \fIname\fR +refers to a symbolic link the information returned in \fIvarName\fR +is for the link rather than the file it refers to. On systems that +don't support symbolic links this option behaves exactly the same +as the \fBstat\fR option. +.TP +\fBfile mkdir \fIdir\fR ?\fIdir\fR ...? +. +Creates each directory specified. For each pathname \fIdir\fR specified, +this command will create all non-existing parent directories as +well as \fIdir\fR itself. If an existing directory is specified, then +no action is taken and no error is returned. Trying to overwrite an existing +file with a directory will result in an error. Arguments are processed in +the order specified, halting at the first error, if any. +.TP +\fBfile mtime \fIname\fR ?\fItime\fR? +. +Returns a decimal string giving the time at which file \fIname\fR was last +modified. If \fItime\fR is specified, it is a modification time to set for +the file (equivalent to Unix \fBtouch\fR). The time is measured in the +standard POSIX fashion as seconds from a fixed starting time (often January +1, 1970). If the file doesn't exist or its modified time cannot be queried +or set then an error is generated. +.TP +\fBfile nativename \fIname\fR +. +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. +.TP +\fBfile normalize \fIname\fR +. +.RS +Returns a unique normalized path representation for the file-system +object (file, directory, link, etc), whose string value can be used as a +unique identifier for it. A normalized path is an absolute path which has +all '../', './' removed. Also it is one which is in the ``standard'' +format for the native platform. On Unix, this means the segments +leading up to the path must be free of symbolic links/aliases (but the +very last path component may be a symbolic link), and on Windows it also +means we want the long form with that form's case-dependence (which +gives us a unique, case-dependent path). The one exception concerning the +last link in the path is necessary, because Tcl or the user may wish to +operate on the actual symbolic link itself (for example 'file delete', 'file +rename', 'file copy' are defined to operate on symbolic links, not on the +things that they point to). +.RE +.TP +\fBfile owned \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR +otherwise. +.TP +\fBfile pathtype \fIname\fR +. +Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If +\fIname\fR refers to a specific file on a specific volume, the path type will +be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current +working directory, then the path type will be \fBrelative\fR. If \fIname\fR +refers to a file relative to the current working directory on a specified +volume, or to a specific file on the current working volume, then the path +type is \fBvolumerelative\fR. +.TP +\fBfile readable \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is readable by the current user, +\fB0\fR otherwise. +.TP +\fBfile readlink \fIname\fR +. +Returns the value of the symbolic link given by \fIname\fR (i.e. the name +of the file it points to). If \fIname\fR isn't a symbolic link or its +value cannot be read, then an error is returned. On systems that don't +support symbolic links this option is undefined. +.TP +\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +.TP +\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR +.RS +The first form takes the file or directory specified by pathname +\fIsource\fR and renames it to \fItarget\fR, moving the file if the +pathname \fItarget\fR specifies a name in a different directory. If +\fItarget\fR is an existing directory, then the second form is used. +The second form moves each \fIsource\fR file or directory into the +directory \fItargetDir\fR. Existing files will not be overwritten +unless the \fB\-force\fR option is specified. When operating inside a +single filesystem, Tcl will rename symbolic links rather than the +things that 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. 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 rootname \fIname\fR +. +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\fR ?\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 +the file doesn't exist or its size cannot be queried then an error is +generated. +.TP +\fBfile split \fIname\fR +. +Returns a list whose elements are the path components in \fIname\fR. The +first element of the list will have the same path type as \fIname\fR. +All other elements will be relative. Path separators will be discarded +unless they are needed ensure that an element is unambiguously relative. +For example, under Unix +.RS +.CS +file split /foo/~bar/baz +.CE +returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands +that use the third component do not attempt to perform tilde +substitution. +.RE +.TP +\fBfile stat \fIname varName\fR +. +Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable +given by \fIvarName\fR to hold information returned from the kernel call. +\fIVarName\fR is treated as an array variable, and the following elements +of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, +\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, +\fBuid\fR. Each element except \fBtype\fR is a decimal string with the +value of the corresponding field from the \fBstat\fR return structure; +see the manual entry for \fBstat\fR for details on the meanings of the +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 one or two elements, the first of which is the name of +the filesystem to use for the file, and the second, if given, an +arbitrary string representing the filesystem-specific nature or type of +the location within that filesystem. If a filesystem only supports one +type of file, the second element may not be supplied. For example the +native files have a first element 'native', and a second element which +when given is a platform-specific type name for the file's system +(e.g. 'NTFS', 'FAT', on Windows). 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 the last filesystem component of +\fIname\fR. Any trailing directory separator in \fIname\fR is ignored. +If \fIname\fR contains no separators then returns \fIname\fR. So, +\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all +return \fBb\fR. +.TP +\fBfile type \fIname\fR +. +Returns a string giving the type of file \fIname\fR, which will be one of +\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, +\fBfifo\fR, \fBlink\fR, or \fBsocket\fR. +.TP +\fBfile volumes\fR +. +Returns the absolute paths to the volumes mounted on the system, as a +proper Tcl list. Without any virtual filesystems mounted as root +volumes, on UNIX, the command will always return "/", since all +filesystems are locally mounted. +On Windows, it will return a list of the available local drives +(e.g. {a:/ c:/}). If any virtual filesystem has mounted additional +volumes, they will be in the returned list. +.TP +\fBfile writable \fIname\fR +. +Returns \fB1\fR if file \fIname\fR is writable by the current user, +\fB0\fR otherwise. +.SH "PORTABILITY ISSUES" +.TP +\fBUnix\fR\0\0\0\0\0\0\0 +. +These commands always operate using the real user and group identifiers, +not the effective ones. +.SH EXAMPLES +This procedure shows how to search for C files in a given directory +that have a correspondingly-named object file in the current +directory: +.CS +proc findMatchingCFiles {dir} { + set files {} + switch $::tcl_platform(platform) { + windows { + set ext .obj + } + unix { + set ext .o + } + } + foreach file [glob -nocomplain -directory $dir *.c] { + set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext + if {[\fBfile exists\fR $objectFile]} { + lappend files $file + } + } + return $files +} +.CE +.PP +Rename a file and leave a symbolic link pointing from the old location +to the new place: +.CS +set oldName foobar.txt +set newName foo/bar.txt +# Make sure that where we're going to move to exists... +if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { + \fBfile mkdir\fR [\fBfile dirname\fR $newName] +} +\fBfile rename\fR $oldName $newName +\fBfile link\fR -symbolic $oldName $newName +.CE + +.SH "SEE ALSO" +filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), +fblocked(n), flush(n) + +.SH KEYWORDS +attributes, copy files, delete files, directory, file, move files, name, rename files, stat -- cgit v0.12