Tcl Windows API extension

This package provides procedures related to file, logical disk and volume information. For commands related to physical disks see the twapi_device module.

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.

Logical drives

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. drive_ready checks if the specified drive is ready. 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 system

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

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

The command flush_channel flushes operating system buffers associated with a Tcl channel to disk.

The commands find_file_open, find_file_next and find_file_close can be used to incrementally iterate through directory or file system contents while retrieving file meta-information.

The command normalize_device_rooted_path converts a device based path to a normalized Win32 path with drive letters.

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 id 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.
-patterns PATTERNLIST	If specified, notification callbacks are invoked only on those files and directories that match one of the patterns in PATTERNLIST. See below for more detail.
-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 two additional parameters the first being the id that was returned by the command and the second being a list of alternating elements consisting of the notification type and the file or directory name (except when the type is error). The type 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.
error	There was an error in the operation. In this case the corresponding paired element is an error code. On receiving an error notification, the monitoring should generally be canceled by calling cancel_filesystem_monitor.

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.

If the -patterns option is specified, then the value associated with the option is a pattern filter that is used to match against the name component being reported. SCRIPT will be invoked only if the pattern filter matches.

Each element of the pattern list is a string beginning with either + or - followed by a pattern that is used for matching using the same rules as for the Tcl string match -nocase command. Note that \ path separator need to be escaped with another \ just as in the string match case. Alternatively, you can use / as the path separator in the pattern.

The name component being reported is matched against each element of the pattern list. When a match occurs, further elements of the pattern list are not matched. If the matching element is prefixed with a +, then SCRIPT is invoked. If the matching element is prefixed with a -, then the pattern filter is deemed to have not matched and SCRIPT is not invoked for the notification. Even in this case, no further matching is attempted against the remaining patterns. Pattern elements that do not begin with +, or - are treated as having an implicit + prefix.

If a non-empty pattern filter is specified but no element matches, the pattern filter is treated as having not matched, and SCRIPT is not invoked. Thus a pattern filter that only has - type elements will never match anything. Note a pattern list where no element matches is different from the case where -patterns is not specified or PATTERNLIST is empty in which case the pattern filter is treated as matched.

Note that the pattern matching is done only against the name component being reported, not against the full path.

Some examples of pattern matching are below (assume callback is your SCRIPT procedure):

begin_filesystem_monitor c:/temp callback -patterns {*.exe}

will only monitor files in c:\temp with .exe extensions.

begin_filesystem_monitor c:/temp callback -patterns {-*.foo +*.fo*}

will monitor files in c:\temp with an extension beginning with .fo except if the extension is .foo.

begin_filesystem_monitor c:/temp callback -patterns {+*.fo* -*.foo}

will monitor files in c:\temp with an extension beginning with .fo including those with extension .foo. The second pattern -*.foo has no effect as the matching stops as soon as a match is found.

This command requires a threaded build of Tcl and will raise an exception on non-threaded builds.

cancel_filesystem_monitor MONITORID

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

drive_ready DRIVE

Returns 1 if the specified drive is ready and 0 otherwise (for example if the drive media is not inserted). The drive must exist else an error is raised.

find_file_close FFTOKEN

Closes a token previously returned by find_file_open.

find_file_next FFTOKEN VARNAME

Each call returns the next entry from file iteration corresponding to FFTOKEN which must be a token returned by find_file_open. If there are additional entries in the iteration, the command returns a boolean true value and stores the entry in a variable VARNAME in the caller's context. If no more entries remain the command returns a boolean false. The entry stored in VARNAME is in the form of a dictionary with the following keys.

atime	Last access time as 100ns units since Jan 1, 1601.
attrs	Bit mask of file attributes. This can be decoded with the decode_file_attributes command.
ctime	Creation time as 100ns units since Jan 1, 1601.
mtime	Last modification time as 100ns units since Jan 1, 1601.
size	File size. This will always be 0 for directories.
name	File name.
altname	Alternate name (generally, the short name) of file, if any. The -detail option to the find_file_open must be specified as full for this to be retrieved. The element will be present bu empty if the option was specified as basic or if there is no alternate name.

Any additional dictionary keys should be ignored.

find_file_open PATH ?-detail basic|full?

Returns a token that can be used to iterate through files with the find_file_next command. The iteration will include all files that match PATH which may include wildcard patterns in the filename component. The wildcards are as interpreted by Windows and different from the patterns expected by the Tcl glob command. The -detail option may be specified as basic (default) or full. See the find_file_next command for the difference. The returned token must be closed by calling find_file_close.

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.

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.

flush_channel CHANNEL

Flushes operating system buffers associated with a Tcl channel to disk.

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_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 local drive or path to a volume mount point. Specifying remote file shares will generate an error.

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 -extents, -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, read_only_volume, sequential_write_once, supports_transactions, supports_hard_links, supports_extended_attributes, supports_open_by_file_id, or supports_usn_journal. 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. For UNC paths, an empty string will be returned.
-extents	Returns a list of disk extents describing the physical location of the volume. Each disk extent is a keyed list containing 3 fields: -disknumber identifying the physical disk, -startingoffset containing the byte offset in the physical disk that the extent starts at, and -extentlength containing the size of the extent. An empty list is returned for extents if they cannot be determined (for example, for remote drives).
-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.

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.

decode_file_attributes ATTRS

Decodes the bitmask ATTRS as returned in file entries by the find_file_next command. The return value is a list of elements from amongst archive, compressed, device, directory, encrypted, hidden, integrity, normal, not, no, offline, readonly, recall, recall, reparse, sparse, system, temporary, virtual. Any bits not recognized will be returned as numeric values.

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.

normalize_device_rooted_path PATH ?PATHVAR?

Converts a device based path such as DeviceHarddiskVolume5in to a Win32 drive-based path like C:in. If PATHVAR is not present, the converted path is returned or an exception raised if it cannot be converted. If PATHVAR is present, it is treated as a variable in the caller's context. If the conversion is successful, the path is stored in the variable and the command returns 1. Otherwise the command returns 0.

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.

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.

Storage

SYNOPSIS

DESCRIPTION

Volumes

Logical drives

File system

Commands

COPYRIGHT

TWAPI 4.7.1 Documentation