diff options
Diffstat (limited to 'lib/libefi/libefi.3')
-rw-r--r-- | lib/libefi/libefi.3 | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/lib/libefi/libefi.3 b/lib/libefi/libefi.3 new file mode 100644 index 0000000..7350508 --- /dev/null +++ b/lib/libefi/libefi.3 @@ -0,0 +1,143 @@ +.\"- +.\" 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 accessible 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 . |