CreateEnvironmentBlock function (userenv.h)

Retrieves the environment variables for the specified user. This block can then be passed to the CreateProcessAsUser function.

Syntax

BOOL CreateEnvironmentBlock(
  [out]          LPVOID *lpEnvironment,
  [in, optional] HANDLE hToken,
  [in]           BOOL   bInherit
);

Parameters

[out] lpEnvironment

Type: LPVOID*

When this function returns, receives a pointer to the new environment block. The environment block is an array of null-terminated Unicode strings. The list ends with two nulls (\0\0).

[in, optional] hToken

Type: HANDLE

Token for the user, returned from the LogonUser function. If this is a primary token, the token must have TOKEN_QUERY and TOKEN_DUPLICATE access. If the token is an impersonation token, it must have TOKEN_QUERY access. For more information, see Access Rights for Access-Token Objects.

If this parameter is NULL, the returned environment block contains system variables only.

[in] bInherit

Type: BOOL

Specifies whether to inherit from the current process' environment. If this value is TRUE, the process inherits the current process' environment. If this value is FALSE, the process does not inherit the current process' environment.

Return value

Type: BOOL

TRUE if successful; otherwise, FALSE. To get extended error information, call GetLastError.

Remarks

To free the buffer when you have finished with the environment block, call the DestroyEnvironmentBlock function.

If the environment block is passed to CreateProcessAsUser, you must also specify the CREATE_UNICODE_ENVIRONMENT flag. After CreateProcessAsUser has returned, the new process has a copy of the environment block, and DestroyEnvironmentBlock can be safely called.

User-specific environment variables such as %USERPROFILE% are set only when the user's profile is loaded. To load a user's profile, call the LoadUserProfile function.

Requirements

See also

CreateProcessAsUser

DestroyEnvironmentBlock

LogonUser

User Profiles Overview

User Profiles Reference