file(n) Tcl Built-In Commands file(n) _________________________________________________________________ NAME file - Manipulate file names and attributes SYNOPSIS file _o_p_t_i_o_n _n_a_m_e ?_a_r_g _a_r_g ...? _________________________________________________________________ DESCRIPTION This command provides several operations on a file's name or attributes. _N_a_m_e 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 filename for details). _O_p_t_i_o_n indicates what to do with the file name. Any unique abbreviation for _o_p_t_i_o_n is acceptable. The valid options are: file atime _n_a_m_e Returns a decimal string giving the time at which file _n_a_m_e was last accessed. 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 then an error is generated. file copy ?-force? ?--? _s_o_u_r_c_e _t_a_r_g_e_t file copy ?-force? ?--? _s_o_u_r_c_e ?_s_o_u_r_c_e ...? _t_a_r_g_e_t_D_i_r The first form makes a copy of the file or directory _s_o_u_r_c_e under the pathname _t_a_r_g_e_t. If _t_a_r_g_e_t is an existing directory, then the second form is used. The second form makes a copy inside _t_a_r_g_e_t_D_i_r of each _s_o_u_r_c_e file listed. If a directory is specified as a _s_o_u_r_c_e, then the contents of the directory will be recursively copied into _t_a_r_g_e_t_D_i_r. Existing files will not be overwritten unless the -force option is speci- fied. 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 -_f_o_r_c_e was specified. Arguments are processed in the order speci- fied, halting at the first error, if any. A - - marks the end of switches; the argument following the -- will be treated as a _s_o_u_r_c_e even if it starts with a -. file delete ?-force? ?--? _p_a_t_h_n_a_m_e ?_p_a_t_h_n_a_m_e ... ? Removes the file or directory specified by each _p_a_t_h_- _n_a_m_e argument. Non-empty directories will be removed only if the -force option is specified. Trying to delete a non-existant file is not considered an error. Trying to delete a read-only file will cause the file to be deleted, even if the - force flags is not Tcl Last change: 7.6 1 file(n) Tcl Built-In Commands file(n) specified. Arguments are processed in the order speci- fied, halting at the first error, if any. A -- marks the end of switches; the argument following the -- will be treated as a _p_a_t_h_n_a_m_e even if it starts with a -. file dirname _n_a_m_e Returns a name comprised of all of the path components in _n_a_m_e excluding the last element. If _n_a_m_e is a rela- tive file name and only contains one path element, then returns ``.'' (or ``:'' on the Macintosh). If _n_a_m_e refers to a root directory, then the root directory is returned. For example, file dirname c:/ returns c:/. Note that tilde substitution will only be performed if it is necessary to complete the command. For example, file dirname ~/src/foo.c returns ~/src, whereas file dirname ~ returns /home (or something similar). file executable _n_a_m_e Returns 1 if file _n_a_m_e is executable by the current user, 0 otherwise. file exists _n_a_m_e Returns 1 if file _n_a_m_e exists and the current user has search privileges for the directories leading to it, 0 otherwise. file extension _n_a_m_e Returns all of the characters in _n_a_m_e after and includ- ing the last dot in the last element of _n_a_m_e. If there is no dot in the last element of _n_a_m_e then returns the empty string. file isdirectory _n_a_m_e Returns 1 if file _n_a_m_e is a directory, 0 otherwise. file isfile _n_a_m_e Returns 1 if file _n_a_m_e is a regular file, 0 otherwise. file join _n_a_m_e ?_n_a_m_e ...? Takes one or more file names and combines them, using the correct path separator for the current platform. If a particular _n_a_m_e 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, file join a b /foo bar returns /foo/bar. Tcl Last change: 7.6 2 file(n) Tcl Built-In Commands file(n) Note that any of the names can contain separators, and that the result is always canonical for the current platform: / for Unix and Windows, and : for Macintosh. file lstat _n_a_m_e _v_a_r_N_a_m_e Same as stat option (see below) except uses the _l_s_t_a_t kernel call instead of _s_t_a_t. This means that if _n_a_m_e refers to a symbolic link the information returned in _v_a_r_N_a_m_e 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 stat option. file mkdir _d_i_r ?_d_i_r ...? Creates each directory specified. For each pathname _d_i_r specified, this command will create all non- existing parent directories as well as _d_i_r 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. file mtime _n_a_m_e Returns a decimal string giving the time at which file _n_a_m_e was last modified. 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 then an error is generated. file owned _n_a_m_e Returns 1 if file _n_a_m_e is owned by the current user, 0 otherwise. file pathtype _n_a_m_e Returns one of absolute, relative, volumerelative. If _n_a_m_e refers to a specific file on a specific volume, the path type will be absolute. If _n_a_m_e refers to a file relative to the current working directory, then the path type will be relative. If _n_a_m_e 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 volumerelative. file readable _n_a_m_e Returns 1 if file _n_a_m_e is readable by the current user, 0 otherwise. file readlink _n_a_m_e Returns the value of the symbolic link given by _n_a_m_e (i.e. the name of the file it points to). If _n_a_m_e isn't a symbolic link or its value cannot be read, then Tcl Last change: 7.6 3 file(n) Tcl Built-In Commands file(n) an error is returned. On systems that don't support symbolic links this option is undefined. file rename ?-force? ?--? _s_o_u_r_c_e _t_a_r_g_e_t file rename ?-force? ?--? _s_o_u_r_c_e ?_s_o_u_r_c_e ...? _t_a_r_g_e_t_D_i_r The first form takes the file or directory specified by pathname _s_o_u_r_c_e and renames it to _t_a_r_g_e_t, moving the file if the pathname _t_a_r_g_e_t specifies a name in a dif- ferent directory. If _t_a_r_g_e_t is an existing directory, then the second form is used. The second form moves each _s_o_u_r_c_e file or directory into the directory _t_a_r_- _g_e_t_D_i_r. Existing files will not be overwritten unless the -force option is specified. 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 -- marks the end of switches; the argument following the -- will be treated as a _s_o_u_r_c_e even if it starts with a -. file rootname _n_a_m_e Returns all of the characters in _n_a_m_e up to but not including the last ``.'' character in the last com- ponent of name. If the last component of _n_a_m_e doesn't contain a dot, then returns _n_a_m_e. file size _n_a_m_e Returns a decimal string giving the size of file _n_a_m_e in bytes. If the file doesn't exist or its size cannot be queried then an error is generated. file split _n_a_m_e Returns a list whose elements are the path components in _n_a_m_e. The first element of the list will have the same path type as _n_a_m_e. 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 file split /foo/~bar/baz returns / foo ./~bar baz to ensure that later com- mands that use the third component do not attempt to perform tilde substitution. file stat _n_a_m_e _v_a_r_N_a_m_e Invokes the stat kernel call on _n_a_m_e, and uses the variable given by _v_a_r_N_a_m_e to hold information returned from the kernel call. _V_a_r_N_a_m_e is treated as an array variable, and the following elements of that variable are set: atime, ctime, dev, gid, ino, mode, mtime, nlink, size, type, uid. Each element except type is a decimal string with the value of the corresponding field from the stat return structure; see the manual Tcl Last change: 7.6 4 file(n) Tcl Built-In Commands file(n) entry for stat for details on the meanings of the values. The type element gives the type of the file in the same form returned by the command file type. This command returns an empty string. file tail _n_a_m_e Returns all of the characters in _n_a_m_e after the last directory separator. If _n_a_m_e contains no separators then returns _n_a_m_e. file type _n_a_m_e Returns a string giving the type of file _n_a_m_e, which will be one of file, directory, characterSpecial, blockSpecial, fifo, link, or socket. file writable _n_a_m_e Returns 1 if file _n_a_m_e is writable by the current user, 0 otherwise. PORTABILITY ISSUES Unix These commands always operate using the real user and group identifiers, not the effective ones. SEE ALSO filename KEYWORDS attributes, copy files, delete files, directory, file, move files, name, rename files, stat Tcl Last change: 7.6 5