Handles

Commands for managing operating system handles

SYNOPSIS

package require twapi

close_handles ?HANDLELIST HANDLELIST?
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 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.

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 ACCESSRIGHTSSpecifies 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.
-closesourceIf specified, HANDLE is closed after it is duplicated.
-inheritIf 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