2
'\" Copyright (c) 1993 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8
'\" RCS: @(#) $Id: file.n,v 1.46 2007/10/25 14:07:32 dkf Exp $
11
.TH file n 8.3 Tcl "Tcl Built-In Commands"
13
'\" Note: do not modify the .SH NAME line immediately below!
15
file \- Manipulate file names and attributes
17
\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
22
This command provides several operations on a file's name or attributes.
23
\fIName\fR is the name of a file; if it starts with a tilde, then tilde
24
substitution is done before executing the command (see the manual entry for
25
\fBfilename\fR for details). \fIOption\fR indicates what to do with the
26
file name. Any unique abbreviation for \fIoption\fR is acceptable. The
29
\fBfile atime \fIname\fR ?\fBtime\fR?
31
Returns a decimal string giving the time at which file \fIname\fR was last
32
accessed. If \fItime\fR is specified, it is an access time to set
33
for the file. The time is measured in the standard POSIX fashion as
34
seconds from a fixed starting time (often January 1, 1970). If the file
35
doesn't exist or its access time cannot be queried or set then an error is
36
generated. On Windows, FAT file systems do not support access time.
38
\fBfile attributes \fIname\fR
40
\fBfile attributes \fIname\fR ?\fBoption\fR?
42
\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
44
This subcommand returns or sets platform specific values associated
45
with a file. The first form returns a list of the platform specific
46
flags and their values. The second form returns the value for the
47
specific option. The third form sets one or more of the values. The
48
values are as follows:
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).
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.
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
85
\fBfile channels ?\fIpattern\fR?
87
If \fIpattern\fR isn't 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.
92
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
94
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
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.
115
\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
117
Removes the file or directory specified by each \fIpathname\fR
118
argument. Non-empty directories will be removed only if the
119
\fB\-force\fR option is specified. When operating on symbolic links,
120
the links themselves will be deleted, not the objects they point to.
121
Trying to delete a non-existent file is not considered an error.
122
Trying to delete a read-only file will cause the file to be deleted,
123
even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR
124
option is specified on a directory, Tcl will attempt both to change
125
permissions and move the current directory
127
out of the given path
128
if that is necessary to allow the deletion to proceed. Arguments are
129
processed in the order specified, halting at the first error, if any.
130
A \fB\-\|\-\fR marks the end of switches; the argument following the
131
\fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
134
\fBfile dirname \fIname\fR
135
Returns a name comprised of all of the path components in \fIname\fR
136
excluding the last element. If \fIname\fR is a relative file name and
137
only contains one path element, then returns
139
If \fIname\fR refers to a root directory, then the root directory is
140
returned. For example,
143
\fBfile dirname c:/\fR
147
Note that tilde substitution will only be
148
performed if it is necessary to complete the command. For example,
150
\fBfile dirname ~/src/foo.c\fR
152
returns \fB~/src\fR, whereas
156
returns \fB/home\fR (or something similar).
159
\fBfile executable \fIname\fR
161
Returns \fB1\fR if file \fIname\fR is executable by the current user,
164
\fBfile exists \fIname\fR
166
Returns \fB1\fR if file \fIname\fR exists and the current user has
167
search privileges for the directories leading to it, \fB0\fR otherwise.
169
\fBfile extension \fIname\fR
171
Returns all of the characters in \fIname\fR after and including the last
172
dot in the last element of \fIname\fR. If there is no dot in the last
173
element of \fIname\fR then returns the empty string.
175
\fBfile isdirectory \fIname\fR
177
Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise.
179
\fBfile isfile \fIname\fR
181
Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise.
183
\fBfile join \fIname\fR ?\fIname ...\fR?
185
Takes one or more file names and combines them, using the correct path
186
separator for the current platform. If a particular \fIname\fR is
187
relative, then it will be joined to the previous file name argument.
188
Otherwise, any earlier arguments will be discarded, and joining will
189
proceed from the current argument. For example,
192
\fBfile join a b /foo bar\fR
194
returns \fB/foo/bar\fR.
196
Note that any of the names can contain separators, and that the result
197
is always canonical for the current platform: \fB/\fR for Unix and
201
\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
203
If only one argument is given, that argument is assumed to be
204
\fIlinkName\fR, and this command returns the value of the link given by
205
\fIlinkName\fR (i.e. the name of the file it points to). If
206
\fIlinkName\fR isn't a link or its value cannot be read (as, for example,
207
seems to be the case with hard links, which look just like ordinary
208
files), then an error is returned.
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
doesn't 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 doesn't care what type of
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
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,
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.
244
\fBfile lstat \fIname varName\fR
246
Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
247
kernel call instead of \fIstat\fR. This means that if \fIname\fR
248
refers to a symbolic link the information returned in \fIvarName\fR
249
is for the link rather than the file it refers to. On systems that
250
don't support symbolic links this option behaves exactly the same
251
as the \fBstat\fR option.
253
\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
255
Creates each directory specified. For each pathname \fIdir\fR specified,
256
this command will create all non-existing parent directories as
257
well as \fIdir\fR itself. If an existing directory is specified, then
258
no action is taken and no error is returned. Trying to overwrite an existing
259
file with a directory will result in an error. Arguments are processed in
260
the order specified, halting at the first error, if any.
262
\fBfile mtime \fIname\fR ?\fItime\fR?
264
Returns a decimal string giving the time at which file \fIname\fR was last
265
modified. If \fItime\fR is specified, it is a modification time to set for
266
the file (equivalent to Unix \fBtouch\fR). The time is measured in the
267
standard POSIX fashion as seconds from a fixed starting time (often January
268
1, 1970). If the file doesn't exist or its modified time cannot be queried
269
or set then an error is generated.
271
\fBfile nativename \fIname\fR
273
Returns the platform-specific name of the file. This is useful if the
274
filename is needed to pass to a platform-specific call, such as exec
277
\fBfile normalize \fIname\fR
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
286
removed. Also it is one which is in the
288
format for the native platform. On Unix, this means the segments
289
leading up to the path must be free of symbolic links/aliases (but the
290
very last path component may be a symbolic link), and on Windows it also
291
means we want the long form with that form's case-dependence (which
292
gives us a unique, case-dependent path). The one exception concerning the
293
last link in the path is necessary, because Tcl or the user may wish to
294
operate on the actual symbolic link itself (for example \fBfile
295
delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate
296
on symbolic links, not on the things that they point to).
299
\fBfile owned \fIname\fR
301
Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
304
\fBfile pathtype \fIname\fR
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.
314
\fBfile readable \fIname\fR
316
Returns \fB1\fR if file \fIname\fR is readable by the current user,
319
\fBfile readlink \fIname\fR
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 isn't a symbolic link or its
323
value cannot be read, then an error is returned. On systems that don't
324
support symbolic links this option is undefined.
326
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
328
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
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.
346
\fBfile rootname \fIname\fR
348
Returns all of the characters in \fIname\fR up to but not including the
351
character in the last component of name. If the last
352
component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
354
\fBfile separator\fR ?\fIname\fR?
356
If no argument is given, returns the character which is used to separate
357
path segments for native files on this platform. If a path is given,
358
the filesystem responsible for that path is asked to return its
359
separator character. If no file system accepts \fIname\fR, an error
362
\fBfile size \fIname\fR
364
Returns a decimal string giving the size of file \fIname\fR in bytes. If
365
the file doesn't exist or its size cannot be queried then an error is
368
\fBfile split \fIname\fR
370
Returns a list whose elements are the path components in \fIname\fR. The
371
first element of the list will have the same path type as \fIname\fR.
372
All other elements will be relative. Path separators will be discarded
373
unless they are needed ensure that an element is unambiguously relative.
374
For example, under Unix
377
file split /foo/~bar/baz
379
returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
380
that use the third component do not attempt to perform tilde
384
\fBfile stat \fIname varName\fR
386
Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable
387
given by \fIvarName\fR to hold information returned from the kernel call.
388
\fIVarName\fR is treated as an array variable, and the following elements
389
of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR,
390
\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR,
391
\fBuid\fR. Each element except \fBtype\fR is a decimal string with the
392
value of the corresponding field from the \fBstat\fR return structure;
393
see the manual entry for \fBstat\fR for details on the meanings of the
394
values. The \fBtype\fR element gives the type of the file in the same
395
form returned by the command \fBfile type\fR. This command returns an
398
\fBfile system \fIname\fR
400
Returns a list of one or two elements, the first of which is the name of
401
the filesystem to use for the file, and the second, if given, an
402
arbitrary string representing the filesystem-specific nature or type of
403
the location within that filesystem. If a filesystem only supports one
404
type of file, the second element may not be supplied. For example the
405
native files have a first element
407
and a second element which
408
when given is a platform-specific type name for the file's system
412
on Windows). A generic virtual file system might return the list
414
to represent a file on a remote ftp site mounted as a virtual
415
filesystem through an extension called
417
If the file does not belong to any filesystem, an error is generated.
419
\fBfile tail \fIname\fR
421
Returns all of the characters in the last filesystem component of
422
\fIname\fR. Any trailing directory separator in \fIname\fR is ignored.
423
If \fIname\fR contains no separators then returns \fIname\fR. So,
424
\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
427
\fBfile type \fIname\fR
429
Returns a string giving the type of file \fIname\fR, which will be one of
430
\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,
431
\fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
435
Returns the absolute paths to the volumes mounted on the system, as a proper
436
Tcl list. Without any virtual filesystems mounted as root volumes, on UNIX,
437
the command will always return
439
since all filesystems are locally mounted. On Windows, it will return a list
440
of the available local drives (e.g.
442
If any virtual filesystem has mounted additional volumes, they will be in the
445
\fBfile writable \fIname\fR
447
Returns \fB1\fR if file \fIname\fR is writable by the current user,
449
.SH "PORTABILITY ISSUES"
451
\fBUnix\fR\0\0\0\0\0\0\0
453
The subcommands that test whether a particular mode of access is permitted
454
always operate using the real user and group identifiers, not the effective
455
ones. As such, robust code should just \fBopen\fR a file for reading instead
456
of testing to see whether it is readable with \fBfile readable\fR. This also
457
avoids potential race conditions.
459
This procedure shows how to search for C files in a given directory
460
that have a correspondingly-named object file in the current
463
proc findMatchingCFiles {dir} {
465
switch $::tcl_platform(platform) {
473
foreach file [glob -nocomplain -directory $dir *.c] {
474
set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
475
if {[\fBfile exists\fR $objectFile]} {
483
Rename a file and leave a symbolic link pointing from the old location
486
set oldName foobar.txt
487
set newName foo/bar.txt
488
# Make sure that where we're going to move to exists...
489
if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
490
\fBfile mkdir\fR [\fBfile dirname\fR $newName]
492
\fBfile rename\fR $oldName $newName
493
\fBfile link\fR -symbolic $oldName $newName
497
chan(n), close(n), eof(n), fblocked(n), filename(n), flush(n), gets(n),
498
open(n), seek(n), tell(n)
500
attributes, copy files, delete files, directory, file, move files, name, rename files, stat
added
removed
doc/file.n
