Files, Disks and Volumes

Commands related to files, disks and volumes

SYNOPSIS

package require twapi

begin_filesystem_monitor PATH SCRIPT ?options?
cancel_filesystem_monitor MONITORID
find_logical_drives ?-type DRIVETYPELIST?
file_properties_dialog FILEPATH ?options?
find_volumes
find_volume_mount_points VOLNAME
get_drive_info DRIVE ?options?
get_drive_type DRIVE
get_file_times FILE ?options?
get_file_version_resource PATH ?options? ?STRINGNAME...?
get_mounted_volume_name MOUNTPOINT
get_volume_info DRIVE ?options?
get_volume_mount_point_for_path PATH
map_drive_local DRIVE PATH ?options?
mount_volume MOUNTPOINTPATH VOLNAME
set_drive_label DRIVE NAME
set_file_times FILE ?options?
unmap_drive_local DRIVE ?options?
unmount_volume MOUNTPOINTPATH
user_drive_space_available drive space
volume_properties_dialog VOLUME ?options?

DESCRIPTION

This package provides procedures related to file, disk and volume information in Windows operating systems.

Volume Commands

The command find_volumes returns a list of volumes on the system. The command get_volume_info returns various information about a volume (logical drive) including size and space utilization, file system characteristics and device.

The command find_volume_mount_points returns the list of volume mount points on a particular volume. Commands mount_volume and unmount_volume can be used to set and remove volumes from volume mount points. The command get_mounted_volume_name will return the name of the volume mounted on a drive letter or volume mount point.

The command volume_properties_dialog displays the shell property sheet dialog for a volume.

Drive Commands

For all drive related commands, the drive parameter may be specified as a single drive letter, a drive letter followed by a :, or as the root path of the drive (eg. C:\)

The command find_logical_drives returns a list of drives in the system of a specified type. get_drive_type returns the type (fixed, remote, etc.) of the logical drive.

The command user_drive_space_available can be used to check if sufficient free space is available on a drive.

The command set_drive_label may be used to set the volume name (drive label).

The command map_drive_local and unmap_drive_local may be used to assign and unassign a drive letter to a local path.

File commands

The commands begin_filesystem_monitor and cancel_filesystem_monitor can be used for monitoring changes to the file system.

The get_file_version_resource returns various information stored within the version resource of a file.

The command file_properties_dialog displays the shell property sheet dialog for a file.

The commands get_file_times and set_file_times and allow retrieval and setting of the times associated with a file.

Commands

begin_filesystem_monitor PATH SCRIPT ?options?
Registers SCRIPT to be invoked when the specified types of changes occur in the directory of subtree matching PATH.

The command returns an identifier corresponding to the monitoring callback. When no longer interested in the specified changes, the returned identifier should be passed to cancel_filesystem_monitor to end the monitoring.

The following options specify the type of changes to be monitored:

-access BOOLEAN If true, changes to the last access time are monitored.
-attr BOOLEAN If true, attribute changes, are monitored.
-create BOOLEAN If true, changes to the creation times are monitored.
-dirname BOOLEAN If true, directory name changes, including creation and renaming, are monitored.
-filename BOOLEAN If true, file name changes, including file creation, renaming and deletion, are monitored.
-secd BOOLEAN If true, changes to security descriptors in the specified directories are monitored.
-size BOOLEAN If true, size changes in the specified directories are monitored.
-subtree BOOLEAN If true, all subdirectories under the specified directory PATH are monitored in addition to PATH itself. If false (default), only the directory indicated by PATH is monitored.
-write BOOLEAN If true, changes to the last write time of files in the specified directories are monitored.


By default, all options are false if unspecified. However, if no options related to the type changes to be monitored are present (either true or false), the command will monitor all types of changes.

When a file system change is detected, the SCRIPT is invoked after being appended with a list each element of which is a pair consisting the type of change and the file or directory name. The type of change is one of the following values:

added The file or directory was added.
removed The file or directory was deleted.
modified The file or directory was modified. This includes changes to attributes or timestamps.
renameold The file or directory was renamed. The associated name is the old name.
renamenew The file or directory was renamed. The associated name is the new name.


Note that the file names being reported may be either in longname or shortname (8.3) format. Moreover, depending on the buffering and caching by the operating system, a single write may result in one or more notifications.

cancel_filesystem_monitor MONITORID
Cancels monitoring of the file system corresponding to MONITORID which must be an identifier returned by begin_filesystem_monitor.

find_logical_drives ?-type DRIVETYPELIST?
Returns a list of the logical drives in the system. If option -type not specified, all drives in the system are returned. Otherwise, only drives whose type is in DRIVETYPELIST are returned. DRIVETYPELIST must be a subset of the values returned by the get_drive_type command.

Example: List all drives on a system

Example: List the remote drives on a system

file_properties_dialog FILEPATH ?options?
Displays the shell property dialog for the specified file. The following options may be specified:

-hwin HWIN If specified, HWIN is the handle to the window to be used as the parent for the dialog.
-page PAGENAME Specifies the name of the property sheet page to be displayed. If unspecified, the default page is displayed.


This command is not available on Windows NT 4.0 and will raise a Tcl error.

find_volumes
Returns the list of volumes in the system. Each entry in the list includes a trailing slash.

find_volume_mount_points VOLNAME
Returns the list of volume mount points on the volume whose name is VOLNAME.

get_drive_info DRIVE ?options?
Synonym for get_volume_info.

get_drive_type DRIVE
Returns the type of the drive - unknown, removable, fixed, remote, cdrom or ramdisk or invalid.

get_file_times FILE ?options?
Retrieves the creation, access and modification timestamps for a file. The latter two are available through the Tcl file command which however does not provide the creation time for a file. FILE may either be the path to the file, an open Tcl channel to the open file or a Win32 handle to an open file. In the latter two cases, the file must have been opened for read access.

The information returned is a flat list of option value pairs. options, which may contain one or more of the following values, controls the information returned.

-all Returns all fields.
-atime Returns the time of last access for the file.
-ctime Returns the creation time for the file.
-mtime Returns the time of last modification for the file.


All times are returned in the same format as get_system_time.

get_file_version_resource PATH ?options? ?STRINGNAME...?
Returns the information stored within the version resource of a file. The command will generate a Tcl error if the file specified by PATH does not contain a version resource.

The version resource consists of two parts. The information in the first part is in a fixed format and can be retrieved by specifying appropriate options in options. The second part is a string table, the entries in which can be retrieved by specifying the key as a STRINGNAME argument.

The following options may be used with the command:

-all Returns all information in the fixed part.
-fileversion Returns the file version as indicated in the version resource. This is returned in the format MAJOR.MINOR.BUILD.PRIVATE. Note this is not necessarily identical to the value specified for the FileVersion entry in the string table.
-fileos Returns a value specifying the platform for which the file was designed. This may be one of dos (MS-DOS), os216 (16-bit OS/2), os232 (16-bit OS/2), nt (Windows NT), wince (Windows CE), windows16 (16-bit Windows), pm16 (16-bit Presentation Manager), pm32 (32-bit Presentation Manager), windows32 (32-bit Windows), dos_windows32 (32-bit Windows on MS-DOS), os216_pm16 (16-bit Presentation Manager on 16-bit OS/2), os232_pm32 (32-bit Presentation Manager on 32-bit OS/2) or nt_windows32 (32-bit Windows on Windows NT).
-filetype Returns the file type which may be one of the following: application, dll, driver.printer, driver.keyboard, driver.language, driver.display, driver.mouse, driver.network, driver.system, driver.installable, driver.sound, driver.comm, driver.inputmethod, driver.versionedprinter, driver.DRIVERSUBTYPENUMBER, font.raster, font.vector, font.truetype, font.FONTSUBTYPENUMBER, vxd.VIRTUALDEVICEID, staticlib or FILETYPENUMBER.FILESUBTYPENUMBER. (Note in cases where the file type or subtype is not recognized, the actual numeric value is returned.)
-flags Returns a list of symbols corresponding to flags set in the version resource. The list may contain symbols from the following: debug, prerelease, patched, privatebuild, infoinferred and specialbuild. In addition, the list may also contain a numeric value corresponding to bits that are set but are not recognized as one of the above.
-langid LANGID Specifies LANGID as the language identifier to be used for string table lookup (see below). By default, the language identifier returned by get_user_ui_langid is used.
-codepage CODEPAGE Specifies CODEPAGE as the code page to be used for string table lookup (see below).
-productversion Returns the product version as indicated in the version resource. This is returned in the format MAJOR.MINOR.BUILD.PRIVATE. Note this is not necessarily identical to the value specified for the ProductVersion entry in the string table.
-signature Contains a longword that is a signature for the fixed part of the version resource. Not particularly useful for the application.
-structversion Returns the version of the version resource format.


In addition to the options that retrieve fixed portions of the version resource, the caller may also specify string names corresponding to language-specific string tables in the version resource. Each such STRINGNAME is looked up in the string table and returned as a STRINGNAME VALUE pair. If a particular string name does not exist in the string table, an empty string is returned as its value. The following string names are commonly defined in version resources: Comments, InternalName, ProductName, CompanyName, LegalCopyright, ProductVersion, FileDescription, LegalTrademarks, PrivateBuild, FileVersion, OriginalFilename, SpecialBuild.

The version resource may contain multiple string tables for different languages and code pages. The caller can control the string table used through the -langid and -codepage options. The command uses the following algorithm in selecting the string table that is looked up.



get_mounted_volume_name MOUNTPOINT
Returns the name of a mounted volume. The returned name has a trailing backslash appended. MOUNTPOINT must specify a root directory of a drive or the path to a volume mount point.

get_volume_info DRIVE ?options?
Returns attributes and properties of the specified volume as a list of the form "option1 value1 ...". DRIVE may be either a DOS drive, file share or a volume. Note certain options are not valid except when DRIVE specifies a drive letter (see below).

The values returned depend on which of the following options are specified:

-all Returns all fields except -type and -device which have to be explicitly specified since they are not valid for volumes.
-attr Returns a list containing one or more of the values case_preserved_names, unicode_on_disk, persistent_acls, file_compression, volume_quotas, supports_sparse_files, supports_reparse_points, supports_remote_storage, volume_is_compressed, supports_object_ids, supports_encryption, named_streams, or read_only_volume. These indicate the features supported by the drive's file system. Refer to the documentation for GetVolumeInformation function in the Windows SDK for details on these.
-device Returns a list the first element of which is the device name mapping for the drive. Remaining elements containing prior undeleted mappings for the drive. Only valid if DRIVE is a drive letter.
-freespace Returns the total size of the unused space on the drive in bytes.
-fstype Returns the type of the file system on the volume (eg. NTFS).
-label Returns the label of the drive.
-maxcomponentlen Returns the maximum length allowed for a single component in a file path.
-serialnum Returns the serial number of the drive in hexadecimal format.
-size Returns the size of the drive in bytes.
-type Returns the type of the drive. Only valid if DRIVE is a drive letter. This may have one of the values unknown, removable, fixed, remote, cdrom or ramdisk. In case the drive path is invalid, the value invalid is returned in this field.
-used Returns the total size of the used space on the drive in bytes.
-useravail Returns the total size of the unused space on the drive that is available for the caller. This may be less than the freespace field if quotas are in effect.


Example: List drives that are almost full

Example: Check if the given drive supports unicode filenames

get_volume_mount_point_for_path PATH
Returns the volume mount point below which the file specified by PATH resides. Refer to documentation for GetVolumePathName in the Windows SDK for more details.

map_drive_local DRIVE PATH ?options?
Maps the fully qualified path PATH to the specified drive letter. The mapping established by this command is not persistent across reboots. It may also be removed using the unmap_drive_local command.

The following options may be specified with the command:

-raw Specifies that PATH is a raw path specification that includes the device name as opposed to a drive letter.


mount_volume MOUNTPOINTPATH VOLNAME
Mounts the volume specified by VOLNAME at the mount point specified by MOUNTPOINTPATH. The directory MOUNTPOINTPATH must be empty. VOLNAME must be of the form \\?\VOLUME{GUID}\. If any volume is already mounted at MOUNTPOINTPATH, it will be silently unmounted before the new mount is performed.

set_drive_label DRIVE NAME
Sets the volume name for the specified drive. NAME may be an empty string in which case the drive label is removed.

Example: Change the label of a drive

set_file_times FILE ?options?
Sets the creation, access or modification timestamps for a file. FILE may either be the path to the file, an open Tcl channel to the open file or a Win32 handle to an open file. In the latter two cases, the file must have been opened for write access.

The timestamps modified depend on the options specified:

-atime LARGETIMESTAMP Sets the time of last access for the file.
-ctime LARGETIMESTAMP Sets the creation time for the file.
-mtime LARGETIMESTAMP Sets the time of last modification for the file.
-preserveatime Indicates that the time of last access for an open file should be preserved and not updated when the file is closed. This option can only be specified if FILE is either an open Tcl channel or Win32 handle and not if it is a file path. Also, the option cannot be used together with -atime.


All time values must be specified in the same format as get_system_time. You can use secs_since_1970_to_large_system_time to convert the format used by Tcl's clock command to this format.

unmap_drive_local DRIVE ?options?
Unmaps the drive specified by DRIVE. This must reference a local drive. The following options may be specified with the command:

-path PATH Specifies that the drive should be unmapped only if it refers to the location specified by PATH. This is useful to ensure drive letters are not unmapped when they have been redefined to point elsewhere.
-raw Specifies that PATH argument specified with the -path option is a raw path specification that includes the device name as opposed to a drive letter.


unmount_volume MOUNTPOINTPATH
Unmounts the volume at the mount point specified by MOUNTPOINTPATH. If MOUNTPOINTPATH is a root directory of a drive, the corresponding DOS drive letter mapping is removed.

user_drive_space_available drive space
Returns 1 if the given drive has at least space bytes free, and 0 otherwise. Note that space is compared to the free bytes available to the caller as opposed to total free bytes on the drive. The former may be smaller if disk quotas are being enforced on the drive.

Example: Check available disk space



volume_properties_dialog VOLUME ?options?
Displays the shell property dialog for the specified volume. The following options may be specified:

-hwin HWIN If specified, HWIN is the handle to the window to be used as the parent for the dialog.
-page PAGENAME Specifies the name of the property sheet page to be displayed. If unspecified, the default page is displayed.


This command is not available on Windows NT 4.0 and will raise a Tcl error.

COPYRIGHT

Copyright © 2003-2007 Ashok P. Nadkarni