Information about Files - file, glob

There are two commands that provide information about the file system, glob and file.

glob provides the access to the names of files in a directory. It uses a name matching mechanism similar to the UNIX ls command or the Windows (DOS) dir command, to return a list of names that match a pattern.

file provides three sets of functionality:

Between these two commands, a program can obtain most of the information that it may need and manipulate the files and directories.

While retrieving information about what files are present and what properties they have is usually a highly platform-dependent matter, Tcl provides an interface that hides almost all details that are specific to the platform (but are irrelevant to the programmer).

To take advantage of this feature, always manipulate file names via the file join, file split commands and the others in the first category.

For instance to refer to a file in a directory upwards of the current one:

set upfile [file join ".." "myfile.out"]
# upfile will have the value "../myfile.out"

(The ".." indicates the "parent directory")

Because external commands may not always deal gracefully with the uniform representation that Tcl employs (with forward slashes as directory separators), Tcl also provides a command to turn the string into one that is native to the platform:

#
# On Windows the name becomes "..\myfile.out"
#
set newname [file nativename [file join ".." "myfile.out"]]

Retrieving all the files with extension ".tcl" in the current directory:

set tclfiles [glob *.tcl]
puts "Name - date of last modification"
foreach f $tclfiles {
    puts "$f - [clock format [file mtime $f] -format %x]"
}
(The clock command turns the number of seconds returned by the file mtime command into a simple date string, like "12/22/04")
glob ?switches? pattern ?patternN?
returns a list of file names that match pattern or patternN

switches may be one of the following (there are more switches available):

-nocomplain
Allows glob to return an empty list without causing an error. Without this flag, an error would be generated when the empty list was returned.
-types typeList
Selects which type of files/directory the command should return. The typeList may consist of type letters, like a "d" for directories and "f" for ordinary files as well as letters and keywords indicating the user's permissions ("r" for files/directories that can be read for instance).
--
Marks the end of switches. This allows the use of "-" in a pattern without confusing the glob parser.

pattern follows the same matching rules as the string match globbing rules with these exceptions:

Note that the filenames that match pattern are returned in an arbitrary order (that is, do not expect them to be sorted in alphabetical order, for instance).

file atime name
Returns the number of seconds since some system-dependent start date, also known as the "epoch" (frequently 1/1/1970) when the file name was last accessed. Generates an error if the file doesn't exist, or the access time cannot be queried.
file copy ?-force? name target
Copy the file/directory name to a new file target (or to an existing directory with that name)
The switch -force allows you to overwrite existing files.
file delete ?-force? name
Delete the file/directory name.
The switch -force allows you to delete non-empty directories.
file dirname name
Returns the directory portion of a path/filename string. If name contains no slashes, file dirname returns a ".". If the last "/" in name is also the first character, it returns a "/".
file executable name
Returns 1 if file name is executable by the current user, otherwise returns 0.
file exists name
Returns 1 if the file name exists, and the user has search access in all the directories leading to the file. Otherwise, 0 is returned.
file extension name
Returns the file extension.
file isdirectory name
Returns 1 if file name is a directory, otherwise returns 0.
file isfile name
Returns 1 if file name is a regular file, otherwise returns 0.
file lstat name varName
This returns the same information returned by the system call lstat. The results are placed in the associative array varName. The indexes in varName are: Because this calls lstat, if name is a symbolic link, the values in varName will refer to the link, not the file that is linked to. (See also the stat subcommand)
file mkdir name
Create a new directory name.
file mtime name
Returns the time of the last modification in seconds since Jan 1, 1970 or whatever start date the system uses.
file owned name
Returns 1 if the file is owned by the current user, otherwise returns 0.
file readable name
Returns 1 if the file is readable by the current user, otherwise returns 0.
file readlink name
Returns the name of the file a symlink is pointing to. If name isn't a symlink, or can't be read, an error is generated.
file rename ?-force? name target
Rename file/directory name to the new name target (or to an existing directory with that name)
The switch -force allows you to overwrite existing files.
file rootname name
Returns all the characters in name up to but not including the last ".". Returns $name if name doesn't include a ".".
file size name
Returns the size of name in bytes.
file stat name varName
This returns the same information returned by the system call stat. The results are placed in the associative array varName. The indexes in varName are:
file tail name
Returns all of the characters in name after the last slash. Returns the name if name contains no slashes.
file type name
Returns a string giving the type of file name, which will be one of:
file writable name
Returns 1 if file name is writable by the current user, otherwise returns 0.

Note: The overview given above does not cover all the details of the various subcommands, nor does it list all subcommands. Please check the man pages for these.


Example

#
# Report all the files and subdirectories in the current directory
# For files: show the size
# For directories: show that they _are_ directories
#

set dirs [glob -nocomplain -type d *]
if { $dirs != {} } {
    puts "Directories:
    foreach d [lsort $dirs] {
        puts "    $d"
    }
} else {
    puts "(no subdirectories)"
}

set files [glob -nocomplain -type f *]
if { $files != {} } {
    puts "Files:
    foreach f [lsort $files] {
        puts "    [file size $f] - $f"
    }
} else {
    puts "(no files)"
}