ExGetFirmwareEnvironmentVariable function (wdm.h)

Article
03/14/2023

The ExGetFirmwareEnvironmentVariable routine gets the value of the specified system firmware environment variable.

Syntax

NTSTATUS ExGetFirmwareEnvironmentVariable(
  [in]            PUNICODE_STRING VariableName,
  [in]            LPGUID          VendorGuid,
  [out, optional] PVOID           Value,
  [in, out]       PULONG          ValueLength,
  [out, optional] PULONG          Attributes
);

Parameters

[in] VariableName

A pointer to a UNICODE_STRING structure that contains the name of the specified environment variable.

[in] VendorGuid

A pointer to a GUID that identifies the vendor associated with the specified environment variable. Environment variables are grouped into namespaces based on their vendor GUIDs. Some hardware platforms might not support vendor GUIDs. On these platforms, all variables are grouped into one, common namespace, and the VendorGuid parameter is ignored.

[out, optional] Value

A pointer to a caller-allocated buffer to which the routine writes the value of the specified environment variable.

[in, out] ValueLength

A pointer to a location that contains the buffer size. On entry, the location pointed to by this parameter contains the size, in bytes, of the caller-supplied Value buffer. Before exiting, the routine writes to this location the size, in bytes, of the variable value. If the routine returns STATUS_SUCCESS, the *ValueLength output value is the number of bytes of data written to the Value buffer. If the routine returns STATUS_BUFFER_TOO_SMALL, *ValueLength is the required buffer size.

[out, optional] Attributes

A pointer to a location to which the routine writes the attributes of the specified environment variable. This parameter is optional and can be set to NULL if the caller does not need the attributes. For more information, see Remarks.

Return value

ExGetFirmwareEnvironmentVariable returns STATUS_SUCCESS if it is successful. Possible return values include the following error status codes.

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	Available system resources are insufficient to complete the requested operation.
STATUS_BUFFER_TOO_SMALL	The Value buffer is too small.
STATUS_VARIABLE_NOT_FOUND	The requested variable does not exist.
STATUS_INVALID_PARAMETER	One of the parameters is not valid.
STATUS_NOT_IMPLEMENTED	This routine is not supported on this platform.
STATUS_UNSUCCESSFUL	The firmware returned an unrecognized error.

Remarks

System firmware environment variables contain data values that are passed between the boot firmware environment implemented in the hardware platform and the operating-system loaders and other software that runs in the firmware environment.

The set of firmware environment variables that is available in a hardware platform depends on the boot firmware. The location of these environment variables is also specified by the firmware. For example, on a UEFI-based platform, NVRAM contains firmware environment variables that specify system boot settings. For information about specific variables used, see the Unified Extensible Firmware Interface Specification at the UEFI website. For more information about UEFI and Windows, see UEFI and Windows.

Firmware environment variables are not supported on a legacy BIOS-based platform. Calls to ExGetFirmwareEnvironmentVariable always fail on a legacy BIOS-based platform; they also fail if Windows was installed using the legacy BIOS on a platform that supports both legacy BIOS and UEFI. To identify these conditions, first use uuidgen or a similar tool to generate a random unique GUID statically. Then call this routine to look for a specific variable name, providing that GUID as the VendorGuid parameter.

On a legacy BIOS-based platform, or on a platform that supports both legacy BIOS and UEFI but in which Windows was installed using the legacy BIOS, the function will fail with STATUS_NOT_IMPLEMENTED. On a UEFI-based platform, the function will fail with an error specific to the firmware, such as STATUS_VARIABLE_NOT_FOUND, to indicate that the dummy GUID namespace does not exist.

If the caller specifies a non-NULL Attributes parameter, the routine writes the attributes of the specified system firmware environment variable to the location pointed to by Attributes. Version 2.3.1 of the UEFI specification defines the following attributes for firmware environment variables.

Variable name	Value
EFI_VARIABLE_NON_VOLATILE	0x00000001
EFI_VARIABLE_BOOTSERVICE_ACCESS	0x00000002
EFI_VARIABLE_RUNTIME_ACCESS	0x00000004
EFI_VARIABLE_HARDWARE_ERROR_RECORD	0x00000008
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS	0x00000010
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS	0x00000020
EFI_VARIABLE_APPEND_WRITE	0x00000040

These attribute values are defined as flag bits. The value written to the ULONG variable pointed to by Attributes is either zero or the bitwise OR of one or more attributes in the preceding table. For more information, see the UEFI specification at the UEFI website.

If you create a backup datastore, you can use this function to save all the boot settings for the platform so they can be restored by calling the ExSetFirmwareEnvironmentVariable routine if needed.

ExGetFirmwareEnvironmentVariable is the kernel-mode equivalent of the Win32 GetFirmwareEnvironmentVariable function.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL