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 51The 52.Nm libefi 53library provides access to a select set of the runtime services of the 54Extensible Firmware Interface (EFI). 55.Pp 56The 57.Fn efi_nextvarname 58function is used to enumerate the variables. 59The 60.Fa namesize 61parameter needs to be set to the size of the buffer pointed to by 62.Fa name . 63On return, 64.Fa namesize 65is set to the length of the variable name (including the terminating 66.Ql \e0 ) 67irrespective of whether the buffer was big enough. 68The buffer pointed to by 69.Fa name 70contains the full or partial variable name on return. 71Only on successful completion of the request is the 72.Fa vendor 73updated. 74The values returned should be passed to successive calls to 75.Fn efi_nextvarname 76until all variables have been enumerated. 77.Pp 78The variable name and vendor as returned by 79.Fn efi_nextvarname 80can be passed to 81.Fn efi_getvar 82to obtain the value and attribute of the variable. 83The buffer that is to contain the value is specified by 84.Fa data 85and the size of the buffer is given by 86.Fa datasize . 87The attribute pointed to by 88.Fa attrib 89consists of the bit values defined by the EFI specification. 90.Pp 91Variables can be created, modified and deleted using the 92.Fn efi_setvar 93function. 94All new variables must be non-volatile and runtime accessible in 95order for the request to succeed. 96Note that for runtime accessable variables the boottime accessable bit must 97be set as well. 98To delete a variable, set 99.Fa datasize 100to 0. 101.Pp 102The vendor UUID is used to avoid collisions between variable names of 103different vendors. 104Variables created for use by 105.Fx 106should use the 107.Dv EFI_FREEBSD_VARIABLE 108UUID as defined in the 109.In libefi.h 110header file. 111.Sh RETURN VALUES 112Upon successful completion, these functions return 0. 113Otherwise, the error number is returned. 114These functions will fail if: 115.Bl -tag -width Er 116.It Bq Er EACCES 117Insufficient permissions to access the EFI services. 118.It Bq Er EILSEQ 119The variable name is not in UTF-8. 120.It Bq Er EINVAL 121The request has invalid parameters. 122.It Bq Er ENOENT 123The variable does not exist or no more variables exist. 124.It Bq Er ENOMEM 125Temporary storage could not be allocated. 126.It Bq Er EOVERFLOW 127The variable name is too long or the data is too big to fit in 128the buffer provided. 129.El 130.Sh SEE ALSO 131.Xr errno 2 , 132.Xr uuid 3 133.Sh HISTORY 134The 135.Nm libefi 136library first appeared in 137.Fx 9.0 138for the ia64 architecture. 139.Sh AUTHORS 140The 141.Nm libefi 142library and this manual page were written by 143.An Marcel Moolenaar Aq marcel@FreeBSD.org . 144