Win32API::Process - Perl extension for handling the processes using the plain Win32 API

- NAME
- SYNOPSIS
- DESCRIPTION

- EXPORTS
- CONSTANTS
- FUNCTIONS

- AUTHOR
- COPYRIGHT
- SEE ALSO

# NAME

Win32API::Process - Perl extension for handling the processes using the plain Win32 API

# SYNOPSIS

      use Win32API::Process ':All';

      # --- opens handle to the current process
      my $handle = OpenProcess(PROCESS_ALL_ACCESS, 0, $$);
      CloseProcess($handle);

# DESCRIPTION

The Process functions exposes the part of Win32 API handling the processes.

It contains just process opening an terminating functionality in the meanwhile. It is supposed to be used with the `Win32API::ProcessStatus` module or modules that need handles to processes on their interfaces.

(Note that much of the following documentation refers to the behavior of the underlying Win32 API calls which may vary in its current and future versions without any changes to this module. Therefore you should check the Win32 API documentation in MSDN directly when needed.)

## EXPORTS

Nothing is exported by default. The following tags can be used to have sets of symbols exported:

:Func
  The basic function names: CloseProcess GetLastProcessError OpenProcess SetLastProcessError TerminateProcess.

## CONSTANTS

The constants described here and exported by this module are used only in its structures and functions. See the module `Win32API::Const` for the common Win32 constants.

`PROCESS_` constants are used as flags in the process handlingopening functions.

PROCESS_ALL_ACCESS
  Specifies all possible access flags for the process object.

PROCESS_CREATE_PROCESS
  Used internally.

PROCESS_CREATE_THREAD
  Enables using the process handle in the `CreateRemoteThread` function to create a thread in the process.

PROCESS_DUP_HANDLE
  Enables using the process handle as either the source or target process in the `DuplicateHandle` function to duplicate a handle.

PROCESS_QUERY_INFORMATION
  Enables using the process handle in the `GetExitCodeProcess` and `GetPriorityClass` functions to read information from the process object.

PROCESS_SET_QUOTA
  Enables using the process handle in the `AssignProcessToJobObject` and `SetProcessWorkingSetSize` functions to set memory limits.

PROCESS_SET_INFORMATION
  Enables using the process handle in the `SetPriorityClass` function to set the priority class of the process.

PROCESS_TERMINATE
  Enables using the process handle in the `TerminateProcess` function to terminate the process.

PROCESS_VM_OPERATION
  Enables using the process handle in the `VirtualProtectEx` and `WriteProcessMemory` functions to modify the virtual memory of the process.

PROCESS_VM_READ
  Enables using the process handle in the `ReadProcessMemory` function to read from the virtual memory of the process.

PROCESS_VM_WRITE
  Enables using the process handle in the `WriteProcessMemory` function to write to the virtual memory of the process.

STANDARD_RIGHTS_REQUIRED
  Combines `DELETE`, `READ_CONTROL`, `WRITE_DAC`, and `WRITE_OWNER` access.

SYNCHRONIZE
  Windows NT/2000/XP: Enables using the process handle in any of the wait functions to wait for the process to terminate.

## FUNCTIONS

Process functions return either a boolean status of the function's result or a handle to a process. To retrieve an extended information about the error if it occurs use the `GetLastProcessError` function. If no error happens `GetLastProcessError` still returns the last occured error code (successful calls do not modify the last stored error code). You can set or reset the internally stored error code explicitely by the function `SetLastProcessError`.

To use something more convenient than numbers for comparisons of return values and error codes see the module `Win32API::Const`.

`CloseProcess($hProcess)`
  Closes an open process handle.
  hProcess [IN]
    Handle to the open process.

  [RETVAL]
    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessError`.

    Windows NT/2000/XP: Closing an invalid handle raises an exception when the application is running under a debugger. This includes closing a handle twice, for example.

  It invalidates the specified process handle, decrements the object's handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

`GetLastProcessError()`
  Retrieves the last-error code value of the Process functions. The last-error code is stored if a function fails and remembered until another function calls when it is overwritten by the new error code. Successful calls do not modify this internally stored last-error code value.
  [RETVAL]
    The return value is the last-error code value. Functions set this value by calling the `SetLastProcessError` function if they fail.

  To obtain an error string for system error codes, use the `FormatMessage` function. For a complete list of error codes, see the System Error Codes section in MSDN. There are pre-defined constants for the Win32 system error codes in the module <Win32API::Const>.

  You should call the `GetLastProcessError` function immediately when a function's return value indicates that such a call will return useful data. A subsequent call to another Process function could fail as well and `GetLastProcessError` would return its error code instead of the former one.

  Function failure is typically indicated by a return value such as zero, undefined, or –1 (0xffffffff).

  Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is `ERROR_SUCCESS`.

OpenProcess($dwDesiredAccess, $bInheritHandle, $dwProcessId)
  Takes a snapshot of the processes and the heaps, modules, and threads used by the processes.
  dwDesiredAccess [IN]
    Specifies the access to the process object. For operating systems that support security checking, this access is checked against any security descriptor for the target process. The values available are listed in the description of `PROCESS__` constants.

  bInheritHandle [IN]
    Specifies whether the returned handle can be inherited by a new process created by the current process. If TRUE, the handle is inheritable.

  dwProcessId [IN]
    Specifies the identifier of the process to open.

  [RETVAL]
    If the function succeeds, the return value is an open handle to the specified process. If the function fails, the return value is NULL. To get extended error information, call `GetLastProcessError`.

  The handle returned by the `OpenProcess` function can be used in any function that requires a handle to a process, such as the wait functions, provided the appropriate access rights were requested.

  When you are finished with the handle, be sure to close it using the `CloseProcess` or `CloseHandle` function.

`SetLastProcessError($dwError)`
  Sets the last-error code value of the Process functions.
  dwError [IN]
    Specifies the last-error code.

  Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is `ERROR_SUCCESS`.

  Applications can retrieve the value saved by this function by using the `GetLastProcessError` function. The use of `GetLastProcessError` is optional; an application can call it to find out the specific reason for a function failure.

TerminateProcess($hProcess, $uExitCode)
  Terminates the specified process and all of its threads.
  hProcess [IN]
    Handle to the process to terminate.

  uExitCode [IN]
    Specifies the exit code for the process and for all threads terminated as a result of this call. Use the `GetExitCodeProcess` function to retrieve the process's exit value. Use the `GetExitCodeThread` function to retrieve a thread's exit value.

  [RETVAL]
    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessError`.

  The `TerminateProcess` function is used to unconditionally cause a process to exit. Use it only in extreme circumstances. The state of global data maintained by dynamic-link libraries (DLLs) may be compromised if `TerminateProcess` is used rather than `ExitProcess`.

  `TerminateProcess` causes all threads within a process to terminate, and causes a process to exit, but DLLs attached to the process are not notified that the process is terminating.

  Terminating a process causes the following:

  All of the object handles opened by the process are closed.

  All of the threads in the process terminate their execution.

  The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.

  The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.

  The termination status of the process changes from `STILL_ACTIVE` to the exit value of the process.

  Terminating a process does not cause child processes to be terminated.

  Terminating a process does not necessarily remove the process object from the system. A process object is deleted when the last handle to the process is closed.

  Terminating a process does not generate notifications for `WH_CBT` hook procedures.

# AUTHOR

Ferdinand Prantl <prantl@host.sk>

See http://prantl.host.sk/perl/modules/Win32API/Process for the most recent version.

# COPYRIGHT

Copyright (c) 2002, Ferdinand Prantl. All rights reserved.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Author makes no representations about the suitability of this software for any purpose. It is provided ``as is'' without express or implied warranty.

# SEE ALSO

the Win32API::ProcessStatus manpage, the Win32::Process manpage, the Win32::Job manpage and the Win32API::Const manpage.

Win32API::Process - Perl extension for handling the processes using the plain Win32 API