fu-common

fu-common — common functionality for plugins to use

Functions

Types and Values

Description

Helper functions that can be used by the daemon and plugins.

See also: FuPlugin

Functions

FuOutputHandler ()

void
(*FuOutputHandler) (const gchar *line,
                    gpointer user_data);

fu_common_spawn_sync ()

gboolean
fu_common_spawn_sync (const gchar * const *argv,
                      FuOutputHandler handler_cb,
                      gpointer handler_user_data,
                      guint timeout_ms,
                      GCancellable *cancellable,
                      GError **error);

Runs a subprocess and waits for it to exit. Any output on standard out or standard error will be forwarded to handler_cb as whole lines.

Parameters

argv

The argument list to run

 

handler_cb

A FuOutputHandler or NULL.

[scope call]

handler_user_data

the user data to pass to handler_cb

 

timeout_ms

a timeout in ms, or 0 for no limit

 

cancellable

a GCancellable, or NULL

 

error

A GError or NULL

 

Returns

TRUE for success


fu_common_get_path ()

gchar *
fu_common_get_path (FuPathKind path_kind);

Gets a fwupd-specific system path. These can be overridden with various environment variables, for instance FWUPD_DATADIR.

Parameters

path_kind

A FuPathKind e.g. FU_PATH_KIND_DATADIR_PKG

 

Returns

a system path, or NULL if invalid


fu_common_realpath ()

gchar *
fu_common_realpath (const gchar *filename,
                    GError **error);

Finds the canonicalized absolute filename for a path.

Parameters

filename

a filename

 

error

A GError or NULL

 

Returns

A filename, or NULL if invalid or not found


fu_common_rmtree ()

gboolean
fu_common_rmtree (const gchar *directory,
                  GError **error);

Recursively removes a directory.

Parameters

directory

a directory name

 

error

A GError or NULL

 

Returns

TRUE for success, FALSE otherwise


fu_common_get_files_recursive ()

GPtrArray *
fu_common_get_files_recursive (const gchar *path,
                               GError **error);

Returns every file found under directory , and any subdirectory. If any path under directory cannot be accessed due to permissions an error will be returned.

Parameters

path

a directory name

 

error

A GError or NULL

 

Returns

array of files, or NULL for error.

[element-type][transfer container]


fu_common_mkdir_parent ()

gboolean
fu_common_mkdir_parent (const gchar *filename,
                        GError **error);

Creates any required directories, including any parent directories.

Parameters

filename

A full pathname

 

error

A GError, or NULL

 

Returns

TRUE for success


fu_common_set_contents_bytes ()

gboolean
fu_common_set_contents_bytes (const gchar *filename,
                              GBytes *bytes,
                              GError **error);

Writes a blob of data to a filename, creating the parent directories as required.

Parameters

filename

A filename

 

bytes

The data to write

 

error

A GError, or NULL

 

Returns

TRUE for success


fu_common_get_contents_bytes ()

GBytes *
fu_common_get_contents_bytes (const gchar *filename,
                              GError **error);

Reads a blob of data from a file.

Parameters

filename

A filename

 

error

A GError, or NULL

 

Returns

a GBytes, or NULL for failure


fu_common_get_contents_fd ()

GBytes *
fu_common_get_contents_fd (gint fd,
                           gsize count,
                           GError **error);

Reads a blob from a specific file descriptor.

Note: this will close the fd when done

Parameters

fd

A file descriptor

 

count

The maximum number of bytes to read

 

error

A GError, or NULL

 

Returns

a GBytes, or NULL.

[transfer full]


fu_common_extract_archive ()

gboolean
fu_common_extract_archive (GBytes *blob,
                           const gchar *dir,
                           GError **error);

Extracts an achive to a directory.

Parameters

blob

a GBytes archive as a blob

 

dir

a directory name to extract to

 

error

A GError, or NULL

 

Returns

TRUE for success


fu_common_firmware_builder ()

GBytes *
fu_common_firmware_builder (GBytes *bytes,
                            const gchar *script_fn,
                            const gchar *output_fn,
                            GError **error);

Builds a firmware file using tools from the host session in a bubblewrap jail. Several things happen during build:

  1. The bytes data is untarred to a temporary location

  2. A bubblewrap container is set up

  3. The startup.sh script is run inside the container

  4. The firmware.bin is extracted from the container

  5. The temporary location is deleted

Parameters

bytes

The data to use

 

script_fn

Name of the script to run in the tarball, e.g. startup.sh

 

output_fn

Name of the generated firmware, e.g. firmware.bin

 

error

A GError, or NULL

 

Returns

a new GBytes, or NULL for error


fu_common_error_array_get_best ()

GError *
fu_common_error_array_get_best (GPtrArray *errors);

Finds the 'best' error to show the user from a array of errors, creating a completely bespoke error where required.

Parameters

errors

array of errors.

[element-type GError]

Returns

a GError, never NULL.

[transfer full]


fu_common_strtoull ()

guint64
fu_common_strtoull (const gchar *str);

Converts a string value to an integer. Values are assumed base 10, unless prefixed with "0x" where they are parsed as base 16.

Parameters

str

A string, e.g. "0x1234"

 

Returns

integer value, or 0x0 for error


fu_common_find_program_in_path ()

gchar *
fu_common_find_program_in_path (const gchar *basename,
                                GError **error);

fu_common_strstrip ()

gchar *
fu_common_strstrip (const gchar *str);

Removes leading and trailing whitespace from a constant string.

Parameters

str

A string, e.g. " test "

 

Returns

newly allocated string


fu_common_dump_raw ()

void
fu_common_dump_raw (const gchar *log_domain,
                    const gchar *title,
                    const guint8 *data,
                    gsize len);

Dumps a raw buffer to the screen.

Parameters

log_domain

log domain, typically G_LOG_DOMAIN or NULL

 

title

prefix title, or NULL

 

data

buffer to print

 

len

the size of data

 

Since: 1.2.2


fu_common_dump_full ()

void
fu_common_dump_full (const gchar *log_domain,
                     const gchar *title,
                     const guint8 *data,
                     gsize len,
                     guint columns,
                     FuDumpFlags flags);

Dumps a raw buffer to the screen.

Parameters

log_domain

log domain, typically G_LOG_DOMAIN or NULL

 

title

prefix title, or NULL

 

data

buffer to print

 

len

the size of data

 

columns

break new lines after this many bytes

 

flags

some FuDumpFlags, e.g. FU_DUMP_FLAGS_SHOW_ASCII

 

Since: 1.2.4


fu_common_dump_bytes ()

void
fu_common_dump_bytes (const gchar *log_domain,
                      const gchar *title,
                      GBytes *bytes);

Dumps a byte buffer to the screen.

Parameters

log_domain

log domain, typically G_LOG_DOMAIN or NULL

 

title

prefix title, or NULL

 

bytes

a GBytes

 

Since: 1.2.2


fu_common_bytes_align ()

GBytes *
fu_common_bytes_align (GBytes *bytes,
                       gsize blksz,
                       gchar padval);

Aligns a block of memory to blksize using the padval value; if the block is already aligned then the original bytes is returned.

Parameters

bytes

a GBytes

 

blksz

block size in bytes

 

padval

the byte used to pad the byte buffer

 

Returns

a GBytes, possibly bytes .

[transfer full]

Since: 1.2.4


fu_common_bytes_is_empty ()

gboolean
fu_common_bytes_is_empty (GBytes *bytes);

Checks if a byte array are just empty (0xff) bytes.

Parameters

bytes

a GBytes

 

Returns

TRUE if bytes is empty


fu_common_bytes_compare ()

gboolean
fu_common_bytes_compare (GBytes *bytes1,
                         GBytes *bytes2,
                         GError **error);

Checks if a byte array are just empty (0xff) bytes.

Parameters

bytes1

a GBytes

 

bytes2

another GBytes

 

error

A GError or NULL

 

Returns

TRUE if bytes1 and bytes2 are identical


fu_common_write_uint16 ()

void
fu_common_write_uint16 (guint8 *buf,
                        guint16 val_native,
                        FuEndianType endian);

Writes a value to a buffer using a specified endian.

Parameters

buf

A writable buffer

 

val_native

a value in host byte-order

 

endian

A FuEndianType, e.g. G_LITTLE_ENDIAN

 

fu_common_write_uint32 ()

void
fu_common_write_uint32 (guint8 *buf,
                        guint32 val_native,
                        FuEndianType endian);

Writes a value to a buffer using a specified endian.

Parameters

buf

A writable buffer

 

val_native

a value in host byte-order

 

endian

A FuEndianType, e.g. G_LITTLE_ENDIAN

 

fu_common_read_uint16 ()

guint16
fu_common_read_uint16 (const guint8 *buf,
                       FuEndianType endian);

Read a value from a buffer using a specified endian.

Parameters

buf

A readable buffer

 

endian

A FuEndianType, e.g. G_LITTLE_ENDIAN

 

Returns

a value in host byte-order


fu_common_read_uint32 ()

guint32
fu_common_read_uint32 (const guint8 *buf,
                       FuEndianType endian);

Read a value from a buffer using a specified endian.

Parameters

buf

A readable buffer

 

endian

A FuEndianType, e.g. G_LITTLE_ENDIAN

 

Returns

a value in host byte-order


fu_common_string_replace ()

guint
fu_common_string_replace (GString *string,
                          const gchar *search,
                          const gchar *replace);

Performs multiple search and replace operations on the given string.

Parameters

string

The GString to operate on

 

search

The text to search for

 

replace

The text to use for substitutions

 

Returns

the number of replacements done, or 0 if search is not found.

Since: 1.2.0

Types and Values

enum FuAppFlags

The flags to use when loading an application.

Members

FU_APP_FLAGS_NONE

No flags set

 

FU_APP_FLAGS_NO_IDLE_SOURCES

Disallow idle sources

 

enum FuDumpFlags

The flags to use when configuring debugging

Members

FU_DUMP_FLAGS_NONE

No flags set

 

FU_DUMP_FLAGS_SHOW_ASCII

Show ASCII in debugging dumps

 

FU_DUMP_FLAGS_SHOW_ADDRESSES

Show addresses in debugging dumps

 

enum FuPathKind

Path types to use when dynamically determining a path at runtime

Members

FU_PATH_KIND_CACHEDIR_PKG

The cache directory (IE /var/cache/fwupd)

 

FU_PATH_KIND_DATADIR_PKG

The non-volatile data store (IE /usr/share/fwupd)

 

FU_PATH_KIND_EFIAPPDIR

The location to store EFI apps before install (IE /usr/libexec/fwupd/efi)

 

FU_PATH_KIND_LOCALSTATEDIR

The local state directory (IE /var)

 

FU_PATH_KIND_LOCALSTATEDIR_PKG

The local state directory for the package (IE /var/lib/fwupd)

 

FU_PATH_KIND_PLUGINDIR_PKG

The location to look for plugins for package (IE /usr/lib/[triplet]/fwupd-plugins-3)

 

FU_PATH_KIND_SYSCONFDIR

The configuration location (IE /etc)

 

FU_PATH_KIND_SYSCONFDIR_PKG

The package configuration location (IE /etc/fwupd)

 

FU_PATH_KIND_SYSFSDIR_FW

The sysfs firmware location (IE /sys/firmware)

 

FU_PATH_KIND_SYSFSDIR_DRIVERS

The platform sysfs directory (IE /sys/bus/platform/drivers)

 

FU_PATH_KIND_SYSFSDIR_TPM

The TPM sysfs directory (IE /sys/class/tpm)

 

FuEndianType

typedef guint FuEndianType;