Process functions(n) "Processes and threads"
Process functions - Functions related to processes and threads
package require twapi
This package provides procedures for controlling processes and retrieving
process related information.
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.
- 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.
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 © 2003, Ashok P. Nadkarni