ExGetFirmwareEnvironmentVariable function (wdm.h)
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 |
See also
ExSetFirmwareEnvironmentVariable