fu-common: fwupd Reference Manual

## fu-common fu-common |

## Functions

void | (*FuOutputHandler) ()
gboolean | fu_common_spawn_sync ()
gchar * | fu_common_get_path ()
gchar * | fu_common_realpath ()
GPtrArray * | fu_common_filename_glob ()
gboolean | fu_common_fnmatch ()
gboolean | fu_common_rmtree ()
GPtrArray * | fu_common_get_files_recursive ()
gboolean | fu_common_mkdir_parent ()
gboolean | fu_common_set_contents_bytes ()
GBytes * | fu_common_get_contents_bytes ()
GBytes * | fu_common_get_contents_fd ()
gboolean | fu_common_extract_archive ()
GBytes * | fu_common_firmware_builder ()
GError * | fu_common_error_array_get_best ()
guint64 | fu_common_strtoull ()
gchar * | fu_common_find_program_in_path ()
gchar * | fu_common_strstrip ()
void | fu_common_dump_raw ()
void | fu_common_dump_full ()
void | fu_common_dump_bytes ()
GBytes * | fu_common_bytes_align ()
const guint8 * | fu_bytes_get_data_safe ()
gboolean | fu_common_bytes_is_empty ()
gboolean | fu_common_bytes_compare ()
gboolean | fu_common_bytes_compare_raw ()
GBytes * | fu_common_bytes_pad ()
GBytes * | fu_common_bytes_new_offset ()
gsize | fu_common_strwidth ()
guint8 * | fu_memdup_safe ()
gboolean | fu_memcpy_safe ()
gboolean | fu_common_read_uint8_safe ()
gboolean | fu_common_read_uint16_safe ()
gboolean | fu_common_read_uint32_safe ()
gboolean | fu_common_read_uint64_safe ()
gboolean | fu_common_write_uint8_safe ()
gboolean | fu_common_write_uint16_safe ()
gboolean | fu_common_write_uint32_safe ()
gboolean | fu_common_write_uint64_safe ()
void | fu_byte_array_set_size ()
void | fu_byte_array_set_size_full ()
void | fu_byte_array_align_up ()
void | fu_byte_array_append_uint8 ()
void | fu_byte_array_append_uint16 ()
void | fu_byte_array_append_uint32 ()
void | fu_byte_array_append_uint64 ()
void | fu_byte_array_append_bytes ()
void | fu_common_write_uint16 ()
void | fu_common_write_uint32 ()
void | fu_common_write_uint64 ()
guint16 | fu_common_read_uint16 ()
guint32 | fu_common_read_uint32 ()
guint64 | fu_common_read_uint64 ()
guint | fu_common_string_replace ()
void | fu_common_string_append_kv ()
void | fu_common_string_append_ku ()
void | fu_common_string_append_kx ()
void | fu_common_string_append_kb ()
gchar ** | fu_common_strnsplit ()
gchar * | fu_common_strsafe ()
gchar * | fu_common_strjoin_array ()
gboolean | fu_common_kernel_locked_down ()
gboolean | fu_common_cpuid ()
FuCpuVendor | fu_common_get_cpu_vendor ()
gboolean | fu_common_is_live_media ()
guint64 | fu_common_get_memory_size ()
GPtrArray * | fu_common_get_volumes_by_kind ()
FuVolume * | fu_common_get_volume_by_device ()
FuVolume * | fu_common_get_volume_by_devnum ()
FuVolume * | fu_common_get_esp_for_path ()
FuVolume * | fu_common_get_esp_default ()
guint8 | fu_common_crc8 ()
guint16 | fu_common_crc16 ()
guint32 | fu_common_crc32 ()
guint32 | fu_common_crc32_full ()
gchar * | fu_common_uri_get_scheme ()
gsize | fu_common_align_up ()
const gchar * | fu_battery_state_to_string ()
void | fu_xmlb_builder_insert_kv ()
void | fu_xmlb_builder_insert_kx ()
void | fu_xmlb_builder_insert_kb ()

## Types and Values

enum | FuAppFlags
enum | FuDumpFlags
typedef | FuEndianType
enum | FuPathKind
enum | FuCpuVendor
#define | FU_BATTERY_VALUE_INVALID
enum | FuBatteryState

## Description

## Functions

### FuOutputHandler ()

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

The process spawn iteration callback.

#### Parameters

line | text data |
user_data | 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 | optional FuOutputHandler. | [scope call][nullable]
handler_user_data | the user data to pass to `handler_cb` . | [nullable]
timeout_ms | a timeout in ms, or 0 for no limit |
cancellable | optional GCancellable. | [nullable]
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success

Since: 0.9.7

### 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

Since: 1.0.8

### 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 | optional return location for an error. | [nullable]

#### Returns

a filename, or `NULL` if invalid or not found

Since: 1.2.6

### fu_common_filename_glob ()

    GPtrArray *
    fu_common_filename_glob (const gchar *directory,
                             const gchar *pattern,
                             GError **error);

Returns all the filenames that match a specific glob pattern. Any results are sorted. No matching files will set `error` .

#### Parameters

directory | a directory path |
pattern | a glob pattern, e.g. `*foo*` |
error | optional return location for an error. | [nullable]

#### Returns

matching files, or `NULL`.

[element-type utf8][transfer container]

Since: 1.5.0

### fu_common_fnmatch ()

    gboolean
    fu_common_fnmatch (const gchar *pattern,
                       const gchar *str);

Matches a string against a glob pattern.

#### Parameters

pattern | a glob pattern, e.g. `*foo*` |
str | a string to match against the pattern, e.g. `bazfoobar` |

#### Returns

`TRUE` if the string matched

Since: 1.3.5

### fu_common_rmtree ()

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

Recursively removes a directory.

#### Parameters

directory | a directory name |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success, `FALSE` otherwise

Since: 0.9.7

### 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 | optional return location for an error. | [nullable]

#### Returns

array of files, or `NULL` for error.

[transfer container][element-type utf8]

Since: 1.0.6

### 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 | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success

Since: 0.9.7

### 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 | data to write |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success

Since: 0.9.5

### 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 | optional return location for an error. | [nullable]

#### Returns

a GBytes, or `NULL` for failure

Since: 0.9.7

### 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 | optional return location for an error. | [nullable]

#### Returns

a GBytes, or `NULL`.

[transfer full]

Since: 0.9.5

### fu_common_extract_archive ()

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

Extracts an archive to a directory.

#### Parameters

blob | data archive as a blob |
dir | a directory name to extract to |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` for success

Since: 0.9.7

### 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 | optional return location for an error. | [nullable]

#### Returns

a new GBytes, or `NULL` for error

Since: 0.9.7

### 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]

Since: 1.0.8

### 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

Since: 1.1.2

### fu_common_find_program_in_path ()

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

Looks for a program in the PATH variable

#### Parameters

basename | the program to search |
error | optional return location for an error. | [nullable]

#### Returns

a new gchar, or `NULL` for error

Since: 1.1.2

### 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

Since: 1.1.2

### 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 | optional log domain, typically `G_LOG_DOMAIN`. | [nullable]
title | optional prefix title. | [nullable]
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 | optional log domain, typically `G_LOG_DOMAIN`. | [nullable]
title | optional prefix title. | [nullable]
data | buffer to print |
len | the size of `data` |
columns | break new lines after this many bytes |
flags | dump flags, 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 | optional log domain, typically `G_LOG_DOMAIN`. | [nullable]
title | optional prefix title. | [nullable]
bytes | data blob |

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 | data blob |
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_bytes_get_data_safe ()

    const guint8 *
    fu_bytes_get_data_safe (GBytes *bytes,
                            gsize *bufsz,
                            GError **error);

Get the byte data in the GBytes. This data should not be modified. This function will always return the same pointer for a given GBytes.

If the size of `bytes` is zero, then `NULL` is returned and the `error` is set, which differs in behavior to that of `g_bytes_get_data()`.

This may be useful when calling `g_mapped_file_new()` on a zero-length file.

#### Parameters

bytes | data blob |
bufsz | location to return size of byte data. | [out][optional]
error | optional return location for an error. | [nullable]

#### Returns

a pointer to the byte data, or `NULL`.

Since: 1.6.0

### 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 | data blob |

#### Returns

`TRUE` if `bytes` is empty

Since: 1.2.6

### fu_common_bytes_compare ()

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

Compares the buffers for equality.

#### Parameters

bytes1 | a data blob |
bytes2 | another GBytes |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `bytes1` and `bytes2` are identical

Since: 1.2.6

### fu_common_bytes_compare_raw ()

    gboolean
    fu_common_bytes_compare_raw (const guint8 *buf1,
                                 gsize bufsz1,
                                 const guint8 *buf2,
                                 gsize bufsz2,
                                 GError **error);

Compares the buffers for equality.

#### Parameters

buf1 | a buffer |
bufsz1 | sizeof `buf1` |
buf2 | another buffer |
bufsz2 | sizeof `buf2` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `buf1` and `buf2` are identical

Since: 1.3.2

### fu_common_bytes_pad ()

    GBytes *
    fu_common_bytes_pad (GBytes *bytes,
                         gsize sz);

Pads a GBytes to a minimum `sz` with `0xff`.

#### Parameters

bytes | data blob |
sz | the desired size in bytes |

#### Returns

a data blob.

[transfer full]

Since: 1.3.1

### fu_common_bytes_new_offset ()

    GBytes *
    fu_common_bytes_new_offset (GBytes *bytes,
                                gsize offset,
                                gsize length,
                                GError **error);

Creates a GBytes which is a subsection of another GBytes.

#### Parameters

bytes | data blob |
offset | where subsection starts at |
length | length of subsection |
error | optional return location for an error. | [nullable]

#### Returns

a GBytes, or NULL if range is invalid.

[transfer full]

Since: 1.5.4

### fu_common_strwidth ()

    gsize
    fu_common_strwidth (const gchar *text);

Returns the width of the string in displayed characters on the console.

#### Parameters

text | the string to operate on |

#### Returns

width of text

Since: 1.3.2

### fu_memdup_safe ()

    guint8 *
    fu_memdup_safe (const guint8 *src,
                    gsize n,
                    GError **error);

Duplicates some memory using memdup in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

NOTE: This function intentionally limits allocation size to 1GB.

#### Parameters

src | source buffer |
n | number of bytes to copy from `src` |
error | optional return location for an error. | [nullable]

#### Returns

block of allocated memory, or `NULL` for an error.

[transfer full]

Since: 1.5.6

### fu_memcpy_safe ()

    gboolean
    fu_memcpy_safe (guint8 *dst,
                    gsize dst_sz,
                    gsize dst_offset,
                    const guint8 *src,
                    gsize src_sz,
                    gsize src_offset,
                    gsize n,
                    GError **error);

Copies some memory using memcpy in a safe way. Providing the buffer sizes of both the destination and the source allows us to check for buffer overflow.

Providing the buffer offsets also allows us to check reading past the end of the source buffer. For this reason the caller should NEVER add an offset to `src` or `dst` .

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

dst | destination buffer |
dst_sz | maximum size of `dst` , typically `sizeof(dst)` |
dst_offset | offset in bytes into `dst` to copy to |
src | source buffer |
src_sz | maximum size of `dst` , typically `sizeof(src)` |
src_offset | offset in bytes into `src` to copy from |
n | number of bytes to copy from `src` +`offset` from |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if the bytes were copied, `FALSE` otherwise

Since: 1.3.1

### fu_common_read_uint8_safe ()

    gboolean
    fu_common_read_uint8_safe (const guint8 *buf,
                               gsize bufsz,
                               gsize offset,
                               guint8 *value,
                               GError **error);

Read a value from a buffer in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to copy from |
value | the parsed value. | [out][nullable]
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was set, `FALSE` otherwise

Since: 1.3.3

### fu_common_read_uint16_safe ()

    gboolean
    fu_common_read_uint16_safe (const guint8 *buf,
                                gsize bufsz,
                                gsize offset,
                                guint16 *value,
                                FuEndianType endian,
                                GError **error);

Read a value from a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to copy from |
value | the parsed value. | [out][nullable]
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was set, `FALSE` otherwise

Since: 1.3.3

### fu_common_read_uint32_safe ()

    gboolean
    fu_common_read_uint32_safe (const guint8 *buf,
                                gsize bufsz,
                                gsize offset,
                                guint32 *value,
                                FuEndianType endian,
                                GError **error);

Read a value from a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to copy from |
value | the parsed value. | [out][nullable]
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was set, `FALSE` otherwise

Since: 1.3.3

### fu_common_read_uint64_safe ()

    gboolean
    fu_common_read_uint64_safe (const guint8 *buf,
                                gsize bufsz,
                                gsize offset,
                                guint64 *value,
                                FuEndianType endian,
                                GError **error);

Read a value from a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to copy from |
value | the parsed value. | [out][nullable]
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was set, `FALSE` otherwise

Since: 1.5.8

### fu_common_write_uint8_safe ()

    gboolean
    fu_common_write_uint8_safe (guint8 *buf,
                                gsize bufsz,
                                gsize offset,
                                guint8 value,
                                GError **error);

Write a value to a buffer in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to write to |
value | the value to write |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was written, `FALSE` otherwise

Since: 1.5.8

### fu_common_write_uint16_safe ()

    gboolean
    fu_common_write_uint16_safe (guint8 *buf,
                                 gsize bufsz,
                                 gsize offset,
                                 guint16 value,
                                 FuEndianType endian,
                                 GError **error);

Write a value to a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to write to |
value | the value to write |
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was written, `FALSE` otherwise

Since: 1.5.8

### fu_common_write_uint32_safe ()

    gboolean
    fu_common_write_uint32_safe (guint8 *buf,
                                 gsize bufsz,
                                 gsize offset,
                                 guint32 value,
                                 FuEndianType endian,
                                 GError **error);

Write a value to a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to write to |
value | the value to write |
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was written, `FALSE` otherwise

Since: 1.5.8

### fu_common_write_uint64_safe ()

    gboolean
    fu_common_write_uint64_safe (guint8 *buf,
                                 gsize bufsz,
                                 gsize offset,
                                 guint64 value,
                                 FuEndianType endian,
                                 GError **error);

Write a value to a buffer using a specified endian in a safe way.

You don't need to use this function in "obviously correct" cases, nor should you use it when performance is a concern. Only us it when you're not sure if malicious data from a device or firmware could cause memory corruption.

#### Parameters

buf | source buffer |
bufsz | maximum size of `buf` , typically `sizeof(buf)` |
offset | offset in bytes into `buf` to write to |
value | the value to write |
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if `value` was written, `FALSE` otherwise

Since: 1.5.8

### fu_byte_array_set_size ()

    void
    fu_byte_array_set_size (GByteArray *array,
                            guint length);

Sets the size of the GByteArray, expanding it with NULs if necessary.

#### Parameters

array | a GByteArray |
length | the new size of the GByteArray |

Since: 1.5.0

### fu_byte_array_set_size_full ()

    void
    fu_byte_array_set_size_full (GByteArray *array,
                                 guint length,
                                 guint8 data);

Sets the size of the GByteArray, expanding with `data` as required.

#### Parameters

array | a GByteArray |
length | the new size of the GByteArray |
data | the byte used to pad the array |

Since: 1.6.0

### fu_byte_array_align_up ()

    void
    fu_byte_array_align_up (GByteArray *array,
                            guint8 alignment,
                            guint8 data);

Align a byte array length to a power of 2 boundary, where `alignment` is the bit position to align to. If `alignment` is zero then `array` is unchanged.

#### Parameters

array | a GByteArray |
alignment | align to this power of 2 |
data | the byte used to pad the array |

Since: 1.6.0

### fu_byte_array_append_uint8 ()

    void
    fu_byte_array_append_uint8 (GByteArray *array,
                                guint8 data);

Adds a 8 bit integer to a byte array.

#### Parameters

array | a GByteArray |
data | value |

Since: 1.3.1

### fu_byte_array_append_uint16 ()

    void
    fu_byte_array_append_uint16 (GByteArray *array,
                                 guint16 data,
                                 FuEndianType endian);

Adds a 16 bit integer to a byte array.

#### Parameters

array | a GByteArray |
data | value |
endian | endian type, e.g. G_LITTLE_ENDIAN |

Since: 1.3.1

### fu_byte_array_append_uint32 ()

    void
    fu_byte_array_append_uint32 (GByteArray *array,
                                 guint32 data,
                                 FuEndianType endian);

Adds a 32 bit integer to a byte array.

#### Parameters

array | a GByteArray |
data | value |
endian | endian type, e.g. G_LITTLE_ENDIAN |

Since: 1.3.1

### fu_byte_array_append_uint64 ()

    void
    fu_byte_array_append_uint64 (GByteArray *array,
                                 guint64 data,
                                 FuEndianType endian);

Adds a 64 bit integer to a byte array.

#### Parameters

array | a GByteArray |
data | value |
endian | endian type, e.g. G_LITTLE_ENDIAN |

Since: 1.5.8

### fu_byte_array_append_bytes ()

    void
    fu_byte_array_append_bytes (GByteArray *array,
                                GBytes *bytes);

Adds the contents of a GBytes to a byte array.

#### Parameters

array | a GByteArray |
bytes | data blob |

Since: 1.5.8

### 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 | an endian type, e.g. `G_LITTLE_ENDIAN` |

Since: 1.0.3

### 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 | an endian type, e.g. `G_LITTLE_ENDIAN` |

Since: 1.0.3

### fu_common_write_uint64 ()

    void
    fu_common_write_uint64 (guint8 *buf,
                            guint64 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 | an endian type, e.g. `G_LITTLE_ENDIAN` |

Since: 1.5.8

### 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 | an endian type, e.g. `G_LITTLE_ENDIAN` |

#### Returns

a value in host byte-order

Since: 1.0.3

### 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 | an endian type, e.g. `G_LITTLE_ENDIAN` |

#### Returns

a value in host byte-order

Since: 1.0.3

### fu_common_read_uint64 ()

    guint64
    fu_common_read_uint64 (const guint8 *buf,
                           FuEndianType endian);

Read a value from a buffer using a specified endian.

#### Parameters

buf | a readable buffer |
endian | an endian type, e.g. `G_LITTLE_ENDIAN` |

#### Returns

a value in host byte-order

Since: 1.5.8

### 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

### fu_common_string_append_kv ()

    void
    fu_common_string_append_kv (GString *str,
                                guint idt,
                                const gchar *key,
                                const gchar *value);

Appends a key and string value to a string

#### Parameters

str | a GString |
idt | the indent |
key | a string to append |
value | a string to append |

Since: 1.2.4

### fu_common_string_append_ku ()

    void
    fu_common_string_append_ku (GString *str,
                                guint idt,
                                const gchar *key,
                                guint64 value);

Appends a key and unsigned integer to a string

#### Parameters

str | a GString |
idt | the indent |
key | a string to append |
value | guint64 |

Since: 1.2.4

### fu_common_string_append_kx ()

    void
    fu_common_string_append_kx (GString *str,
                                guint idt,
                                const gchar *key,
                                guint64 value);

Appends a key and hex integer to a string

#### Parameters

str | a GString |
idt | the indent |
key | a string to append |
value | guint64 |

Since: 1.2.4

### fu_common_string_append_kb ()

    void
    fu_common_string_append_kb (GString *str,
                                guint idt,
                                const gchar *key,
                                gboolean value);

Appends a key and boolean value to a string

#### Parameters

str | a GString |
idt | the indent |
key | a string to append |
value | Boolean |

Since: 1.2.4

### fu_common_strnsplit ()

    gchar **
    fu_common_strnsplit (const gchar *str,
                         gsize sz,
                         const gchar *delimiter,
                         gint max_tokens);

Splits a string into a maximum of `max_tokens` pieces, using the given delimiter. If `max_tokens` is reached, the remainder of string is appended to the last token.

#### Parameters

str | a string to split |
sz | size of `str` |
delimiter | a string which specifies the places at which to split the string |
max_tokens | the maximum number of pieces to split `str` into |

#### Returns

a newly-allocated NULL-terminated array of strings.

[transfer full]

Since: 1.3.1

### fu_common_strsafe ()

    gchar *
    fu_common_strsafe (const gchar *str,
                       gsize maxsz);

Converts a string into something that can be safely printed.

#### Parameters

str | a string to make safe for printing. | [nullable]
maxsz | maximum size of returned string |

#### Returns

safe string, or `NULL` if there was nothing valid.

[transfer full]

Since: 1.5.5

### fu_common_strjoin_array ()

    gchar *
    fu_common_strjoin_array (const gchar *separator,
                             GPtrArray *array);

Joins an array of strings together to form one long string, with the optional separator inserted between each of them.

If `array` has no items, the return value will be an empty string. If `array` contains a single item, separator will not appear in the resulting string.

#### Parameters

separator | string to insert between each of the strings. | [nullable]
array | a GPtrArray. | [element-type utf8]

#### Returns

a string

Since: 1.5.6

### fu_common_kernel_locked_down ()

    gboolean
    fu_common_kernel_locked_down (void);

Determines if kernel lockdown in effect

Since: 1.3.8

### fu_common_cpuid ()

    gboolean
    fu_common_cpuid (guint32 leaf,
                     guint32 *eax,
                     guint32 *ebx,
                     guint32 *ecx,
                     guint32 *edx,
                     GError **error);

Calls CPUID and returns the registers for the given leaf.

#### Parameters

leaf | the CPUID level, now called the 'leaf' by Intel |
eax | EAX register. | [out][nullable]
ebx | EBX register. | [out][nullable]
ecx | ECX register. | [out][nullable]
edx | EDX register. | [out][nullable]
error | optional return location for an error. | [nullable]

#### Returns

`TRUE` if the registers are set.

Since: 1.5.0

### fu_common_get_cpu_vendor ()

    FuCpuVendor
    fu_common_get_cpu_vendor (void);

Uses CPUID to discover the CPU vendor.

#### Returns

a CPU vendor, e.g. `FU_CPU_VENDOR_AMD` if the vendor was AMD.

Since: 1.5.5

### fu_common_is_live_media ()

    gboolean
    fu_common_is_live_media (void);

Checks if the user is running from a live media using various heuristics.

#### Returns

`TRUE` if live

Since: 1.4.6

### fu_common_get_memory_size ()

    guint64
    fu_common_get_memory_size (void);

Returns the size of physical memory.

#### Returns

bytes

Since: 1.5.6

### fu_common_get_volumes_by_kind ()

    GPtrArray *
    fu_common_get_volumes_by_kind (const gchar *kind,
                                   GError **error);

Finds all volumes of a specific partition type

#### Parameters

kind | a volume kind, typically a GUID |
error | optional return location for an error. | [nullable]

#### Returns

a GPtrArray, or `NULL` if the kind was not found.

[transfer container][element-type FuVolume]

Since: 1.4.6

### fu_common_get_volume_by_device ()

    FuVolume *
    fu_common_get_volume_by_device (const gchar *device,
                                    GError **error);

Finds the first volume from the specified device.

#### Parameters

device | a device string, typically starting with `/dev/` |
error | optional return location for an error. | [nullable]

#### Returns

a volume, or `NULL` if the device was not found.

[transfer full]

Since: 1.5.1

### fu_common_get_volume_by_devnum ()

    FuVolume *
    fu_common_get_volume_by_devnum (guint32 devnum,
                                    GError **error);

Finds the first volume from the specified device.

#### Parameters

devnum | a device number |
error | optional return location for an error. | [nullable]

#### Returns

a volume, or `NULL` if the device was not found.

[transfer full]

Since: 1.5.1

### fu_common_get_esp_for_path ()

    FuVolume *
    fu_common_get_esp_for_path (const gchar *esp_path,
                                GError **error);

Gets the platform ESP using a UNIX or UDisks path

#### Parameters

esp_path | a path to the ESP |
error | optional return location for an error. | [nullable]

#### Returns

a volume, or `NULL` if the ESP was not found.

[transfer full]

Since: 1.4.6

### fu_common_get_esp_default ()

    FuVolume *
    fu_common_get_esp_default (GError **error);

Gets the platform default ESP

#### Parameters

error | optional return location for an error. | [nullable]

#### Returns

a volume, or `NULL` if the ESP was not found.

[transfer full]

Since: 1.4.6

### fu_common_crc8 ()

    guint8
    fu_common_crc8 (const guint8 *buf,
                    gsize bufsz);

Returns the cyclic redundancy check value for the given memory buffer.

#### Parameters

buf | memory buffer |
bufsz | size of `buf` |

#### Returns

CRC value

Since: 1.5.0

### fu_common_crc16 ()

    guint16
    fu_common_crc16 (const guint8 *buf,
                     gsize bufsz);

Returns the cyclic redundancy check value for the given memory buffer.

#### Parameters

buf | memory buffer |
bufsz | size of `buf` |

#### Returns

CRC value

Since: 1.5.0

### fu_common_crc32 ()

    guint32
    fu_common_crc32 (const guint8 *buf,
                     gsize bufsz);

Returns the cyclic redundancy check value for the given memory buffer.

#### Parameters

buf | memory buffer |
bufsz | size of `buf` |

#### Returns

CRC value

Since: 1.5.0

### fu_common_crc32_full ()

    guint32
    fu_common_crc32_full (const guint8 *buf,
                          gsize bufsz,
                          guint32 crc,
                          guint32 polynomial);

Returns the cyclic redundancy check value for the given memory buffer.

#### Parameters

buf | memory buffer |
bufsz | size of `buf` |
crc | initial CRC value, typically 0xFFFFFFFF |
polynomial | CRC polynomial, typically 0xEDB88320 |

#### Returns

CRC value

Since: 1.5.0

### fu_common_uri_get_scheme ()

    gchar *
    fu_common_uri_get_scheme (const gchar *uri);

Returns the USI scheme for the given URI.

#### Parameters

uri | valid URI, e.g. `https://foo.bar/baz` |

#### Returns

scheme value, or `NULL` if invalid, e.g. `https`

Since: 1.5.6

### fu_common_align_up ()

    gsize
    fu_common_align_up (gsize value,
                        guint8 alignment);

Align a value to a power of 2 boundary, where `alignment` is the bit position to align to. If `alignment` is zero then `value` is always returned unchanged.

#### Parameters

value | value to align |
alignment | align to this power of 2, where 0x1F is the maximum value of 2GB |

#### Returns

aligned value, which will be the same as `value` if already aligned, or `G_MAXSIZE` if the value would overflow

Since: 1.6.0

### fu_battery_state_to_string ()

    const gchar *
    fu_battery_state_to_string (FuBatteryState battery_state);

Converts an enumerated type to a string.

#### Parameters

battery_state | a battery state, e.g. `FU_BATTERY_STATE_FULLY_CHARGED` |

#### Returns

a string, or `NULL` for invalid

Since: 1.6.0

### fu_xmlb_builder_insert_kv ()

    void
    fu_xmlb_builder_insert_kv (XbBuilderNode *bn,
                               const gchar *key,
                               const gchar *value);

Convenience function to add an XML node with a string value. If `value` is `NULL` then no member is added.

#### Parameters

bn | XbBuilderNode |
key | string key |
value | string value |

Since: 1.6.0

### fu_xmlb_builder_insert_kx ()

    void
    fu_xmlb_builder_insert_kx (XbBuilderNode *bn,
                               const gchar *key,
                               guint64 value);

Convenience function to add an XML node with an integer value. If `value` is 0 then no member is added.

#### Parameters

bn | XbBuilderNode |
key | string key |
value | integer value |

Since: 1.6.0

### fu_xmlb_builder_insert_kb ()

    void
    fu_xmlb_builder_insert_kb (XbBuilderNode *bn,
                               const gchar *key,
                               gboolean value);

Convenience function to add an XML node with a boolean value.

#### Parameters

bn | XbBuilderNode |
key | string key |
value | boolean value |

Since: 1.6.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 |

### FuEndianType

    typedef guint FuEndianType;

The endian type, e.g. `G_LITTLE_ENDIAN`

### 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) |
FU_PATH_KIND_PROCFS | The procfs location (IE /proc) |
FU_PATH_KIND_POLKIT_ACTIONS | The directory for policy kit actions (IE /usr/share/polkit-1/actions/) |
FU_PATH_KIND_OFFLINE_TRIGGER | The file for the offline trigger (IE /system-update) |
FU_PATH_KIND_SYSFSDIR_SECURITY | The sysfs security location (IE /sys/kernel/security) |
FU_PATH_KIND_ACPI_TABLES | The location of the ACPI tables |
FU_PATH_KIND_LOCKDIR | The lock directory (IE /run/lock) |

### enum FuCpuVendor

The CPU vendor.

#### Members

FU_CPU_VENDOR_UNKNOWN | Unknown |
FU_CPU_VENDOR_INTEL | Intel |
FU_CPU_VENDOR_AMD | AMD |

### FU_BATTERY_VALUE_INVALID

    #define FU_BATTERY_VALUE_INVALID			101

This value signifies the battery level is either unset, or the value cannot be discovered.

### enum FuBatteryState

The device battery state.

#### Members

FU_BATTERY_STATE_UNKNOWN | Unknown |
FU_BATTERY_STATE_CHARGING | Charging |
FU_BATTERY_STATE_DISCHARGING | Discharging |
FU_BATTERY_STATE_EMPTY | Empty |
FU_BATTERY_STATE_FULLY_CHARGED | Fully charged |