Module Description

Supplementary environment APIs.
These functions work with both separate environment blocks and the process environment.
Passing them a NULL environment pointer will cause them to address the process environment.

Macros
#define	DeleteEnvironmentVar(pwEnv, Name) SetEnvironmentVar( pwEnv, Name, NULL )

Enumerations
enum	eModenvFlags { MEF_PREPEND = 0, MEF_APPEND = 1 }

Functions
bool	GetEnvironmentSize (WSTR pwEnv, PUINT pSize, PUINT pUsed)

WSTR	CloneEnvironment (OPTOUT PUINT pLength, OPTOUT PUINT pUsed)

WSTR	FreeEnvironment (WSTR Env)

bool	SetEnvironmentVar (OPTIO WSTR *pwEnv, IN CSTR Name, IN CSTR Value)

bool	GetEnvironmentVar (OPTIN WSTR pwEnv, IN CSTR Name, OUT TSTR Value, INOUT PUINT ccValBuf)

UINT	ModifyEnvironmentVar (OPTIO WSTR *pwEnv, IN BYTE Option, IN CSTR Name, IN CSTR Addendum, OPTIN TCHAR Sep)

UINT	DeduplicatePathStr (INOUT TSTR Path)

Macro Definition Documentation

◆ DeleteEnvironmentVar

#define DeleteEnvironmentVar	(	pwEnv,
		Name
	)	SetEnvironmentVar( pwEnv, Name, NULL )

This macro removes a variable from an environment block or from the process environment.

Definition at line 765 of file UtilFunc.h.

Enumeration Type Documentation

◆ eModenvFlags

enum eModenvFlags

Option flags for ModifyEnvironmentVar().

Enumerator
MEF_PREPEND	ModifyEnvironmentVar() prepends the Addendum.
MEF_APPEND	ModifyEnvironmentVar() appends the Addendum.

Definition at line 865 of file UtilFunc.h.

Function Documentation

◆ GetEnvironmentSize()

bool GetEnvironmentSize	(	WSTR	pwEnv,
		PUINT	pSize,
		PUINT	pUsed
	)

Get the size and used amount, in WCHARs, from an environment block or the process environment.

Parameters

pwEnv The environment block to query. If NULL, the process environment is addressed.

Definition at line 714 of file KernelUtil.cpp.

◆ CloneEnvironment()

WSTR CloneEnvironment	(	OPTOUT PUINT	pLength,
		OPTOUT PUINT	pUsed
	)

CloneEnvironment creates a copy of the current process environment.

This is useful when you need to modify the environment before passing it to a child process.
The cloned environment is Unicode, to accomodate GetEnvironmentVar() and SetEnvironmentVar().

Parameters

pLength	[opt] Recieves the allocated size of the environment clone, in WCHARs.
pUsed	[opt] Recieves the currently used length of environment strings, in WCHARs, including the final multi-string null.

On error the function returns NULL, and GetLastError() has the code.
Delete the block with FreeEnvironment() when you're done with it.

Note: Don't forget to include CREATE_UNICODE_ENVIRONMENT in the flags
for the CreateProcess() family when you pass them this environment block.

If, for some reason, You need to translate the environment block to ANSI, You may use the following code:

bool __stdcall xlate_WideStr( WSTR wStr, PVOID ppStr )
{
    TSTR pStr = *(TSTR*)ppStr;
    int len = 1 + wcslen( wStr );
    TSTR pEnd = pStr + WideCharToMultiByte( CP_ACP, 0, wStr,len, pStr,len, NULL, NULL );
    *(TSTR*)ppStr = pEnd; // Update the buffer pointer
    return true;
}
ASTR TranslateEnvToAnsi( WCSTR wzEnv, UINT envLen )
{
    ASTR pzEnv = mem_AllocAStr( envLen ), _pzEnv = pzEnv;
    EnumerateMultiSzW( (WSTR)wzEnv, xlate_WideStr, &_pzEnv );
    return pzEnv;
}

Definition at line 747 of file KernelUtil.cpp.

◆ FreeEnvironment()

WSTR FreeEnvironment ( WSTR Env )

Return NULL on success. See also CloneEnvironment().

Definition at line 797 of file KernelUtil.cpp.

◆ SetEnvironmentVar()

bool SetEnvironmentVar	(	OPTIO WSTR *	pwEnv,
		IN CSTR	Name,
		IN CSTR	Value
	)

SetEnvironmentVar sets the value of an environment variable.
This function works with both separate environment blocks and the process environment.
Note: The environment block is Unicode, complying with RtlSetEnvironmentVariable(),
however, the Name and Value arguments are transmutable for application convenience.

Parameters

pwEnv	The environment block to modify. If NULL, the process environment is modified.
Name	Name of the environment variable.
Value	Specifies the value of the variable. If NULL, the variable is removed.

Side Effects: The function may reallocate a non-null pwEnv, and return the new block in *pwEnv.

On error the function returns false, and GetLastError() has the code.
See also CloneEnvironment(), GetEnvironmentVar(), RtlSetEnvironmentVariable().

Definition at line 841 of file KernelUtil.cpp.

◆ GetEnvironmentVar()

bool GetEnvironmentVar	(	OPTIN WSTR	pwEnv,
		IN CSTR	Name,
		OUT TSTR	Value,
		INOUT PUINT	ccValBuf
	)

GetEnvironmentVar retrieves the value of an environment variable.
This function works with both separate environment blocks and the process environment.

Parameters

pwEnv	The environment block to query. If NULL, the process environment is queried.
Name	Name of the environment variable.
Value	Buffer that recieves the (transmutable) value of the variable.
ccValBuf	On input it specifies the length of the Value buffer, in TCHARs. On output it recieves the length of the retrieved value, in TCHARs. Note: This parameter can not be NULL.

On error the function returns false, and GetLastError() has the code.
See also CloneEnvironment(), SetEnvironmentVar(), RtlQueryEnvironmentVariable_U().

Definition at line 867 of file KernelUtil.cpp.

◆ ModifyEnvironmentVar()

UINT ModifyEnvironmentVar	(	OPTIO WSTR *	pwEnv,
		IN BYTE	Option,
		IN CSTR	Name,
		IN CSTR	Addendum,
		OPTIN TCHAR	Sep
	)

ModifyEnvironmentVar appends or prepends content to an environment variable.
This function works with both separate environment blocks and the process environment.

Parameters

pwEnv	The environment block to modify. If NULL, the process environment is modified.
Name	Name of the environment variable.
Addendum	Content to add to the value of the variable.
Sep	[opt] Separator char to use, e.g ';' for the PATH. Note: In non-unicode builds, if a separator is specified, the resulting value is also deduplicated, keeping only the first instance of each duplicate, which is useful for any kind of list, like PATH or CLASSPATH. When deduplicating, any trailing separator is also removed.
Option	One of MEF_PREPEND or MEF_APPEND.

Returns: Return the length of the modified env variable, or zero on failure.

Side Effects: The function may reallocate a non-null pwEnv, and return the new block in *pwEnv.

◆ DeduplicatePathStr()

UINT DeduplicatePathStr ( INOUT TSTR Path )

DeduplicatePathStr removes duplicate paths from e.g the PATH variable.
Only the first occurence of each duplicate is retained.

Parameters

Path	Buffer containg the path to be culled. Note: The buffer must have room for one extra char at the end, due to temporary in-place conversion to multi-sz.

Returns the length of the culled path. See also DeduplicateCharSepText()
Note: This function is currently not available in _UNICODE builds.
For additional path functions see SHLWAPI, e.g PathCanonicalize().

Module Description

Macros

Enumerations

Functions

Macro Definition Documentation

◆ DeleteEnvironmentVar

Enumeration Type Documentation

◆ eModenvFlags

Function Documentation

◆ GetEnvironmentSize()

◆ CloneEnvironment()

◆ FreeEnvironment()

◆ SetEnvironmentVar()

◆ GetEnvironmentVar()

◆ ModifyEnvironmentVar()

◆ DeduplicatePathStr()