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.23 2003/02/28 12:11:49 vincentdarley Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or "in/out" to describe whether procedure reads or modifies arg,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
21 '\" Give maximum sizes of arguments for setting tab stops. Type and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to .AP later. If args are omitted, default tab stops are used.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
30 '\" End of box enclosure.
33 '\" Begin code excerpt.
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar, for use in marking newly-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version when the .VS was added, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present, then a line break is forced before starting the sidebar.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display.
52 '\" End of indented unfilled display.
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH file n 8.3 Tcl "Tcl Built-In Commands"
248 '\" Note: do not modify the .SH NAME line immediately below!
250 file \- Manipulate file names and attributes
252 \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
257 This command provides several operations on a file's name or attributes.
258 \fIName\fR is the name of a file; if it starts with a tilde, then tilde
259 substitution is done before executing the command (see the manual entry for
260 \fBfilename\fR for details). \fIOption\fR indicates what to do with the
261 file name. Any unique abbreviation for \fIoption\fR is acceptable. The
264 \fBfile atime \fIname\fR ?\fBtime\fR?
266 Returns a decimal string giving the time at which file \fIname\fR was last
267 accessed. If \fItime\fR is specified, it is an access time to set
268 for the file. The time is measured in the standard POSIX fashion as
269 seconds from a fixed starting time (often January 1, 1970). If the file
270 doesn't exist or its access time cannot be queried or set then an error is
271 generated. On Windows, FAT file systems do not support access time.
273 \fBfile attributes \fIname\fR
275 \fBfile attributes \fIname\fR ?\fBoption\fR?
277 \fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
279 This subcommand returns or sets platform specific values associated
280 with a file. The first form returns a list of the platform specific
281 flags and their values. The second form returns the value for the
282 specific option. The third form sets one or more of the values. The
283 values are as follows:
285 On Unix, \fB-group\fR gets or sets the group name for the file. A group id
286 can be given to the command, but it returns a group name. \fB-owner\fR gets
287 or sets the user name of the owner of the file. The command returns the
288 owner name, but the numerical id can be passed when setting the
289 owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1)
290 uses. This command does also has limited support for setting using the
291 symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]],
292 where multiple symbolic attributes can be separated by commas (example:
293 \fBu+s,go\-rw\fR add sticky bit for user, remove read and write
294 permissions for group and other). A simplified \fBls\fR style string,
295 of the form rwxrwxrwx (must be 9 characters), is also supported
296 (example: \fBrwxr\-xr\-t\fR is equivalent to 01755).
298 On Windows, \fB-archive\fR gives the value or sets or clears the
299 archive attribute of the file. \fB-hidden\fR gives the value or sets
300 or clears the hidden attribute of the file. \fB-longname\fR will
301 expand each path element to its long version. This attribute cannot be
302 set. \fB-readonly\fR gives the value or sets or clears the readonly
303 attribute of the file. \fB-shortname\fR gives a string where every
304 path element is replaced with its short (8.3) version of the
305 name. This attribute cannot be set. \fB-system\fR gives or sets or
306 clears the value of the system attribute of the file.
308 On Macintosh, \fB-creator\fR gives or sets the Finder creator type of
309 the file. \fB-hidden\fR gives or sets or clears the hidden attribute
310 of the file. \fB-readonly\fR gives or sets or clears the readonly
311 attribute of the file. Note that directories can only be locked if
312 File Sharing is turned on. \fB-type\fR gives or sets the Finder file
317 \fBfile channels ?\fIpattern\fR?
319 If \fIpattern\fR isn't specified, returns a list of names of all
320 registered open channels in this interpreter. If \fIpattern\fR is
321 specified, only those names matching \fIpattern\fR are returned. Matching
322 is determined using the same rules as for \fBstring match\fR.
325 \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
327 \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
329 The first form makes a copy of the file or directory \fIsource\fR under
330 the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
331 then the second form is used. The second form makes a copy inside
332 \fItargetDir\fR of each \fIsource\fR file listed. If a directory is
333 specified as a \fIsource\fR, then the contents of the directory will be
334 recursively copied into \fItargetDir\fR. Existing files will not be
335 overwritten unless the \fB\-force\fR option is specified. When copying
336 within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
337 the links themselves are copied, not the things they point to). Trying
338 to overwrite a non-empty directory, overwrite a directory with a file,
339 or a file with a directory will all result in errors even if
340 \fI\-force\fR was specified. Arguments are processed in the order
341 specified, halting at the first error, if any. A \fB\-\|\-\fR marks
342 the end of switches; the argument following the \fB\-\|\-\fR will be
343 treated as a \fIsource\fR even if it starts with a \fB\-\fR.
346 \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
348 Removes the file or directory specified by each \fIpathname\fR
349 argument. Non-empty directories will be removed only if the
350 \fB\-force\fR option is specified. When operating on symbolic links,
351 the links themselves will be deleted, not the objects they point to.
352 Trying to delete a non-existent file is not considered an error.
353 Trying to delete a read-only file will cause the file to be deleted,
354 even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR
355 option is specified on a directory, Tcl will attempt both to change
356 permissions and move the current directory 'pwd' out of the given path
357 if that is necessary to allow the deletion to proceed. Arguments are
358 processed in the order specified, halting at the first error, if any.
359 A \fB\-\|\-\fR marks the end of switches; the argument following the
360 \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
363 \fBfile dirname \fIname\fR
364 Returns a name comprised of all of the path components in \fIname\fR
365 excluding the last element. If \fIname\fR is a relative file name and
366 only contains one path element, then returns ``\fB.\fR'' (or ``\fB:\fR''
367 on the Macintosh). If \fIname\fR refers to a root directory, then the
368 root directory is returned. For example,
371 \fBfile dirname c:/\fR
375 Note that tilde substitution will only be
376 performed if it is necessary to complete the command. For example,
378 \fBfile dirname ~/src/foo.c\fR
380 returns \fB~/src\fR, whereas
384 returns \fB/home\fR (or something similar).
387 \fBfile executable \fIname\fR
389 Returns \fB1\fR if file \fIname\fR is executable by the current user,
392 \fBfile exists \fIname\fR
394 Returns \fB1\fR if file \fIname\fR exists and the current user has
395 search privileges for the directories leading to it, \fB0\fR otherwise.
397 \fBfile extension \fIname\fR
399 Returns all of the characters in \fIname\fR after and including the last
400 dot in the last element of \fIname\fR. If there is no dot in the last
401 element of \fIname\fR then returns the empty string.
403 \fBfile isdirectory \fIname\fR
405 Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise.
407 \fBfile isfile \fIname\fR
409 Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise.
411 \fBfile join \fIname\fR ?\fIname ...\fR?
413 Takes one or more file names and combines them, using the correct path
414 separator for the current platform. If a particular \fIname\fR is
415 relative, then it will be joined to the previous file name argument.
416 Otherwise, any earlier arguments will be discarded, and joining will
417 proceed from the current argument. For example,
420 \fBfile join a b /foo bar\fR
422 returns \fB/foo/bar\fR.
424 Note that any of the names can contain separators, and that the result
425 is always canonical for the current platform: \fB/\fR for Unix and
426 Windows, and \fB:\fR for Macintosh.
429 \fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
431 If only one argument is given, that argument is assumed to be
432 \fIlinkName\fR, and this command returns the value of the link given by
433 \fIlinkName\fR (i.e. the name of the file it points to). If
434 \fIlinkName\fR isn't a link or its value cannot be read (as, for example,
435 seems to be the case with hard links, which look just like ordinary
436 files), then an error is returned.
438 If 2 arguments are given, then these are assumed to be \fIlinkName\fR and
439 \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
440 doesn't exist, an error will be returned. Otherwise, Tcl creates a new
441 link called \fIlinkName\fR which points to the existing filesystem object
442 at \fItarget\fR, where the type of the link is platform-specific (on Unix
443 a symbolic link will be the default). This is useful for the case where
444 the user wishes to create a link in a cross-platform way, and doesn't
445 care what type of link is created.
447 If the user wishes to make a link of a specific type only, (and signal an
448 error if for some reason that is not possible), then the optional
449 \fI-linktype\fR argument should be given. Accepted values for
450 \fI-linktype\fR are "-symbolic" and "-hard".
452 When creating links on filesystems that either do not support any links,
453 or do not support the specific type requested, an error message will be
454 returned. In particular Windows 95, 98 and ME do not support any links
455 at present, but most Unix platforms support both symbolic and hard links
456 (the latter for files only), MacOS supports symbolic links and Windows
457 NT/2000/XP (on NTFS drives) support symbolic directory links and hard
460 \fBfile lstat \fIname varName\fR
462 Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
463 kernel call instead of \fIstat\fR. This means that if \fIname\fR
464 refers to a symbolic link the information returned in \fIvarName\fR
465 is for the link rather than the file it refers to. On systems that
466 don't support symbolic links this option behaves exactly the same
467 as the \fBstat\fR option.
469 \fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
471 Creates each directory specified. For each pathname \fIdir\fR specified,
472 this command will create all non-existing parent directories as
473 well as \fIdir\fR itself. If an existing directory is specified, then
474 no action is taken and no error is returned. Trying to overwrite an existing
475 file with a directory will result in an error. Arguments are processed in
476 the order specified, halting at the first error, if any.
478 \fBfile mtime \fIname\fR ?\fItime\fR?
480 Returns a decimal string giving the time at which file \fIname\fR was last
481 modified. If \fItime\fR is specified, it is a modification time to set for
482 the file (equivalent to Unix \fBtouch\fR). The time is measured in the
483 standard POSIX fashion as seconds from a fixed starting time (often January
484 1, 1970). If the file doesn't exist or its modified time cannot be queried
485 or set then an error is generated.
487 \fBfile nativename \fIname\fR
489 Returns the platform-specific name of the file. This is useful if the
490 filename is needed to pass to a platform-specific call, such as exec
491 under Windows or AppleScript on the Macintosh.
493 \fBfile normalize \fIname\fR
496 Returns a unique normalised path representation for the file-system
497 object (file, directory, link, etc), whose string value can be used as a
498 unique identifier for it. A normalized path is an absolute path which has
499 all '../', './' removed. Also it is one which is in the ``standard''
500 format for the native platform. On MacOS, Unix, this means the segments
501 leading up to the path must be free of symbolic links/aliases (but the
502 very last path component may be a symbolic link), and on Windows it also
503 means means we want the long form with that form's case-dependence (which
504 gives us a unique, case-dependent path). The one exception concerning the
505 last link in the path is necessary, because Tcl or the user may wish to
506 operate on the actual symbolic link itself (for example 'file delete', 'file
507 rename', 'file copy' are defined to operate on symbolic links, not on the
508 things that they point to).
511 \fBfile owned \fIname\fR
513 Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
516 \fBfile pathtype \fIname\fR
518 Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
519 \fIname\fR refers to a specific file on a specific volume, the path type
520 will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the
521 current working directory, then the path type will be \fBrelative\fR. If
522 \fIname\fR refers to a file relative to the current working directory on
523 a specified volume, or to a specific file on the current working volume, then
524 the file type is \fBvolumerelative\fR.
526 \fBfile readable \fIname\fR
528 Returns \fB1\fR if file \fIname\fR is readable by the current user,
531 \fBfile readlink \fIname\fR
533 Returns the value of the symbolic link given by \fIname\fR (i.e. the name
534 of the file it points to). If \fIname\fR isn't a symbolic link or its
535 value cannot be read, then an error is returned. On systems that don't
536 support symbolic links this option is undefined.
538 \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
540 \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
542 The first form takes the file or directory specified by pathname
543 \fIsource\fR and renames it to \fItarget\fR, moving the file if the
544 pathname \fItarget\fR specifies a name in a different directory. If
545 \fItarget\fR is an existing directory, then the second form is used.
546 The second form moves each \fIsource\fR file or directory into the
547 directory \fItargetDir\fR. Existing files will not be overwritten
548 unless the \fB\-force\fR option is specified. When operating inside a
549 single filesystem, Tcl will rename symbolic links rather than the
550 things that they point to. Trying to overwrite a non-empty directory,
551 overwrite a directory with a file, or a file with a directory will all
552 result in errors. Arguments are processed in the order specified,
553 halting at the first error, if any. A \fB\-\|\-\fR marks the end of
554 switches; the argument following the \fB\-\|\-\fR will be treated as a
555 \fIsource\fR even if it starts with a \fB\-\fR.
558 \fBfile rootname \fIname\fR
560 Returns all of the characters in \fIname\fR up to but not including the
561 last ``.'' character in the last component of name. If the last
562 component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
564 \fBfile separator\fR ?\fIname\fR?
566 If no argument is given, returns the character which is used to separate
567 path segments for native files on this platform. If a path is given,
568 the filesystem responsible for that path is asked to return its
569 separator character. If no file system accepts \fIname\fR, an error
572 \fBfile size \fIname\fR
574 Returns a decimal string giving the size of file \fIname\fR in bytes. If
575 the file doesn't exist or its size cannot be queried then an error is
578 \fBfile split \fIname\fR
580 Returns a list whose elements are the path components in \fIname\fR. The
581 first element of the list will have the same path type as \fIname\fR.
582 All other elements will be relative. Path separators will be discarded
583 unless they are needed ensure that an element is unambiguously relative.
584 For example, under Unix
587 file split /foo/~bar/baz
589 returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
590 that use the third component do not attempt to perform tilde
594 \fBfile stat \fIname varName\fR
596 Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable
597 given by \fIvarName\fR to hold information returned from the kernel call.
598 \fIVarName\fR is treated as an array variable, and the following elements
599 of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR,
600 \fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR,
601 \fBuid\fR. Each element except \fBtype\fR is a decimal string with the
602 value of the corresponding field from the \fBstat\fR return structure;
603 see the manual entry for \fBstat\fR for details on the meanings of the
604 values. The \fBtype\fR element gives the type of the file in the same
605 form returned by the command \fBfile type\fR. This command returns an
608 \fBfile system \fIname\fR
610 Returns a list of two elements, the first of which is the name of the
611 filesystem to use for the file, and the second an arbitrary string
612 representing the filesystem-specific nature or type of the location
613 within that filesystem. If a filesystem only supports one type of file,
614 the second element may be null. For example the native files have a
615 first element 'native', and a second element which is a platform-specific
616 type name for the file's system (e.g. 'NTFS', 'FAT', etc), or possibly
617 the empty string if no further information is available or if this
618 is not implemented. A generic virtual file system might return the
619 list 'vfs ftp' to represent a file on a remote ftp site mounted as a
620 virtual filesystem through an extension called 'vfs'. If the file does
621 not belong to any filesystem, an error is generated.
623 \fBfile tail \fIname\fR
625 Returns all of the characters in \fIname\fR after the last directory
626 separator. If \fIname\fR contains no separators then returns
629 \fBfile type \fIname\fR
631 Returns a string giving the type of file \fIname\fR, which will be one of
632 \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,
633 \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
637 Returns the absolute paths to the volumes mounted on the system, as a
638 proper Tcl list. On the Macintosh, this will be a list of the mounted
639 drives, both local and network. N.B. if two drives have the same name,
640 they will both appear on the volume list, but there is currently no way,
641 from Tcl, to access any but the first of these drives. On UNIX, the
642 command will always return "/", since all filesystems are locally mounted.
643 On Windows, it will return a list of the available local drives
646 \fBfile writable \fIname\fR
648 Returns \fB1\fR if file \fIname\fR is writable by the current user,
650 .SH "PORTABILITY ISSUES"
652 \fBUnix\fR\0\0\0\0\0\0\0
654 These commands always operate using the real user and group identifiers,
655 not the effective ones.
658 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
659 fblocked(n), flush(n)
662 attributes, copy files, delete files, directory, file, move files, name, rename files, stat
OSDN Git Service
