lib/libefi/libefi.3

   1 .\"-
   2 .\" Copyright (c) 2010 Marcel Moolenaar
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 29, 2010
  29 .Dt LIBEFI 3
  30 .Os
  31 .Sh NAME
  32 .Nm efi_getvar , efi_nextvarname , efi_setvar
  33 .Nd "interface for accessing the EFI variable services"
  34 .Sh LIBRARY
  35 .Lb libefi
  36 .Sh SYNOPSIS
  37 .In libefi.h
  38 .Ft int
  39 .Fo efi_getvar
  40 .Fa "char *name" "uuid_t *vendor" "uint32_t *attrib"
  41 .Fa "size_t *datasize" "void *data"
  42 .Fc
  43 .Ft int
  44 .Fn efi_nextvarname "size_t *namesize" "char *name" "uuid_t *vendor"
  45 .Ft int
  46 .Fo efi_setvar
  47 .Fa "char *name" "uuid_t *vendor" "uint32_t attrib"
  48 .Fa "size_t datasize" "void *data"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The
  52 .Nm libefi
  53 library provides access to a select set of the runtime services of the
  54 Extensible Firmware Interface (EFI).
  55 .Pp
  56 The
  57 .Fn efi_nextvarname
  58 function is used to enumerate the variables.
  59 The
  60 .Fa namesize
  61 parameter needs to be set to the size of the buffer pointed to by
  62 .Fa name .
  63 On return,
  64 .Fa namesize
  65 is set to the length of the variable name (including the terminating
  66 .Ql \e0 )
  67 irrespective of whether the buffer was big enough.
  68 The buffer pointed to by
  69 .Fa name
  70 contains the full or partial variable name on return.
  71 Only on successful completion of the request is the
  72 .Fa vendor
  73 updated.
  74 The values returned should be passed to successive calls to
  75 .Fn efi_nextvarname
  76 until all variables have been enumerated.
  77 .Pp
  78 The variable name and vendor as returned by
  79 .Fn efi_nextvarname
  80 can be passed to
  81 .Fn efi_getvar
  82 to obtain the value and attribute of the variable.
  83 The buffer that is to contain the value is specified by
  84 .Fa data
  85 and the size of the buffer is given by
  86 .Fa datasize .
  87 The attribute pointed to by
  88 .Fa attrib
  89 consists of the bit values defined by the EFI specification.
  90 .Pp
  91 Variables can be created, modified and deleted using the
  92 .Fn efi_setvar
  93 function.
  94 All new variables must be non-volatile and runtime accessible in
  95 order for the request to succeed.
  96 Note that for runtime accessable variables the boottime accessable bit must
  97 be set as well.
  98 To delete a variable, set
  99 .Fa datasize
 100 to 0.
 101 .Pp
 102 The vendor UUID is used to avoid collisions between variable names of
 103 different vendors.
 104 Variables created for use by
 105 .Fx
 106 should use the
 107 .Dv EFI_FREEBSD_VARIABLE
 108 UUID as defined in the
 109 .In libefi.h
 110 header file.
 111 .Sh RETURN VALUES
 112 Upon successful completion, these functions return 0.
 113 Otherwise, the error number is returned.
 114 These functions will fail if:
 115 .Bl -tag -width Er
 116 .It Bq Er EACCES
 117 Insufficient permissions to access the EFI services.
 118 .It Bq Er EILSEQ
 119 The variable name is not in UTF-8.
 120 .It Bq Er EINVAL
 121 The request has invalid parameters.
 122 .It Bq Er ENOENT
 123 The variable does not exist or no more variables exist.
 124 .It Bq Er ENOMEM
 125 Temporary storage could not be allocated.
 126 .It Bq Er EOVERFLOW
 127 The variable name is too long or the data is too big to fit in
 128 the buffer provided.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr errno 2 ,
 132 .Xr uuid 3
 133 .Sh HISTORY
 134 The
 135 .Nm libefi
 136 library first appeared in
 137 .Fx 9.0
 138 for the ia64 architecture.
 139 .Sh AUTHORS
 140 The
 141 .Nm libefi
 142 library and this manual page were written by
 143 .An Marcel Moolenaar Aq marcel@FreeBSD.org .