Provided by: libefivar-dev_37-6ubuntu2_amd64 bug

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 <efivar.h>

       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) 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 <pjones@redhat.com>

                                         Thu Nov 11 2014                        EFI_VARIABLE_T(3)