[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: file.n,v 1.53 2007/12/13 15:22:32 dgp Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH file n 8.3 Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | file \- Manipulate file names and attributes |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? |
---|
| 18 | .BE |
---|
| 19 | .SH DESCRIPTION |
---|
| 20 | .PP |
---|
| 21 | This command provides several operations on a file's name or attributes. |
---|
| 22 | \fIName\fR is the name of a file; if it starts with a tilde, then tilde |
---|
| 23 | substitution is done before executing the command (see the manual entry for |
---|
| 24 | \fBfilename\fR for details). \fIOption\fR indicates what to do with the |
---|
| 25 | file name. Any unique abbreviation for \fIoption\fR is acceptable. The |
---|
| 26 | valid options are: |
---|
| 27 | .TP |
---|
| 28 | \fBfile atime \fIname\fR ?\fBtime\fR? |
---|
| 29 | . |
---|
| 30 | Returns a decimal string giving the time at which file \fIname\fR was last |
---|
| 31 | accessed. If \fItime\fR is specified, it is an access time to set |
---|
| 32 | for the file. The time is measured in the standard POSIX fashion as |
---|
| 33 | seconds from a fixed starting time (often January 1, 1970). If the file |
---|
| 34 | does not exist or its access time cannot be queried or set then an error is |
---|
| 35 | generated. On Windows, FAT file systems do not support access time. |
---|
| 36 | .TP |
---|
| 37 | \fBfile attributes \fIname\fR |
---|
| 38 | .TP |
---|
| 39 | \fBfile attributes \fIname\fR ?\fBoption\fR? |
---|
| 40 | .TP |
---|
| 41 | \fBfile attributes \fIname\fR ?\fBoption value option value...\fR? |
---|
| 42 | . |
---|
| 43 | This subcommand returns or sets platform specific values associated |
---|
| 44 | with a file. The first form returns a list of the platform specific |
---|
| 45 | flags and their values. The second form returns the value for the |
---|
| 46 | specific option. The third form sets one or more of the values. The |
---|
| 47 | values are as follows: |
---|
| 48 | .RS |
---|
| 49 | .PP |
---|
| 50 | On Unix, \fB\-group\fR gets or sets the group name for the file. A group id |
---|
| 51 | can be given to the command, but it returns a group name. \fB\-owner\fR gets |
---|
| 52 | or sets the user name of the owner of the file. The command returns the |
---|
| 53 | owner name, but the numerical id can be passed when setting the |
---|
| 54 | owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1) |
---|
| 55 | uses. This command does also has limited support for setting using the |
---|
| 56 | symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], |
---|
| 57 | where multiple symbolic attributes can be separated by commas (example: |
---|
| 58 | \fBu+s,go\-rw\fR add sticky bit for user, remove read and write |
---|
| 59 | permissions for group and other). A simplified \fBls\fR style string, |
---|
| 60 | of the form rwxrwxrwx (must be 9 characters), is also supported |
---|
| 61 | (example: \fBrwxr\-xr\-t\fR is equivalent to 01755). |
---|
| 62 | On versions of Unix supporting file flags, \fB\-readonly\fR gives the |
---|
| 63 | value or sets or clears the readonly attribute of the file, |
---|
| 64 | i.e. the user immutable flag \fBuchg\fR to chflags(1). |
---|
| 65 | .PP |
---|
| 66 | On Windows, \fB\-archive\fR gives the value or sets or clears the |
---|
| 67 | archive attribute of the file. \fB\-hidden\fR gives the value or sets |
---|
| 68 | or clears the hidden attribute of the file. \fB\-longname\fR will |
---|
| 69 | expand each path element to its long version. This attribute cannot be |
---|
| 70 | set. \fB\-readonly\fR gives the value or sets or clears the readonly |
---|
| 71 | attribute of the file. \fB\-shortname\fR gives a string where every |
---|
| 72 | path element is replaced with its short (8.3) version of the |
---|
| 73 | name. This attribute cannot be set. \fB\-system\fR gives or sets or |
---|
| 74 | clears the value of the system attribute of the file. |
---|
| 75 | .PP |
---|
| 76 | On Mac OS X and Darwin, \fB\-creator\fR gives or sets the |
---|
| 77 | Finder creator type of the file. \fB\-hidden\fR gives or sets or clears |
---|
| 78 | the hidden attribute of the file. \fB\-readonly\fR gives or sets or |
---|
| 79 | clears the readonly attribute of the file. \fB\-rsrclength\fR gives |
---|
| 80 | the length of the resource fork of the file, this attribute can only be |
---|
| 81 | set to the value 0, which results in the resource fork being stripped |
---|
| 82 | off the file. |
---|
| 83 | .RE |
---|
| 84 | .TP |
---|
| 85 | \fBfile channels ?\fIpattern\fR? |
---|
| 86 | . |
---|
| 87 | If \fIpattern\fR is not specified, returns a list of names of all |
---|
| 88 | registered open channels in this interpreter. If \fIpattern\fR is |
---|
| 89 | specified, only those names matching \fIpattern\fR are returned. Matching |
---|
| 90 | is determined using the same rules as for \fBstring match\fR. |
---|
| 91 | .TP |
---|
| 92 | \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR |
---|
| 93 | .TP |
---|
| 94 | \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR |
---|
| 95 | . |
---|
| 96 | The first form makes a copy of the file or directory \fIsource\fR under |
---|
| 97 | the pathname \fItarget\fR. If \fItarget\fR is an existing directory, |
---|
| 98 | then the second form is used. The second form makes a copy inside |
---|
| 99 | \fItargetDir\fR of each \fIsource\fR file listed. If a directory is |
---|
| 100 | specified as a \fIsource\fR, then the contents of the directory will be |
---|
| 101 | recursively copied into \fItargetDir\fR. Existing files will not be |
---|
| 102 | overwritten unless the \fB\-force\fR option is specified (when Tcl will |
---|
| 103 | also attempt to adjust permissions on the destination file or directory |
---|
| 104 | if that is necessary to allow the copy to proceed). When copying |
---|
| 105 | within a single filesystem, \fIfile copy\fR will copy soft links (i.e. |
---|
| 106 | the links themselves are copied, not the things they point to). Trying |
---|
| 107 | to overwrite a non-empty directory, overwrite a directory with a file, |
---|
| 108 | or overwrite a file with a directory will all result in errors even if |
---|
| 109 | \fI\-force\fR was specified. Arguments are processed in the order |
---|
| 110 | specified, halting at the first error, if any. A \fB\-\|\-\fR marks |
---|
| 111 | the end of switches; the argument following the \fB\-\|\-\fR will be |
---|
| 112 | treated as a \fIsource\fR even if it starts with a \fB\-\fR. |
---|
| 113 | .TP |
---|
| 114 | \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ? |
---|
| 115 | . |
---|
| 116 | Removes the file or directory specified by each \fIpathname\fR |
---|
| 117 | argument. Non-empty directories will be removed only if the |
---|
| 118 | \fB\-force\fR option is specified. When operating on symbolic links, |
---|
| 119 | the links themselves will be deleted, not the objects they point to. |
---|
| 120 | Trying to delete a non-existent file is not considered an error. |
---|
| 121 | Trying to delete a read-only file will cause the file to be deleted, |
---|
| 122 | even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR |
---|
| 123 | option is specified on a directory, Tcl will attempt both to change |
---|
| 124 | permissions and move the current directory |
---|
| 125 | .QW pwd |
---|
| 126 | out of the given path if that is necessary to allow the deletion to |
---|
| 127 | proceed. Arguments are processed in the order specified, halting at |
---|
| 128 | the first error, if any. |
---|
| 129 | A \fB\-\|\-\fR marks the end of switches; the argument following the |
---|
| 130 | \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with |
---|
| 131 | a \fB\-\fR. |
---|
| 132 | .TP |
---|
| 133 | \fBfile dirname \fIname\fR |
---|
| 134 | Returns a name comprised of all of the path components in \fIname\fR |
---|
| 135 | excluding the last element. If \fIname\fR is a relative file name and |
---|
| 136 | only contains one path element, then returns |
---|
| 137 | .QW \fB.\fR . |
---|
| 138 | If \fIname\fR refers to a root directory, then the root directory is |
---|
| 139 | returned. For example, |
---|
| 140 | .RS |
---|
| 141 | .CS |
---|
| 142 | \fBfile dirname c:/\fR |
---|
| 143 | .CE |
---|
| 144 | returns \fBc:/\fR. |
---|
| 145 | .PP |
---|
| 146 | Note that tilde substitution will only be |
---|
| 147 | performed if it is necessary to complete the command. For example, |
---|
| 148 | .CS |
---|
| 149 | \fBfile dirname ~/src/foo.c\fR |
---|
| 150 | .CE |
---|
| 151 | returns \fB~/src\fR, whereas |
---|
| 152 | .CS |
---|
| 153 | \fBfile dirname ~\fR |
---|
| 154 | .CE |
---|
| 155 | returns \fB/home\fR (or something similar). |
---|
| 156 | .RE |
---|
| 157 | .TP |
---|
| 158 | \fBfile executable \fIname\fR |
---|
| 159 | . |
---|
| 160 | Returns \fB1\fR if file \fIname\fR is executable by the current user, |
---|
| 161 | \fB0\fR otherwise. |
---|
| 162 | .TP |
---|
| 163 | \fBfile exists \fIname\fR |
---|
| 164 | . |
---|
| 165 | Returns \fB1\fR if file \fIname\fR exists and the current user has |
---|
| 166 | search privileges for the directories leading to it, \fB0\fR otherwise. |
---|
| 167 | .TP |
---|
| 168 | \fBfile extension \fIname\fR |
---|
| 169 | . |
---|
| 170 | Returns all of the characters in \fIname\fR after and including the last |
---|
| 171 | dot in the last element of \fIname\fR. If there is no dot in the last |
---|
| 172 | element of \fIname\fR then returns the empty string. |
---|
| 173 | .TP |
---|
| 174 | \fBfile isdirectory \fIname\fR |
---|
| 175 | . |
---|
| 176 | Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. |
---|
| 177 | .TP |
---|
| 178 | \fBfile isfile \fIname\fR |
---|
| 179 | . |
---|
| 180 | Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. |
---|
| 181 | .TP |
---|
| 182 | \fBfile join \fIname\fR ?\fIname ...\fR? |
---|
| 183 | . |
---|
| 184 | Takes one or more file names and combines them, using the correct path |
---|
| 185 | separator for the current platform. If a particular \fIname\fR is |
---|
| 186 | relative, then it will be joined to the previous file name argument. |
---|
| 187 | Otherwise, any earlier arguments will be discarded, and joining will |
---|
| 188 | proceed from the current argument. For example, |
---|
| 189 | .RS |
---|
| 190 | .CS |
---|
| 191 | \fBfile join a b /foo bar\fR |
---|
| 192 | .CE |
---|
| 193 | returns \fB/foo/bar\fR. |
---|
| 194 | .PP |
---|
| 195 | Note that any of the names can contain separators, and that the result |
---|
| 196 | is always canonical for the current platform: \fB/\fR for Unix and |
---|
| 197 | Windows. |
---|
| 198 | .RE |
---|
| 199 | .TP |
---|
| 200 | \fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? |
---|
| 201 | . |
---|
| 202 | If only one argument is given, that argument is assumed to be |
---|
| 203 | \fIlinkName\fR, and this command returns the value of the link given by |
---|
| 204 | \fIlinkName\fR (i.e. the name of the file it points to). If |
---|
| 205 | \fIlinkName\fR is not a link or its value cannot be read (as, for example, |
---|
| 206 | seems to be the case with hard links, which look just like ordinary |
---|
| 207 | files), then an error is returned. |
---|
| 208 | .RS |
---|
| 209 | .PP |
---|
| 210 | If 2 arguments are given, then these are assumed to be \fIlinkName\fR |
---|
| 211 | and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR |
---|
| 212 | does not exist, an error will be returned. Otherwise, Tcl creates a new |
---|
| 213 | link called \fIlinkName\fR which points to the existing filesystem |
---|
| 214 | object at \fItarget\fR (which is also the returned value), where the |
---|
| 215 | type of the link is platform-specific (on Unix a symbolic link will be |
---|
| 216 | the default). This is useful for the case where the user wishes to |
---|
| 217 | create a link in a cross-platform way, and does not care what type of |
---|
| 218 | link is created. |
---|
| 219 | .PP |
---|
| 220 | If the user wishes to make a link of a specific type only, (and signal an |
---|
| 221 | error if for some reason that is not possible), then the optional |
---|
| 222 | \fI\-linktype\fR argument should be given. Accepted values for |
---|
| 223 | \fI\-linktype\fR are |
---|
| 224 | .QW \-symbolic |
---|
| 225 | and |
---|
| 226 | .QW \-hard . |
---|
| 227 | .PP |
---|
| 228 | On Unix, symbolic links can be made to relative paths, and those paths |
---|
| 229 | must be relative to the actual \fIlinkName\fR's location (not to the |
---|
| 230 | cwd), but on all other platforms where relative links are not supported, |
---|
| 231 | target paths will always be converted to absolute, normalized form |
---|
| 232 | before the link is created (and therefore relative paths are interpreted |
---|
| 233 | as relative to the cwd). Furthermore, |
---|
| 234 | .QW ~user |
---|
| 235 | paths are always expanded |
---|
| 236 | to absolute form. When creating links on filesystems that either do not |
---|
| 237 | support any links, or do not support the specific type requested, an |
---|
| 238 | error message will be returned. In particular Windows 95, 98 and ME do |
---|
| 239 | not support any links at present, but most Unix platforms support both |
---|
| 240 | symbolic and hard links (the latter for files only) and Windows |
---|
| 241 | NT/2000/XP (on NTFS drives) support symbolic |
---|
| 242 | directory links and hard file links. |
---|
| 243 | .RE |
---|
| 244 | .TP |
---|
| 245 | \fBfile lstat \fIname varName\fR |
---|
| 246 | . |
---|
| 247 | Same as \fBstat\fR option (see below) except uses the \fIlstat\fR |
---|
| 248 | kernel call instead of \fIstat\fR. This means that if \fIname\fR |
---|
| 249 | refers to a symbolic link the information returned in \fIvarName\fR |
---|
| 250 | is for the link rather than the file it refers to. On systems that |
---|
| 251 | do not support symbolic links this option behaves exactly the same |
---|
| 252 | as the \fBstat\fR option. |
---|
| 253 | .TP |
---|
| 254 | \fBfile mkdir \fIdir\fR ?\fIdir\fR ...? |
---|
| 255 | . |
---|
| 256 | Creates each directory specified. For each pathname \fIdir\fR specified, |
---|
| 257 | this command will create all non-existing parent directories as |
---|
| 258 | well as \fIdir\fR itself. If an existing directory is specified, then |
---|
| 259 | no action is taken and no error is returned. Trying to overwrite an existing |
---|
| 260 | file with a directory will result in an error. Arguments are processed in |
---|
| 261 | the order specified, halting at the first error, if any. |
---|
| 262 | .TP |
---|
| 263 | \fBfile mtime \fIname\fR ?\fItime\fR? |
---|
| 264 | . |
---|
| 265 | Returns a decimal string giving the time at which file \fIname\fR was last |
---|
| 266 | modified. If \fItime\fR is specified, it is a modification time to set for |
---|
| 267 | the file (equivalent to Unix \fBtouch\fR). The time is measured in the |
---|
| 268 | standard POSIX fashion as seconds from a fixed starting time (often January |
---|
| 269 | 1, 1970). If the file does not exist or its modified time cannot be queried |
---|
| 270 | or set then an error is generated. |
---|
| 271 | .TP |
---|
| 272 | \fBfile nativename \fIname\fR |
---|
| 273 | . |
---|
| 274 | Returns the platform-specific name of the file. This is useful if the |
---|
| 275 | filename is needed to pass to a platform-specific call, such as to a |
---|
| 276 | subprocess via \fBexec\fR under Windows (see \fBEXAMPLES\fR below). |
---|
| 277 | .TP |
---|
| 278 | \fBfile normalize \fIname\fR |
---|
| 279 | . |
---|
| 280 | Returns a unique normalized path representation for the file-system |
---|
| 281 | object (file, directory, link, etc), whose string value can be used as a |
---|
| 282 | unique identifier for it. A normalized path is an absolute path which has |
---|
| 283 | all |
---|
| 284 | .QW ../ |
---|
| 285 | and |
---|
| 286 | .QW ./ |
---|
| 287 | removed. Also it is one which is in the |
---|
| 288 | .QW standard |
---|
| 289 | format for the native platform. On Unix, this means the segments |
---|
| 290 | leading up to the path must be free of symbolic links/aliases (but the |
---|
| 291 | very last path component may be a symbolic link), and on Windows it also |
---|
| 292 | means we want the long form with that form's case-dependence (which |
---|
| 293 | gives us a unique, case-dependent path). The one exception concerning the |
---|
| 294 | last link in the path is necessary, because Tcl or the user may wish to |
---|
| 295 | operate on the actual symbolic link itself (for example \fBfile delete\fR, |
---|
| 296 | \fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic |
---|
| 297 | links, not on the things that they point to). |
---|
| 298 | .TP |
---|
| 299 | \fBfile owned \fIname\fR |
---|
| 300 | . |
---|
| 301 | Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR |
---|
| 302 | otherwise. |
---|
| 303 | .TP |
---|
| 304 | \fBfile pathtype \fIname\fR |
---|
| 305 | . |
---|
| 306 | Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If |
---|
| 307 | \fIname\fR refers to a specific file on a specific volume, the path type will |
---|
| 308 | be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current |
---|
| 309 | working directory, then the path type will be \fBrelative\fR. If \fIname\fR |
---|
| 310 | refers to a file relative to the current working directory on a specified |
---|
| 311 | volume, or to a specific file on the current working volume, then the path |
---|
| 312 | type is \fBvolumerelative\fR. |
---|
| 313 | .TP |
---|
| 314 | \fBfile readable \fIname\fR |
---|
| 315 | . |
---|
| 316 | Returns \fB1\fR if file \fIname\fR is readable by the current user, |
---|
| 317 | \fB0\fR otherwise. |
---|
| 318 | .TP |
---|
| 319 | \fBfile readlink \fIname\fR |
---|
| 320 | . |
---|
| 321 | Returns the value of the symbolic link given by \fIname\fR (i.e. the name |
---|
| 322 | of the file it points to). If \fIname\fR is npt a symbolic link or its |
---|
| 323 | value cannot be read, then an error is returned. On systems that do not |
---|
| 324 | support symbolic links this option is undefined. |
---|
| 325 | .TP |
---|
| 326 | \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR |
---|
| 327 | .TP |
---|
| 328 | \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR |
---|
| 329 | . |
---|
| 330 | The first form takes the file or directory specified by pathname |
---|
| 331 | \fIsource\fR and renames it to \fItarget\fR, moving the file if the |
---|
| 332 | pathname \fItarget\fR specifies a name in a different directory. If |
---|
| 333 | \fItarget\fR is an existing directory, then the second form is used. |
---|
| 334 | The second form moves each \fIsource\fR file or directory into the |
---|
| 335 | directory \fItargetDir\fR. Existing files will not be overwritten |
---|
| 336 | unless the \fB\-force\fR option is specified. When operating inside a |
---|
| 337 | single filesystem, Tcl will rename symbolic links rather than the |
---|
| 338 | things that they point to. Trying to overwrite a non-empty directory, |
---|
| 339 | overwrite a directory with a file, or a file with a directory will all |
---|
| 340 | result in errors. Arguments are processed in the order specified, |
---|
| 341 | halting at the first error, if any. A \fB\-\|\-\fR marks the end of |
---|
| 342 | switches; the argument following the \fB\-\|\-\fR will be treated as a |
---|
| 343 | \fIsource\fR even if it starts with a \fB\-\fR. |
---|
| 344 | .TP |
---|
| 345 | \fBfile rootname \fIname\fR |
---|
| 346 | . |
---|
| 347 | Returns all of the characters in \fIname\fR up to but not including the |
---|
| 348 | last |
---|
| 349 | .QW . |
---|
| 350 | character in the last component of name. If the last |
---|
| 351 | component of \fIname\fR does not contain a dot, then returns \fIname\fR. |
---|
| 352 | .TP |
---|
| 353 | \fBfile separator\fR ?\fIname\fR? |
---|
| 354 | . |
---|
| 355 | If no argument is given, returns the character which is used to separate |
---|
| 356 | path segments for native files on this platform. If a path is given, |
---|
| 357 | the filesystem responsible for that path is asked to return its |
---|
| 358 | separator character. If no file system accepts \fIname\fR, an error |
---|
| 359 | is generated. |
---|
| 360 | .TP |
---|
| 361 | \fBfile size \fIname\fR |
---|
| 362 | . |
---|
| 363 | Returns a decimal string giving the size of file \fIname\fR in bytes. If |
---|
| 364 | the file does not exist or its size cannot be queried then an error is |
---|
| 365 | generated. |
---|
| 366 | .TP |
---|
| 367 | \fBfile split \fIname\fR |
---|
| 368 | . |
---|
| 369 | Returns a list whose elements are the path components in \fIname\fR. The |
---|
| 370 | first element of the list will have the same path type as \fIname\fR. |
---|
| 371 | All other elements will be relative. Path separators will be discarded |
---|
| 372 | unless they are needed ensure that an element is unambiguously relative. |
---|
| 373 | For example, under Unix |
---|
| 374 | .RS |
---|
| 375 | .CS |
---|
| 376 | file split /foo/~bar/baz |
---|
| 377 | .CE |
---|
| 378 | returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands |
---|
| 379 | that use the third component do not attempt to perform tilde |
---|
| 380 | substitution. |
---|
| 381 | .RE |
---|
| 382 | .TP |
---|
| 383 | \fBfile stat \fIname varName\fR |
---|
| 384 | . |
---|
| 385 | Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable |
---|
| 386 | given by \fIvarName\fR to hold information returned from the kernel call. |
---|
| 387 | \fIVarName\fR is treated as an array variable, and the following elements |
---|
| 388 | of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, |
---|
| 389 | \fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, |
---|
| 390 | \fBuid\fR. Each element except \fBtype\fR is a decimal string with the |
---|
| 391 | value of the corresponding field from the \fBstat\fR return structure; |
---|
| 392 | see the manual entry for \fBstat\fR for details on the meanings of the |
---|
| 393 | values. The \fBtype\fR element gives the type of the file in the same |
---|
| 394 | form returned by the command \fBfile type\fR. This command returns an |
---|
| 395 | empty string. |
---|
| 396 | .TP |
---|
| 397 | \fBfile system \fIname\fR |
---|
| 398 | . |
---|
| 399 | Returns a list of one or two elements, the first of which is the name of |
---|
| 400 | the filesystem to use for the file, and the second, if given, an |
---|
| 401 | arbitrary string representing the filesystem-specific nature or type of |
---|
| 402 | the location within that filesystem. If a filesystem only supports one |
---|
| 403 | type of file, the second element may not be supplied. For example the |
---|
| 404 | native files have a first element |
---|
| 405 | .QW native , |
---|
| 406 | and a second element which when given is a platform-specific type name |
---|
| 407 | for the file's system (e.g. |
---|
| 408 | .QW NTFS , |
---|
| 409 | .QW FAT , |
---|
| 410 | on Windows). A generic virtual file system might return |
---|
| 411 | the list |
---|
| 412 | .QW "vfs ftp" |
---|
| 413 | to represent a file on a remote ftp site mounted as a |
---|
| 414 | virtual filesystem through an extension called |
---|
| 415 | .QW vfs . |
---|
| 416 | If the file does not belong to any filesystem, an error is generated. |
---|
| 417 | .TP |
---|
| 418 | \fBfile tail \fIname\fR |
---|
| 419 | . |
---|
| 420 | Returns all of the characters in the last filesystem component of |
---|
| 421 | \fIname\fR. Any trailing directory separator in \fIname\fR is ignored. |
---|
| 422 | If \fIname\fR contains no separators then returns \fIname\fR. So, |
---|
| 423 | \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all |
---|
| 424 | return \fBb\fR. |
---|
| 425 | .TP |
---|
| 426 | \fBfile type \fIname\fR |
---|
| 427 | . |
---|
| 428 | Returns a string giving the type of file \fIname\fR, which will be one of |
---|
| 429 | \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, |
---|
| 430 | \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. |
---|
| 431 | .TP |
---|
| 432 | \fBfile volumes\fR |
---|
| 433 | . |
---|
| 434 | Returns the absolute paths to the volumes mounted on the system, as a |
---|
| 435 | proper Tcl list. Without any virtual filesystems mounted as root |
---|
| 436 | volumes, on UNIX, the command will always return |
---|
| 437 | .QW / , |
---|
| 438 | since all filesystems are locally mounted. |
---|
| 439 | On Windows, it will return a list of the available local drives |
---|
| 440 | (e.g. |
---|
| 441 | .QW "a:/ c:/" ). |
---|
| 442 | If any virtual filesystem has mounted additional |
---|
| 443 | volumes, they will be in the returned list. |
---|
| 444 | .TP |
---|
| 445 | \fBfile writable \fIname\fR |
---|
| 446 | . |
---|
| 447 | Returns \fB1\fR if file \fIname\fR is writable by the current user, |
---|
| 448 | \fB0\fR otherwise. |
---|
| 449 | .SH "PORTABILITY ISSUES" |
---|
| 450 | .TP |
---|
| 451 | \fBUnix\fR\0\0\0\0\0\0\0 |
---|
| 452 | . |
---|
| 453 | These commands always operate using the real user and group identifiers, |
---|
| 454 | not the effective ones. |
---|
| 455 | .SH EXAMPLES |
---|
| 456 | This procedure shows how to search for C files in a given directory |
---|
| 457 | that have a correspondingly-named object file in the current |
---|
| 458 | directory: |
---|
| 459 | .CS |
---|
| 460 | proc findMatchingCFiles {dir} { |
---|
| 461 | set files {} |
---|
| 462 | switch $::tcl_platform(platform) { |
---|
| 463 | windows { |
---|
| 464 | set ext .obj |
---|
| 465 | } |
---|
| 466 | unix { |
---|
| 467 | set ext .o |
---|
| 468 | } |
---|
| 469 | } |
---|
| 470 | foreach file [glob \-nocomplain \-directory $dir *.c] { |
---|
| 471 | set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext |
---|
| 472 | if {[\fBfile exists\fR $objectFile]} { |
---|
| 473 | lappend files $file |
---|
| 474 | } |
---|
| 475 | } |
---|
| 476 | return $files |
---|
| 477 | } |
---|
| 478 | .CE |
---|
| 479 | .PP |
---|
| 480 | Rename a file and leave a symbolic link pointing from the old location |
---|
| 481 | to the new place: |
---|
| 482 | .CS |
---|
| 483 | set oldName foobar.txt |
---|
| 484 | set newName foo/bar.txt |
---|
| 485 | # Make sure that where we're going to move to exists... |
---|
| 486 | if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} { |
---|
| 487 | \fBfile mkdir\fR [\fBfile dirname\fR $newName] |
---|
| 488 | } |
---|
| 489 | \fBfile rename\fR $oldName $newName |
---|
| 490 | \fBfile link\fR \-symbolic $oldName $newName |
---|
| 491 | .CE |
---|
| 492 | .PP |
---|
| 493 | On Windows, a file can be |
---|
| 494 | .QW started |
---|
| 495 | easily enough (equivalent to double-clicking on it in the Explorer |
---|
| 496 | interface) but the name passed to the operating system must be in |
---|
| 497 | native format: |
---|
| 498 | .CS |
---|
| 499 | exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] |
---|
| 500 | .CE |
---|
| 501 | .SH "SEE ALSO" |
---|
| 502 | filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), |
---|
| 503 | fblocked(n), flush(n) |
---|
| 504 | .SH KEYWORDS |
---|
| 505 | attributes, copy files, delete files, directory, file, move files, name, rename files, stat |
---|