fu-common: fwupd Reference Manual

## fu-common fu-common — common functionality for plugins to use |

## Functions

void | (*FuOutputHandler) ()
gboolean | fu_common_spawn_sync ()
gchar * | fu_common_get_path ()
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_write_uint16 ()
void | fu_common_write_uint32 ()
guint16 | fu_common_read_uint16 ()
guint32 | fu_common_read_uint32 ()
guint | fu_common_string_replace ()

## Types and Values

enum | FuAppFlags
enum | FuPathKind
typedef | FuEndianType

## 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,
                          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` |
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_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_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

#### Members

FU_APP_FLAGS_NONE |  |
FU_APP_FLAGS_NO_IDLE_SOURCES |  |
FU_APP_FLAGS_LAST |  |

### enum FuPathKind

#### Members

FU_PATH_KIND_CACHEDIR_PKG |  |
FU_PATH_KIND_DATADIR_PKG |  |
FU_PATH_KIND_EFIAPPDIR |  |
FU_PATH_KIND_LOCALSTATEDIR |  |
FU_PATH_KIND_LOCALSTATEDIR_PKG |  |
FU_PATH_KIND_PLUGINDIR_PKG |  |
FU_PATH_KIND_SYSCONFDIR |  |
FU_PATH_KIND_SYSCONFDIR_PKG |  |
FU_PATH_KIND_SYSFSDIR_FW |  |
FU_PATH_KIND_SYSFSDIR_DRIVERS |  |
FU_PATH_KIND_LAST |  |

### FuEndianType

    typedef guint FuEndianType;