--- name: "efi_variable_t" section: "3" platform: "linux" package: "efivar" version: "39-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/efi_variable_t" --- # efi\_variable\_t(3) utility functions to import and export UEFI variables to files. ## NAME efi\_variable\_import, efi\_variable\_export, efi\_variable\_alloc, efi\_variable\_free, efi\_variable\_set\_name, efi\_variable\_get\_name, efi\_variable\_set\_guid, efi\_variable\_get\_guid, efi\_variable\_set\_data, efi\_variable\_get\_data, efi\_variable\_set\_attributes, efi\_variable\_get\_attributes, efi\_variable\_realize - utility functions to import and export UEFI variables to files. ## SYNOPSIS ``` #include typedef struct efi_variable efi_variable_t; ssize_t efi_variable_import(uint8_t *data, size_t size, efi_variable_t **var); ssize_t efi_variable_export(efi_variable_t *var, uint8_t **data, size_t *size); efi_variable_t *efi_variable_alloc(void); void efi_variable_free(efi_variable_t *var, int free_data); int efi_variable_set_name(efi_variable_t *var, char *name); char *efi_variable_get_name(efi_variable_t *var); int efi_variable_set_guid(efi_variable_t *var, efi_guid_t *guid); int efi_variable_get_guid(efi_variable_t *var, efi_guid_t **guid); int efi_variable_set_data(efi_variable_t *var, uint8_t *data, size_t size); int efi_variable_get_data(efi_variable_t *var, uint8_t **data, size_t *size); #define EFI_VARIABLE_NON_VOLATILE 0x0000000000000001 #define EFI_VARIABLE_BOOTSERVICE_ACCESS 0x0000000000000002 #define EFI_VARIABLE_RUNTIME_ACCESS 0x0000000000000004 #define EFI_VARIABLE_HARDWARE_ERROR_RECORD 0x0000000000000008 #define EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS 0x0000000000000010 #define EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS 0x0000000000000020 #define EFI_VARIABLE_APPEND_WRITE 0x0000000000000040 #define EFI_VARIABLE_HAS_AUTH_HEADER 0x0000000100000000 #define EFI_VARIABLE_HAS_SIGNATURE 0x0000000200000000 int efi_variable_set_attributes(efi_variable_t *var, uint64_t attrs); int efi_variable_get_attributes(efi_variable_t *var, uint64_t *attrs); int efi_variable_realize(efi_variable_t *var); ``` ## DESCRIPTION **efi\_variable\_t** is an opaque data type used to store variables in-memory for use with this API. **efi\_variable\_import**() is used to import raw data read from a file. This function returns the amount of data consumed with this variable, and may be used successively, using its return code as an offset, to parse a list of variables. Note that the internal guid, name, and data values are allocated separately, and must be freed either individually or using the **free\_data** parameter of **efi\_variable\_free**(). **\_get**() accessors for those values return data suitable for freeing individually, except in such cases where a **\_set**() accessor has been passed an object already unsuitable for that. **efi\_variable\_export**() is used to marshall **efi\_variable\_t** objects into linear data which can be written to a file. If **data** or **size** parameters are not provided, this function will return how much storage a caller must allocate. Otherwise, **efi\_variable\_export**() will use the storage referred to as its buffer; if **size** is smaller than the amount of needed storage , the buffer will not be modified, and the difference between the needed space and **size** will be returned. **efi\_variable\_alloc**() is used to allocate an unpopulated **efi\_variable\_t** object suitable to be used throughout this API. **efi\_variable\_free**() is used to free an **efi\_variable\_t** object, and if **free\_data** is nonzero, to free its constituent data. Each pair of **\_set**() and **\_get**() accessors have essentially the same semantics. Neither operation performs any memory management, including freeing of previously set values or values set by **efi\_variable\_import**(), and so in some cases it may be necessary to use a **\_get**() accessor to retrieve an object to be freed. In cases where no value has been set, **\_get**() accessors will set **errno** to **ENOENT** and return a negative value or NULL. **efi\_variable\_set\_name**() and **efi\_variable\_get\_name**() are used to set and retrieve the name of the variable referred to by the **efi\_variable\_t** object. **efi\_variable\_set\_guid**() and **efi\_variable\_get\_guid**() are used to set and retrieve the Vendor GUID value of the variable referred to by the **efi\_variable\_t** object. **efi\_variable\_set\_data**() and **efi\_variable\_get\_data**() are used to set and retrieve an **efi\_variable\_t** object's variable data. **efi\_variable\_set\_attributes**() and **efi\_variable\_get\_attributes** are used to set and retrieve an **efi\_variable\_t** object's attributes. All bits except **EFI\_VARIABLE\_HAS\_AUTH\_HEADER** and **EFI\_VARIABLE\_HAS\_SIGNATURE** are defined in the UEFI specification and should be used accordingly. **EFI\_VARIABLE\_HAS\_AUTH\_HEADER** should be used by applications to track whether the variable data contents include an authentication header. **EFI\_VARIABLE\_HAS\_SIGNATURE** should be used by applications to track if the variable's data contents include a signature, and should not be set unless **EFI\_VARIABLE\_HAS\_AUTH\_HEADER** is also set. These attributes are used to track if an exported variable is in a state of partial construction, for example if an authenticated variable has been created but is intended to be signed at a later date. **efi\_variable\_realize**() is a convenience function to set or append a UEFI variable on the running system from an **efi\_variable\_t** object. its return codes are the same as [**efi\_append\_variable**(3)](/efi_append_variable/3.md) if EFI\_VARIABLE\_APPEND\_WRITE is set, and **efi\_set\_variable**() if that bit is not set. Additionally, in the case that any of the authentication bits are set, **efi\_variable\_realize**() will return error and set **errno** to **EPERM** unless both **EFI\_VARIABLE\_HAS\_AUTH\_HEADER** and **EFI\_VARIABLE\_HAS\_SIGNATURE** attribute bits are been set. ## RETURN VALUE **efi\_variable\_import**() returns 0 on success, and -1 on failure. In cases where it cannot parse the data, **errno** will be set to **EINVAL**. In cases where memory has been exhausted, **errno** will be set to **ENOMEM**. **efi\_variable\_export**() returns the size of the buffer data on success, or a negative value in the case of an error. If **data** or **size** parameters are not provided, this function will return how much storage a caller must allocate. Otherwise, this function will use the storage provided in **data**; if **size** is less than the needed space, the buffer will not be modified, and the return value will be the difficiency in size. **efi\_variable\_alloc**() returns a newly allocated **efi\_variable\_t** object, but does not peform any allocation for that object's **name**, **guid**, or **data**. In the case that memory is exhausted, **NULL** will be returned, and **errno** will be set to **ENOMEM**. **efi\_variable\_get\_name**() returns a pointer the NUL-terminated string containing the **efi\_variable\_t** object's name information. **efi\_variable\_set\_name**(), **efi\_variable\_set\_guid**(), **efi\_variable\_get\_guid**(), **efi\_variable\_set\_data**(), **efi\_variable\_get\_data**(), **efi\_variable\_set\_attributes**(), **efi\_variable\_get\_attributes**(), and **efi\_variable\_realize**() return 0 on success and -1 on error. ## AUTHORS ``` Peter Jones ```