Process functions(n) "Processes and threads"

NAME

Process functions - Functions related to processes and threads

SYNOPSIS

package require twapi

get_current_process_id
get_current_thread_id
get_thread_parent_process_id TID
get_process_ids ?options?
get_process_thread_ids PID
process_exists PID ?options?
get_process_modules PID ?options?
get_process_path PID
get_process_name PID
get_process_info PID ?options?
get_thread_info TID ?options?
get_device_drivers ?options?
end_process PID ?options?

DESCRIPTION

This package provides procedures for controlling processes and retrieving process related information.

Overview

The commands get_process_ids and get_current_process_id retrieve process id information.

The command get_current_thread_id retrieves the current thread id. get_thread_parent_process_id retrieves the id of the process containing the specified thread. get_process_thread_ids retrieves the thread ids of all threads in the specified process.

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.

process_exists checks for the existence of a process.

get_process_modules retrieves information pertaining to the modules loaded into a process.

end_process allows termination of a process.

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

Commands

get_current_process_id
Returns the current process id.

get_current_thread_id
Returns the current thread id.

get_thread_parent_process_id TID
Returns the id of the parent process of the thread with id TID.

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:

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

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

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


get_process_thread_ids PID
Returns a list of ids of all threads in the process whose id is PID.

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.


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 in the form of a list of sublists each of which corresponds to a loaded module. The sublist for each module is in the form "option VALUE". The following options may be specified:

-all
Returns the data for all options described below.

-handle
Includes the handle to the module in the returned data for each module.

-path
Includes the full path from which the module was loaded.

-name
Includes the name of the module - generally the file name portion of the path.

-imagedata
Includes the base address in memory where the module is loaded, the size of the module in memory and the address of the entry point to the module as a sublist for each module.


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_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_info PID ?options?
Returns various pieces of information related to the process whose id is PID. The information returned depends on the options specified and is in the form of a flat list of the form "option1 value1 ...". The values returned may be scalars (e.g. -name) or rate based measured over an interval (e.g. -processorutilization). The option -interval may be used to indicate the interval over which the rate based fields are measured. One of more of the following options may be specified with the command:

-all
Returns all values.

-basepriority
Returns the base priority of the process.

-elapsedtime
Returns the total time (seconds) that the process has been running.

-handlecount
Returns the number of handles that the process currently has open.

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

-iodatabytesrate
Returns the rate at which the process is reading and writing bytes.

-iodataopsrate
Returns the rate at which the process is issuing I/O operation.

-iootherbytesrate
Returns the rate at which the process is reading and writing non-data bytes (such as control bytes).

-iootheropsrate
Returns the rate at which the process is issuing non-data I/O operations.

-ioreadbytesrate
Returns the rate at which the process is reading bytes through I/O operations.

-ioreadopsrate
Returns the rate at which the process is issuing read I/O operations.

-iowritebytesrate
Returns the rate at which the process is writing bytes through I/O operations. All types of I/O operations are including in this rate.

-iowriteopsrate
Returns the rate at which the process is issuing write I/O operations.

-name
Returns the name of the process. This is identical to the value returned by the get_process_name function.

-pagefaultrate
Returns the rate at which the process is generating page faults.

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

-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 should be identical to that passed in as the PID argument.

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

-privatebytes
Returns the number of bytes allocated for this process' private use.

-privilegedutilization
Returns the percentage of elapsed time that this process has spent executing in privileged mode.

-processorutilization
Returns the percentage of CPU time that this process has used.

-threadcount
Returns the total number of threads in the process.

-tids
Returns a list of ids of the threads in the process.

-toplevels
Returns a list of the window handles of all toplevel windows owned by the process.

-userutilization
Returns the percentage of elapsed time that this process has spent executing in user mode.

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

-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_thread_info TID ?options?
Returns various pieces of information related to the thread whose id is TID. The information returned depends on the options specified and is in the form of a flat list of the form "option1 value1 ...". The values returned may be scalars (e.g. -name) or rate based measured over an interval (e.g. -processorutilization). The option -interval may be used to indicate the interval over which the rate based fields are measured. One of more of the following options may be specified with the command:

-all
Returns all values.

-basepriority
Returns the base priority of the thread.

-contextswitches
Returns the rate of context switches for the thread.

-elapsedtime
Returns the total time (seconds) that the process has been running.

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

-pid
Returns the id of the process the thread belongs to.

-priority
Returns the current priority of the thread.

-privilegedutilization
Returns the percentage of elapsed time that this process has spent executing in privileged mode.

-processorutilization
Returns the percentage of CPU time that this process has used.

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

-userutilization
Returns the percentage of elapsed time that this process has spent executing in user mode.

-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_device_drivers ?options?
This command returns information about the device drivers loaded in the system. The returned information is in the form of a list of sublist with each sublist corresponding to a loaded driver. Each sublist is a flat list of "option value" pairs where option may be one of the following:

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


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 MILLISECONDS
Normally, the function will return without actually waiting for the process to end. If this option is specified, the function returns after waiting for milliseconds 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.

KEYWORDS

CPU utilization, I/O rates, device driver, executable path, memory usage, performance, process, process existence, process modules, process priority, process termination, thread, virtual memory, working set

COPYRIGHT

Copyright © 2003, Ashok P. Nadkarni