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
16 This command provides several operations on a file's name or
17 attributes. Name is the name of a file; if it starts with a tilde,
18 then tilde substitution is done before executing the command (see the
19 manual entry for filename for details). Option indicates what to do
20 with the file name. Any unique abbreviation for option is acceptable.
21 The valid options are:
22 file atime name ?time?
24 Returns a decimal string giving the time at which file name was
25 last accessed. If time is specified, it is an access time to
26 set for the file. The time is measured in the standard POSIX
27 fashion as seconds from a fixed starting time (often January 1,
28 1970). If the file doesn't exist or its access time cannot be
29 queried or set then an error is generated. On Windows, FAT file
30 systems do not support access time.
31 file attributes name
33 file attributes name ?option?
35 file attributes name ?option value option value...?
37 This subcommand returns or sets platform specific values associ‐
38 ated with a file. The first form returns a list of the platform
39 specific flags and their values. The second form returns the
40 value for the specific option. The third form sets one or more
41 of the values. The values are as follows:
42 On Unix, -group gets or sets the group name for the file. A
44 group id can be given to the command, but it returns a group
45 name. -owner gets or sets the user name of the owner of the
46 file. The command returns the owner name, but the numerical id
47 can be passed when setting the owner. -permissions sets or
48 retrieves the octal code that chmod(1) uses. This command does
49 also has limited support for setting using the symbolic
50 attributes for chmod(1), of the form [ugo]?[[+-=][rwxst],[...]],
51 where multiple symbolic attributes can be separated by commas
52 (example: u+s,go-rw add sticky bit for user, remove read and
53 write permissions for group and other). A simplified ls style
54 string, of the form rwxrwxrwx (must be 9 characters), is also
55 supported (example: rwxr-xr-t is equivalent to 01755).
56 On Windows, -archive gives the value or sets or clears the ar‐
58 chive attribute of the file. -hidden gives the value or sets or
59 clears the hidden attribute of the file. -longname will expand
60 each path element to its long version. This attribute cannot be
61 set. -readonly gives the value or sets or clears the readonly
62 attribute of the file. -shortname gives a string where every
63 path element is replaced with its short (8.3) version of the
64 name. This attribute cannot be set. -system gives or sets or
65 clears the value of the system attribute of the file.
66 On Macintosh, -creator gives or sets the Finder creator type of
68 the file. -hidden gives or sets or clears the hidden attribute
69 of the file. -readonly gives or sets or clears the readonly
70 attribute of the file. Note that directories can only be locked
71 if File Sharing is turned on. -type gives or sets the Finder
72 file type for the file.
73 file channels ?pattern? │
75 If pattern isn't specified, returns a list of names of all reg‐ │
76 istered open channels in this interpreter. If pattern is speci‐ │
77 fied, only those names matching pattern are returned. Matching │
78 is determined using the same rules as for string match.
79 file copy ?-force? ?--? source target
81 file copy ?-force? ?--? source ?source ...? targetDir
83 The first form makes a copy of the file or directory source
84 under the pathname target. If target is an existing directory,
85 then the second form is used. The second form makes a copy
86 inside targetDir of each source file listed. If a directory is
87 specified as a source, then the contents of the directory will
88 be recursively copied into targetDir. Existing files will not be
89 overwritten unless the -force option is specified. When copying
90 within a single filesystem, file copy will copy soft links (i.e.
91 the links themselves are copied, not the things they point to).
92 Trying to overwrite a non-empty directory, overwrite a directory
93 with a file, or overwrite a file with a directory will all
94 result in errors even if -force was specified. Arguments are
95 processed in the order specified, halting at the first error, if
96 any. A -- marks the end of switches; the argument following the
97 -- will be treated as a source even if it starts with a -.
98 file delete ?-force? ?--? pathname ?pathname ... ?
100 Removes the file or directory specified by each pathname argu‐
101 ment. Non-empty directories will be removed only if the -force
102 option is specified. When operating on symbolic links, the
103 links themselves will be deleted, not the objects they point to.
104 Trying to delete a non-existent file is not considered an error.
105 Trying to delete a read-only file will cause the file to be
106 deleted, even if the -force flags is not specified. If the
107 -force option is specified on a directory, Tcl will attempt both
108 to change permissions and move the current directory 'pwd' out
109 of the given path if that is necessary to allow the deletion to
110 proceed. Arguments are processed in the order specified, halt‐
111 ing at the first error, if any. A -- marks the end of switches;
112 the argument following the -- will be treated as a pathname even
113 if it starts with a -.
114 file dirname name
116 Returns a name comprised of all of the path components in name
117 excluding the last element. If name is a relative file name and
118 only contains one path element, then returns ``.'' (or ``:'' on
119 the Macintosh). If name refers to a root directory, then the
120 root directory is returned. For example,
121 file dirname c:/
122 returns c:/.
123 Note that tilde substitution will only be performed if it is
125 necessary to complete the command. For example,
126 file dirname ~/src/foo.c
127 returns ~/src, whereas
128 file dirname ~
129 returns /home (or something similar).
130 file executable name
132 Returns 1 if file name is executable by the current user, 0 oth‐
133 erwise.
134 file exists name
136 Returns 1 if file name exists and the current user has search
137 privileges for the directories leading to it, 0 otherwise.
138 file extension name
140 Returns all of the characters in name after and including the
141 last dot in the last element of name. If there is no dot in the
142 last element of name then returns the empty string.
143 file isdirectory name
145 Returns 1 if file name is a directory, 0 otherwise.
146 file isfile name
148 Returns 1 if file name is a regular file, 0 otherwise.
149 file join name ?name ...?
151 Takes one or more file names and combines them, using the cor‐
152 rect path separator for the current platform. If a particular
153 name is relative, then it will be joined to the previous file
154 name argument. Otherwise, any earlier arguments will be dis‐
155 carded, and joining will proceed from the current argument. For
156 example,
157 file join a b /foo bar
158 returns /foo/bar.
159 Note that any of the names can contain separators, and that the
161 result is always canonical for the current platform: / for Unix
162 and Windows, and : for Macintosh.
163 file link ?-linktype? linkName ?target?
165 If only one argument is given, that argument is assumed to be
166 linkName, and this command returns the value of the link given
167 by linkName (i.e. the name of the file it points to). If
168 linkName isn't a link or its value cannot be read (as, for exam‐
169 ple, seems to be the case with hard links, which look just like
170 ordinary files), then an error is returned. If 2 arguments are
171 given, then these are assumed to be linkName and target. If
172 linkName already exists, or if target doesn't exist, an error
173 will be returned. Otherwise, Tcl creates a new link called
174 linkName which points to the existing filesystem object at tar‐
175 get, where the type of the link is platform-specific (on Unix a
176 symbolic link will be the default). This is useful for the case
177 where the user wishes to create a link in a cross-platform way,
178 and doesn't care what type of link is created. If the user
179 wishes to make a link of a specific type only, (and signal an
180 error if for some reason that is not possible), then the
181 optional -linktype argument should be given. Accepted values
182 for -linktype are "-symbolic" and "-hard". When creating links
183 on filesystems that either do not support any links, or do not
184 support the specific type requested, an error message will be
185 returned. In particular Windows 95, 98 and ME do not support
186 any links at present, but most Unix platforms support both sym‐
187 bolic and hard links (the latter for files only), MacOS supports
188 symbolic links and Windows NT/2000/XP (on NTFS drives) support
189 symbolic directory links and hard file links.
190 file lstat name varName
192 Same as stat option (see below) except uses the lstat kernel
193 call instead of stat. This means that if name refers to a sym‐
194 bolic link the information returned in varName is for the link
195 rather than the file it refers to. On systems that don't sup‐
196 port symbolic links this option behaves exactly the same as the
197 stat option.
198 file mkdir dir ?dir ...?
200 Creates each directory specified. For each pathname dir speci‐
201 fied, this command will create all non-existing parent directo‐
202 ries as well as dir itself. If an existing directory is speci‐
203 fied, then no action is taken and no error is returned. Trying
204 to overwrite an existing file with a directory will result in an
205 error. Arguments are processed in the order specified, halting
206 at the first error, if any.
207 file mtime name ?time?
209 Returns a decimal string giving the time at which file name was
210 last modified. If time is specified, it is a modification time
211 to set for the file (equivalent to Unix touch). The time is
212 measured in the standard POSIX fashion as seconds from a fixed
213 starting time (often January 1, 1970). If the file doesn't
214 exist or its modified time cannot be queried or set then an
215 error is generated.
216 file nativename name
218 Returns the platform-specific name of the file. This is useful
219 if the filename is needed to pass to a platform-specific call,
220 such as exec under Windows or AppleScript on the Macintosh.
221 file normalize name
223 Returns a unique normalized path representation for the file-
224 system object (file, directory, link, etc), whose string value
225 can be used as a unique identifier for it. A normalized path is
226 an absolute path which has all '../', './' removed. Also it is
227 one which is in the ``standard'' format for the native platform.
228 On MacOS, Unix, this means the segments leading up to the path
229 must be free of symbolic links/aliases (but the very last path
230 component may be a symbolic link), and on Windows it also means
231 we want the long form with that form's case-dependence (which
232 gives us a unique, case-dependent path). The one exception con‐
233 cerning the last link in the path is necessary, because Tcl or
234 the user may wish to operate on the actual symbolic link itself
235 (for example 'file delete', 'file rename', 'file copy' are
236 defined to operate on symbolic links, not on the things that
237 they point to).
238 file owned name
240 Returns 1 if file name is owned by the current user, 0 other‐
241 wise.
242 file pathtype name
244 Returns one of absolute, relative, volumerelative. If name
245 refers to a specific file on a specific volume, the path type
246 will be absolute. If name refers to a file relative to the cur‐
247 rent working directory, then the path type will be relative. If
248 name refers to a file relative to the current working directory
249 on a specified volume, or to a specific file on the current
250 working volume, then the file type is volumerelative.
251 file readable name
253 Returns 1 if file name is readable by the current user, 0 other‐
254 wise.
255 file readlink name
257 Returns the value of the symbolic link given by name (i.e. the
258 name of the file it points to). If name isn't a symbolic link
259 or its value cannot be read, then an error is returned. On sys‐
260 tems that don't support symbolic links this option is undefined.
261 file rename ?-force? ?--? source target
263 file rename ?-force? ?--? source ?source ...? targetDir
265 The first form takes the file or directory specified by pathname
266 source and renames it to target, moving the file if the pathname
267 target specifies a name in a different directory. If target is
268 an existing directory, then the second form is used. The second
269 form moves each source file or directory into the directory tar‐
270 getDir. Existing files will not be overwritten unless the -force
271 option is specified. When operating inside a single filesystem,
272 Tcl will rename symbolic links rather than the things that they
273 point to. Trying to overwrite a non-empty directory, overwrite
274 a directory with a file, or a file with a directory will all
275 result in errors. Arguments are processed in the order speci‐
276 fied, halting at the first error, if any. A -- marks the end of
277 switches; the argument following the -- will be treated as a
278 source even if it starts with a -.
279 file rootname name
281 Returns all of the characters in name up to but not including
282 the last ``.'' character in the last component of name. If the
283 last component of name doesn't contain a dot, then returns name.
284 file separator ?name?
286 If no argument is given, returns the character which is used to
287 separate path segments for native files on this platform. If a
288 path is given, the filesystem responsible for that path is asked
289 to return its separator character. If no file system accepts
290 name, an error is generated.
291 file size name
293 Returns a decimal string giving the size of file name in bytes.
294 If the file doesn't exist or its size cannot be queried then an
295 error is generated.
296 file split name
298 Returns a list whose elements are the path components in name.
299 The first element of the list will have the same path type as
300 name. All other elements will be relative. Path separators
301 will be discarded unless they are needed ensure that an element
302 is unambiguously relative. For example, under Unix
303 file split /foo/~bar/baz
304 returns / foo ./~bar baz to ensure that later commands that
305 use the third component do not attempt to perform tilde substi‐
306 tution.
307 file stat name varName
309 Invokes the stat kernel call on name, and uses the variable
310 given by varName to hold information returned from the kernel
311 call. VarName is treated as an array variable, and the follow‐
312 ing elements of that variable are set: atime, ctime, dev, gid,
313 ino, mode, mtime, nlink, size, type, uid. Each element except
314 type is a decimal string with the value of the corresponding
315 field from the stat return structure; see the manual entry for
316 stat for details on the meanings of the values. The type ele‐
317 ment gives the type of the file in the same form returned by the
318 command file type. This command returns an empty string.
319 file system name
321 Returns a list of two elements, the first of which is the name
322 of the filesystem to use for the file, and the second an arbi‐
323 trary string representing the filesystem-specific nature or type
324 of the location within that filesystem. If a filesystem only
325 supports one type of file, the second element may be null. For
326 example the native files have a first element 'native', and a
327 second element which is a platform-specific type name for the
328 file's system (e.g. 'NTFS', 'FAT', etc), or possibly the empty
329 string if no further information is available or if this is not
330 implemented. A generic virtual file system might return the
331 list 'vfs ftp' to represent a file on a remote ftp site mounted
332 as a virtual filesystem through an extension called 'vfs'. If
333 the file does not belong to any filesystem, an error is gener‐
334 ated.
335 file tail name
337 Returns all of the characters in name after the last directory
338 separator. If name contains no separators then returns name.
339 file type name
341 Returns a string giving the type of file name, which will be one
342 of file, directory, characterSpecial, blockSpecial, fifo, link,
343 or socket.
344 file volumes
346 Returns the absolute paths to the volumes mounted on the system,
347 as a proper Tcl list. On the Macintosh, this will be a list of
348 the mounted drives, both local and network. N.B. if two drives
349 have the same name, they will both appear on the volume list,
350 but there is currently no way, from Tcl, to access any but the
351 first of these drives. On UNIX, the command will always return
352 "/", since all filesystems are locally mounted. On Windows, it
353 will return a list of the available local drives (e.g. {a:/
354 c:/}).
355 file writable name
357 Returns 1 if file name is writable by the current user, 0 other‐
358 wise.
359
361 Unix
362 These commands always operate using the real user and group
363 identifiers, not the effective ones.
364
366 This procedure shows how to search for C files in a given directory
367 that have a correspondingly-named object file in the current directory:
368 proc findMatchingCFiles {dir} {
369 set files {}
370 switch $::tcl_platform(platform) {
371 windows {
372 set ext .obj
373 }
374 unix {
375 set ext .o
376 }
377 }
378 foreach file [glob -nocomplain -directory $dir *.c] {
379 set objectFile [file tail [file rootname $file]]$ext
380 if {[file exists $objectFile]} {
381 lappend files $file
382 }
383 }
384 return $files
385 }
386 Rename a file and leave a symbolic link pointing from the old location
388 to the new place:
389 set oldName foobar.txt
390 set newName foo/bar.txt
391 # Make sure that where we're going to move to exists...
392 if {![file isdirectory [file dirname $newName]]} {
393 file mkdir [file dirname $newName]
394 }
395 file rename $oldName $newName
396 file link -symbolic $oldName $newName
397
400 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
401 fblocked(n), flush(n)
402
405 attributes, copy files, delete files, directory, file, move files,
406 name, rename files, stat
407Tcl 8.3 file(n)