Module Description

Kernel related functions... (KernelUtil.cpp)

Groups
	Date/time support

	Environment Functions

Macros
#define	DOS_EXEPAGE_SIZE 512

#define	GlobalAllocStr GlobalAllocStrA

#define	GlobalDupStr GlobalDupStrA

Functions
UINT	GlobalPurgeAtom (CSTR Name)

CSTR	GlobalAtomName (ATOM atom)

CSTR	LocalAtomName (ATOM atom)

HANDLE	GetCurrentThreadHandle ()

HANDLE	GetCurrentProcessHandle ()

HANDLE	CloseHandleEx (HANDLE H)

HANDLE	CheckHandle (HANDLE Hnd)

bool	WaitFor (HANDLE hObj, DWORD msWait)

ASTR	GlobalAllocStrA (UINT nChr)

WSTR	GlobalAllocStrW (UINT nChr)

ASTR	GlobalDupStrA (ACSTR Str, bool isMz=false)

WSTR	GlobalDupStrW (WCSTR Str, bool isMz=false)

HANDLE	GlobalUnlockedHandle (PVOID Ptr, PUINT pCount=NULL)

bool	IsBadReadWritePtr (const PVOID address, UINT_PTR size)

HANDLE	Launch (CSTR ExePath, CSTR CmdLn, CSTR StartDir=NULL, int iShow=SW_SHOW, DWORD Flags=NORMAL_PRIORITY_CLASS)

HANDLE	CreateCapturedProcess (IN CSTR cmdLn, INOUT LPSTARTUPINFO pSi, IN DWORD Flags, OPTOUT PHANDLE pRdHnd, OPTOUT PHANDLE pWrHnd, OPTOUT PHANDLE pErrHnd, OPTOUT PHANDLE phThread=NULL)

HANDLE	CreateCapturedProcessEx (OPTIN CSTR ExePath, OPTIN CSTR CmdLn, OPTIN CSTR EnvStr, OPTIN CSTR WorkDir, INOUT LPSTARTUPINFO pSI, IN DWORD Flags, OPTOUT PHANDLE pRdHnd, OPTOUT PHANDLE pWrHnd, OPTOUT PHANDLE pErrHnd, OPTOUT PHANDLE phThread)

HANDLE	CloseCapturedProcess (IN HANDLE hProc, IN LPSTARTUPINFO pSi, OPTIN PHANDLE pRdHnd, OPTIN PHANDLE pWrHnd, OPTIN PHANDLE pErrHnd)

HANDLE	TerminateCapturedProcess (OPTIN HANDLE hProc, IN LPSTARTUPINFO pSi, IN PHANDLE pRdHnd, IN PHANDLE pWrHnd, IN PHANDLE pErrHnd, IN UINT RetCode=EXIT_SUCCESS)

HMODULE	GetOrLoadModule (CSTR modName)

HMODULE	LoadProcLibrary (HANDLE hProcess, LPCSTR DllPathName, DWORD msWait=5000)

BOOL	UnloadProcLibrary (HANDLE hProcess, HMODULE hRemoteLib, DWORD msWait=5000)

SHORT	GetProcDLLRefCount (HANDLE hProcess, WCSTR DllName)

HMODULE	GetProcDLLHandle (HANDLE hProcess, WCSTR DllName)

WORD	GetTargetMachine (CSTR ExeName)

bool	Is64BitExecutable (CSTR ExeName)

bool	ReadNTHeaders (CSTR ExeName, IMAGE_NT_HEADERS *Hdr, bool GetOptHdr)

WORD	GetInstanceTargetMachine (HINSTANCE hInst)

bool	Is64BitInstance (HINSTANCE hInst)

bool	Is32BitInstance (HINSTANCE hInst)

CSTR	GetMachineStr (WORD Machine)

CSTR	GetSubSystemStr (WORD SubSys)

Macro Definition Documentation

◆ DOS_EXEPAGE_SIZE

#define DOS_EXEPAGE_SIZE 512

The size of an exe file "page". See IMAGE_DOS_HEADER::e_cp.
FYI: This value is (or was) equivalent to the standard HDD sector size.

Definition at line 473 of file UtilFunc.h.

◆ GlobalAllocStr

#define GlobalAllocStr GlobalAllocStrA

Definition at line 505 of file UtilFunc.h.

◆ GlobalDupStr

#define GlobalDupStr GlobalDupStrA

Definition at line 506 of file UtilFunc.h.

Function Documentation

◆ GlobalPurgeAtom()

UINT GlobalPurgeAtom ( CSTR Name )

Purge all counts of a global atom (delete it).

Definition at line 23 of file KernelUtil.cpp.

◆ GlobalAtomName()

CSTR GlobalAtomName ( ATOM atom )

Note: Uses static buffer.

Definition at line 36 of file KernelUtil.cpp.

◆ LocalAtomName()

CSTR LocalAtomName ( ATOM atom )

Note: Uses static buffer.

Definition at line 43 of file KernelUtil.cpp.

◆ GetCurrentThreadHandle()

HANDLE GetCurrentThreadHandle ( )

Get a real handle to the current thread.

Definition at line 54 of file KernelUtil.cpp.

◆ GetCurrentProcessHandle()

HANDLE GetCurrentProcessHandle ( )

Get a real handle to the current process.

Definition at line 62 of file KernelUtil.cpp.

◆ CloseHandleEx()

HANDLE CloseHandleEx ( HANDLE H )

Return NULL if successful, else H.

Definition at line 80 of file KernelUtil.cpp.

◆ CheckHandle()

HANDLE CheckHandle ( HANDLE Hnd )

Return NULL if invalid handle, else Hnd.

Definition at line 75 of file KernelUtil.cpp.

◆ WaitFor()

bool WaitFor	(	HANDLE	hObj,
		DWORD	msWait
	)

WaitFor uses an alertable WaitForSingleObjectEx.
It returns true on WAIT_OBJECT_0, else false and GetLastError() == wait result.

Definition at line 95 of file KernelUtil.cpp.

◆ GlobalAllocStrA()

ASTR GlobalAllocStrA ( UINT nChr )

Alloc nr of CHARs.

Definition at line 108 of file KernelUtil.cpp.

◆ GlobalAllocStrW()

WSTR GlobalAllocStrW ( UINT nChr )

Alloc nr of WCHARs (not nr of bytes).

Definition at line 112 of file KernelUtil.cpp.

◆ GlobalDupStrA()

ASTR GlobalDupStrA	(	ACSTR	Str,
		bool	isMz = `false`
	)

Duplicate ANSI/MB string into Global memory.

Definition at line 119 of file KernelUtil.cpp.

◆ GlobalDupStrW()

WSTR GlobalDupStrW	(	WCSTR	Str,
		bool	isMz = `false`
	)

Duplicate UNICODE string into Global memory.

Definition at line 142 of file KernelUtil.cpp.

◆ GlobalUnlockedHandle()

HANDLE GlobalUnlockedHandle	(	PVOID	Ptr,
		PUINT	pCount = `NULL`
	)

GlobalUnlockedHandle releases all locks on Ptr and returns the global handle.
pCount, if provided, recieves the lock count. On failure the function returns NULL.

Definition at line 156 of file KernelUtil.cpp.

◆ IsBadReadWritePtr()

bool IsBadReadWritePtr	(	const PVOID	address,
		UINT_PTR	size
	)

Memory access check. See also [MSDN] IsBadReadPtr/IsBadWritePtr.
Note: Success does not guarantee accessibility when multithreading.

Definition at line 179 of file KernelUtil.cpp.

◆ Launch()

HANDLE Launch	(	CSTR	ExePath,
		CSTR	CmdLn,
		CSTR	StartDir = `NULL`,
		int	iShow = `SW_SHOW`,
		DWORD	Flags = `NORMAL_PRIORITY_CLASS`
	)

Launch is a simplified wrap for CreateProcess().

Parameters

ExePath	File path of the executable, may be NULL if specified in CmdLn.
CmdLn	Command line arguments. See remarks below..
StartDir	Working directory, may be NULL (to use the exe directory).
iShow	Appropriate SW_xx option.
Flags	CreateProcess flags. See [MSDN] Process Creation Flags.

Note: If you pass both ExePath and CmdLn, the child process can only get the CmdLn
by using GetCommandLine().. The szCmdLn of WinMain doesn't deliver the goods.
(That smells BUG, maybe in CreateProcess, or maybe in the C startup library,
I haven't the energy to find out.)

However, if you pass NULL for ExePath and insert the executable pathname as the
first part of CmdLn followed by the actual command line args, then not only does
szCmdLn deliver, but CreateProcess also searches the PATH to find the executable
if no full pathname is given.
Go figure..

Note: For security, if you pass the executable pathname in CmdLn,
be sure to enclose it in quotes, due to how CreateProcess parses spaces.

Returns: Returns the process handle, or NULL on failure.

Definition at line 188 of file KernelUtil.cpp.

◆ CreateCapturedProcess()

HANDLE CreateCapturedProcess	(	IN CSTR	cmdLn,
		INOUT LPSTARTUPINFO	pSi,
		IN DWORD	Flags,
		OPTOUT PHANDLE	pRdHnd,
		OPTOUT PHANDLE	pWrHnd,
		OPTOUT PHANDLE	pErrHnd,
		OPTOUT PHANDLE	phThread = `NULL`
	)

CreateCapturedProcess launches a process who's STDIN/OUT/ERR are redirected
to three anonymous pipes that are automatically created by the function.

When done using the process, close it's handle and all six pipe handles.
The not so obvious three are the child's handles in the STARTUPINFO struct.
Note: Do not preset the std handles in STARTUPINFO, they're assigned for you.

Returns: Returns the process handle, or NULL on failure.

See also CreateCapturedProcessEx(), TerminateCapturedProcess(), CloneEnvironment(), [MSDN] CreateProcess().

Parameters

cmdLn	Command line string. (Exe and parameters.)
pSi	STARTUPINFO (less the std handles) for the proc.
Flags	Creation flags for CreateProcess.
pRdHnd	Recieves a pipe handle for reading the child's stdout.
pWrHnd	Recieves a pipe handle for writing the child's stdin.
pErrHnd	Recieves a pipe handle for reading the child's stderr.
phThread	phThread [optional] If you need the thread handle.

◆ CreateCapturedProcessEx()

HANDLE CreateCapturedProcessEx	(	OPTIN CSTR	ExePath,
		OPTIN CSTR	CmdLn,
		OPTIN CSTR	EnvStr,
		OPTIN CSTR	WorkDir,
		INOUT LPSTARTUPINFO	pSI,
		IN DWORD	Flags,
		OPTOUT PHANDLE	pRdHnd,
		OPTOUT PHANDLE	pWrHnd,
		OPTOUT PHANDLE	pErrHnd,
		OPTOUT PHANDLE	phThread
	)

CreateCapturedProcessEx launches a process who's STDIN/OUT/ERR are redirected
to three anonymous pipes. It returns the handle of the process, or NULL.

Note: DefSec is used as the security attribute for both process and thread.

Parameters

ExePath	Executable path name. Note: ExePath and CmdLn can't both be NULL.
CmdLn	Command line string.
EnvStr	Environment block (multi-sz). If NULL, the current environment is used.
WorkDir	Working directory.
pSI	STARTUPINFO (less the std handles) for the new proc.
Flags	Creation flags for CreateProcess.
pRdHnd	We read child's stdout from here. Note: pRdHnd and pErrHnd can't both be NULL.
pWrHnd	We write child's stdin to here.
pErrHnd	We read child's stderr from here.
phThread	If you need the child's main thread handle.

◆ CloseCapturedProcess()

HANDLE CloseCapturedProcess	(	IN HANDLE	hProc,
		IN LPSTARTUPINFO	pSi,
		OPTIN PHANDLE	pRdHnd,
		OPTIN PHANDLE	pWrHnd,
		OPTIN PHANDLE	pErrHnd
	)

CloseCapturedProcess closes all seven handles from CreateCapturedProcess().
That is, the process handle and all six pipe handles.
On success it returns NULL, else hProc.

Parameters

hProc	Process handle.
pSi	STARTUPINFO used in CreateCapturedProcess.
pRdHnd	The inhnd returned from CreateCapturedProcess.
pWrHnd	The outhnd returned from CreateCapturedProcess.
pErrHnd	The errhnd returned from CreateCapturedProcess.

◆ TerminateCapturedProcess()

HANDLE TerminateCapturedProcess	(	OPTIN HANDLE	hProc,
		IN LPSTARTUPINFO	pSi,
		IN PHANDLE	pRdHnd,
		IN PHANDLE	pWrHnd,
		IN PHANDLE	pErrHnd,
		IN UINT	RetCode = `EXIT_SUCCESS`
	)

TerminateCapturedProcess terminates a CreateCapturedProcess(),
and then calls CloseCapturedProcess().

Note: Normally one should wait on the process handle, not terminate it.

It is perfectly legal to call TerminateCapturedProcess with hProc == NULL.
In that case only the pipe handles will be closed, no attempt to terminate the process is made,
and it's assumed you close hProc yourself.

See also TerminateProcess(), CreateCapturedProcess(), CreateCapturedProcessEx().

Parameters

hProc	The process handle. If not NULL, TerminateProcess is called!
pSi	The STARTUPINFO that was used.
pRdHnd	The RdHnd pipe handle returned by CreateCapturedProcess.
pWrHnd	The WrHnd pipe handle (dito).
pErrHnd	The ErrHnd pipe handle (dito).
RetCode	Return value to pass to TerminateProcess.

◆ GetOrLoadModule()

HMODULE GetOrLoadModule ( CSTR modName )

First tries to quickly GetModuleHandle, and if that fails
(not loaded) loads the module with LoadLibrary.

Definition at line 376 of file KernelUtil.cpp.

◆ LoadProcLibrary()

HMODULE LoadProcLibrary	(	HANDLE	hProcess,
		LPCSTR	DllPathName,
		DWORD	msWait = `5000`
	)

LoadProcLibrary loads a DLL into another process.
It returns the remote DLL handle, or NULL on failure.
Note: DllPathName must be the full pathname of the DLL to load. See also GetProcDLLHandle().

Definition at line 397 of file KernelUtil.cpp.

◆ UnloadProcLibrary()

BOOL UnloadProcLibrary	(	HANDLE	hProcess,
		HMODULE	hRemoteLib,
		DWORD	msWait = `5000`
	)

UnloadProcLibrary unloads a DLL from another process.
The DLL handle has to be in hProcess's address space.
See also LoadProcLibrary(), GetProcDLLHandle().

Definition at line 483 of file KernelUtil.cpp.

◆ GetProcDLLRefCount()

SHORT GetProcDLLRefCount	(	HANDLE	hProcess,
		WCSTR	DllName
	)

[PRELIMINARY] GetDLLRefCount returns the load count of a DLL in hProcess.
A value of -1 means the DLL is statically linked/loaded (can't be unloaded).
The function is intended for anti-malware use, but have other uses as well.

Definition at line 520 of file KernelUtil.cpp.

◆ GetProcDLLHandle()

HMODULE GetProcDLLHandle	(	HANDLE	hProcess,
		WCSTR	DllName
	)

[PRELIMINARY] GetProcDLLHandle returns the remote handle of a DLL in hProcess.
A return of NULL means the DLL was not loaded in that process.
The function is intended for anti-malware use, but have other uses as well.

Example:

void PurgeProcLib( HANDLE hAffectedProc, WCSTR DllName )
{
   SHORT refCount = GetProcDLLRefCount( hAffectedProc, DllName );
   if (refCount > 0) // -1 means it's statically linked/loaded.
   {
      // Get the remote handle for the dll to expungate...
      HMODULE hProcLib = GetProcDLLHandle( hAffectedProc, DllName );
      for( SHORT k = 0; k < refCount; ++k )
      {
         UnloadProcLibrary( hAffectedProc, hProcLib, 5000 );
      }
      // DllName is now unloaded from hAffectedProc, and the dll file
      // is no longer locked (unless it's loaded in some other proc as well),
      // so it can be deleted or quarantined.
   }
}

◆ GetTargetMachine()

WORD GetTargetMachine ( CSTR ExeName )

Get executable target architecture (IMAGE_NT_HEADERS.FileHeader.Machine).
If ExeName is NULL, get target architecture from current process' exe file.
Note: For the current process, GetInstanceTargetMachine() is faster.

Definition at line 1042 of file KernelUtil.cpp.

◆ Is64BitExecutable()

bool Is64BitExecutable ( CSTR ExeName )

Return true if ExeName is a 64-bit executable.

Definition at line 1049 of file KernelUtil.cpp.

◆ ReadNTHeaders()

bool ReadNTHeaders	(	CSTR	ExeName,
		IMAGE_NT_HEADERS *	Hdr,
		bool	GetOptHdr
	)

Read PE executable file header(s).

Definition at line 994 of file KernelUtil.cpp.

◆ GetInstanceTargetMachine()

WORD GetInstanceTargetMachine ( HINSTANCE hInst )

Get target architecture for the instance (IMAGE_NT_HEADERS.FileHeader.Machine).
See also IsWin64Bit(), IsWow64(), IsWinVer(), Is64BitInstance(), Is32BitInstance(), GetWinSystemInfo().

Definition at line 1062 of file KernelUtil.cpp.

◆ Is64BitInstance()

bool Is64BitInstance ( HINSTANCE hInst )

Return true if hInst is x64.

Definition at line 1074 of file KernelUtil.cpp.

◆ Is32BitInstance()

bool Is32BitInstance ( HINSTANCE hInst )

Return true if hInst is x86.

Definition at line 1081 of file KernelUtil.cpp.

◆ GetMachineStr()

CSTR GetMachineStr ( WORD Machine )

Human readable machine type name.

Definition at line 1101 of file KernelUtil.cpp.

◆ GetSubSystemStr()

CSTR GetSubSystemStr ( WORD SubSys )

Human readable subsystem name.

Definition at line 1150 of file KernelUtil.cpp.

Module Description

Groups

Macros

Functions

Macro Definition Documentation

◆ DOS_EXEPAGE_SIZE

◆ GlobalAllocStr

◆ GlobalDupStr

Function Documentation

◆ GlobalPurgeAtom()

◆ GlobalAtomName()

◆ LocalAtomName()

◆ GetCurrentThreadHandle()

◆ GetCurrentProcessHandle()

◆ CloseHandleEx()

◆ CheckHandle()

◆ WaitFor()

◆ GlobalAllocStrA()

◆ GlobalAllocStrW()

◆ GlobalDupStrA()

◆ GlobalDupStrW()

◆ GlobalUnlockedHandle()

◆ IsBadReadWritePtr()

◆ Launch()

◆ CreateCapturedProcess()

◆ CreateCapturedProcessEx()

◆ CloseCapturedProcess()

◆ TerminateCapturedProcess()

◆ GetOrLoadModule()

◆ LoadProcLibrary()

◆ UnloadProcLibrary()

◆ GetProcDLLRefCount()

◆ GetProcDLLHandle()

◆ GetTargetMachine()

◆ Is64BitExecutable()

◆ ReadNTHeaders()

◆ GetInstanceTargetMachine()

◆ Is64BitInstance()

◆ Is32BitInstance()

◆ GetMachineStr()

◆ GetSubSystemStr()