1file(n) Tcl Built-In Commands file(n)
2______________________________________________________________________________
6
8 file - Manipulate file names and attributes
9
11 file option name ?arg arg ...?
12______________________________________________________________________________
13
15 This command provides several operations on a file's name or at‐
16 tributes. Name is the name of a file; if it starts with a tilde, then
17 tilde substitution is done before executing the command (see the manual
18 entry for filename for details). Option indicates what to do with the
19 file name. Any unique abbreviation for option is acceptable. The
20 valid options are:
21 file atime name ?time?
23 Returns a decimal string giving the time at which file name was
24 last accessed. If time is specified, it is an access time to
25 set for the file. The time is measured in the standard POSIX
26 fashion as seconds from a fixed starting time (often January 1,
27 1970). If the file does not exist or its access time cannot be
28 queried or set then an error is generated. On Windows, FAT file
29 systems do not support access time.
30 file attributes name
32 file attributes name ?option?
34 file attributes name ?option value option value...?
36 This subcommand returns or sets platform-specific values associ‐
37 ated with a file. The first form returns a list of the platform-
38 specific options and their values. The second form returns the
39 value for the given option. The third form sets one or more of
40 the values. The values are as follows:
41 On Unix, -group gets or sets the group name for the file. A
43 group id can be given to the command, but it returns a group
44 name. -owner gets or sets the user name of the owner of the
45 file. The command returns the owner name, but the numerical id
46 can be passed when setting the owner. -permissions retrieves or
47 sets a file's access permissions, using octal notation by de‐
48 fault. This option also provides limited support for setting
49 permissions using the symbolic notation accepted by the chmod
50 command, following the form [ugo]?[[+-=][rwxst],[...]]. Multiple
51 permission specifications may be given, separated by commas.
52 E.g., u+s,go-rw would set the setuid bit for a file's owner as
53 well as remove read and write permission for the file's group
54 and other users. An ls-style string of the form rwxrwxrwx is
55 also accepted but must always be 9 characters long. E.g., rwxr-
56 xr-t is equivalent to 01755. On versions of Unix supporting file
57 flags, -readonly returns the value of, or sets, or clears the
58 readonly attribute of a file, i.e., the user immutable flag
59 (uchg) to the chflags command.
60 On Windows, -archive gives the value or sets or clears the ar‐
62 chive attribute of the file. -hidden gives the value or sets or
63 clears the hidden attribute of the file. -longname will expand
64 each path element to its long version. This attribute cannot be
65 set. -readonly gives the value or sets or clears the readonly
66 attribute of the file. -shortname gives a string where every
67 path element is replaced with its short (8.3) version of the
68 name. This attribute cannot be set. -system gives or sets or
69 clears the value of the system attribute of the file.
70 On Mac OS X and Darwin, -creator gives or sets the Finder cre‐
72 ator type of the file. -hidden gives or sets or clears the hid‐
73 den attribute of the file. -readonly gives or sets or clears the
74 readonly attribute of the file. -rsrclength gives the length of
75 the resource fork of the file, this attribute can only be set to
76 the value 0, which results in the resource fork being stripped
77 off the file.
78 file channels ?pattern?
80 If pattern is not specified, returns a list of names of all reg‐
81 istered open channels in this interpreter. If pattern is speci‐
82 fied, only those names matching pattern are returned. Matching
83 is determined using the same rules as for string match.
84 file copy ?-force? ?--? source target
86 file copy ?-force? ?--? source ?source ...? targetDir
88 The first form makes a copy of the file or directory source un‐
89 der the pathname target. If target is an existing directory,
90 then the second form is used. The second form makes a copy in‐
91 side targetDir of each source file listed. If a directory is
92 specified as a source, then the contents of the directory will
93 be recursively copied into targetDir. Existing files will not be
94 overwritten unless the -force option is specified (when Tcl will
95 also attempt to adjust permissions on the destination file or
96 directory if that is necessary to allow the copy to proceed).
97 When copying within a single filesystem, file copy will copy
98 soft links (i.e. the links themselves are copied, not the
99 things they point to). Trying to overwrite a non-empty direc‐
100 tory, overwrite a directory with a file, or overwrite a file
101 with a directory will all result in errors even if -force was
102 specified. Arguments are processed in the order specified,
103 halting at the first error, if any. A -- marks the end of
104 switches; the argument following the -- will be treated as a
105 source even if it starts with a -.
106 file delete ?-force? ?--? ?pathname ... ?
108 Removes the file or directory specified by each pathname argu‐
109 ment. Non-empty directories will be removed only if the -force
110 option is specified. When operating on symbolic links, the
111 links themselves will be deleted, not the objects they point to.
112 Trying to delete a non-existent file is not considered an error.
113 Trying to delete a read-only file will cause the file to be
114 deleted, even if the -force flags is not specified. If the
115 -force option is specified on a directory, Tcl will attempt both
116 to change permissions and move the current directory “pwd” out
117 of the given path if that is necessary to allow the deletion to
118 proceed. Arguments are processed in the order specified, halt‐
119 ing at the first error, if any. A -- marks the end of switches;
120 the argument following the -- will be treated as a pathname even
121 if it starts with a -.
122 file dirname name
124 Returns a name comprised of all of the path components in name
125 excluding the last element. If name is a relative file name and
126 only contains one path element, then returns “.”. If name
127 refers to a root directory, then the root directory is returned.
128 For example,
129 file dirname c:/
131 returns c:/.
133 Note that tilde substitution will only be performed if it is
135 necessary to complete the command. For example,
136 file dirname ~/src/foo.c
138 returns ~/src, whereas
140 file dirname ~
142 returns /home (or something similar).
144 file executable name
146 Returns 1 if file name is executable by the current user, 0 oth‐
147 erwise. On Windows, which does not have an executable attribute,
148 the command treats all directories and any files with extensions
149 exe, com, cmd or bat as executable.
150 file exists name
152 Returns 1 if file name exists and the current user has search
153 privileges for the directories leading to it, 0 otherwise.
154 file extension name
156 Returns all of the characters in name after and including the
157 last dot in the last element of name. If there is no dot in the
158 last element of name then returns the empty string.
159 file isdirectory name
161 Returns 1 if file name is a directory, 0 otherwise.
162 file isfile name
164 Returns 1 if file name is a regular file, 0 otherwise.
165 file join name ?name ...?
167 Takes one or more file names and combines them, using the cor‐
168 rect path separator for the current platform. If a particular
169 name is relative, then it will be joined to the previous file
170 name argument. Otherwise, any earlier arguments will be dis‐
171 carded, and joining will proceed from the current argument. For
172 example,
173 file join a b /foo bar
175 returns /foo/bar.
177 Note that any of the names can contain separators, and that the
179 result is always canonical for the current platform: / for Unix
180 and Windows.
181 file link ?-linktype? linkName ?target?
183 If only one argument is given, that argument is assumed to be
184 linkName, and this command returns the value of the link given
185 by linkName (i.e. the name of the file it points to). If
186 linkName is not a link or its value cannot be read (as, for ex‐
187 ample, seems to be the case with hard links, which look just
188 like ordinary files), then an error is returned.
189 If 2 arguments are given, then these are assumed to be linkName
191 and target. If linkName already exists, or if target does not
192 exist, an error will be returned. Otherwise, Tcl creates a new
193 link called linkName which points to the existing filesystem ob‐
194 ject at target (which is also the returned value), where the
195 type of the link is platform-specific (on Unix a symbolic link
196 will be the default). This is useful for the case where the
197 user wishes to create a link in a cross-platform way, and does
198 not care what type of link is created.
199 If the user wishes to make a link of a specific type only, (and
201 signal an error if for some reason that is not possible), then
202 the optional -linktype argument should be given. Accepted val‐
203 ues for -linktype are “-symbolic” and “-hard”.
204 On Unix, symbolic links can be made to relative paths, and those
206 paths must be relative to the actual linkName's location (not to
207 the cwd), but on all other platforms where relative links are
208 not supported, target paths will always be converted to abso‐
209 lute, normalized form before the link is created (and therefore
210 relative paths are interpreted as relative to the cwd). Fur‐
211 thermore, “~user” paths are always expanded to absolute form.
212 When creating links on filesystems that either do not support
213 any links, or do not support the specific type requested, an er‐
214 ror message will be returned. Most Unix platforms support both
215 symbolic and hard links (the latter for files only). Windows
216 supports symbolic directory links and hard file links on NTFS
217 drives.
218 file lstat name varName
220 Same as stat option (see below) except uses the lstat kernel
221 call instead of stat. This means that if name refers to a sym‐
222 bolic link the information returned in varName is for the link
223 rather than the file it refers to. On systems that do not sup‐
224 port symbolic links this option behaves exactly the same as the
225 stat option.
226 file mkdir ?dir ...?
228 Creates each directory specified. For each pathname dir speci‐
229 fied, this command will create all non-existing parent directo‐
230 ries as well as dir itself. If an existing directory is speci‐
231 fied, then no action is taken and no error is returned. Trying
232 to overwrite an existing file with a directory will result in an
233 error. Arguments are processed in the order specified, halting
234 at the first error, if any.
235 file mtime name ?time?
237 Returns a decimal string giving the time at which file name was
238 last modified. If time is specified, it is a modification time
239 to set for the file (equivalent to Unix touch). The time is
240 measured in the standard POSIX fashion as seconds from a fixed
241 starting time (often January 1, 1970). If the file does not ex‐
242 ist or its modified time cannot be queried or set then an error
243 is generated.
244 file nativename name
246 Returns the platform-specific name of the file. This is useful
247 if the filename is needed to pass to a platform-specific call,
248 such as to a subprocess via exec under Windows (see EXAMPLES be‐
249 low).
250 file normalize name
252 Returns a unique normalized path representation for the file-
253 system object (file, directory, link, etc), whose string value
254 can be used as a unique identifier for it. A normalized path is
255 an absolute path which has all “../” and “./” removed. Also it
256 is one which is in the “standard” format for the native plat‐
257 form. On Unix, this means the segments leading up to the path
258 must be free of symbolic links/aliases (but the very last path
259 component may be a symbolic link), and on Windows it also means
260 we want the long form with that form's case-dependence (which
261 gives us a unique, case-dependent path). The one exception con‐
262 cerning the last link in the path is necessary, because Tcl or
263 the user may wish to operate on the actual symbolic link itself
264 (for example file delete, file rename, file copy are defined to
265 operate on symbolic links, not on the things that they point
266 to).
267 file owned name
269 Returns 1 if file name is owned by the current user, 0 other‐
270 wise.
271 file pathtype name
273 Returns one of absolute, relative, volumerelative. If name
274 refers to a specific file on a specific volume, the path type
275 will be absolute. If name refers to a file relative to the cur‐
276 rent working directory, then the path type will be relative. If
277 name refers to a file relative to the current working directory
278 on a specified volume, or to a specific file on the current
279 working volume, then the path type is volumerelative.
280 file readable name
282 Returns 1 if file name is readable by the current user, 0 other‐
283 wise.
284 file readlink name
286 Returns the value of the symbolic link given by name (i.e. the
287 name of the file it points to). If name is not a symbolic link
288 or its value cannot be read, then an error is returned. On sys‐
289 tems that do not support symbolic links this option is unde‐
290 fined.
291 file rename ?-force? ?--? source target
293 file rename ?-force? ?--? source ?source ...? targetDir
295 The first form takes the file or directory specified by pathname
296 source and renames it to target, moving the file if the pathname
297 target specifies a name in a different directory. If target is
298 an existing directory, then the second form is used. The second
299 form moves each source file or directory into the directory tar‐
300 getDir. Existing files will not be overwritten unless the -force
301 option is specified. When operating inside a single filesystem,
302 Tcl will rename symbolic links rather than the things that they
303 point to. Trying to overwrite a non-empty directory, overwrite
304 a directory with a file, or a file with a directory will all re‐
305 sult in errors. Arguments are processed in the order specified,
306 halting at the first error, if any. A -- marks the end of
307 switches; the argument following the -- will be treated as a
308 source even if it starts with a -.
309 file rootname name
311 Returns all of the characters in name up to but not including
312 the last “.” character in the last component of name. If the
313 last component of name does not contain a dot, then returns
314 name.
315 file separator ?name?
317 If no argument is given, returns the character which is used to
318 separate path segments for native files on this platform. If a
319 path is given, the filesystem responsible for that path is asked
320 to return its separator character. If no file system accepts
321 name, an error is generated.
322 file size name
324 Returns a decimal string giving the size of file name in bytes.
325 If the file does not exist or its size cannot be queried then an
326 error is generated.
327 file split name
329 Returns a list whose elements are the path components in name.
330 The first element of the list will have the same path type as
331 name. All other elements will be relative. Path separators
332 will be discarded unless they are needed to ensure that an ele‐
333 ment is unambiguously relative. For example, under Unix
334 file split /foo/~bar/baz
336 returns “/ foo ./~bar baz” to ensure that later commands that
338 use the third component do not attempt to perform tilde substi‐
339 tution.
340 file stat name varName
342 Invokes the stat kernel call on name, and uses the variable
343 given by varName to hold information returned from the kernel
344 call. VarName is treated as an array variable, and the follow‐
345 ing elements of that variable are set: atime, ctime, dev, gid,
346 ino, mode, mtime, nlink, size, type, uid. Each element except
347 type is a decimal string with the value of the corresponding
348 field from the stat return structure; see the manual entry for
349 stat for details on the meanings of the values. The type ele‐
350 ment gives the type of the file in the same form returned by the
351 command file type. This command returns an empty string.
352 file system name
354 Returns a list of one or two elements, the first of which is the
355 name of the filesystem to use for the file, and the second, if
356 given, an arbitrary string representing the filesystem-specific
357 nature or type of the location within that filesystem. If a
358 filesystem only supports one type of file, the second element
359 may not be supplied. For example the native files have a first
360 element “native”, and a second element which when given is a
361 platform-specific type name for the file's system (e.g. “NTFS”,
362 “FAT”, on Windows). A generic virtual file system might return
363 the list “vfs ftp” to represent a file on a remote ftp site
364 mounted as a virtual filesystem through an extension called
365 “vfs”. If the file does not belong to any filesystem, an error
366 is generated.
367 file tail name
369 Returns all of the characters in the last filesystem component
370 of name. Any trailing directory separator in name is ignored.
371 If name contains no separators then returns name. So, file tail
372 a/b, file tail a/b/ and file tail b all return b.
373 file tempfile ?nameVar? ?template?
375 Creates a temporary file and returns a read-write channel opened │
376 on that file. If the nameVar is given, it specifies a variable │
377 that the name of the temporary file will be written into; if ab‐ │
378 sent, Tcl will attempt to arrange for the temporary file to be │
379 deleted once it is no longer required. If the template is │
380 present, it specifies parts of the template of the filename to │
381 use when creating it (such as the directory, base-name or exten‐ │
382 sion) though some platforms may ignore some or all of these │
383 parts and use a built-in default instead. │
384 Note that temporary files are only ever created on the native │
386 filesystem. As such, they can be relied upon to be used with op‐ │
387 erating-system native APIs and external programs that require a │
388 filename. │
389 file type name
391 Returns a string giving the type of file name, which will be one
392 of file, directory, characterSpecial, blockSpecial, fifo, link,
393 or socket.
394 file volumes
396 Returns the absolute paths to the volumes mounted on the system,
397 as a proper Tcl list. Without any virtual filesystems mounted
398 as root volumes, on UNIX, the command will always return “/”,
399 since all filesystems are locally mounted. On Windows, it will
400 return a list of the available local drives (e.g. “a:/ c:/”).
401 If any virtual filesystem has mounted additional volumes, they
402 will be in the returned list.
403 file writable name
405 Returns 1 if file name is writable by the current user, 0 other‐
406 wise.
407
409 Unix
410 These commands always operate using the real user and group
411 identifiers, not the effective ones.
412 Windows
414 The file owned subcommand uses the user identifier (SID) of the
415 process token, not the thread token which may be impersonating
416 some other user.
417
419 This procedure shows how to search for C files in a given directory
420 that have a correspondingly-named object file in the current directory:
421 proc findMatchingCFiles {dir} {
423 set files {}
424 switch $::tcl_platform(platform) {
425 windows {
426 set ext .obj
427 }
428 unix {
429 set ext .o
430 }
431 }
432 foreach file [glob -nocomplain -directory $dir *.c] {
433 set objectFile [file tail [file rootname $file]]$ext
434 if {[file exists $objectFile]} {
435 lappend files $file
436 }
437 }
438 return $files
439 }
440 Rename a file and leave a symbolic link pointing from the old location
442 to the new place:
443 set oldName foobar.txt
445 set newName foo/bar.txt
446 # Make sure that where we're going to move to exists...
447 if {![file isdirectory [file dirname $newName]]} {
448 file mkdir [file dirname $newName]
449 }
450 file rename $oldName $newName
451 file link -symbolic $oldName $newName
452 On Windows, a file can be “started” easily enough (equivalent to dou‐
454 ble-clicking on it in the Explorer interface) but the name passed to
455 the operating system must be in native format:
456 exec {*}[auto_execok start] {} [file nativename ~/example.txt]
458
460 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
461 fblocked(n), flush(n)
462
464 attributes, copy files, delete files, directory, file, move files,
465 name, rename files, stat, user
466Tcl 8.3 file(n)