freebsd-dev/lib/libefi/libefi.3

.\"-
.\" Copyright (c) 2010 Marcel Moolenaar
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 29, 2010
.Dt LIBEFI 3
.Os
.Sh NAME
.Nm efi_getvar , efi_nextvarname , efi_setvar
.Nd "interface for accessing the EFI variable services"
.Sh LIBRARY
.Lb libefi
.Sh SYNOPSIS
.In libefi.h
.Ft int
.Fo efi_getvar
.Fa "char *name" "uuid_t *vendor" "uint32_t *attrib"
.Fa "size_t *datasize" "void *data"
.Fc
.Ft int
.Fn efi_nextvarname "size_t *namesize" "char *name" "uuid_t *vendor"
.Ft int
.Fo efi_setvar
.Fa "char *name" "uuid_t *vendor" "uint32_t attrib"
.Fa "size_t datasize" "void *data"
.Fc
.Sh DESCRIPTION
The
.Nm libefi
library provides access to a select set of the runtime services of the
Extensible Firmware Interface (EFI).
.Pp
The
.Fn efi_nextvarname
function is used to enumerate the variables.
The
.Fa namesize
parameter needs to be set to the size of the buffer pointed to by
.Fa name .
On return,
.Fa namesize
is set to the length of the variable name (including the terminating
.Ql \e0 )
irrespective of whether the buffer was big enough.
The buffer pointed to by
.Fa name
contains the full or partial variable name on return.
Only on successful completion of the request is the
.Fa vendor
updated.
The values returned should be passed to successive calls to
.Fn efi_nextvarname
until all variables have been enumerated.
.Pp
The variable name and vendor as returned by
.Fn efi_nextvarname
can be passed to
.Fn efi_getvar
to obtain the value and attribute of the variable.
The buffer that is to contain the value is specified by
.Fa data
and the size of the buffer is given by
.Fa datasize .
The attribute pointed to by
.Fa attrib
consists of the bit values defined by the EFI specification.
.Pp
Variables can be created, modified and deleted using the
.Fn efi_setvar
function.
All new variables must be non-volatile and runtime accessable in
order for the request to succeed.
Note that for runtime accessable variables the boottime accessable bit must
be set as well.
To delete a variable, set
.Fa datasize
to 0.
.Pp
The vendor UUID is used to avoid collisions between variable names of
different vendors.
Variables created for use by
.Fx
should use the
.Dv EFI_FREEBSD_VARIABLE
UUID as defined in the
.In libefi.h
header file.
.Sh RETURN VALUES
Upon successful completion, these functions return 0.
Otherwise, the error number is returned.
These functions will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
Insufficient permissions to access the EFI services.
.It Bq Er EILSEQ
The variable name is not in UTF-8.
.It Bq Er EINVAL
The request has invalid parameters.
.It Bq Er ENOENT
The variable does not exist or no more variables exist.
.It Bq Er ENOMEM
Temporary storage could not be allocated.
.It Bq Er EOVERFLOW
The variable name is too long or the data is too big to fit in
the buffer provided.
.El
.Sh SEE ALSO
.Xr errno 2 ,
.Xr uuid 3
.Sh HISTORY
The
.Nm libefi
library first appeared in
.Fx 9.0
for the ia64 architecture.
.Sh AUTHORS
The
.Nm libefi
library and this manual page were written by
.An Marcel Moolenaar Aq marcel@FreeBSD.org .