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 ?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:/
128 returns c:/.
129 Note that tilde substitution will only be performed if it is
131 necessary to complete the command. For example,
132 file dirname ~/src/foo.c
133 returns ~/src, whereas
134 file dirname ~
135 returns /home (or something similar).
136 file executable name
138 Returns 1 if file name is executable by the current user, 0 oth‐
139 erwise.
140 file exists name
142 Returns 1 if file name exists and the current user has search
143 privileges for the directories leading to it, 0 otherwise.
144 file extension name
146 Returns all of the characters in name after and including the
147 last dot in the last element of name. If there is no dot in the
148 last element of name then returns the empty string.
149 file isdirectory name
151 Returns 1 if file name is a directory, 0 otherwise.
152 file isfile name
154 Returns 1 if file name is a regular file, 0 otherwise.
155 file join name ?name ...?
157 Takes one or more file names and combines them, using the cor‐
158 rect path separator for the current platform. If a particular
159 name is relative, then it will be joined to the previous file
160 name argument. Otherwise, any earlier arguments will be dis‐
161 carded, and joining will proceed from the current argument. For
162 example,
163 file join a b /foo bar
164 returns /foo/bar.
165 Note that any of the names can contain separators, and that the
167 result is always canonical for the current platform: / for Unix
168 and Windows.
169 file link ?-linktype? linkName ?target?
171 If only one argument is given, that argument is assumed to be
172 linkName, and this command returns the value of the link given
173 by linkName (i.e. the name of the file it points to). If
174 linkName is not a link or its value cannot be read (as, for
175 example, seems to be the case with hard links, which look just
176 like ordinary files), then an error is returned.
177 If 2 arguments are given, then these are assumed to be linkName
179 and target. If linkName already exists, or if target does not
180 exist, an error will be returned. Otherwise, Tcl creates a new
181 link called linkName which points to the existing filesystem
182 object at target (which is also the returned value), where the
183 type of the link is platform-specific (on Unix a symbolic link
184 will be the default). This is useful for the case where the
185 user wishes to create a link in a cross-platform way, and does
186 not care what type of link is created.
187 If the user wishes to make a link of a specific type only, (and
189 signal an error if for some reason that is not possible), then
190 the optional -linktype argument should be given. Accepted val‐
191 ues for -linktype are “-symbolic” and “-hard”.
192 On Unix, symbolic links can be made to relative paths, and those
194 paths must be relative to the actual linkName's location (not to
195 the cwd), but on all other platforms where relative links are
196 not supported, target paths will always be converted to abso‐
197 lute, normalized form before the link is created (and therefore
198 relative paths are interpreted as relative to the cwd). Fur‐
199 thermore, “~user” paths are always expanded to absolute form.
200 When creating links on filesystems that either do not support
201 any links, or do not support the specific type requested, an
202 error message will be returned. In particular Windows 95, 98
203 and ME do not support any links at present, but most Unix plat‐
204 forms support both symbolic and hard links (the latter for files
205 only) and Windows NT/2000/XP (on NTFS drives) support symbolic
206 directory links and hard file links.
207 file lstat name varName
209 Same as stat option (see below) except uses the lstat kernel
210 call instead of stat. This means that if name refers to a sym‐
211 bolic link the information returned in varName is for the link
212 rather than the file it refers to. On systems that do not sup‐
213 port symbolic links this option behaves exactly the same as the
214 stat option.
215 file mkdir dir ?dir ...?
217 Creates each directory specified. For each pathname dir speci‐
218 fied, this command will create all non-existing parent directo‐
219 ries as well as dir itself. If an existing directory is speci‐
220 fied, then no action is taken and no error is returned. Trying
221 to overwrite an existing file with a directory will result in an
222 error. Arguments are processed in the order specified, halting
223 at the first error, if any.
224 file mtime name ?time?
226 Returns a decimal string giving the time at which file name was
227 last modified. If time is specified, it is a modification time
228 to set for the file (equivalent to Unix touch). The time is
229 measured in the standard POSIX fashion as seconds from a fixed
230 starting time (often January 1, 1970). If the file does not
231 exist or its modified time cannot be queried or set then an
232 error is generated.
233 file nativename name
235 Returns the platform-specific name of the file. This is useful
236 if the filename is needed to pass to a platform-specific call,
237 such as to a subprocess via exec under Windows (see EXAMPLES
238 below).
239 file normalize name
241 Returns a unique normalized path representation for the file-
242 system object (file, directory, link, etc), whose string value
243 can be used as a unique identifier for it. A normalized path is
244 an absolute path which has all “../” and “./” removed. Also it
245 is one which is in the “standard” format for the native plat‐
246 form. On Unix, this means the segments leading up to the path
247 must be free of symbolic links/aliases (but the very last path
248 component may be a symbolic link), and on Windows it also means
249 we want the long form with that form's case-dependence (which
250 gives us a unique, case-dependent path). The one exception con‐
251 cerning the last link in the path is necessary, because Tcl or
252 the user may wish to operate on the actual symbolic link itself
253 (for example file delete, file rename, file copy are defined to
254 operate on symbolic links, not on the things that they point
255 to).
256 file owned name
258 Returns 1 if file name is owned by the current user, 0 other‐
259 wise.
260 file pathtype name
262 Returns one of absolute, relative, volumerelative. If name
263 refers to a specific file on a specific volume, the path type
264 will be absolute. If name refers to a file relative to the cur‐
265 rent working directory, then the path type will be relative. If
266 name refers to a file relative to the current working directory
267 on a specified volume, or to a specific file on the current
268 working volume, then the path type is volumerelative.
269 file readable name
271 Returns 1 if file name is readable by the current user, 0 other‐
272 wise.
273 file readlink name
275 Returns the value of the symbolic link given by name (i.e. the
276 name of the file it points to). If name is not a symbolic link
277 or its value cannot be read, then an error is returned. On sys‐
278 tems that do not support symbolic links this option is unde‐
279 fined.
280 file rename ?-force? ?--? source target
282 file rename ?-force? ?--? source ?source ...? targetDir
284 The first form takes the file or directory specified by pathname
285 source and renames it to target, moving the file if the pathname
286 target specifies a name in a different directory. If target is
287 an existing directory, then the second form is used. The second
288 form moves each source file or directory into the directory tar‐
289 getDir. Existing files will not be overwritten unless the -force
290 option is specified. When operating inside a single filesystem,
291 Tcl will rename symbolic links rather than the things that they
292 point to. Trying to overwrite a non-empty directory, overwrite
293 a directory with a file, or a file with a directory will all
294 result in errors. Arguments are processed in the order speci‐
295 fied, halting at the first error, if any. A -- marks the end of
296 switches; the argument following the -- will be treated as a
297 source even if it starts with a -.
298 file rootname name
300 Returns all of the characters in name up to but not including
301 the last “.” character in the last component of name. If the
302 last component of name does not contain a dot, then returns
303 name.
304 file separator ?name?
306 If no argument is given, returns the character which is used to
307 separate path segments for native files on this platform. If a
308 path is given, the filesystem responsible for that path is asked
309 to return its separator character. If no file system accepts
310 name, an error is generated.
311 file size name
313 Returns a decimal string giving the size of file name in bytes.
314 If the file does not exist or its size cannot be queried then an
315 error is generated.
316 file split name
318 Returns a list whose elements are the path components in name.
319 The first element of the list will have the same path type as
320 name. All other elements will be relative. Path separators
321 will be discarded unless they are needed to ensure that an ele‐
322 ment is unambiguously relative. For example, under Unix
323 file split /foo/~bar/baz
324 returns / foo ./~bar baz to ensure that later commands that
325 use the third component do not attempt to perform tilde substi‐
326 tution.
327 file stat name varName
329 Invokes the stat kernel call on name, and uses the variable
330 given by varName to hold information returned from the kernel
331 call. VarName is treated as an array variable, and the follow‐
332 ing elements of that variable are set: atime, ctime, dev, gid,
333 ino, mode, mtime, nlink, size, type, uid. Each element except
334 type is a decimal string with the value of the corresponding
335 field from the stat return structure; see the manual entry for
336 stat for details on the meanings of the values. The type ele‐
337 ment gives the type of the file in the same form returned by the
338 command file type. This command returns an empty string.
339 file system name
341 Returns a list of one or two elements, the first of which is the
342 name of the filesystem to use for the file, and the second, if
343 given, an arbitrary string representing the filesystem-specific
344 nature or type of the location within that filesystem. If a
345 filesystem only supports one type of file, the second element
346 may not be supplied. For example the native files have a first
347 element “native”, and a second element which when given is a
348 platform-specific type name for the file's system (e.g. “NTFS”,
349 “FAT”, on Windows). A generic virtual file system might return
350 the list “vfs ftp” to represent a file on a remote ftp site
351 mounted as a virtual filesystem through an extension called
352 “vfs”. If the file does not belong to any filesystem, an error
353 is generated.
354 file tail name
356 Returns all of the characters in the last filesystem component
357 of name. Any trailing directory separator in name is ignored.
358 If name contains no separators then returns name. So, file tail
359 a/b, file tail a/b/ and file tail b all return b.
360 file type name
362 Returns a string giving the type of file name, which will be one
363 of file, directory, characterSpecial, blockSpecial, fifo, link,
364 or socket.
365 file volumes
367 Returns the absolute paths to the volumes mounted on the system,
368 as a proper Tcl list. Without any virtual filesystems mounted
369 as root volumes, on UNIX, the command will always return “/”,
370 since all filesystems are locally mounted. On Windows, it will
371 return a list of the available local drives (e.g. “a:/ c:/”).
372 If any virtual filesystem has mounted additional volumes, they
373 will be in the returned list.
374 file writable name
376 Returns 1 if file name is writable by the current user, 0 other‐
377 wise.
378
380 Unix
381 These commands always operate using the real user and group
382 identifiers, not the effective ones.
383
385 This procedure shows how to search for C files in a given directory
386 that have a correspondingly-named object file in the current directory:
387 proc findMatchingCFiles {dir} {
388 set files {}
389 switch $::tcl_platform(platform) {
390 windows {
391 set ext .obj
392 }
393 unix {
394 set ext .o
395 }
396 }
397 foreach file [glob -nocomplain -directory $dir *.c] {
398 set objectFile [file tail [file rootname $file]]$ext
399 if {[file exists $objectFile]} {
400 lappend files $file
401 }
402 }
403 return $files
404 }
405 Rename a file and leave a symbolic link pointing from the old location
407 to the new place:
408 set oldName foobar.txt
409 set newName foo/bar.txt
410 # Make sure that where we're going to move to exists...
411 if {![file isdirectory [file dirname $newName]]} {
412 file mkdir [file dirname $newName]
413 }
414 file rename $oldName $newName
415 file link -symbolic $oldName $newName
416 On Windows, a file can be “started” easily enough (equivalent to dou‐
418 ble-clicking on it in the Explorer interface) but the name passed to
419 the operating system must be in native format:
420 exec {*}[auto_execok start] {} [file nativename ~/example.txt]
421
423 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
424 fblocked(n), flush(n)
425
427 attributes, copy files, delete files, directory, file, move files,
428 name, rename files, stat
429Tcl 8.3 file(n)