util.h

A set of generic helper functions that can be used when working with Netplan data structures. Such as handling of NetplanError data.

Functions

gboolean netplan_delete_connection(const char *id, const char *rootdir)

Parses YAML hierarchy from rootdir, drops the configuration for id from the NetplanState and re-generates the YAML files.

Parameters:

  • id -- [in] The Netplan ID for a specific configuration block of network interface(s)

  • rootdir -- [in] If not NULL, parse configuration from this root directory (useful for testing)

Returns:

Indication of success or failure

ssize_t netplan_get_id_from_nm_filepath(const char *filename, const char *ssid, char *out_buffer, size_t out_buf_size)

Extract the Netplan ID from the filepath of a NetworkManager keyfile.

Copies a NUL-terminated string into a sized out_buffer. If the buffer is too small, its content is not NUL-terminated.

Note

This can be applied to NetworkManager connection profiles generated by Netplan, following a netplan-ID[-SSID].nmconnection naming scheme, as used by the NetworkManager YAML backend.

Parameters:

  • filename -- [in] Full path to a NetworkManager keyfile

  • ssid -- [in] Wi-Fi SSID of this connection profile, or NULL

  • out_buffer -- [out] A pre-allocated buffer to write the output string into, owned by the caller

  • out_buf_size -- [in] The maximum size (in bytes) available for out_buffer

Returns:

The size of the copied string, including the final NUL character. If the buffer is too small, returns NETPLAN_BUFFER_TOO_SMALL instead.

void netplan_error_clear(NetplanError **error)

Free a NetplanError, including any dynamically allocated data.

Free error and set *error to NULL.

Parameters:
ssize_t netplan_error_message(NetplanError *error, char *buf, size_t buf_size)

Get the human readable error message of a NetplanError.

Copies a NUL-terminated string into a sized out_buffer. If the buffer is too small, its content is not NUL-terminated.

Parameters:

  • error -- [in] The NetplanError to query

  • buf -- [out] A pre-allocated buffer to write the output string into, owned by the caller

  • buf_size -- [in] The maximum size (in bytes) available for out_buffer

Returns:

The size of the copied string, including the final NUL character. If the buffer is too small, returns NETPLAN_BUFFER_TOO_SMALL instead.

uint64_t netplan_error_code(NetplanError *error)

Returns a u64 value containing both the NETPLAN_ERROR_DOMAINS and specific error code of that domain.

The two values are concatenated, so relevant data can be masked: (u32)domain | (u32)code

Example: 

     domain = error >> 32  # upper 32 bits
     code = (uint32_t) error  # lower 32 bits

Note

Error codes can be of enumeration type NETPLAN_PARSER_ERRORS, NETPLAN_VALIDATION_ERRORS, NETPLAN_BACKEND_ERRORS, etc.

Returns:

A u64 value containing concatenated NetplanError domain and a specific error code

gboolean netplan_util_create_yaml_patch(const char *conf_obj_path, const char *obj_payload, int out_fd, NetplanError **error)

Create a YAML document from a netplan-set expression.

A set expression here consists of a path formed of TAB-separated keys, indicating where in the YAML file we want to make our changes, and a valid YAML expression that is the payload to insert at that place. The result is a well-formed YAML document. Example: 

     # netplan set "network.ethernets.eth0={dhcp4: true}"
     conf_obj_path = "network\tethernets\teth0"
     obj_payload = "{dhcp4: true}"

Parameters:

  • conf_obj_path -- [in] A TAB-separated YAML path

  • obj_payload -- [in] YAML expression

  • out_fd -- [inout] A file descriptor referencing the output file to contain the resulting YAML document

  • error -- [out] Filled with a NetplanError in case of failure

Returns:

Indication of success or failure

gboolean netplan_util_dump_yaml_subtree(const char *prefix, int input_fd, int output_fd, NetplanError **error)

Get a subset of a YAML document given in input_fd.

A set expression here consists of a path formed of TAB-separated keys, indicating where in the YAML doc we want to make our changes, and a valid YAML expression that is the payload to insert at that place. The result is a well-formed YAML document. Example: 

     # netplan get "network.ethernets.eth0"
     prefix = "network\tethernets\teth0"

Parameters:

  • prefix -- [in] A TAB-separated YAML path

  • input_fd -- [in] A file descriptor, referencing the input YAML file

  • output_fd -- [inout] A file descriptor, referencing the output file to contain the resulting subset of the input YAML file

  • error -- [out] Filled with a NetplanError in case of failure

Returns:

Indication of success or failure