.TH LIBFWUP 3 "Mon 11 May 2015"
.SH NAME 
libfwup - library to support management of system firmware updates
.SH SYNOPSIS
.nf
#include <\fBfwup.h\fR>
.sp
\fBint \fRfwup_supported\fB(void);\fR\p
 \- test if firmware updating is supported on the running machine

\fBtypedef struct fwup_resource_s \fRfwup_resource\fB;\fR\p
\fBtypedef struct fwup_resource_iter_s \fRfwup_resource_iter\fB;\fR\p

\fBint \fRfwup_resource_iter_create\fB(fwup_resource_iter **\fIiter\fB);\fR\p
\fBint \fRfwup_resource_iter_next\fB(\kZfwup_resource_iter *\fIiter\fB,
.ta \nZu
	fwup_resource **\fIre\fB);\fR\p
\fBint \fRfwup_resource_iter_destroy\fB(fwup_resource_iter **\fIiter\fB);\fR\p
 \- iterate the list of updateable firmware images

\fBint \fRfwup_set_guid\fB(\kZfwup_resource_iter *\fIiter\fB, fwup_resource **\fIre\fB,
.ta \nZu
	const efi_guid_t *\fIguid\fB);\fR\p
 \- manually set a guid for update

\fBint \fRfwup_set_guid_forced\fB(\kZfwup_resource_iter *\fIiter\fB, fwup_resource **\fIre\fB,
.ta \nZu
	const efi_guid_t *\fIguid\fB, bool \fIforce\fB);\fR\p
 \- manually set a guid for update (with a force option)

\fBvoid \fRfwup_resource_free\fB(fwup_resource *\fIre\fB);\fR\p
 \- free resource allocated by \fRfwup_set_guid_forced\fB()\fR

\fBint \fRfwup_set_up_update\fB(fwup_resource *\fIre\fB, uint64_t \fIhw_inst\fB, int \fIinfd\fB);\fR\p
\fBint \fRfwup_clear_status\fB(fwup_resource *\fIre\fB);\fR\p
\fBint \fRfwup_get_guid\fB(fwup_resource *\fIre\fB, efi_guid_t **\fIguid\fB);\fR\p
\fBint \fRfwup_get_fw_version\fB(fwup_resource *\fIre\fB, uint32_t *\fIversion\fB);\fR\p
\fBint \fRfwup_get_fw_type\fB(fwup_resource *\fIre\fB, uint32_t *\fItype\fB);\fR\p
\fBint \fRfwup_get_lowest_supported_fw_version\fB(\kZfwup_resource *\fIre\fB,
.ta \nZu
	uint32_t *\fIversion\fB);\fR\p
\fBint \fRfwup_get_last_attempt_info\fB(\kZfwup_resource *\fIre\fB, uint32_t *\fIversion\fB,
.ta \nZu
	uint32_t *\fIstatus\fB, time_t *\fIwhen\fB);\fR\p
 \- operate on an individual firmware entry

\fBint \fRfwup_get_debug_log\fB(char **\fIutf8\fB, size_t *\fIsize\fB);\fR\p
 \- show the debug log from the last update attempt

\fBvoid \fRfwup_use_existing_media_path\fB(int \fIuse_existing_media_path\fB);\fR\p
 \- instruct fwupdate on whether to reuse old capsule filenames on the ESP.

\fBvoid \fRfwup_set_esp_mountpoint\fB(char *\fIpath\fB);\fR\p
 \- Override detection of the mountpoint for the ESP directory

\fBconst char *\fRfwup_get_esp_mountpoint\fB(void);\fR\p
 \- Get the current mountpoint for the ESP directory

\fBint \fRfwup_get_ux_capsule_info\fB(\kZuint32_t *\fIscreen_x_size\fB,
.tz \nZu
	uint32_t *\fIscreen_y_size\fB);\fR\p
 \- get the dimensions of the screen during boot
.SH DESCRIPTION
.nf
.PP
\fBint \fRfwup_supported\fB(void);\fR
Tests if the current machine supports firmware updates
.PP
\fBtypedef struct fwup_resource_s \fRfwup_resource\fB;\fR\p
\fBtypedef struct fwup_resource_iter_s \fRfwup_resource_iter\fB;\fR\p

\fBint \fRfwup_resource_iter_create\fB(fwup_resource_iter **\fIiter\fB);\fR\p
Create a new firmware resoure iterator \fIiter\fR.

\fBint \fRfwup_resource_iter_next\fB(\kZfwup_resource_iter *\fIiter\fB,
.ta \nZu
	fwup_resource **\fIre\fB);\fR\p
Get the next firmware resource \fIre\fR from iterator \fIiter\fR.

\fBint \fRfwup_resource_iter_destroy\fB(fwup_resource_iter **\fIiter\fB);\fR\p
Destroy firmware resource iterator \fIiter\fR.

\fBint \fRfwup_set_up_update\fB(fwup_resource *\fIre\fB, uint64_t \fIhw_inst\fB, int \fIinfd\fB);\fR\p
Set up an update for resource \fIre\fR, hardware instance number \fIhw_inst\fR,
with the file referenced by the file descriptor \fIinfd\fR.  \fIinfd\fR must
support read\fB(3)\fR.

\fBint \fRfwup_clear_status\fB(fwup_resource *\fIre\fB);\fR\p
Clear the status of the firmware resource \fIre\fR.  This removes any pending
attempt to update it, as well as clearing any pending error report.

\fBint \fRfwup_get_guid\fB(fwup_resource *\fIre\fB, efi_guid_t **\fIguid\fB);\fR\p
Set \fIguid\fR to the GUID which uniquely identifies firmware resource \fIre\fR.

\fBint \fRfwup_get_fw_version\fB(fwup_resource *\fIre\fB, uint32_t *\fIversion\fB);\fR\p
Set \fIversion\fR to the version of the firmware resource \fIre\fR.

#define \fBFWUP_RESOURCE_TYPE_UNKNOWN\fR         0
#define \fBFWUP_RESOURCE_TYPE_SYSTEM_FIRMWARE\fR 1
#define \fBFWUP_RESOURCE_TYPE_DEVICE_FIRMWARE\fR 2
#define \fBFWUP_RESOURCE_TYPE_UEFI_DRIVER\fR     3
\fBint \fRfwup_get_fw_type\fB(fwup_resource *\fIre\fB, uint32_t *\fItype\fB);\fR\p
Set \fItype\fR to the type of the firmware resource \fIre\fR.

\fBint \fRfwup_get_lowest_supported_fw_version\fB(\kZfwup_resource *\fIre\fB,
.ta \nZu
	uint32_t *\fIversion\fB);\fR
Set \fIversion\fR to the lowest firmware version resource \fIre\fR can be
updated to.

\fBint \fRfwup_get_last_attempt_info\fB(\kZfwup_resource *\fIre\fB, uint32_t *\fIversion\fB,
.ta \nZu
	uint32_t *\fIstatus\fB, time_t *\fIwhen\fB);\fR\p
Get the status for the last attempt to update firmware resource \fIre\fR.

\fBint \fRfwup_get_debug_log\fB(char **\fIutf8\fB, size_t *\fIsize\fB);\fR\p
Get the debug log from the last update attempt.  This allocates a buffer
which the caller must free.

\fBvoid \fRfwup_print_update_info\fB(void);\fR\p
Print the information of firmware update status.

\fBvoid \fRfwup_use_existing_media_path\fB(int \fIuse_existing_media_path\fB);\fR\p
Instruct fwupdate on whether to reuse old capsule filenames on the ESP.

\fBvoid \fRfwup_set_esp_mountpoint\fB(char *\fIpath\fB);\fR\p
Override detection of the mountpoint for the ESP directory.

\fBint \fRfwup_get_ux_capsule_info\fB(\kZuint32_t *\fIscreen_x_size\fB,
.tz \nZu
	uint32_t *\fIscreen_y_size\fB);\fR\p
Get the dimensions of the screen during boot.
.SH AUTHORS
.nf
Peter Jones <pjones@redhat.com>
.SH SEE ALSO
\fBerrno\fR(3), \fBstrerror\fR(3), \fBstrerror_r\fR(3)