Tcl Windows API extension

get_version returns TWAPI version information. export_public_commands and import_commands enable export and import of commands defined in the TWAPI namespace.

Handles

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.

An application can wait on a handle to be signalled using the wait_on_handle command. The wait can be cancelled by calling cancel_wait_on_handle command.

The twapi_base package includes some commonly used commands related to user accounts. The command lookup_account_name, map_account_to_name, lookup_account_sid and map_account_to_sid translate between user and group account names and their SID's. The command is_valid_sid_syntax validates the syntax of an SID.

A more complete set of commands related to accounts, credentials and security are in the twapi_account and twapi_security packages.

Passwords

Commands cred_prompt_console, cred_prompt_gui, cred_get, and cred_confirm allow interfacing to the Windows credentials manager and getting user credentials such as passwords from the user.

make_logon_identity constructs a logon account, domain and password in a form required by many other commands.

Protecting data in memory

Passwords are sensitive data and need to be protected in memory. For example, in case of error exceptions being logged to file, plaintext passwords should not be exposed. The above commands return passwords in an encrypted form. TWAPI commands that deal with passwords expect them to be passed in this encrypted form. The conceal and reveal commands can also be used for this purpose. Note however using conceal is not as secure as the argument passed to it is still in clear text.

Writing to the Windows event log

Commands for writing to the Windows event log are included in the twapi_base package. Documentation for these is however part of the twapi_eventlog package.

Error generation and handling

The twapi_base module also provides various facilities for generating and handing errors and Tcl exceptions.

TWAPI generates Tcl exceptions when errors are encountered. Information pertaining to the error is stored in Tcl global variables as with any standard Tcl errors. The global variable errorInfo contains a traceback of the Tcl stack when the error occured. The global errorCode contains a list with additional information about the error. The first element is the error class and determines the format of the rest of the list. This may take one of the following values:

TWAPI_WIN32

This error class corresponds to Windows error codes. The second element of the list is the integer Windows error code. The map_windows_error can be used to retrieve the correesponding text description. The third element is the corresponding localized text string describing the error. The fourth element is optional and its format is dependent on the specific error code.

The command win32_error can be used to generate an error in this format.

TWAPI

This error class is used for non-Windows related errors, for example invalid options to commands. The format is similar to that of TWAPI_WIN32 except that the error code is an internal TWAPI error code and the text is not localized.

For handling errors, the command trap provides exception handling with finalization features.

For troubleshooting and debug purposes, TWAPI provides the debuglog command which writes to an internal log. This command is normally a no-op and must be enabled with debuglog_enable for logging to have effect. It can be disabled again with debuglog_disable. The current contents of the debug log can be retrieved with debuglog_get.

Record arrays

Some TWAPI commands return data in a form that is similar to a table with named columns. For example, the event tracing module returns a list of event trace records. The form of the returned data is called a record array and is intended to be opaque and manipulated through the recordarray command. The command takes various forms shown in the table below and is flexible enough to retrieve data as dictionaries or lists as well as support operations like filtering and column slicing.

recordarray cell	Returns the value in a specified field in a specific record.
recordarray column	Returns values for a specified field for all records.
recordarray concat	Returns a record array containing records from one or more record arrays.
recordarray fields	Returns field names for the records in the record array.
recordarray get	Returns another record array containing a subset of the records and fields.
recordarray getdict	Returns a dictionary containing a subset of the records and fields.
recordarray getlist	Returns a list containing a subset of the records and fields.
recordarray index	Returns the record at a specified position in list or dictionary format.
recordarray iterate	Iterates over the records in the record array.
recordarray range	Returns a new record array containing records in the specified range.
recordarray rename	Renames one or more fields in the record array.
recordarray size	Returns the number of records in the record array.

Many record array commands accept some of the following common options:

-filter FILTERLIST

Specifies a list of matching filters. Only the records matching all the filter expressions in FILTERLIST are returned. FILTERLIST is a list of filter expressions. Each filter expression is a 3 or 4 element list consisting of a record field name, a matching operator, the value to match and optionally a fourth element -nocase which may be used with any of the string or pattern matching operators to indicate that character case should be ignored. The matching operator must be one of the following:

eq	String equality
ne	Strings inequality
~	Pattern matched (as in string match)
!~	Pattern not matched (as in string match)
==	Integer equality
!=	Integer inequality
<	Integer less than
<=	Integer less than or equal
>	Integer greater than
>	Integer greater than or equal

-format FORMAT

Specifies the format of each record element returned. FORMAT may be one of the following values:

list	each record is returned as a list (default).
dict	each record is returned as a dictionary whose keys are the fields names of the record array.
flat	Field values of returned as a flat list. Only valid for the recordarray getlist command.

-slice FIELDLIST

Specifies that the return value should only include the fields specified in FIELDLIST and in that order.

Here is an example that returns a plain list of PID of processes that have a privileged port (any port under 1024) open. get_tcp_connections returns a record array.

recordarray getlist [get_tcp_connections] -filter {{-localport < 1024}} -slice -pid -format flat

Another example, which shows all services that are marked as interacting with the desktop, returned as a dictionary keyed by the service name.

recordarray getdict [get_multiple_service_status] -filter {{interactive == 1}} -key name

Utility commands

parseargs

parses an argument list based on specified options. format_message formats a operating system or application message.

Commands large_system_time_to_secs_since_1970, large_system_time_to_timelist, secs_since_1970_to_large_system_time and timelist_to_large_system_time convert between various time formats.

A Universally Unique Identifier (UUID) can be generated by the command new_uuid. A nil UUID can be generated by nil_uuid. Similarly, a Globally Unique Identifier (GUID) which has a slightly different format can be generated by new_guid. In most commands, UUID's and GUID's are interchangeable. The command canonicalize_guid will convert a GUID into a canonical format that can be used for comparison.

The commands load_library and free_library can be used to load and free DLL's.

The commands tclcast and tcltype are useful for manipulating internal Tcl value types. This is sometimes useful and required when dealing with external APIs and data formats like COM. hex formats a binary string as a hexadecimal string. hex32 and hex64 format numbers as fixed length hexadecimal strings. lambda returns an anonymous proc definition based on the Tcl apply command.

Commands

cancel_wait_on_handle HANDLE

Cancels any previously registered asynchronous wait on a handle that was registered using wait_on_handle.

canonicalize_guid GUID

Returns the canonicalized form of GUID with hexadecimal letters converted to upper case and braces added.

close_handle HANDLE

Closes the operating system handle HANDLE. If the handle has been registered for asynchronous notifications via wait_on_handle, the notifications are canceled (via cancel_wait_on_handle).

conceal PLAINTEXT

Returns an encrypted binary string corresponding to PLAINTEXT. reveal can be used to decrypt the result within the same process. The returned value should never be used for comparisons as the same PLAINTEXT may result in different encrypted values on each call.

confirm_credentials TARGET VALIDITY

Deprecated. Use cred_confirm.

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.

cred_confirm TARGET VALIDITY

Informs the Windows Credentials Manager that the previously obtained credentials for the specified TARGET are valid or not. This command should be called whenever the user is prompted for credentials via cred_prompt_console or cred_prompt_gui with the -persist option specified as true. After the returned credentials are validated, the application should call cred_confirm with VALIDITY set to true. Conversely, if the credentials are invalid, cred_confirm should be called with VALIDITY set to false.

cred_prompt_console TARGET ?options?

Prompts the user for credentials via the console. TARGET is name of the target for the credentials, for example the server name. This is used as the key when retrieving credentials. The command returns a list of three elements, the user name, the password, and a boolean indicating whether the user selected for the credentials to be saved or not.

The following options may be specified:

-forceui BOOLEAN	If specified as true, the user is prompted even if the credentials manager already has the requested credentials. Default is false. This option may only be used for generic credentials.
-persist BOOLEAN	If true, credentials are to be persisted by the credentials manager if so desired by the user. Default is false. If specified as true, cred_confirm must be called with the result of the validation.
-showsaveoption BOOLEAN	Specifies whether the user should be given the option to save the credentials. Defaults to false (meaning user is not shown the choice). Note if specified as true but the options -persist is not specified or is false, it is up to the caller to save credentials appropriately by some application-specific means.
-type TYPE	Specifies the type of credentials. TYPE must be generic (default), domain or runas. If domain, if the entered user name is not fully qualified, it is returned qualified with TARGET as the domain. For generic, user names are returned as entered. If runas, the -username option must be specified and if unqualified, is qualified with the name of the system in the returned list.
-username USERNAME	The user name to display. If specified and not empty, the user is only prompted for the password.

By default, credentials are not saved for future use. If they need to be saved, the application has the choice of using the Windows credential manager or saving them in some application-specific (and secure!) manner. In the former case, the -persist option must be specified as true and when the call returns, the credentials must be verified and the validity of the credentials must be communicated to the Windows credentials manager by calling cred_confirm iff the third element of the returned list (indicating the save setting) is true. In the latter case where the Windows credential manager is not being used, the manner of securely saving the credentials is entirely up to the application. In both cases, the user may be given the choice of saving the credentials or not by specifying the -showsaveoption as true. The command cred_prompt_gui provides a GUI version of this command.

cred_prompt_gui TARGET ?options?

Shows a dialog prompting the user for credentials. If the user cancels the dialog, the command returns an empty list. Otherwise, it returns a list of three elements, the user name, the password, and a boolean indicating whether the user selected for the credentials to be saved or not.

The following options may be specified:

-bitmap HANDLE	Specifies a hande to a bitmap to be displayed in the dialog. The bitmap dimensions should be 320x60 pixels.
-caption CAPTION	Specifies a caption to be displayed in the dialog.
-completeusername BOOLEAN	If specified as a true value, the user name component of the return value is of the form TARGET\USERNAME.
-excludecertificates BOOLEAN	Does not show certificate-based credentials in the combo box.
-filllocaladmins BOOLEAN	Fill the user name combobox with local administrator accounts only.
-forceui BOOLEAN	If specified as true, the user is prompted even if the credentials manager already has the requested credentials. Default is false. This option may only be used for generic credentials.
-keepusername BOOLEAN	Prefills the user name and does not permit user to change it.
-message MESSAGE	Specifies a message to be displayed in the dialog.
-parent HWIN	Specifies the handle of a windows to be used as the parent for the dialog.
-password PASSWORD	The password to be used as default. PASSWORD must be in the form accepted by reveal which is also the form returned by this command. Plain text passwords are not supported by this command.
-persist BOOLEAN	If true, credentials are to be persisted by the credentials manager if so desired by the user. Default is false. If specified as true, cred_confirm must be called with the result of the validation.
-requirecertificate BOOLEAN	Only show certificate-based credentials in the combo box.
-requiresmartcard BOOLEAN	Only show smartcard-based credentials in the combo box.
-showsaveoption BOOLEAN	Specifies whether the user should be given the option to save the credentials. Defaults to false (meaning user is not shown the choice). Note if specified as true but the options -persist is not specified or is false, it is up to the caller to save credentials appropriately by some application-specific means.
-type TYPE	Specifies the type of credentials. TYPE must be generic (default), domain or runas. If domain, if the entered user name is not fully qualified, it is returned qualified with TARGET as the domain. If runas, then an unqualified user name is qualified with the name of the system. For generic, user names are returned as entered.
-username USERNAME	The user name to display as the default. Defaults to the empty string.
-validateusername BOOLEAN	If true, forces the user to choose a user name of the form [email protected] or netbiosname\username.

debuglog ?MESSAGE?

Writes each specified argument as a message to an internal log. There is an internal limit on the number of messages stored. Older messages are discarded once the log reaches this limit. The command must be enabled with debuglog_enable for logging to have effect.

debuglog_clear

Clears the internal debug log.

debuglog_disable

Disables the debuglog command.

debuglog_enable

Enables the debuglog command.

debuglog_get

Returns the current content of the internal debug log.

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.

export_public_commands

Export public commands in the twapi:: namespace. The commands in the twapi:: namespace are not exported by default.

format_message ?options?

Formats and returns a message string based on a format string. The format string may be directly supplied, obtained from a loaded library or module, or the system message tables. The format string may contain format insert specifiers of the form %N where N is a number between 1 and 99. The format specifier is replaced by the corresponding positional parameter. The format specifier %0 is treated specially as indicating that a newline character is not to be appended to the result. See FormatMessage in the Windows SDK for more details regarding this command including format specifiers. The command takes the following options:

-module MODULE	Specifies that the format string is to be loaded from the module identified by MODULE. MODULE may either be a handle returned from a command such as load_library or the path to a DLL. If this option is specified, options -messageid and -langid must also be specified. This option cannot be used with the -fmtstring option.
-fmtstring FORMATSTRING	Specifies that FORMATSTRING should be used as the format string for the message. Cannot be used with the -module option.
-messageid MESSAGEID	Specifies the message identifier of the format string. This option cannot be used with the -fmtstring option.
-langid LANGID	Specifies the language identifier to be used in constructing the message. This option cannot be used with the -fmtstring option.
-includesystem	Specifies that the system message tables should also be searched in addition to the message tables in the module specified by -module. This option cannot be used with the -fmtstring option.
-params PARAMLIST	Specifies a list of positional parameters that are to be used to replace the %N format insert sequences in the format string. If the number of parameters does not match the number of escape sequences, a Tcl exception may be generated.
-ignoreinserts	If specified, the %N format insert sequences are not replaced in the returned string.
-width MAXLINEWIDTH	If MAXLINEWIDTH is 0 (default), the returned string contains the same line breaks as in the original format string. The -width option may be used to control the maximum line width in the created message. If MAXLINEWIDTH is between 1 and 254, the command will insert line end characters at appropriate points in the message. In this case, line end characters in the original message are ignored. However, hard coded line end characters, specified as %n in the format string are kept. A MAXLINEWIDTH value of -1 also ignores line end characters while keeping the hard coded %n line end specifiers, but does not insert any line end characters to limit the line length and to terminate the message.

Warning: This command requires all insert placeholders to be strings. Decimal format specifiers such as %|u! will not result in the correct decimal value being inserted.

free_library HMODULE

Frees a loaded module. HMODULE must be a handle previously returned through load_library, get_module_handle or get_module_handle_from_address.

get_build_config ?CONFIGKEY?

If no arguments are specified, returns an dictionary that contains the TWAPI build configuration. If CONFIGKEY is specified, only returns the value for that configuration key. The build configuration keys are:

comobj_ootype	The underlying object system on which the TWAPI COM support is built.
compiler	The compiler used for the build (e.g. vc++)
compiler_version	The version of the build compiler.
opts	List of additional options used in the build.
platform	One of x86 or x64.
sdk_version	Version of the Windows SDK used for the build.
tcl_header_version	Version of the Tcl headers used for the build.
tea	Boolean indicating whether the build used Tcl Extension Architecture or native builds.

get_handle_inheritance HANDLE

Indicates whether the specified handle is marked as inheritable by child processes.

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.)

get_version ?-patchlevel?

Without any arguments, the command returns the major/minor TWAPI version number in the form MAJOR.MINOR. If the option -patchlevel is specified, the returned string includes patchlevel and release information similar to the Tcl info patchlevel command, for example, 1.0.2 for final release of version 1.0 patch 2, 1.0b3 for the third beta release of version 1.0 and 1.0a3 for the third alpha release of version 1.0.

hex BIN

Returns the binary string BIN as a hexadecimal string.

hex32 INT32VAL

Returns INT32VAL as a fixed width hexadecimal string.

hex64 INT64VAL

Returns INT64VAL as a fixed width hexadecimal string.

import_commands

Imports all public commands in the twapi:: namespace into the caller's namespace.

is_valid_sid_syntax sid

Returns true or false depending on whether sid is a valid SID or not. Note this only checks the syntax of the SID, not whether it corresponds to a real account.

lambda ARGLIST BODY ?NAMESPACE?

Simple wrapper that returns an anonymous proc definition based on the Tcl apply command.

large_system_time_to_secs_since_1970 SYSTEMTIMEVALUE ?BOOLEAN?

Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to seconds since the epoch Jan 1, 1970. If BOOLEAN is false (default), an integral number of seconds is returned. Otherwise, the fractional part is also returned.

large_system_time_to_timelist SYSTEMTIMEVALUE

Some Windows functions return time as the number of 100 nanosecond units since Jan 1, 1601. The command converts such time values to a list of 8 elements representing the year, month, day, hour, minutes, seconds, milliseconds and day of week.

load_library FILEPATH ?options?

Loads a DLL and returns a handle to it. The handle must later be released by calling free_library, not close_handle. The following options may be specified:

-dontresolverefs	Normally, if the module being loaded is a DLL, the system will load any other modules referenced by it and also call its DllMain function to initialize it. If this option is specified, neither of these actions will be done.
-datafile	If specified, the module is loaded as a data file as opposed to an executable module. This is useful when the file is being loaded only to extract resources or format messages.
-alteredpath	Uses an alternative search strategy to find modules referenced by this module. See the Windows SDK for more details.

See LoadLibraryEx in the Windows SDK for more details regarding this command.

lookup_account_name name ?options?

name specifies the name of the account and may be fully qualified in the form domain\name.

If no options are specified, this command returns the SID for the account. If one or more options are specified, returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all	Returns all values.
-sid	Returns the SID for the account.
-domain	Returns the domain in which the account was found.
-system	Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type	Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), logonid, wellknowngroup, deletedaccount, invalid, unknown, computer or label. The logonid type is returned for SID's that identify a logon session.

lookup_account_sid sid ?options?

Argument sid specifies the SID of the account. If no options are specified, this command returns the name for the account. If one or more options are specified, the command returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all	Returns all values.
-name	Returns the name for the account.
-domain	Returns the domain in which the account was found.
-system	Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type	Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), wellknowngroup, deletedaccount, invalid, unknown, logonsession or computer.

make_logon_identity USERNAME PASSWORD DOMAIN

Returns a descriptor containing credentials to be used for authenticating in a form required by several other commands. PASSWORD may be either plaintext or in encrypted form as returned by by the credentials_prompt, credentials_dialog or conceal commands.

map_account_to_name ACCOUNT ?-system SYSTEMNAME?

Returns the name for an account. If ACCOUNT is a valid account name, it is returned as is. Otherwise, it is assumed to be a SID and the corresponding account name is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

map_account_to_sid ACCOUNT ?-system SYSTEMNAME?

Returns the SID corresponding to an account. If ACCOUNT is a SID, it is returned as is. Otherwise, it is assumed to be an account name and the corresponding SID is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

map_windows_error ERRORCODE

Returns the text string corresponding to a Windows error code.

new_uuid ?-localok?

Returns a UUID. If the system does not contain a network card, the operating system may return an error as it cannot guarantee uniqueness across systems. Specifying the -localok option causes this to be ignored and a identifier value to be returned anyways.

nil_uuid

Returns a nil UUID.

new_guid

Returns a GUID.

parseargs ARGLISTVAR OPTLIST ?-ignoreunknown? ?-nulldefault? ?-hyphenated? ?-maxleftover MAXLEFTOVER? ?-setvars?

Parses the options specified in a list of arguments. ARGLISTVAR is the name of a variable in the caller's scope that contains a list of arguments. Option names are case-sensitive and begin with a - character. Option processing is terminated when an argument does not begin with a leading - or is one of the special - or --.

OPTLIST specifies the valid options allowed and is list of option specifiers. Each option specifier is a list of up to 3 elements and takes the following form:

OPTNAME?.OPTTYPE? ?DEFAULTVALUE ?VALUEOPTS??

OPTNAME is the name of the option (without a leading -) and is required. OPTTYPE should be separated from the name with a . and specifies the type of the option. It must have one of the following values: arg, bool, int, sym or switch. In the first three cases, the argument following the option is taken as the value of the option and must be of an appropriate type: an arbitrary string, a boolean value (0, 1, off, on, false, true) or an integer respectively. If OPTTYPE is sym, the the option value is expected to be an integer or a a key into the dictionary VALUEOPTS and the returned value of the option is the mapped value from this dictionary. If the option type is switch, or is not specified at all, then the option is not associated with any value and is treated as a binary switch.

DEFAULTVALUE, specifies a default value to be assumed for the option if it is not present in ARGLISTVAR. This is ignored for options of type switch.

If VALUEOPTS is specified for option types arg or int, it is treated as a list of allowed values for the option. If an option's value is not in the list, the command will return an error. For option type sym, VALUEOPTS is a dictionary as described previously. If the option type is bool or switch, VALUEOPTS is the treated as the value to return when the value of the option is boolean true (by default 1 is returned). This is commonly used in TWAPI to return a integer bit mask for the true value of an option.

If the option -setvars is not specified, the command returns a list of the form OPTION VALUE OPTION VALUE.... If the -hyphenated option is not specified, the OPTION fields in the returned value contain the option name without a leading - character. If the -hyphenated option is specified, OPTION includes the leading - character. This is useful when options are passed through to other commands after partial processing.

If the option -setvars is specified, the command sets variables with the names of the specified options to the corresponding values. The command returns an empty string in this case.

If the -nulldefault option is not present, only options that are present in ARGLISTVAR, or have a default value specified, or are of type switch are included in the returned result. If the -nulldefault option is present, then the returned list also includes values for options that are not present - 0 for options of type int and bool, and an empty string for arguments of type arg.

As a side effect, the variable ARGLISTVAR is modified to remove the parsed options and associated values. If the -maxleftover option is specified, the command will raise a Tcl error if the number of arguments left over after parsing the options is more than MAXLEFTOVER.

The command will normally generate a Tcl error if the arguments include an unknown option (an argument that begins with a - character and is not in OPTLIST). If the -ignoreunknown option is specified to the command, unknown options in ARGLISTVAR are ignored instead of an error being generated and are not removed from ARGLISTVAR.

random_bytes NUMBER

Returns the specified number of random bytes. This is a call into the RtlGenRandom Win32 API.

read_credentials ?options?

Deprecated. Use credentials_prompt.

recordarray cell RECORDARRAY INDEX FIELD

Returns the value of the field FIELD of the record at index INDEX in the specified record array.

recordarray column RECORDARRAY FIELD ?-filter FILTERLIST?

Returns a list of values of the field FIELD in all records. If option -filter is specified only the values from the matching records are included in the returned list. See Record arrays for the format of FILTERLIST.

recordarray concat ?RECORDARRAY RECORDARRAY...?

Returns a record array containing records from one or more record arrays. The fields in each record array must be the same.

recordarray fields RECORDARRAY

Returns field names for the records in the record array.

recordarray get RECORDARRAY ?options?

Returns a record array containing a subset of the records and fields from RECORDARRAY. options may be include -filter and -slice from amongst the standard options described in Record arrays. Other options are silently ignored.

recordarray getdict RECORDARRAY ?options?

Returns a dictionary containing a subset of the records and fields from RECORDARRAY. The keys of the dictionary are specified through option -key the value for which must be the name of a field in the dictionary. If the option is not specified, the first field in the record definition for the record array is used as the key. options may include any of the standard options described in Record arrays.

recordarray getlist RECORDARRAY ?options?

Returns a list containing a subset of the records and fields from RECORDARRAY. The form and content of the elements of the returned list depend on the options as described in Record arrays.

recordarray index RECORDARRAY INDEX ?options?

Returns the record at a specified position in the record array. The options -format and -slice as described in Record arrays control the fields returned and their format.

recordarray iterate ARRAYVAR RECORDARRAY ?options? BODY

Iterates over all records in a recordarray. For each record, sets the array variable ARRAYVAR to the current record and evaluates BODY in the caller's context. The keys of ARRAYVAR are the field names of the record array.

options may include the -slice and -filter options as described in Record arrays.

recordarray range RECORDARRAY LOW HIGH

Returns a new record array containing the records in the specified index range.

recordarray rename RECORDARRAY FIELDRENAMEMAP

Returns a new record array with the same records as RECORDARRY but with the fields renamed as per the contents of the dictionary FIELDRENAMEMAP which should map the old field name to a new one. Names of any fields not in FIELDRENAMEMAP are preserved.

recordarray size RECORDARRAY

Returns the number of records in the record array.

rethrow

Raises a Tcl error where the error options, including values of errorCode and errorStack, are the same as when an exception was raised inside a trap command. This command can only be used inside a onerror clause of a trap and is useful to regenerate the original error when the error handler cannot handle the exception.

reveal ENCRYPTED

Decrypts a binary string that was encrypted by conceal within the same process.

safearray TYPE LISTVALUE

Returns LISTVALUE in a form that is interpreted by COM related commands as a single-dimensioned safearray of type TYPE. TYPE must be one of the COM types bool, int or i4, double or r8, bstr, or variant.

secs_since_1970_to_large_system_time SECONDS

This command converts SECONDS which is the number of seconds since the epoch Jan 1, 1970 to the number of 100 nanoseconds since Jan 1, 1601.

set_handle_inheritance HANDLE BOOLEAN

If BOOLEAN is true, HANDLE is marked as being inheritable by child processes. If false, the handle will not be inherited.

swap2 BYTES2

Byte swaps a 16 bit value.

swap4 BYTES4

Byte swaps a 32 bit value.

swap8 BYTES8

Byte swaps a 64 bit value.

timelist_to_large_system_time TIMELIST

Converts TIMELIST to the number of 100 nanoseconds since Jan 1, 1601. If TIMELIST is an empty list, it defaults to the current date and time. Otherwise it is a list of 3-7 elements that specify the year, month, day, hours, minutes, seconds and milliseconds. The last four are optional and default to 0. TIMELIST must be a list of 7 elements representing the year, month, day, hour, minutes, seconds and milliseconds.

tclcast TYPE VALUE

Returns VALUE whose internal Tcl type is set to TYPE. See Controlling Parameter Types for a use case. TYPE must be one of empty, null, bstr, (corresponding to COM VARIANT types VT_EMPTY, VT_NULL and VT_BSTR), or one of the Tcl internal types int, boolean, double, string, list, or dict.

tcltype VALUE

Returns the internal Tcl type for a value.

trap SCRIPT ?onerror ERRORPATTERN ERRORSCRIPT?... ?finally FINALSCRIPT?

The command executes SCRIPT in the caller's context. If the script completes without generating any Tcl exceptions, the command executes the script FINALSCRIPT if specified. The result of the command is the result of SCRIPT.

If SCRIPT generates any errors, the command matches the Tcl global ::errorCode variable against each specified ERRORPATTERN in turn. When the first match is found, the corresponding ERRORSCRIPT is executed. Then FINALSCRIPT is executed if specified. The return value from the command is the result of the executed ERRORSCRIPT script.

If the none of the ERRORPATTERN arguments match when an error occurs in SCRIPT, the command executes FINALSCRIPT if specified, and then regenerates the original error.

Each ERRORPATTERN should be a list and is matched against the first (facility) and second (code) elements of ::errorCode. If ERRORPATTERN is empty, it matches any value of ::errorCode. If ERRORPATTERN contains only one element, it is matched against the first element of ::errorCode with the second field of ::errorCode not used for matching. When matching against the second element of ::errorCode, first a exact string match is tried and if that fails, an integer match is tried if both operands being compared are valid integers.

Within an onerror clause, the command rethrow may be used to raise the error that was caught by the clause. This is useful when an error handler finds it cannot handle the case and wants to raise the original error. Similarly, the trapresult and trapoptions commands can be used in a onerror clause to retrieve the error message and error options dictionary captured by the onerror clause.

wait_on_handle HANDLE ?options?

The command waits on the specified HANDLE until it is either signalled or a timeout expires. The command can also be used for non-blocking asynchronous notification. HANDLE may be any operating system handle for which Windows supports the WaitForSingleObject API.

WARNING: HANDLE must NOT be closed while it is being waited on. Windows behaviour is undefined in this case and may result in a program crash.

The command may return one of the following values if the -async option is not specified: signalled, timeout, abandoned. If -async is specified, the command returns an empty string and the result is passed to the callback script instead.

The following options may be specified:

-wait MILLISECS	Specifies the number of number of milliseconds to wait for the handle to be signalled. The default is -1 which indicates no timeout.
-async SCRIPT	If specified, the command returns immediately. SCRIPT is then invoked when the handle is signalled or the timeout specified through -wait has elapsed. Note that if a timeout is specified with the -wait option, the timeout does not cancel the wait and the script is invoked repeatedly every MILLISECONDS if the handle is not signalled. Two additional arguments are appended to SCRIPT - HANDLE and the return value (signalled etc.). Once a handle is registered for asynchronous notification, it must not be used for synchronous notification unless the asynchronous notification is first canceled through the cancel_wait_on_handle command. If the handle was already registered for asynchronous notification, the previously registered script is replaced with SCRIPT.
-executeonce BOOLEAN	If this option is specified as true, the SCRIPT is executed only once, even if the object HANDLE stays in a signalled state. Default is false. This option is ignored if -async is not specified.

win32_error WINERROR ?MESSAGE?

Generates a Tcl exception corresponding to the Windows error code WINERROR. MESSAGE may be specified as the error message in which case the system error message for WINERROR is appended to it.

Base module

SYNOPSIS

DESCRIPTION

Package information