Handles

Commands for managing operating system handles

SYNOPSIS

package require twapi

close_handles ?HANDLELIST HANDLELIST?

create_file PATH ?options?

duplicate_handle HANDLE ?options?

get_tcl_channel_handle CHANNEL DIRECTION

DESCRIPTION

This module provides commands that deal with operating system handles.

Overview

Several Win32 and TWAPI commands return operating system handles to various types of resources. The following commands allow manipulation and retrieval of information regarding handles.

The command create_file returns a handle to a file or device.

The operating system associated with a Tcl channel can be retrieved using the get_tcl_channel_handle command.

The command duplicate_handle can be used to duplicate a handle, for example to pass down to a child process with different access rights.

The command close_handle closes a operating system handle and frees resources associated with it.

Commands

close_handles ?HANDLELIST HANDLELIST?

This command concatenates its arguments and treats the result as a list of operating system handles. It closes each handle in this list. In case of errors, closing any handles, it continues to try and close the remaining handles before generating an exception.

create_file PATH ?options?

This is a thin wrapper around the Win32 CreateFile function that returns a handle to a file or device. The wrapper primarily provides mnemonics and defaults for the CreateFile parameters. PATH specifies the file or device path. Additional options and default values are shown below.

-access ACCESSRIGHTS	Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.
-createdisposition DISPOSITION	DISPOSITION must be one of create_always, create_new, open_always, open_existing or truncate_existing. Refer to the Windows SDK for the meaning. Defaults to open_always.
-flags FLAGS	An integer bit mask corresponding to the dwFlagsAndAttributes parameter to CreateFile function. See the Windows SDK for detail. Defaults to 0.
-inherit BOOL	If true, the returned handle is inheritable by child processes. Defaults to false.
-secd SECURITY_DESCRIPTOR	Specifies a security descriptor to be attached to the file or device if it has to be created. Defaults to a null security descriptor which results in the process' default security descriptor being applied.
-share	Specifies the sharing mode of the object. This is list containing zero or more of the constants read, write and delete that control what kind of shared access should be allowed while the file or device is open. Defaults to {read write delete}.
-templatefile	A handle to a template file with the GENERIC_READ access right from which file attributes and extended attributes are to be copied for the file that is being created. Defaults to NULL.

Refer to the Windows SDK for additional details.

duplicate_handle HANDLE ?options?

Duplicates an operating system handle. HANDLE may be either in the form returned by commands such as get_tcl_channel_handle or get_process_handle or may be an actual address (integer) literal corresponding to the handle. The following options specify the context of the handle and control attributes of the duplicated handle:

-access ACCESSRIGHTS	Specifies the access rights desired for the new handle. If unspecified, the new handle is created with the same access rights as the original one. ACCESSRIGHTS is a list of symbolic constants and bit masks as specified in Access Rights.
-closesource	If specified, HANDLE is closed after it is duplicated.
-inherit	If specified, the new handle marked as inheritable. By default, the duplicated handle cannot be inherited by child processes.
-sourcepid SOURCEPID	Specifies the PID of the process in whose context HANDLE is a valid handle. Defaults to the current process.
-targetpid TARGETPID	Specifies the PID of the process in whose context the new handle is to be created. Specifying this also impacts the format of the returned handle value.

If option -targetpid is not specified, the command returns the duplicated handle in symbolic form that can be passed to functions such as close_handle. If -targetpid is specified, the command returns the literal value of the handle. This is true even if the target PID is that of the current process.

get_tcl_channel_handle CHANNEL DIRECTION

Returns the operating system handle corresponding to a Tcl channel identifier (for example, returned by the Tcl open command). If DIRECTION is write, the write-side handle is returned, otherwise the read-side handle is returned. (For many channel types, the two are identical.)

COPYRIGHT

Copyright © 2004-2005 Ashok P. Nadkarni