Processes, threads and DLLs

Commands related to processes, threads and dynamic link libraries

SYNOPSIS

package require twapi_process
create_process PROGRAM ?options?
end_process PID ?options?
expand_environment_strings STRING
expand_environment_vars STRING
expand_system_environment_vars STRING
expand_user_environment_vars TOKEN STRING
get_current_process_id
get_current_thread_id
get_device_drivers ?options?
get_module_handle ?-path PATH? ?-pin BOOLEAN?
get_module_handle_from_address ADDRESS ?-pin BOOLEAN?
get_pid_from_handle HPROCESS
get_priority_class PID
get_process_commandline PID ?options?
get_process_elevation ?-pid PID | -hprocess HPROCESS?
get_process_exit_code HPROCESS
get_process_handle PID ?-access ACCESSRIGHTS? ?-inherit INHERITMODE?
get_process_ids ?options?
get_process_info PID ?options?
get_process_integrity ?-pid PID | -hprocess HPROCESS? ?-raw | -label?
get_process_modules PID ?options?
get_process_name PID
get_process_parent PID
get_process_path PID
get_process_thread_ids PID
get_system_environment_vars ?-normalize BOOLEAN?
get_thread_handle TID ACCESSMODE ?INHERITMODE?
get_thread_info TID ?options?
get_thread_relative_priority TID
get_thread_parent_process_id TID
get_user_environment_vars TOKEN ?-normalize BOOLEAN? ?-inherit BOOLEAN?
is_idle_pid PID
is_system_pid PID
load_user_profile TOKEN ?options?
process_exists PID ?options?
process_in_administrators
process_waiting_for_input PID ?-wait MILLISECONDS?
resume_thread TID
set_priority_class PID PRIORITYCLASS
set_process_integrity INTEGRITY ?-pid PID | -hprocess HPROCESS?
set_process_virtualization ENABLED ?-pid PID | -hprocess HPROCESS?
set_thread_relative_priority TID PRIORITY
SetThreadExecutionState EXECUTIONSTATE
suspend_thread TID
unload_user_profile TOKEN HANDLE
virtualized_process ?-pid PID | -hprocess PROCESSHANDLE?
wow64_process ?-pid PID | -hprocess PROCESSHANDLE?

DESCRIPTION

This module provides procedures related to process, thread and shared library management.

Overview

The commands get_process_ids and get_current_process_id retrieve process id (PID) information. get_process_parent returns the PID for the parent process. The commands is_system_pid and is_idle_pid determine if the given PID is that of the system or idle process.

The command get_current_thread_id retrieves the current thread id (TID). get_thread_parent_process_id retrieves the PID of the process containing the specified thread. get_process_thread_ids retrieves the TID's of all threads in the specified process.

Process and thread handles with the appropriate access rights may retrieved through the get_process_handle and get_thread_handle commands respectively. A process handle may be mapped back to the corresponding PID through get_pid_from_handle.

get_process_name and get_process_path get the name and path respectively for a process. The command get_process_info retrieves detailed information about internal process data. Similarly, get_thread_info retrieves detailed information about a thread.

get_process_commandline retrieves the command line with which a process was invoked.

process_exists checks for the existence of a process. The command process_waiting_for_input can be used to check if a process is waiting for input, and more specifically if it has finished initialization.

get_process_modules retrieves information pertaining to the modules and DLL's loaded into a process. The commands get_module_handle and get_module_handle_from_address retrieve handles to individual modules in the current process.

The commands create_process and end_process allow creation and termination of a process. The exit code from a process can be retrieved with the get_process_exit_code command.

The commands suspend_thread and resume_thread allow threads to be suspended and resumed.

The commands get_priority_class, set_priority_class, get_thread_relative_priority and set_thread_relative_priority deal with retrieving and setting process and thread scheduling priorities.

get_device_drivers retrieves information about the device drivers loaded on the system.

Commands is_wow64_process deal with features related to 64-bit Windows.

Command process_in_administrators can be used to check if the current process is in the administrators group.

Commands get_process_elevation, get_process_integrity and, set_process_integrity and, virtualized_process, set_process_virtualization deal with Windows UAC related features.

Environment variables

The following commands deal with environment variables.

expand_environment_vars Replaces environment variables in a string with their values in the current process.
expand_system_environment_vars Replaces system environment variables in a string with their values.
expand_user_environment_vars Replaces environment variables in a string with the environment values defined for a specific user.
get_system_environment_vars Returns a dictionary of system environment variables and their values.
get_user_environment_vars Returns a dictionary of environment variables and their values for a specific user.

User profiles

The commands load_user_profile and unload_user_profile deal with loading of user profiles.

Commands

create_process PROGRAM ?options?
Creates a new child process. PROGRAM specifies the program to be run and must either include the full path to the program or the program must be in the current working directory. The function does not search the PATH environment variable to locate the program. PROGRAM may be specified as an empty string if the -cmdline option is specified and includes the path to the program as the first argument.

The command returns a list of two elements - the process id and the thread id of the child process. If the -returnhandles option is specified, two additional elements are returned - handles to the child process and thread. Both these handles must be closed when no longer required by calling close_handles.

The following arguments control various characteristics of the child process. For all options that take a boolean argument, the default is 0 (false) unless stated otherwise.
-background COLORLIST Specifies the background color if the child process receives a new console. COLORLIST is a list of one or more of the following values: blue, red, green, bright, white and black. The specified colors are combined to form the foreground color. The default is black.
-cmdline CMDLINE Specifies the command line to be passed to the created process. This generally includes the program being executed as the first token in CMDLINE. Caller should ensure that CMDLINE is quoted appropriately. The -cmdline option must be specified if the PROGRAM parameter is empty.
-childprocesssecd SECURITY_DESCRIPTOR Specifies a security descriptor for the child process. If unspecified, the default security descriptor is used.
-childthreadsecd SECURITY_DESCRIPTOR Specifies a security descriptor for the child thread. If unspecified, the default security descriptor is used.
-createsuspended BOOLEAN If BOOLEAN is true, the process and thread are created suspended. The process will not run until the thread is resumed with a call to resume_thread.
-debugchild BOOLEAN If BOOLEAN is true, indicates that the calling thread will be debugging the child process being created. The thread is notified of debug events in the child process. There is currently no way to receive these events.
-dontdebugchild BOOLEAN If the calling process is itself being debugged, then any debug events from the child process are sent to the debugger if BOOLEAN is false. Otherwise, the child process has no interaction with the debugger.
-desktop DESKTOPNAME Specifies the desktop, optionally along with the window station, for the new process. By default, this is the same as the current process. If DESKTOPNAME is the empty string, the system determines if a new desktop and window station need to be created.
-detached BOOLEAN This option only affects console processes. If BOOLEAN is 0, the child process inherits the current process' console. If BOOLEAN is 1, the console is not inherited.
-env LIST Specifies the environment variables inherited by the child process. LIST is a flat list of the form returned by array get consisting of ENVVARNAME VALUE pairs. By default, the child process inherits the same environment variables as the current process.
-feedbackcursoron BOOLEAN If true, specifies that the feedback cursor (normally a pointer with an hourglass) is shown while the new process starts up.
-feedbackcursoroff BOOLEAN If true, specifies that the feedback cursor is not shown while the new process starts up.
-foreground COLORLIST Specifies the foreground color if the child process receives a new console. COLORLIST is a list of one or more of the following values: blue, red, green, bright, white and black. The specified colors are combined to form the foreground color. The default is white.
-fullscreen BOOLEAN If true, the child process is run in full screen mode if it is a console process.
-inheritablechildprocess BOOLEAN If true, the handle to the child process is inheritable by other child processes spawned off later.
-inheritablechildthread BOOLEAN If true, the handle to the thread in the child process is inheritable by other child processes spawned off later.
-inheriterrormode BOOLEAN If true (default), the child process inherits the error mode setting of the current process.
-inherithandles BOOLEAN If true, the child process will inherit all inheritable handles of the current process.
-newconsole BOOLEAN If true, a new console is created for the child process if it is a console mode program. By default, the child process inherites the console of the current process if that latter is also a console mode program. This option cannot be used with the -detached option.
-newprocessgroup BOOLEAN If true, the created process is made the root of a new process group identified by the PID of the new process. The default value is false and the new process belongs to the same process group as the calling process.
-priority PRIORITY Specifies the priority of the child process. This should have one of the values normal, abovenormal, belownormal, high, realtime, or idle.
-returnhandles BOOLEAN Normally the create_process command returns only the ids of the created process and thread. If this option is specified as true, the command appends handles of the child process and thread to the return value. These must later be closed by calling the close_handles command.
-screenbuffersize XY For console processes, this controls the initial width and height of the screen buffer in characters. XY can be specified as either a list of two integers or as a X,Y string.
-separatevdm BOOLEAN If true, child processes that are 16-bit executables are started in a separate virtual machine. By default, the system will follow the setting specified in the registry.
-sharedvdm BOOLEAN If true, child processes that are 16-bit executables are started in a common virtual machine. By default, the system will follow the setting specified in the registry.
-showwindow WINDOWMODE Specifies the mode in which the first window of the child process is displayed. WINDOWMODE must be one of normal (default), minimized, maximized or hidden.
-startdir PATH Specifies the initial starting directory of the child process. By default the child process starts in the calling thread's current directory.
-stdhandles HANDLELIST Specifies the standard input and output handles for the child process. HANDLELIST is a list of three elements corresponding to the handles to be used for standard input, standard output and standard error respectively. The handle values passed must be Windows handles and must be inheritable. Also, the -inherithandles option must be true if -stdhandles is specified. Note that if these handles correspond to files, the file position pointer is shared with the child process.

This option cannot be used together with the -stdchannels option.
-stdchannels CHANNELS Specifies the standard input and output handles for the child process. CHANNELS is a list of three elements corresponding to the Tcl channels to be used for standard input, standard output and standard error respectively. Note that if these channels correspond to files, the file position pointer is shared with the child process.

This option cannot be used together with the -stdhandles option. Also, the -inherithandles option must be true if -stdchannels is specified.
-title TITLE Specifies the text to diaplay in the title bar if the child process is a console program and receives a new console. By default, the name of the executable is displayed.
-windowpos XY Specifies the initial position in pixels of the top left corner of the main window of the child process if the child creates the window using defaults. XY can be specified as either a list of two integers or as a X,Y string.
-token TOKEN Specifies that the created process should run under the account identity and logon session of the specified access token instead of that of the parent process.
-windowsize XY Specifies the initial size in pixels of the main window of the child process if the child creates the window using defaults. XY can be specified as either a list of two integers or as a X,Y string.
For further details, see the documentation of CreateProcess in the Windows SDK documentation.
end_process PID ?options?
Terminates the process with id PID. This function will first try to gracefully end the process by sending all its toplevel windows a WM_CLOSE command. If the process does not have any toplevels or if it does not end by this means and the -force option is specified, it is forcibly terminated.

The function returns 1 if the process ended and 0 otherwise. Note that if -wait has not been specified, or is too short, the function may return a value of 0 in the case where the process is in the process of terminating but has not fully exited by the time the command returns.

The following options may be specified with this command:
-force If this option is specified, the process will be forcibly terminated if it does not terminate in response to WM_CLOSE messages.
-wait MS Normally, the function will return without actually waiting for the process to end. If this option is specified, the function returns after waiting for MS milliseconds for the process to end.
-exitcode EXITCODE Specifies the exit code that should be returned by the terminating process. This is 1 by default. Depending on the application being terminated, this may not be the actual exit code returned on application exit. Caller should not rely on this.
expand_environment_strings STRING
Deprecated. See expand_environment_strings.
expand_environment_vars STRING
Returns the string formed by replacing all environment variable references in STRING with their values from the current process environment. Environment variable references are in the form %ENVIRONMENTVAR%. References to undefined environment variables are not replaced.
expand_system_environment_vars STRING
Returns the string formed by replacing all environment variable references in STRING with their value defined in the system environment variables (not from the current process environment). Environment variable references are in the form %ENVIRONMENTVAR%. References to undefined environment variables are not replaced.
expand_user_environment_vars TOKEN STRING
Returns the string formed by replacing all environment variable references in STRING with their value defined for a specific user (not from the current process environment even if the process is running under that user account). Environment variable references are in the form %ENVIRONMENTVAR%. References to undefined environment variables are not replaced. TOKEN must be a security token for the user account whose environment is to be retrieved and must have token_impersonate, token_query and token_duplicate access.
get_current_process_id
Returns the PID of the current process.
get_current_thread_id
Returns the TID of the current thread.
get_device_drivers ?options?
Returns a record array describing the device drivers loaded in the system. The fields of the record array are based on which of the following options are specified:
-all Returns all device driver attributes below.
-base Returns the base address in memory where the driver is loaded
-path Returns the path to the file from which the driver was loaded. In some cases, this may not contain a fully qualified path.
-name Returns the name of the driver - generally the file name portion of the file from which the driver was loaded.
get_module_handle ?-path PATH? ?-pin BOOLEAN?
Retrieves a handle for a module loaded in the process. If no arguments are specified, returns a handle to the .exe file from which calling process was created.

If the -path option is present, the command returns a handle to the module loaded from the file specified by PATH. PATH may be either a full path or just the file name.

The command will normally increment the reference count for the specified module. The returned handle must later be released by calling free_library (not close_handle). However, if the -pin option is specified as true, the module will stayed loaded until the process terminates irrespective of how many calls are made to free it.
get_module_handle_from_address ADDRESS ?-pin BOOLEAN?
Retrieves a handle for the module in whose address range the specifed ADDRESS lies.

The command will normally increment the reference count for the specified module. The returned handle must later be released by calling free_library (not close_handle). However, if the -pin option is specified as true, the module will stayed loaded until the process terminates irrespective of how many calls are made to free it.
get_pid_from_handle HPROCESS
Returns the PID of the process corresponding to the process handle HPROCESS.
get_priority_class PID
Returns the scheduling priority class of the process with id PID.
get_process_commandline PID ?options?
Returns the command line with which the process with id PID was invoked. The following options may be specified with the command.
-noexist DEFAULTVALUE If a process does not exist, the command returns the string "(no such process)". This option may be used to specify a different string to be returned for non-existent processes.
-noaccess DEFAULTVALUE If a process exists but cannot be accessed to retrieve the name, the command normally returns the string "(unknown)". This option may be used to specify a different string to be returned in such cases.
get_process_elevation ?-pid PID | -hprocess HPROCESS?
If no options are specified, information for the current process is returned. A different process may be specified using its PID with the -pid option, or with a handle to it through the -hprocess option.

See get_token_elevation for details on the return value and semantics of this command.
get_process_exit_code HPROCESS
Returns the exit code for a process. HPROCESS is a handle to the process of interest. If the process is still running, a null string is returned.
get_process_handle PID ?-access ACCESSRIGHTS? ?-inherit INHERITMODE?
Returns a handle to the process with id PID. If option -access is specified, ACCESSRIGHTS are the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. If option -inherit is specified and INHERITMODE is non-0, the returned handle can be inherited by child processes. If it is 0 (default), the handle cannot be inherited by child processes.
get_process_ids ?options?
This command returns a list of the process ids. If no options are specified, the list includes all processes on the system. The following options may be specified to return a subset of these:
-glob This option modifies the meaning of the -path and -name options. Normally, the match is done using case-insensitive, exact comparison. If -glob is specified, the PROCESSNAME and EXECUTABLEPATH are matched using glob-style pattern matching as in Tcl's string match command.
-name PROCESSNAME If this option is specified, the returned list only includes those processes whose name matches PROCESSNAME. Generally the name is the same as the filename portion of the executable file path. If this information is not available for a process, it is not included in the returned list. This option cannot be used with the -path option.
-path EXECUTABLEPATH If this option is specified, the returned list only includes those processes created from the executable file matching EXECUTABLEPATH. If this information is not available for a process, it is not included in the returned list. This option cannot be used with the -name option.
-logonsession LUID If this option is specified, the returned list only includes those processes running inside the logon session identified by the specified LUID.
-user ACCOUNT If this option is specified, the returned list only includes those processes running under the specified account. ACCOUNT may be either a user name or its SID.
get_process_info PID ?options?
Returns various pieces of information related to the process whose id is PID. The information returned is dictionary whose keys are one or more of the following options that specify the information to be returned:
-all Returns all values except those for unsupported options.
-basepriority Returns the base priority of the process.
-commandline Returns the command line with which the process was invoked.
-createtime Returns the time the process was created as the number of 100ns units since Jan 1, 1601. This can be converted to a date and time string by passing it to large_system_time_to_secs and formatting the result using clock format.
-disabledprivileges Returns the list of privileges for the process that are currently disabled.
-elapsedtime Returns the total time (seconds) that the process has been running.
-elevation Returns the elevation level of the process (see get_process_elevation).
-enabledprivileges Returns the list of privileges that are enabled in the process.
-groupattrs Returns the list of groups SIDs and attributes in the process security token. See get_token_info for a description of the return value.
-groups Returns the list of the names of groups that the process belongs to. An error will be raised if any group SID's cannot be mapped to a name. Use -groupsids to avoid this.
-groupsids Returns the list of SIDs of groups that the process belongs to.
-handlecount Returns the number of handles that the process currently has open.
-integrity Returns the numeric integrity level of the process (see get_process_integrity).
-integritylabel Returns the label for the integrity level range of the process (see get_process_integrity).
-iootherbytes Returns number of non-data bytes the process has read or written through I/O operations.
-iootherops Returns number of non-data I/O operations the process has executed.
-ioreadbytes Returns number of data bytes the process has read through I/O operations.
-ioreadops Returns number of data read I/O operations the process has executed.
-iowritebytes Returns number of data bytes the process has written through I/O operations.
-iowriteops Returns number of data write I/O operations the process has executed.
-logonsession Returns the LUID of the logon session for the process.
-name Returns the name of the process. This is identical to the value returned by the get_process_name function.
-noaccess DEFAULTVALUE If a process exists but cannot be accessed to retrieve the name, the command normally returns the string "(unknown)". This option may be used to specify a different string to be returned in such cases.
-noexist DEFAULTVALUE If a process does not exist, the command returns the string "(no such process)". This option may be used to specify a different string to be returned for non-existent processes.
-pagefilebytes Returns total number of bytes in use for this process in all the system paging files.
-pagefilebytespeak Returns the maximum number of bytes that have been used for this process in the system paging file since the process started.
-parent Returns id of the process that invoked this process. For the system and system idle processes, an empty string is returned since they have no parent process.
-path Returns the path to the executable file from which this process was invoked. This value is the same as that returned by the get_process_path command.
-pid Returns the process id of this process, which will be identical to that passed in as the PID argument if the process exists. Otherwise it is set to the value of the -noexist option.
-poolnonpagedbytes Returns the number of bytes of nonpaged pool memory in use for the process.
-poolpagedbytes Returns the number of bytes of paged pool memory in use for the process.
-primarygroup Returns the primary group that the process belongs to. For domain accounts, an error is raised if the domain is unreachable. Use -primarygroupsid to avoid this.
-primarygroupsid Returns the SID of primary group that the process belongs to.
-priorityclass Returns the priority class of the process.
-privilegedtime The amount of privileged context CPU time used by the process in 100ns units.
-privileges Returns the list of enabled and disabled process privileges in the same format as get_token_privileges. Deprecated, use -enabledprivileges and -disabledprivileges instead.
-restrictedgroupattrs Returns the list of restricted group SIDs and attributes in the process security token. See get_token_info for a description of the return value.
-restrictedgroups Returns the list of restricted groups in the process security token. For domain accounts, an error is raised if the domain is unreachable. Use -restrictedgroupattrs to avoid this.
-threadcount Returns the total number of threads in the process.
-tids Returns a list of ids of the threads in the process.
-tssession Returns the terminal server session id of the process.
-user Returns the user account under which the process is running.
-usertime The amount of user context CPU time used by the process in 100ns units.
-virtualbytes Returns the current size of the process' virtual address space.
-virtualbytespeak Returns the maximum amount of virtual address space that the process has used in the course of its execution.
-virtualized Returns trued if the process is virtualized and false otherwise. See virtualized_process.
-workingset Returns the number of bytes currently in the process' working set.
-workingsetpeak Returns the maximum number of bytes in the process' working set since it began execution.
Note that all the information is not retrieved in a single snapshot so there may be discrepancies between various values. For example, the number of thread ids returned via -tids may not match the thread count returned via -threadcount.

The get_process_info command is intended for one-time retrieval of information and is too inefficient for usage in an application like performance monitoring. Direct access to the performance data should be used in those cases.
get_process_integrity ?-pid PID | -hprocess HPROCESS? ?-raw | -label?
If no options are specified, information for the current process is returned. A different process may be specified using its PID with the -pid option, or with a handle to it through the -hprocess option.

See get_token_integrity for details on the other options, return value and semantics of this command.
get_process_modules PID ?options?
This command returns information about the modules loaded in the process with id PID. If no options are specified, the command returns a list of handles to the modules.

If any options are specified, the returned information is a record array with one record per module. The fields of the record array depend on which of the following options are specified.
-all Returns the data for all options described below.
-base Includes the base address of the module.
-entry Includes the address of the entry point to the module.
-handle Includes the handle to the module in the returned data for each module.
-name Includes the name of the module - generally the file name portion of the path.
-path Includes the full path from which the module was loaded.
-size Includes the size of the module.
get_process_name PID
Returns the name of the process with id PID. This is generally the file name component of the full path of the executable file from which the process was loaded. The following options may be specified to with the command:
-noexist DEFAULTVALUE If a process does not exist, the command returns the string "(no such process)". This option may be used to specify a different string to be returned for non-existent processes.
-noaccess DEFAULTVALUE If a process exists but cannot be accessed to retrieve the name, the command normally returns the string "(unknown)". This option may be used to specify a different string to be returned in such cases.
get_process_parent PID
Returns the PID of the process from whom the process with id PID inherited handles and environment. An empty string is returned if PID corresponds to the System or the System Idle Process. The following options may be specified to with the command:
-noexist DEFAULTVALUE If a process does not exist, the command returns the string "(no such process)". This option may be used to specify a different string to be returned for non-existent processes.
-noaccess DEFAULTVALUE If a process exists but cannot be accessed to retrieve the parent, the command normally returns the string "(unknown)". This option may be used to specify a different string to be returned in such cases.
get_process_path PID
Returns the full path of the executable file from which the process with id PID was loaded. The following options may be specified to with the command:
-noexist DEFAULTVALUE If a process does not exist, the command returns the string (no such process). This option may be used to specify a different string to be returned for non-existent processes.
-noaccess DEFAULTVALUE If a process exists but cannot be accessed to retrieve the path information, the command normally returns the string (unknown). This option may be used to specify a different string to be returned in such cases.
get_process_thread_ids PID
Returns a list of ids of all threads in the process whose id is PID.
get_system_environment_vars ?-normalize BOOLEAN?
Returns a dictionary containing the environment variables defined for the system and their values. If -normalize is false (default), the environment variable names are returned exactly as defined. If specified as true, they are converted to upper case.
get_thread_handle TID ACCESSMODE ?INHERITMODE?
Returns a handle to the thread with id TID. ACCESSMODE specifies the desired access rights and may be specified as a list of integer access rights flags or symbols. Refer to the documentation of TWAPI Security module for more details. If INHERITMODE is non-0, the returned handle can be inherited by child processes. If it is 0 (default), the handle cannot be inherited by child processes.
get_thread_info TID ?options?
Returns various pieces of information related to the thread whose id is TID. The return value is a dictionary whose keys are one or more of the following options that specify what information is to be returned:
-all Returns all values.
-basepriority Returns the base priority of the thread.
-contextswitches Returns the number of context switches done by the thread.
-createtime Returns the time the thread was created as the number of 100ns units since Jan 1, 1601. This can be converted to a date and time string by passing it to large_system_time_to_secs and formatting the result using clock format.
-disabledprivileges Returns the list of privileges for the thread that are currently disabled.
-elapsedtime Returns the total time (seconds) that the thread has been running.
-enabledprivileges Returns the list of privileges that are enabled in the thread.
-groupattrs Returns the list of groups SIDs and attributes in the thread's security token. See get_token_info for a description of the return value.
-groups Returns the list of the names of groups that the thread belongs to. An error will be raised if any group SID's cannot be mapped to a name. Use -groupsids to avoid this.
-groupsids Returns the list of SIDs of groups that the thread belongs to.
-interval INTERVAL Specifies the number of milliseconds over which rate based fields are to be measured. The command will not return until this time has elapsed. By default this is 100ms. If none of the fields requested is a rate based field, this option is ignored and the command returns immediately.
-noaccess DEFAULTVALUE If a thread but cannot be accessed, the command normally returns the string "(unknown)". This option may be used to specify a different string to be returned in such cases.
-noexist DEFAULTVALUE If a thread does not exist, the command returns the string "(no such thread)". This option may be used to specify a different string to be returned for non-existent threads.
-pid Returns the id of the process the thread belongs to.
-primarygroup Returns the primary group that the thread belongs to. For domain accounts, an error is raised if the domain is unreachable. Use -primarygroupsid to avoid this.
-primarygroupsid Returns the SID of primary group that the process belongs to.
-priority Returns the current priority of the thread.
-privilegedtime The amount of privileged context CPU time used by the thread in 100ns units.
-privileges Returns the list of the current thread privileges. Deprecated, use -enabledprivileges and -disabledprivileges instead.
-relativepriority Returns the priority level of the thread relative to the priority class of the containing process.
-restrictedgroupattrs Returns the list of restricted group SIDs and attributes in the thread's security token. See get_token_info for a description of the return value.
-restrictedgroups Returns the list of restricted groups in the thread's security token. For domain accounts, an error is raised if the domain is unreachable. Use -restrictedgroupattrs to avoid this.
-startaddress Returns the address at which the thread began execution.
-state Returns the current state of the thread.
-tid Returns the thread id of this process (which should be identical to that passed in as the TID argument.
-user Returns the user account under which the thread is running.
-usertime The amount of user context CPU time used by the thread in 100ns units.
-waitreason Returns the reason a thread is in wait state. This is only valid when the state field is 5 indicating the thread is in a wait state.
Note that all the information is not retrieved in a single snapshot so there may be discrepancies between various values.

Like the get_process_info command, get_thread_info is intended for one-time retrieval of information and is too inefficient for usage in an application like performance monitoring. Direct access to the performance data should be used in those cases.
get_thread_relative_priority TID
Returns the scheduling priority value of the thread with id TID. This is an integer value relative to the process' priority class as described in the Windows SDK.
get_thread_parent_process_id TID
Returns the id of the parent process of the thread with id TID.
get_user_environment_vars TOKEN ?-normalize BOOLEAN? ?-inherit BOOLEAN?
Returns a dictionary containing the environment variables defined for a user account. This includes system environment variables as well as those specific to that account. TOKEN must be a security token for the user account whose environment is to be retrieved and must have token_impersonate, token_query and token_duplicate access. If -inherit is true, the environment variables of the current process are included in the returned values. If false (default), they are ignored. If -normalize is false (default), the environment variable names are returned exactly as defined. If specified as true, they are converted to upper case.
is_idle_pid PID
Returns true if the passed PID is that of the system idle process.
is_system_pid PID
Returns true if the passed PID is that of the system process.
load_user_profile TOKEN ?options?
Loads the user profile associated with TOKEN. TOKEN should be a security token for the user security context and should have been opened with token_query, token_impersonate, and token_duplicate access. The command returns a handle to the registry hive for the loaded profile. This should be closed by passing it to unload_user_profile.

The following options may be specified with the command.
-defaultuserpath PATH Specifies the path for the default user profile in case no profile has yet been created for this user.
-noui BOOLEAN If true, no dialogs are displayed in case of error. Default is false.
-roamingprofilepath PATH Specifies the path to the user's roaming profile if he has one. Caller can use the -profile option to the get_user_account_info command to retrieve this.
-servername SERVERNAME Specifies the authenticating domain controller for the passed token in NETBIOS format.
-username USERNAME Specifies the user name to be used for the profile. By default the user name associated with TOKEN is used.
process_exists PID ?options?
This command returns 1 if a process with id PID exists and 0 otherwise. The following options may be specified to further restrict the match:
-path EXECUTABLEPATH If this option is specified, the matched process must have been created from the executable file matching EXECUTABLEPATH. This option cannot be used with the -name option.
-name PROCESSNAME If this option is specified, the matched process must have a name that matches PROCESSNAME. Generally the name is the same as the filename portion of the executable file path. This option cannot be used with the -path option.
-glob This option modifies the meaning of the -path and -name options. Normally, the match is done using case-insensitive, exact comparison. If -glob is specified, the PROCESSNAME and EXECUTABLEPATH are matched using glob-style pattern matching.
process_in_administrators
Returns true if a process belongs to an account which is in the Windows administrators group and false otherwise.
process_waiting_for_input PID ?-wait MILLISECONDS?
Returns 1 if the specified process is idle, waiting for input, and 0 otherwise. The main use of this command is to detect when a process (for example, a child process that has just been created) has finished initialization. Note that a console process will always return 1.

The command normally returns right away. Specifying the -wait option causes the command to wait until either MILLISECONDS have passed or the process is idle before returning. Specifying a value of -1 will cause the command to wait without timing out.
resume_thread TID
The command checks the suspend count (see suspend_thread) of the specified thread. If it is 0, the thread is not suspended and the command has no effect. Otherwise, the suspend count is decremented. If the value is now 0, the thread resumes execution. The command returns thread's previous suspend count - a value of 0 meaning the thread was not suspended, 1 meaning the suspending thread is not resumed, and other values signifying that the thread is still suspended.
set_priority_class PID PRIORITYCLASS
Sets the scheduling priority class of the process with id PID to PRIORITYCLASS. PRIORITYCLASS is an integer value identifying a priority class as described in the Windows SDK.
set_process_integrity INTEGRITY ?-pid PID | -hprocess HPROCESS?
Sets the integrity level of a process to INTEGRITY. If no options are specified, the integrity level of the current process is modified. A different process may be specified using its PID with the -pid option, or with a handle to it through the -hprocess option.

See set_token_integrity for possible values of INTEGRITY.
set_process_virtualization ENABLED ?-pid PID | -hprocess HPROCESS?
Enables or disables the virtualization state of a process depending on the boolean value of ENABLED. If no options are specified, the virtualization level of the current process is modified. A different process may be specified using its PID with the -pid option, or with a handle to it through the -hprocess option.

See set_token_integrity for more information.
set_thread_relative_priority TID PRIORITY
Sets the scheduling priority value of the thread with id TID to PRIORITY. PRIORITY is an integer value relative to the process' priority class as described in the Windows SDK.
SetThreadExecutionState EXECUTIONSTATE
Refer to the Windows SDK documentation for details.
suspend_thread TID
Suspends execution of the thread with id TID. The system keeps track of a suspend count for each thread. This is incremented every time a call is made to suspend the thread, and decremented every time a call is made to resume it. The command returns thread's previous suspend count.
unload_user_profile TOKEN HANDLE
Unloads a user profile that was previously loaded with the load_user_profile command.
virtualized_process ?-pid PID | -hprocess PROCESSHANDLE?
Returns true if a process is running as a virtualized process where the system redirects writes to protected file and registry locations and false otherwise. On systems that do not support UAC, the command will always return false.

With no options specified, the command checks the current process. If the -pid option is specified, it checks the process with the specific PID. If the -hprocess option is specified, PROCESSHANDLE must be a handle to the process to be checked. The two options must not be used together.
wow64_process ?-pid PID | -hprocess PROCESSHANDLE?
Returns true if a process is running as a 32-bit Windows process on a 64-bit Windows system and returns false otherwise. With no options specified, the command checks the current process. If the -pid option is specified, it checks the process with the specific PID. If the -hprocess option is specified, PROCESSHANDLE must be a handle to the process to be checked. The two options must not be used together.

COPYRIGHT

Copyright © 2003-2012 Ashok P. Nadkarni

Tcl Windows API 4.2b9