| '\" |
| '\" Copyright (c) 1993 The Regents of the University of California. |
| '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
| '\" |
| '\" See the file "license.terms" for information on usage and redistribution |
| '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| '\" |
| '\" RCS: @(#) $Id: file.n,v 1.22 2002/09/06 17:42:58 dgp Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .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 |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH file n 8.3 Tcl "Tcl Built-In Commands" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| file \- Manipulate file names and attributes |
| .SH SYNOPSIS |
| \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? |
| .BE |
| |
| .SH DESCRIPTION |
| .PP |
| This command provides several operations on a file's name or attributes. |
| \fIName\fR is the name of a file; if it starts with a tilde, then tilde |
| substitution is done before executing the command (see the manual entry for |
| \fBfilename\fR for details). \fIOption\fR indicates what to do with the |
| file name. Any unique abbreviation for \fIoption\fR is acceptable. The |
| valid options are: |
| .TP |
| \fBfile atime \fIname\fR ?\fBtime\fR? |
| . |
| Returns a decimal string giving the time at which file \fIname\fR was last |
| accessed. If \fItime\fR is specified, it is an access time to set |
| for the file. The time is measured in the standard POSIX fashion as |
| seconds from a fixed starting time (often January 1, 1970). If the file |
| doesn't exist or its access time cannot be queried or set then an error is |
| generated. On Windows, FAT file systems do not support access time. |
| .TP |
| \fBfile attributes \fIname\fR |
| .TP |
| \fBfile attributes \fIname\fR ?\fBoption\fR? |
| .TP |
| \fBfile attributes \fIname\fR ?\fBoption value option value...\fR? |
| .RS |
| This subcommand returns or sets platform specific values associated |
| with a file. The first form returns a list of the platform specific |
| flags and their values. The second form returns the value for the |
| specific option. The third form sets one or more of the values. The |
| values are as follows: |
| .PP |
| On Unix, \fB-group\fR gets or sets the group name for the file. A group id |
| can be given to the command, but it returns a group name. \fB-owner\fR gets |
| or sets the user name of the owner of the file. The command returns the |
| owner name, but the numerical id can be passed when setting the |
| owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1) |
| uses. This command does also has limited support for setting using the |
| symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]], |
| where multiple symbolic attributes can be separated by commas (example: |
| \fBu+s,go\-rw\fR add sticky bit for user, remove read and write |
| permissions for group and other). A simplified \fBls\fR style string, |
| of the form rwxrwxrwx (must be 9 characters), is also supported |
| (example: \fBrwxr\-xr\-t\fR is equivalent to 01755). |
| .PP |
| On Windows, \fB-archive\fR gives the value or sets or clears the |
| archive attribute of the file. \fB-hidden\fR gives the value or sets |
| or clears the hidden attribute of the file. \fB-longname\fR will |
| expand each path element to its long version. This attribute cannot be |
| set. \fB-readonly\fR gives the value or sets or clears the readonly |
| attribute of the file. \fB-shortname\fR gives a string where every |
| path element is replaced with its short (8.3) version of the |
| name. This attribute cannot be set. \fB-system\fR gives or sets or |
| clears the value of the system attribute of the file. |
| .PP |
| On Macintosh, \fB-creator\fR gives or sets the Finder creator type of |
| the file. \fB-hidden\fR gives or sets or clears the hidden attribute |
| of the file. \fB-readonly\fR gives or sets or clears the readonly |
| attribute of the file. Note that directories can only be locked if |
| File Sharing is turned on. \fB-type\fR gives or sets the Finder file |
| type for the file. |
| .RE |
| .VS |
| .TP |
| \fBfile channels ?\fIpattern\fR? |
| . |
| If \fIpattern\fR isn't specified, returns a list of names of all |
| registered open channels in this interpreter. If \fIpattern\fR is |
| specified, only those names matching \fIpattern\fR are returned. Matching |
| is determined using the same rules as for \fBstring match\fR. |
| .VE |
| .TP |
| \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR |
| .TP |
| \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR |
| .RS |
| The first form makes a copy of the file or directory \fIsource\fR under |
| the pathname \fItarget\fR. If \fItarget\fR is an existing directory, |
| then the second form is used. The second form makes a copy inside |
| \fItargetDir\fR of each \fIsource\fR file listed. If a directory is |
| specified as a \fIsource\fR, then the contents of the directory will be |
| recursively copied into \fItargetDir\fR. Existing files will not be |
| overwritten unless the \fB\-force\fR option is specified. When copying |
| within a single filesystem, \fIfile copy\fR will copy soft links (i.e. |
| the links themselves are copied, not the things they point to). Trying |
| to overwrite a non-empty directory, overwrite a directory with a file, |
| or a file with a directory will all result in errors even if |
| \fI\-force\fR was specified. Arguments are processed in the order |
| specified, halting at the first error, if any. A \fB\-\|\-\fR marks |
| the end of switches; the argument following the \fB\-\|\-\fR will be |
| treated as a \fIsource\fR even if it starts with a \fB\-\fR. |
| .RE |
| .TP |
| \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ? |
| . |
| Removes the file or directory specified by each \fIpathname\fR |
| argument. Non-empty directories will be removed only if the |
| \fB\-force\fR option is specified. When operating on symbolic links, |
| the links themselves will be deleted, not the objects they point to. |
| Trying to delete a non-existent file is not considered an error. |
| Trying to delete a read-only file will cause the file to be deleted, |
| even if the \fB\-force\fR flags is not specified. If the \fB\-force\fR |
| option is specified on a directory, Tcl will attempt both to change |
| permissions and move the current directory 'pwd' out of the given path |
| if that is necessary to allow the deletion to proceed. Arguments are |
| processed in the order specified, halting at the first error, if any. |
| A \fB\-\|\-\fR marks the end of switches; the argument following the |
| \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with |
| a \fB\-\fR. |
| .TP |
| \fBfile dirname \fIname\fR |
| Returns a name comprised of all of the path components in \fIname\fR |
| excluding the last element. If \fIname\fR is a relative file name and |
| only contains one path element, then returns ``\fB.\fR'' (or ``\fB:\fR'' |
| on the Macintosh). If \fIname\fR refers to a root directory, then the |
| root directory is returned. For example, |
| .RS |
| .CS |
| \fBfile dirname c:/\fR |
| .CE |
| returns \fBc:/\fR. |
| .PP |
| Note that tilde substitution will only be |
| performed if it is necessary to complete the command. For example, |
| .CS |
| \fBfile dirname ~/src/foo.c\fR |
| .CE |
| returns \fB~/src\fR, whereas |
| .CS |
| \fBfile dirname ~\fR |
| .CE |
| returns \fB/home\fR (or something similar). |
| .RE |
| .TP |
| \fBfile executable \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is executable by the current user, |
| \fB0\fR otherwise. |
| .TP |
| \fBfile exists \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR exists and the current user has |
| search privileges for the directories leading to it, \fB0\fR otherwise. |
| .TP |
| \fBfile extension \fIname\fR |
| . |
| Returns all of the characters in \fIname\fR after and including the last |
| dot in the last element of \fIname\fR. If there is no dot in the last |
| element of \fIname\fR then returns the empty string. |
| .TP |
| \fBfile isdirectory \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. |
| .TP |
| \fBfile isfile \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. |
| .TP |
| \fBfile join \fIname\fR ?\fIname ...\fR? |
| . |
| Takes one or more file names and combines them, using the correct path |
| separator for the current platform. If a particular \fIname\fR is |
| relative, then it will be joined to the previous file name argument. |
| Otherwise, any earlier arguments will be discarded, and joining will |
| proceed from the current argument. For example, |
| .RS |
| .CS |
| \fBfile join a b /foo bar\fR |
| .CE |
| returns \fB/foo/bar\fR. |
| .PP |
| Note that any of the names can contain separators, and that the result |
| is always canonical for the current platform: \fB/\fR for Unix and |
| Windows, and \fB:\fR for Macintosh. |
| .RE |
| .TP |
| \fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR? |
| . |
| If only one argument is given, that argument is assumed to be |
| \fIlinkName\fR, and this command returns the value of the link given by |
| \fIlinkName\fR (i.e. the name of the file it points to). If |
| \fIlinkName\fR isn't a link or its value cannot be read (as, for example, |
| seems to be the case with hard links, which look just like ordinary |
| files), then an error is returned. |
| . |
| If 2 arguments are given, then these are assumed to be \fIlinkName\fR and |
| \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR |
| doesn't exist, an error will be returned. Otherwise, Tcl creates a new |
| link called \fIlinkName\fR which points to the existing filesystem object |
| at \fItarget\fR, where the type of the link is platform-specific (on Unix |
| a symbolic link will be the default). This is useful for the case where |
| the user wishes to create a link in a cross-platform way, and doesn't |
| care what type of link is created. |
| . |
| If the user wishes to make a link of a specific type only, (and signal an |
| error if for some reason that is not possible), then the optional |
| \fI-linktype\fR argument should be given. Accepted values for |
| \fI-linktype\fR are "-symbolic" and "-hard". |
| . |
| When creating links on filesystems that either do not support any links, |
| or do not support the specific type requested, an error message will be |
| returned. In particular Windows 95, 98 and ME do not support any links |
| at present, but most Unix platforms support both symbolic and hard links |
| (the latter for files only), MacOS supports symbolic links and Windows |
| NT/2000/XP (on NTFS drives) support symbolic directory links and hard |
| file links. |
| .TP |
| \fBfile lstat \fIname varName\fR |
| . |
| Same as \fBstat\fR option (see below) except uses the \fIlstat\fR |
| kernel call instead of \fIstat\fR. This means that if \fIname\fR |
| refers to a symbolic link the information returned in \fIvarName\fR |
| is for the link rather than the file it refers to. On systems that |
| don't support symbolic links this option behaves exactly the same |
| as the \fBstat\fR option. |
| .TP |
| \fBfile mkdir \fIdir\fR ?\fIdir\fR ...? |
| . |
| Creates each directory specified. For each pathname \fIdir\fR specified, |
| this command will create all non-existing parent directories as |
| well as \fIdir\fR itself. If an existing directory is specified, then |
| no action is taken and no error is returned. Trying to overwrite an existing |
| file with a directory will result in an error. Arguments are processed in |
| the order specified, halting at the first error, if any. |
| .TP |
| \fBfile mtime \fIname\fR ?\fItime\fR? |
| . |
| Returns a decimal string giving the time at which file \fIname\fR was last |
| modified. If \fItime\fR is specified, it is a modification time to set for |
| the file (equivalent to Unix \fBtouch\fR). The time is measured in the |
| standard POSIX fashion as seconds from a fixed starting time (often January |
| 1, 1970). If the file doesn't exist or its modified time cannot be queried |
| or set then an error is generated. |
| .TP |
| \fBfile nativename \fIname\fR |
| . |
| Returns the platform-specific name of the file. This is useful if the |
| filename is needed to pass to a platform-specific call, such as exec |
| under Windows or AppleScript on the Macintosh. |
| .TP |
| \fBfile normalize \fIname\fR |
| . |
| .RS |
| Returns a unique normalised path representation for the file-system |
| object (file, directory, link, etc), whose string value can be used as a |
| unique identifier for it. A normalized path is an absolute path which has |
| all '../', './' removed. Also it is one which is in the ``standard'' |
| format for the native platform. On MacOS, Unix, this means the segments |
| leading up to the path must be free of symbolic links/aliases (but the |
| very last path component may be a symbolic link), and on Windows it also |
| means means we want the long form with that form's case-dependence (which |
| gives us a unique, case-dependent path). The one exception concerning the |
| last link in the path is necessary, because Tcl or the user may wish to |
| operate on the actual symbolic link itself (for example 'file delete', 'file |
| rename', 'file copy' are defined to operate on symbolic links, not on the |
| things that they point to). |
| .RE |
| .TP |
| \fBfile owned \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR |
| otherwise. |
| .TP |
| \fBfile pathtype \fIname\fR |
| . |
| Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If |
| \fIname\fR refers to a specific file on a specific volume, the path type |
| will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the |
| current working directory, then the path type will be \fBrelative\fR. If |
| \fIname\fR refers to a file relative to the current working directory on |
| a specified volume, or to a specific file on the current working volume, then |
| the file type is \fBvolumerelative\fR. |
| .TP |
| \fBfile readable \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is readable by the current user, |
| \fB0\fR otherwise. |
| .TP |
| \fBfile readlink \fIname\fR |
| . |
| Returns the value of the symbolic link given by \fIname\fR (i.e. the name |
| of the file it points to). If \fIname\fR isn't a symbolic link or its |
| value cannot be read, then an error is returned. On systems that don't |
| support symbolic links this option is undefined. |
| .TP |
| \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR |
| .TP |
| \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR |
| .RS |
| The first form takes the file or directory specified by pathname |
| \fIsource\fR and renames it to \fItarget\fR, moving the file if the |
| pathname \fItarget\fR specifies a name in a different directory. If |
| \fItarget\fR is an existing directory, then the second form is used. |
| The second form moves each \fIsource\fR file or directory into the |
| directory \fItargetDir\fR. Existing files will not be overwritten |
| unless the \fB\-force\fR option is specified. When operating inside a |
| single filesystem, Tcl will rename symbolic links rather than the |
| things that they point to. Trying to overwrite a non-empty directory, |
| overwrite a directory with a file, or a file with a directory will all |
| result in errors. Arguments are processed in the order specified, |
| halting at the first error, if any. A \fB\-\|\-\fR marks the end of |
| switches; the argument following the \fB\-\|\-\fR will be treated as a |
| \fIsource\fR even if it starts with a \fB\-\fR. |
| .RE |
| .TP |
| \fBfile rootname \fIname\fR |
| . |
| Returns all of the characters in \fIname\fR up to but not including the |
| last ``.'' character in the last component of name. If the last |
| component of \fIname\fR doesn't contain a dot, then returns \fIname\fR. |
| .TP |
| \fBfile separator\fR ?\fIname\fR? |
| . |
| If no argument is given, returns the character which is used to separate |
| path segments for native files on this platform. If a path is given, |
| the filesystem responsible for that path is asked to return its |
| separator character. If no file system accepts \fIname\fR, an error |
| is generated. |
| .TP |
| \fBfile size \fIname\fR |
| . |
| Returns a decimal string giving the size of file \fIname\fR in bytes. If |
| the file doesn't exist or its size cannot be queried then an error is |
| generated. |
| .TP |
| \fBfile split \fIname\fR |
| . |
| Returns a list whose elements are the path components in \fIname\fR. The |
| first element of the list will have the same path type as \fIname\fR. |
| All other elements will be relative. Path separators will be discarded |
| unless they are needed ensure that an element is unambiguously relative. |
| For example, under Unix |
| .RS |
| .CS |
| file split /foo/~bar/baz |
| .CE |
| returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands |
| that use the third component do not attempt to perform tilde |
| substitution. |
| .RE |
| .TP |
| \fBfile stat \fIname varName\fR |
| . |
| Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable |
| given by \fIvarName\fR to hold information returned from the kernel call. |
| \fIVarName\fR is treated as an array variable, and the following elements |
| of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR, |
| \fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR, |
| \fBuid\fR. Each element except \fBtype\fR is a decimal string with the |
| value of the corresponding field from the \fBstat\fR return structure; |
| see the manual entry for \fBstat\fR for details on the meanings of the |
| values. The \fBtype\fR element gives the type of the file in the same |
| form returned by the command \fBfile type\fR. This command returns an |
| empty string. |
| .TP |
| \fBfile system \fIname\fR |
| . |
| Returns a list of two elements, the first of which is the name of the |
| filesystem to use for the file, and the second an arbitrary string |
| representing the filesystem-specific nature or type of the location |
| within that filesystem. If a filesystem only supports one type of file, |
| the second element may be null. For example the native files have a |
| first element 'native', and a second element which is a platform-specific |
| type name for the file's system (e.g. 'NTFS', 'FAT', etc), or possibly |
| the empty string if no further information is available or if this |
| is not implemented. A generic virtual file system might return the |
| list 'vfs ftp' to represent a file on a remote ftp site mounted as a |
| virtual filesystem through an extension called 'vfs'. If the file does |
| not belong to any filesystem, an error is generated. |
| .TP |
| \fBfile tail \fIname\fR |
| . |
| Returns all of the characters in \fIname\fR after the last directory |
| separator. If \fIname\fR contains no separators then returns |
| \fIname\fR. |
| .TP |
| \fBfile type \fIname\fR |
| . |
| Returns a string giving the type of file \fIname\fR, which will be one of |
| \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, |
| \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. |
| .TP |
| \fBfile volume\fR |
| . |
| Returns the absolute paths to the volumes mounted on the system, as a |
| proper Tcl list. On the Macintosh, this will be a list of the mounted |
| drives, both local and network. N.B. if two drives have the same name, |
| they will both appear on the volume list, but there is currently no way, |
| from Tcl, to access any but the first of these drives. On UNIX, the |
| command will always return "/", since all filesystems are locally mounted. |
| On Windows, it will return a list of the available local drives |
| (e.g. {a:/ c:/}). |
| .TP |
| \fBfile writable \fIname\fR |
| . |
| Returns \fB1\fR if file \fIname\fR is writable by the current user, |
| \fB0\fR otherwise. |
| .SH "PORTABILITY ISSUES" |
| .TP |
| \fBUnix\fR\0\0\0\0\0\0\0 |
| . |
| These commands always operate using the real user and group identifiers, |
| not the effective ones. |
| |
| .SH "SEE ALSO" |
| filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), |
| fblocked(n), flush(n) |
| |
| .SH KEYWORDS |
| attributes, copy files, delete files, directory, file, move files, name, rename files, stat |