1EFI_VARIABLE_T(3)          Library Functions Manual          EFI_VARIABLE_T(3)
2
3
4

NAME

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

SYNOPSIS

14       #include <efivar.h>
15
16       typedef struct efi_variable efi_variable_t;
17
18       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
21       efi_variable_t *efi_variable_alloc(void);
22       void efi_variable_free(efi_variable_t *var, int free_data);
23
24       int efi_variable_set_name(efi_variable_t *var, char *name);
25       char *efi_variable_get_name(efi_variable_t *var);
26
27       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
30       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
33       #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
43       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
46       int efi_variable_realize(efi_variable_t *var);
47

DESCRIPTION

49       efi_variable_t is an opaque data type used to store variables in-memory
50       for use with this API.
51
52       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
62       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
70       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
75       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
83       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
87       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
91       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
94       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
107       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

RETURN VALUE

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
121       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
129       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
134       efi_variable_get_name() returns a  pointer  the  NUL-terminated  string
135       containing the efi_variable_t object's name information.
136
137       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

AUTHORS

143       Peter Jones <pjones@redhat.com>
144
145
146
147                                Thu Nov 11 2014              EFI_VARIABLE_T(3)
Impressum