Windows API Reference

Processes

This section details the Windows API functions related to process management. Processes are fundamental to the Windows operating system, representing instances of running programs.

Process Creation

CreateProcess

BOOL CreateProcess( _In_opt_ LPCTSTR lpApplicationName, _Inout_opt_ LPTSTR lpCommandLine, _In_opt_ LPSECURITY_ATTRIBUTES lpProcessAttributes, _In_opt_ LPSECURITY_ATTRIBUTES lpThreadAttributes, _In_ BOOL bInheritHandles, _In_ DWORD dwCreationFlags, _In_opt_ LPVOID lpEnvironment, _In_opt_ LPCTSTR lpCurrentDirectory, _In_ LPSTARTUPINFO lpStartupInfo, _Out_ LPPROCESS_INFORMATION lpProcessInformation );

Creates a new process and its primary thread. The new process runs in the security context of the calling process.

Parameters:
  • lpApplicationName: The name of the module to be executed.
  • lpCommandLine: The command line for the executable image.
  • lpProcessAttributes: Security attributes for the process object.
  • lpThreadAttributes: Security attributes for the primary thread object.
  • bInheritHandles: Whether the calling process's handles are inherited.
  • dwCreationFlags: Flags that control the execution.
  • lpEnvironment: A pointer to the environment block for the new process.
  • lpCurrentDirectory: The fully qualified path of the current directory for the process.
  • lpStartupInfo: A pointer to a STARTUPINFO structure that specifies how to launch the application.
  • lpProcessInformation: A pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.
Return Value:

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks:

CreateProcess is a powerful function that allows for extensive customization of process creation. It's important to handle errors correctly by checking the return value and calling GetLastError.

See Also:

Process Termination

TerminateProcess

BOOL TerminateProcess( _In_ HANDLE hProcess, _In_ UINT uExitCode );

Terminates the specified process and any threads that it owns.

Parameters:
  • hProcess: A handle to the process to be terminated.
  • uExitCode: The exit code for the process.
Return Value:

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks:

Use this function with caution. Terminating a process abruptly can lead to data loss or system instability. Ensure that all threads in the process have exited and that all memory has been deallocated before calling this function if possible.

See Also:

Process Information

GetCurrentProcess

_Ret_ HANDLE GetCurrentProcess(void);

Returns a pseudohandle for the current process. A pseudohandle is a special constant that is equal to the real handle to the process in all situations.

Return Value:

The return value is a pseudohandle for the current process.

GetProcessId

DWORD GetProcessId( _In_ HANDLE pHandle );

Retrieves the process identifier for the specified process.

Parameters:
  • pHandle: A handle to the process.
Return Value:

If the function succeeds, the return value is the process identifier. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Process Enumeration

EnumProcesses

BOOL EnumProcesses( _Out_ DWORD* pPIDs, _In_ DWORD cb, _Out_ DWORD* pcPIDs );

Retrieves the process identifier for each process running on the local computer.

Parameters:
  • pPIDs: A pointer to an array that receives the list of process identifiers.
  • cb: The size of the array pointed to by pPIDs, in bytes.
  • pcPIDs: A pointer to a variable that receives the number of process identifiers returned in the array.
Return Value:

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks:

You must allocate enough memory for the pPIDs array to hold all the process identifiers. If the array is too small, the function returns zero and GetLastError returns ERROR_INSUFFICIENT_BUFFER.