Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
EFI_VARIABLE_T(3)	   Library Functions Manual	     EFI_VARIABLE_T(3)

NAME
       efi_variable_import, efi_variable_export, efi_variable_alloc, efi_vari-
       able_free,   efi_variable_set_name,   efi_variable_get_name,  efi_vari-
       able_set_guid, efi_variable_get_guid, efi_variable_set_data,  efi_vari-
       able_get_data,	efi_variable_set_attributes,  efi_variable_get_attrib-
       utes, 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()	acces-
       sors  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 se-
       mantics.	 Neither operation performs any	memory	management,  including
       freeing	of  previously	set  values  or	values set by efi_variable_im-
       port(), and so in some cases it may be necessary	to use a _get()	acces-
       sor 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 nega-
       tive 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 ob-
       ject.

       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 con-
       struction, 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_AP-
       PEND_WRITE is set, and efi_set_variable() if that bit is	not set.   Ad-
       ditionally,  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 at-
       tribute 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 parame-
       ters 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_vari-
       able_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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=efi_variable_set_attributes&sektion=3&manpath=FreeBSD+Ports+15.0.quarterly>

home | help