What Is the UEFI GetNextVariableName Function?

This article explains the purpose, operational mechanics, and practical applications of the GetNextVariableName function provided by the Unified Extensible Firmware Interface (UEFI) Runtime Services. It explores how modern operating systems and firmware utilities use this function to enumerate non-volatile memory (NVRAM) variables, how the sequential iteration algorithm operates, and why it is essential for system initialization, boot management, and firmware configuration.

Purpose of GetNextVariableName

The primary purpose of the GetNextVariableName function is to enumerate the names and unique vendor identifiers (GUIDs) of all UEFI environment variables currently stored in the system. UEFI variables reside in non-volatile memory (NVRAM) or volatile system memory, storing critical platform configurations such as boot options, Secure Boot keys, and hardware state data.

Because UEFI does not maintain a simple, directly accessible file system directory for these variables, software cannot retrieve a complete list in a single call. GetNextVariableName solves this by acting as an iterator, allowing the caller to discover every variable existing on the platform sequentially, even when the caller has no prior knowledge of what variables exist.

How the Iteration Mechanism Works

The function relies on an internal cursor-like mechanism driven by the input parameters provided by the caller. It accepts three main parameters:

  1. VariableNameSize: A pointer to the size of the VariableName buffer in bytes.
  2. VariableName: A pointer to a null-terminated UTF-16 (CHAR16) string buffer representing the variable's name.
  3. VendorGuid: A pointer to the globally unique identifier (EFI_GUID) associated with the vendor of the variable.

The enumeration process follows a strict sequence:

  • Starting the Search: To begin traversing the variable list, the caller passes a pointer to a string containing only a null character (an empty string L""). The firmware identifies this as the starting point and populates the buffer with the name and GUID of the first variable in the system.
  • Continuing the Search: On each successive call, the caller passes the name and vendor GUID returned by the previous invocation. The firmware locates that variable and writes the identifier of the next variable in sequence into the provided buffers.
  • Terminating the Search: Once the firmware reaches the end of the available variables, the function returns EFI_NOT_FOUND. This status indicates that the enumeration is complete.

Buffer Management and Error Handling

Variable names can vary in length, making dynamic buffer management a crucial part of working with GetNextVariableName.

If the buffer supplied by the caller is too small to hold the name of the next variable, the function returns EFI_BUFFER_TOO_SMALL and updates the VariableNameSize parameter to the required size in bytes. The calling software must reallocate a buffer of the indicated size and call GetNextVariableName again using the same preceding variable name and GUID.

Other common status codes include EFI_INVALID_PARAMETER (triggered by null pointers or malformed inputs) and EFI_DEVICE_ERROR (indicating hardware read failures in NVRAM).

Practical Applications

Operating systems, bootloaders, and maintenance utilities rely heavily on GetNextVariableName. Common use cases include:

  • Boot Entry Management: Tools like Linux's efibootmgr use the function to scan for existing Boot#### variables to display or modify the current boot order.
  • Firmware Configuration and Auditing: Security tools query all active variables to inspect Secure Boot configurations, platform keys (PK), and key exchange keys (KEK).
  • Backup and Migration: System backup utilities enumerate and read the full contents of NVRAM using GetNextVariableName in tandem with GetVariable to create exact snapshots of firmware configuration data.