1EFI_VARIABLE_T(3) Library Functions Manual EFI_VARIABLE_T(3)
2
6 efi_variable_import, efi_variable_export, efi_variable_alloc, efi_vari‐
7 able_free, efi_variable_set_name, efi_variable_get_name, efi_vari‐
8 able_set_guid, efi_variable_get_guid, efi_variable_set_data, efi_vari‐
9 able_get_data, efi_variable_set_attributes, efi_vari‐
10 able_get_attributes, efi_variable_realize - utility functions to import
11 and export UEFI variables to files.
12
14 #include <efivar.h>
15 typedef struct efi_variable efi_variable_t;
17 ssize_t efi_variable_import(uint8_t *data, size_t size, efi_variable_t **var);
19 ssize_t efi_variable_export(efi_variable_t *var, uint8_t **data, size_t *size);
20 efi_variable_t *efi_variable_alloc(void);
22 void efi_variable_free(efi_variable_t *var, int free_data);
23 int efi_variable_set_name(efi_variable_t *var, char *name);
25 char *efi_variable_get_name(efi_variable_t *var);
26 int efi_variable_set_guid(efi_variable_t *var, efi_guid_t *guid);
28 int efi_variable_get_guid(efi_variable_t *var, efi_guid_t **guid);
29 int efi_variable_set_data(efi_variable_t *var, uint8_t *data, size_t size);
31 int efi_variable_get_data(efi_variable_t *var, uint8_t **data, size_t *size);
32 #define EFI_VARIABLE_NON_VOLATILE 0x0000000000000001
34 #define EFI_VARIABLE_BOOTSERVICE_ACCESS 0x0000000000000002
35 #define EFI_VARIABLE_RUNTIME_ACCESS 0x0000000000000004
36 #define EFI_VARIABLE_HARDWARE_ERROR_RECORD 0x0000000000000008
37 #define EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS 0x0000000000000010
38 #define EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS 0x0000000000000020
39 #define EFI_VARIABLE_APPEND_WRITE 0x0000000000000040
40 #define EFI_VARIABLE_HAS_AUTH_HEADER 0x0000000100000000
41 #define EFI_VARIABLE_HAS_SIGNATURE 0x0000000200000000
42 int efi_variable_set_attributes(efi_variable_t *var, uint64_t attrs);
44 int efi_variable_get_attributes(efi_variable_t *var, uint64_t *attrs);
45 int efi_variable_realize(efi_variable_t *var);
47
49 efi_variable_t is an opaque data type used to store variables in-memory
50 for use with this API.
51 efi_variable_import() is used to import raw data read from a file.
53 This function returns the amount of data consumed with this variable,
54 and may be used successively, using its return code as an offset, to
55 parse a list of variables. Note that the internal guid, name, and data
56 values are allocated separately, and must be freed either individually
57 or using the free_data parameter of efi_variable_free(). _get() acces‐
58 sors for those values return data suitable for freeing individually,
59 except in such cases where a _set() accessor has been passed an object
60 already unsuitable for that.
61 efi_variable_export() is used to marshall efi_variable_t objects into
63 linear data which can be written to a file. If data or size parameters
64 are not provided, this function will return how much storage a caller
65 must allocate. Otherwise, efi_variable_export() will use the storage
66 referred to as its buffer; if size is smaller than the amount of needed
67 storage , the buffer will not be modified, and the difference between
68 the needed space and size will be returned.
69 efi_variable_alloc() is used to allocate an unpopulated efi_variable_t
71 object suitable to be used throughout this API. efi_variable_free() is
72 used to free an efi_variable_t object, and if free_data is nonzero, to
73 free its constituent data.
74 Each pair of _set() and _get() accessors have essentially the same
76 semantics. Neither operation performs any memory management, including
77 freeing of previously set values or values set by efi_vari‐
78 able_import(), and so in some cases it may be necessary to use a _get()
79 accessor to retrieve an object to be freed. In cases where no value
80 has been set, _get() accessors will set errno to ENOENT and return a
81 negative value or NULL.
82 efi_variable_set_name() and efi_variable_get_name() are used to set and
84 retrieve the name of the variable referred to by the efi_variable_t
85 object.
86 efi_variable_set_guid() and efi_variable_get_guid() are used to set and
88 retrieve the Vendor GUID value of the variable referred to by the
89 efi_variable_t object.
90 efi_variable_set_data() and efi_variable_get_data() are used to set and
92 retrieve an efi_variable_t object's variable data.
93 efi_variable_set_attributes() and efi_variable_get_attributes are used
95 to set and retrieve an efi_variable_t object's attributes. All bits
96 except EFI_VARIABLE_HAS_AUTH_HEADER and EFI_VARIABLE_HAS_SIGNATURE are
97 defined in the UEFI specification and should be used accordingly.
98 EFI_VARIABLE_HAS_AUTH_HEADER should be used by applications to track
99 whether the variable data contents include an authentication header.
100 EFI_VARIABLE_HAS_SIGNATURE should be used by applications to track if
101 the variable's data contents include a signature, and should not be set
102 unless EFI_VARIABLE_HAS_AUTH_HEADER is also set. These attributes are
103 used to track if an exported variable is in a state of partial con‐
104 struction, for example if an authenticated variable has been created
105 but is intended to be signed at a later date.
106 efi_variable_realize() is a convenience function to set or append a
108 UEFI variable on the running system from an efi_variable_t object. its
109 return codes are the same as efi_append_variable(3) if EFI_VARI‐
110 ABLE_APPEND_WRITE is set, and efi_set_variable() if that bit is not
111 set. Additionally, in the case that any of the authentication bits are
112 set, efi_variable_realize() will return error and set errno to EPERM
113 unless both EFI_VARIABLE_HAS_AUTH_HEADER and EFI_VARIABLE_HAS_SIGNATURE
114 attribute bits are been set.
115
117 efi_variable_import() returns 0 on success, and -1 on failure. In
118 cases where it cannot parse the data, errno will be set to EINVAL. In
119 cases where memory has been exhausted, errno will be set to ENOMEM.
120 efi_variable_export() returns the size of the buffer data on success,
122 or a negative value in the case of an error. If data or size parame‐
123 ters are not provided, this function will return how much storage a
124 caller must allocate. Otherwise, this function will use the storage
125 provided in data; if size is less than the needed space, the buffer
126 will not be modified, and the return value will be the difficiency in
127 size.
128 efi_variable_alloc() returns a newly allocated efi_variable_t object,
130 but does not peform any allocation for that object's name, guid, or
131 data. In the case that memory is exhausted, NULL will be returned, and
132 errno will be set to ENOMEM.
133 efi_variable_get_name() returns a pointer the NUL-terminated string
135 containing the efi_variable_t object's name information.
136 efi_variable_set_name(), efi_variable_set_guid(), efi_vari‐
138 able_get_guid(), efi_variable_set_data(), efi_variable_get_data(),
139 efi_variable_set_attributes(), efi_variable_get_attributes(), and
140 efi_variable_realize() return 0 on success and -1 on error.
141
143 Peter Jones <pjones@redhat.com>
144 Thu Nov 11 2014 EFI_VARIABLE_T(3)