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