SetFirmwareEnvironmentVariable function

Sets the value of the specified firmware environment variable.


BOOL WINAPI SetFirmwareEnvironmentVariable(
  _In_ LPCTSTR lpName,
  _In_ LPCTSTR lpGuid,
  _In_ PVOID   pBuffer,
  _In_ DWORD   nSize


lpName [in]

The name of the firmware environment variable. The pointer must not be NULL.

lpGuid [in]

The GUID that represents the namespace of the firmware environment variable. The GUID must be a string in the format "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}". If the system does not support GUID-based namespaces, this parameter is ignored.

pBuffer [in]

A pointer to the new value for the firmware environment variable.

nSize [in]

The size of the pBuffer buffer, in bytes. If this parameter is zero, the firmware environment variable is deleted.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Possible error codes include ERROR_INVALID_FUNCTION.


The exact set of firmware environment variables is determined by the boot firmware. The location of these environment variables is also specified by the firmware. For example, on a UEFI-based system, NVRAM contains firmware environment variables that specify system boot settings. For information about specific variables used, see the UEFI specification. For more information about UEFI and Windows, see UEFI and Windows.

Firmware variables are not supported on a legacy BIOS-based system. The SetFirmwareEnvironmentVariable function will always fail on a legacy BIOS-based system, or if Windows was installed using legacy BIOS on a system that supports both legacy BIOS and UEFI. To identify these conditions, call the function with a dummy firmware environment name such as an empty string ("") for the lpName parameter and a dummy GUID such as "{00000000-0000-0000-0000-000000000000}" for the lpGuid parameter. On a legacy BIOS-based system, or on a system that supports both legacy BIOS and UEFI where Windows was installed using legacy BIOS, the function will fail with ERROR_INVALID_FUNCTION. On a UEFI-based system, the function will fail with an error specific to the firmware, such as ERROR_NOACCESS, to indicate that the dummy GUID namespace does not exist.

SetFirmwareEnvironmentVariable is the user-mode equivalent of the ExSetFirmwareEnvironmentVariable kernel-mode routine.


Minimum supported client

Windows Vista, Windows XP with SP1 [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]


Winbase.h (include Windows.h)





Unicode and ANSI names

SetFirmwareEnvironmentVariableW (Unicode) and SetFirmwareEnvironmentVariableA (ANSI)

See also

System Information Functions