diff options
Diffstat (limited to 'doc/file.n')
| -rw-r--r-- | doc/file.n | 300 |
1 files changed, 86 insertions, 214 deletions
@@ -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. -'\" +'\" .TH file n 8.3 Tcl "Tcl Built-In Commands" .so man.macros .BS @@ -23,7 +23,7 @@ substitution is done before executing the command (see the manual entry for file name. Any unique abbreviation for \fIoption\fR is acceptable. The valid options are: .TP -\fBfile atime \fIname\fR ?\fItime\fR? +\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 @@ -31,40 +31,35 @@ 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 does not 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. -On \fBzipfs\fR file systems, access time is mapped to the modification -time. .TP \fBfile attributes \fIname\fR .TP -\fBfile attributes \fIname\fR ?\fIoption\fR? +\fBfile attributes \fIname\fR ?\fBoption\fR? .TP -\fBfile attributes \fIname\fR ?\fIoption value option value...\fR? +\fBfile attributes \fIname\fR ?\fBoption value option value...\fR? . -This subcommand returns or sets platform-specific values associated -with a file. The first form returns a list of the platform-specific -options and their values. The second form returns the value for the -given option. The third form sets one or more of the values. The values -are as follows: +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: .RS .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 retrieves or sets a file's -access permissions, using octal notation by default. This option also -provides limited support for setting permissions using the symbolic -notation accepted by the \fBchmod\fR command, following the form -[\fBugo\fR]?[[\fB+-=\fR][\fBrwxst\fR]\fB,\fR[...]]. Multiple permission -specifications may be given, separated by commas. E.g., \fBu+s,go-rw\fR -would set the setuid bit for a file's owner as well as remove read and -write permission for the file's group and other users. An -\fBls\fR-style string of the form \fBrwxrwxrwx\fR is also accepted but -must always be 9 characters long. E.g., \fBrwxr-xr-t\fR is equivalent -to \fB01755\fR. On versions of Unix supporting file flags, -\fB-readonly\fR returns the value of, or sets, or clears the readonly -attribute of a file, i.e., the user immutable flag (\fBuchg\fR) to the -\fBchflags\fR command. +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 @@ -83,22 +78,9 @@ 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. -.PP -On all platforms, files in \fBzipfs\fR mounted archives return the following -attributes. These are all read-only and cannot be directly set. -\fB-archive\fR gives the path of the mounted ZIP archive containing the file. -\fB-compsize\fR gives the compressed size of the file within the archive. -This is \fB0\fR for directories. -\fB-crc\fR gives the CRC of the file if present, else \fB0\fR. -\fB-mount\fR gives the path where the containing archive is mounted. -\fB-offset\fR gives the offset of the file within the archive. -\fB-uncompsize\fR gives the uncompressed size of the file. -This is \fB0\fR for directories. -Other attributes may be present in the returned list. These should -be ignored. .RE .TP -\fBfile channels\fR ?\fIpattern\fR? +\fBfile channels ?\fIpattern\fR? . If \fIpattern\fR is not specified, returns a list of names of all registered open channels in this interpreter. If \fIpattern\fR is @@ -122,12 +104,12 @@ 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 -\fB\-force\fR was specified. Arguments are processed in the order +\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. .TP -\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? ?\fIpathname\fR ... ? +\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 @@ -154,35 +136,27 @@ only contains one path element, then returns If \fIname\fR refers to a root directory, then the root directory is returned. For example, .RS -.PP .CS -\fBfile dirname\fR c:/ +\fBfile dirname c:/\fR .CE -.PP -returns \fBc:/\fR. +returns \fBc:/\fR. .PP Note that tilde substitution will only be performed if it is necessary to complete the command. For example, -.PP .CS -\fBfile dirname\fR ~/src/foo.c +\fBfile dirname ~/src/foo.c\fR .CE -.PP returns \fB~/src\fR, whereas -.PP .CS -\fBfile dirname\fR ~ +\fBfile dirname ~\fR .CE -.PP 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. On Windows, which does not have an executable attribute, -the command treats all directories and any files with extensions -\fBexe\fR, \fBcom\fR, \fBcmd\fR or \fBbat\fR as executable. +\fB0\fR otherwise. .TP \fBfile exists \fIname\fR . @@ -195,24 +169,6 @@ 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 home ?\fIusername\fR? -.VS "8.7, TIP 602" -If no argument is specified, the command returns the home directory -of the current user. This is generally the value of the \fB$HOME\fR -environment variable except that on Windows platforms backslashes -in the path are replaced by forward slashes. An error is raised if -the \fB$HOME\fR environment variable is not set. -.RS -.PP -If \fIusername\fR is specified, the command returns the home directory -configured in the system for the specified user. Note this may be -different than the value of the \fB$HOME\fR environment variable -even when \fIusername\fR corresponds to the current user. An error is -raised if the \fIusername\fR does not correspond to a user account -on the system. -.RE -.VE "8.7, TIP 602" -.TP \fBfile isdirectory \fIname\fR . Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. @@ -229,11 +185,9 @@ 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 -.PP .CS -\fBfile join\fR a b /foo bar +\fBfile join a b /foo bar\fR .CE -.PP returns \fB/foo/bar\fR. .PP Note that any of the names can contain separators, and that the result @@ -241,7 +195,7 @@ is always canonical for the current platform: \fB/\fR for Unix and Windows. .RE .TP -\fBfile link\fR ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? +\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 @@ -265,9 +219,9 @@ 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 -.QW \fB\-symbolic\fR +.QW \-symbolic and -.QW \fB\-hard\fR . +.QW \-hard . .PP 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 @@ -279,21 +233,23 @@ as relative to the cwd). Furthermore, 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. Most Unix platforms support both -symbolic and hard links (the latter for files only). Windows -supports symbolic directory links and hard file links on NTFS drives. +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. .RE .TP -\fBfile lstat \fIname ?varName?\fR +\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 is for the link -rather than the file it refers to. On systems that do not support -symbolic links this option behaves exactly the same as the -\fBstat\fR option. +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 +do not support symbolic links this option behaves exactly the same +as the \fBstat\fR option. .TP -\fBfile mkdir\fR ?\fIdir\fR ...? +\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 @@ -310,7 +266,6 @@ 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 does not exist or its modified time cannot be queried or set then an error is generated. -On \fBzipfs\fR file systems, modification time cannot be explicitly set. .TP \fBfile nativename \fIname\fR . @@ -339,7 +294,7 @@ operate on the actual symbolic link itself (for example \fBfile delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic links, not on the things that they point to). .TP -\fBfile owned \fIname\fR +\fBfile owned \fIname\fR . Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR otherwise. @@ -357,7 +312,7 @@ type is \fBvolumerelative\fR. \fBfile readable \fIname\fR . Returns \fB1\fR if file \fIname\fR is readable by the current user, -\fB0\fR otherwise. +\fB0\fR otherwise. .TP \fBfile readlink \fIname\fR . @@ -395,7 +350,7 @@ component of \fIname\fR does not 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 +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 @@ -415,32 +370,27 @@ All other elements will be relative. Path separators will be discarded unless they are needed to ensure that an element is unambiguously relative. For example, under Unix .RS -.PP .CS -\fBfile split\fR /foo/~bar/baz +file split /foo/~bar/baz .CE -.PP -returns -.QW \fB/\0\0foo\0\0./~bar\0\0baz\fR -to ensure that later commands +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 returns a -dictionary with the information returned from the kernel call. If -\fIvarName\fR is given, it uses the variable to hold the information. -\fIVarName\fR is treated as an array variable, and in such case the -command returns the empty string. The following elements 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. +\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 . @@ -467,73 +417,10 @@ If the file does not belong to any filesystem, an error is generated. . 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, +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 tempdir\fR ?\fItemplate\fR? -.VS "8.7, TIP 431" -Creates a temporary directory (guaranteed to be newly created and writable by -the current script) and returns its name. If \fItemplate\fR is given, it -specifies one of or both of the existing directory (on a filesystem controlled -by the operating system) to contain the temporary directory, and the base part -of the directory name; it is considered to have the location of the directory -if there is a directory separator in the name, and the base part is everything -after the last directory separator (if non-empty). The default containing -directory is determined by system-specific operations, and the default base -name prefix is -.QW \fBtcl\fR . -.RS -.PP -The following output is typical and illustrative; the actual output will vary -between platforms: -.PP -.CS -% \fBfile tempdir\fR -/var/tmp/tcl_u0kuy5 - % \fBfile tempdir\fR /tmp/myapp -/tmp/myapp_8o7r9L -% \fBfile tempdir\fR /tmp/ -/tmp/tcl_1mOJHD -% \fBfile tempdir\fR myapp -/var/tmp/myapp_0ihS0n -.CE -.RE -.VE "8.7, TIP 431" -.TP -\fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? -'\" TIP #210 -Creates a temporary file and returns a read-write channel opened on that file. -If the \fInameVar\fR is given, it specifies a variable that the name of the -temporary file will be written into; if absent, Tcl will attempt to arrange -for the temporary file to be deleted once it is no longer required. If the -\fItemplate\fR is present, it specifies parts of the template of the filename -to use when creating it (such as the directory, base-name or extension) though -some platforms may ignore some or all of these parts and use a built-in -default instead. -.RS -.PP -Note that temporary files are \fIonly\fR ever created on the native -filesystem. As such, they can be relied upon to be used with operating-system -native APIs and external programs that require a filename. -.RE -.TP -\fBfile tildeexpand \fIname\fR -.VS "8.7, TIP 602" -Returns the result of performing tilde substitution on \fIname\fR. If the name -begins with a tilde, then the file name will be interpreted as if the first -element is replaced with the location of the home directory for the given user. -If the tilde is followed immediately by a path separator, the \fBHOME\fR -environment variable is substituted. Otherwise the characters between the -tilde and the next separator are taken as a user name, which is used to -retrieve the user's home directory for substitution. An error is raised if the -\fBHOME\fR environment variable or user does not exist. -.RS -.PP -If the file name does not begin with a tilde, it is returned unmodified. -.RE -.VE "8.7, TIP 602" -.TP \fBfile type \fIname\fR . Returns a string giving the type of file \fIname\fR, which will be one of @@ -541,7 +428,7 @@ Returns a string giving the type of file \fIname\fR, which will be one of \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 @@ -562,49 +449,40 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user, \fBUnix\fR\0\0\0\0\0\0\0 . These commands always operate using the real user and group identifiers, -not the effective ones. -.TP -\fBWindows\fR\0\0\0\0 -. -The \fBfile owned\fR subcommand uses the user identifier (SID) of -the process token, not the thread token which may be impersonating -some other user. +not the effective ones. .SH EXAMPLES -.PP This procedure shows how to search for C files in a given directory that have a correspondingly-named object file in the current directory: -.PP .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 + 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: -.PP .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 mkdir\fR [\fBfile dirname\fR $newName] } \fBfile rename\fR $oldName $newName \fBfile link\fR \-symbolic $oldName $newName @@ -615,7 +493,6 @@ On Windows, a file can be easily enough (equivalent to double-clicking on it in the Explorer interface) but the name passed to the operating system must be in native format: -.PP .CS exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] .CE @@ -623,9 +500,4 @@ exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] 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, user -'\" Local Variables: -'\" mode: nroff -'\" fill-column: 78 -'\" End: +attributes, copy files, delete files, directory, file, move files, name, rename files, stat |