nm-utils: libnm Reference Manual

## nm-utils nm-utils — Utility functions |

## Functions

gboolean | nm_utils_is_empty_ssid ()
const char * | nm_utils_escape_ssid ()
gboolean | nm_utils_same_ssid ()
char * | nm_utils_ssid_to_utf8 ()
gboolean | nm_utils_security_valid ()
gboolean | nm_utils_ap_mode_security_valid ()
gboolean | nm_utils_wep_key_valid ()
gboolean | nm_utils_wpa_psk_valid ()
gboolean | nm_utils_is_json_object ()
GVariant * | nm_utils_ip4_dns_to_variant ()
char ** | nm_utils_ip4_dns_from_variant ()
GVariant * | nm_utils_ip4_addresses_to_variant ()
GPtrArray * | nm_utils_ip4_addresses_from_variant ()
GVariant * | nm_utils_ip4_routes_to_variant ()
GPtrArray * | nm_utils_ip4_routes_from_variant ()
guint32 | nm_utils_ip4_netmask_to_prefix ()
guint32 | nm_utils_ip4_prefix_to_netmask ()
guint32 | nm_utils_ip4_get_default_prefix ()
GVariant * | nm_utils_ip6_dns_to_variant ()
char ** | nm_utils_ip6_dns_from_variant ()
GVariant * | nm_utils_ip6_addresses_to_variant ()
GPtrArray * | nm_utils_ip6_addresses_from_variant ()
GVariant * | nm_utils_ip6_routes_to_variant ()
GPtrArray * | nm_utils_ip6_routes_from_variant ()
GVariant * | nm_utils_ip_addresses_to_variant ()
GPtrArray * | nm_utils_ip_addresses_from_variant ()
GVariant * | nm_utils_ip_routes_to_variant ()
GPtrArray * | nm_utils_ip_routes_from_variant ()
char * | nm_utils_uuid_generate ()
gboolean | nm_utils_file_is_certificate ()
gboolean | nm_utils_file_is_private_key ()
gboolean | nm_utils_file_is_pkcs12 ()
gboolean | (*NMUtilsFileSearchInPathsPredicate) ()
gboolean | (*NMUtilsCheckFilePredicate) ()
const char * | nm_utils_file_search_in_paths ()
guint32 | nm_utils_wifi_freq_to_channel ()
guint32 | nm_utils_wifi_channel_to_freq ()
guint32 | nm_utils_wifi_find_next_channel ()
gboolean | nm_utils_wifi_is_channel_valid ()
const guint * | nm_utils_wifi_2ghz_freqs ()
const guint * | nm_utils_wifi_5ghz_freqs ()
const char * | nm_utils_wifi_strength_bars ()
gsize | nm_utils_hwaddr_len ()
char * | nm_utils_hwaddr_ntoa ()
GByteArray * | nm_utils_hwaddr_atoba ()
guint8 * | nm_utils_hwaddr_aton ()
gboolean | nm_utils_hwaddr_valid ()
char * | nm_utils_hwaddr_canonical ()
gboolean | nm_utils_hwaddr_matches ()
char * | nm_utils_bin2hexstr ()
GBytes * | nm_utils_hexstr2bin ()
gboolean | nm_utils_iface_valid_name ()
gboolean | nm_utils_is_valid_iface_name ()
gboolean | nm_utils_is_uuid ()
const char * | nm_utils_inet4_ntop ()
const char * | nm_utils_inet6_ntop ()
gboolean | nm_utils_ipaddr_valid ()
gboolean | nm_utils_check_virtual_device_compatibility ()
int | nm_utils_bond_mode_string_to_int ()
const char * | nm_utils_bond_mode_int_to_string ()
char * | nm_utils_enum_to_str ()
gboolean | nm_utils_enum_from_str ()
const char ** | nm_utils_enum_get_values ()
guint | nm_utils_version ()
GHashTable * | nm_utils_parse_variant_attributes ()
char * | nm_utils_format_variant_attributes ()
NMTCQdisc * | nm_utils_tc_qdisc_from_str ()
char * | nm_utils_tc_qdisc_to_str ()
NMTCAction * | nm_utils_tc_action_from_str ()
char * | nm_utils_tc_action_to_str ()
NMTCTfilter * | nm_utils_tc_tfilter_from_str ()
char * | nm_utils_tc_tfilter_to_str ()
char * | nm_utils_sriov_vf_to_str ()
NMSriovVF * | nm_utils_sriov_vf_from_str ()
gint64 | nm_utils_get_timestamp_msec ()
gboolean | nm_utils_base64secret_decode ()

## Types and Values

enum | NMUtilsSecurityType
#define | NM_UTILS_HWADDR_LEN_MAX
#define | NM_UTILS_INET_ADDRSTRLEN
| NMVariantAttributeSpec
struct | stat

## Object Hierarchy

        GEnum
        ╰── NMUtilsSecurityType

## Description

A collection of utility functions for working with SSIDs, IP addresses, Wi-Fi access points and devices, among other things.

## Functions

### nm_utils_is_empty_ssid ()

    gboolean
    nm_utils_is_empty_ssid (const guint8 *ssid,
                            gsize len);

Different manufacturers use different mechanisms for not broadcasting the AP's SSID. This function attempts to detect blank/empty SSIDs using a number of known SSID-cloaking methods.

#### Parameters

ssid | pointer to a buffer containing the SSID data. | [array length=len]
len | length of the SSID data in `ssid` |

#### Returns

`TRUE` if the SSID is "empty", `FALSE` if it is not

### nm_utils_escape_ssid ()

    const char *
    nm_utils_escape_ssid (const guint8 *ssid,
                          gsize len);

This function does a quick printable character conversion of the SSID, simply replacing embedded NULLs and non-printable characters with the hexadecimal representation of that character. Intended for debugging only, should not be used for display of SSIDs.

#### Parameters

ssid | pointer to a buffer containing the SSID data. | [array length=len]
len | length of the SSID data in `ssid` |

#### Returns

pointer to the escaped SSID, which uses an internal static buffer and will be overwritten by subsequent calls to this function

### nm_utils_same_ssid ()

    gboolean
    nm_utils_same_ssid (const guint8 *ssid1,
                        gsize len1,
                        const guint8 *ssid2,
                        gsize len2,
                        gboolean ignore_trailing_null);

Earlier versions of the Linux kernel added a NULL byte to the end of the SSID to enable easy printing of the SSID on the console or in a terminal, but this behavior was problematic (SSIDs are simply byte arrays, not strings) and thus was changed. This function compensates for that behavior at the cost of some compatibility with odd SSIDs that may legitimately have trailing NULLs, even though that is functionally pointless.

#### Parameters

ssid1 | the first SSID to compare. | [array length=len1]
len1 | length of the SSID data in `ssid1` |
ssid2 | the second SSID to compare. | [array length=len2]
len2 | length of the SSID data in `ssid2` |
ignore_trailing_null | `TRUE` to ignore one trailing NULL byte |

#### Returns

`TRUE` if the SSIDs are the same, `FALSE` if they are not

### nm_utils_ssid_to_utf8 ()

    char *
    nm_utils_ssid_to_utf8 (const guint8 *ssid,
                           gsize len);

Wi-Fi SSIDs are byte arrays, they are _not_ strings. Thus, an SSID may contain embedded NULLs and other unprintable characters. Often it is useful to print the SSID out for debugging purposes, but that should be the _only_ use of this function. Do not use this function for any persistent storage of the SSID, since the printable SSID returned from this function cannot be converted back into the real SSID of the access point.

This function does almost everything humanly possible to convert the input into a printable UTF-8 string, using roughly the following procedure:

1) if the input data is already UTF-8 safe, no conversion is performed 2) attempts to get the current system language from the LANG environment variable, and depending on the language, uses a table of alternative encodings to try. For example, if LANG=hu_HU, the table may first try the ISO-8859-2 encoding, and if that fails, try the Windows-1250 encoding. If all fallback encodings fail, replaces non-UTF-8 characters with '?'. 3) If the system language was unable to be determined, falls back to the ISO-8859-1 encoding, then to the Windows-1251 encoding. 4) If step 3 fails, replaces non-UTF-8 characters with '?'.

Again, this function should be used for debugging and display purposes _only_.

#### Parameters

ssid | pointer to a buffer containing the SSID data. | [array length=len]
len | length of the SSID data in `ssid` |

#### Returns

an allocated string containing a UTF-8 representation of the SSID, which must be freed by the caller using `g_free()`. Returns `NULL` on errors.

[transfer full]

### nm_utils_security_valid ()

    gboolean
    nm_utils_security_valid (NMUtilsSecurityType type,
                             NMDeviceWifiCapabilities wifi_caps,
                             gboolean have_ap,
                             gboolean adhoc,
                             NM80211ApFlags ap_flags,
                             NM80211ApSecurityFlags ap_wpa,
                             NM80211ApSecurityFlags ap_rsn);

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device, desired security type, and AP capabilities intersect.

NOTE: this function cannot handle checking security for AP/Hotspot mode; use `nm_utils_ap_mode_security_valid()` instead.

#### Parameters

type | the security type to check AP flags and device capabilities against, e.g. NMU_SEC_STATIC_WEP |
wifi_caps | bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40 |
have_ap | whether the `ap_flags` , `ap_wpa` , and `ap_rsn` arguments are valid |
adhoc | whether the capabilities being tested are from an Ad-Hoc AP (IBSS) |
ap_flags | bitfield of AP capabilities, e.g. NM_802_11_AP_FLAGS_PRIVACY |
ap_wpa | bitfield of AP capabilities derived from the AP's WPA beacon, e.g. (NM_802_11_AP_SEC_PAIR_TKIP | NM_802_11_AP_SEC_KEY_MGMT_PSK) |
ap_rsn | bitfield of AP capabilities derived from the AP's RSN/WPA2 beacon, e.g. (NM_802_11_AP_SEC_PAIR_CCMP | NM_802_11_AP_SEC_PAIR_TKIP) |

#### Returns

`TRUE` if the device capabilities and AP capabilities intersect and are compatible with the desired `type` , `FALSE` if they are not

### nm_utils_ap_mode_security_valid ()

    gboolean
    nm_utils_ap_mode_security_valid (NMUtilsSecurityType type,
                                     NMDeviceWifiCapabilities wifi_caps);

Given a set of device capabilities, and a desired security type to check against, determines whether the combination of device capabilities and desired security type are valid for AP/Hotspot connections.

#### Parameters

type | the security type to check device capabilities against, e.g. NMU_SEC_STATIC_WEP |
wifi_caps | bitfield of the capabilities of the specific Wi-Fi device, e.g. NM_WIFI_DEVICE_CAP_CIPHER_WEP40 |

#### Returns

`TRUE` if the device capabilities are compatible with the desired `type` , `FALSE` if they are not.

### nm_utils_wep_key_valid ()

    gboolean
    nm_utils_wep_key_valid (const char *key,
                            NMWepKeyType wep_type);

Checks if `key` is a valid WEP key

#### Parameters

key | a string that might be a WEP key |
wep_type | the NMWepKeyType type of the WEP key |

#### Returns

`TRUE` if `key` is a WEP key, `FALSE` if not

### nm_utils_wpa_psk_valid ()

    gboolean
    nm_utils_wpa_psk_valid (const char *psk);

Checks if `psk` is a valid WPA PSK

#### Parameters

psk | a string that might be a WPA PSK |

#### Returns

`TRUE` if `psk` is a WPA PSK, `FALSE` if not

### nm_utils_is_json_object ()

    gboolean
    nm_utils_is_json_object (const char *str,
                             GError **error);

#### Parameters

str | the JSON string to test |
error | optional error reason |

#### Returns

whether the passed string is valid JSON. If libnm is not compiled with libjansson support, this check will also return `TRUE` for possibly invalid inputs. If that is a problem for you, you must validate the JSON yourself.

Since: 1.6

### nm_utils_ip4_dns_to_variant ()

    GVariant *
    nm_utils_ip4_dns_to_variant (char **dns);

Utility function to convert an array of IP address strings int a GVariant of type 'au' representing an array of IPv4 addresses.

#### Parameters

dns | an array of IP address strings. | [type utf8]

#### Returns

a new floating GVariant representing `dns` .

[transfer none]

### nm_utils_ip4_dns_from_variant ()

    char **
    nm_utils_ip4_dns_from_variant (GVariant *value);

Utility function to convert a GVariant of type 'au' representing a list of IPv4 addresses into an array of IP address strings.

#### Parameters

value | a GVariant of type 'au' |

#### Returns

a `NULL`-terminated array of IP address strings.

[transfer full][type utf8]

### nm_utils_ip4_addresses_to_variant ()

    GVariant *
    nm_utils_ip4_addresses_to_variant (GPtrArray *addresses,
                                       const char *gateway);

Utility function to convert a GPtrArray of NMIPAddress objects representing IPv4 addresses into a GVariant of type 'aau' representing an array of NetworkManager IPv4 addresses (which are tuples of address, prefix, and gateway). The "gateway" field of the first address will get the value of `gateway` (if non-`NULL`). In all of the other addresses, that field will be 0.

#### Parameters

addresses | an array of NMIPAddress objects. | [element-type NMIPAddress]
gateway | the gateway IP address. | [allow-none]

#### Returns

a new floating GVariant representing `addresses` .

[transfer none]

### nm_utils_ip4_addresses_from_variant ()

    GPtrArray *
    nm_utils_ip4_addresses_from_variant (GVariant *value,
                                         char **out_gateway);

Utility function to convert a GVariant of type 'aau' representing a list of NetworkManager IPv4 addresses (which are tuples of address, prefix, and gateway) into a GPtrArray of NMIPAddress objects. The "gateway" field of the first address (if set) will be returned in `out_gateway` ; the "gateway" fields of the other addresses are ignored.

#### Parameters

value | a GVariant of type 'aau' |
out_gateway | on return, will contain the IP gateway. | [out][allow-none][transfer full]

#### Returns

a newly allocated GPtrArray of NMIPAddress objects.

[transfer full][element-type NMIPAddress]

### nm_utils_ip4_routes_to_variant ()

    GVariant *
    nm_utils_ip4_routes_to_variant (GPtrArray *routes);

Utility function to convert a GPtrArray of NMIPRoute objects representing IPv4 routes into a GVariant of type 'aau' representing an array of NetworkManager IPv4 routes (which are tuples of route, prefix, next hop, and metric).

#### Parameters

routes | an array of NMIP4Route objects. | [element-type NMIPRoute]

#### Returns

a new floating GVariant representing `routes` .

[transfer none]

### nm_utils_ip4_routes_from_variant ()

    GPtrArray *
    nm_utils_ip4_routes_from_variant (GVariant *value);

Utility function to convert a GVariant of type 'aau' representing an array of NetworkManager IPv4 routes (which are tuples of route, prefix, next hop, and metric) into a GPtrArray of NMIPRoute objects.

#### Parameters

value | GVariant of type 'aau' |

#### Returns

a newly allocated GPtrArray of NMIPRoute objects.

[transfer full][element-type NMIPRoute]

### nm_utils_ip4_netmask_to_prefix ()

    guint32
    nm_utils_ip4_netmask_to_prefix (guint32 netmask);

#### Parameters

netmask | an IPv4 netmask in network byte order |

#### Returns

the CIDR prefix represented by the netmask

### nm_utils_ip4_prefix_to_netmask ()

    guint32
    nm_utils_ip4_prefix_to_netmask (guint32 prefix);

#### Parameters

prefix | a CIDR prefix |

#### Returns

the netmask represented by the prefix, in network byte order

### nm_utils_ip4_get_default_prefix ()

    guint32
    nm_utils_ip4_get_default_prefix (guint32 ip);

When the Internet was originally set up, various ranges of IP addresses were segmented into three network classes: A, B, and C. This function will return a prefix that is associated with the IP address specified defining where it falls in the predefined classes.

#### Parameters

ip | an IPv4 address (in network byte order) |

#### Returns

the default class prefix for the given IP

### nm_utils_ip6_dns_to_variant ()

    GVariant *
    nm_utils_ip6_dns_to_variant (char **dns);

Utility function to convert an array of IP address strings int a GVariant of type 'aay' representing an array of IPv6 addresses.

#### Parameters

dns | an array of IP address strings. | [type utf8]

#### Returns

a new floating GVariant representing `dns` .

[transfer none]

### nm_utils_ip6_dns_from_variant ()

    char **
    nm_utils_ip6_dns_from_variant (GVariant *value);

Utility function to convert a GVariant of type 'aay' representing a list of IPv6 addresses into an array of IP address strings. Each "ay" entry must be a IPv6 address in binary form (16 bytes long). Invalid entries are silently ignored.

#### Parameters

value | a GVariant of type 'aay' |

#### Returns

a `NULL`-terminated array of IP address strings.

[transfer full][type utf8]

### nm_utils_ip6_addresses_to_variant ()

    GVariant *
    nm_utils_ip6_addresses_to_variant (GPtrArray *addresses,
                                       const char *gateway);

Utility function to convert a GPtrArray of NMIPAddress objects representing IPv6 addresses into a GVariant of type 'a(ayuay)' representing an array of NetworkManager IPv6 addresses (which are tuples of address, prefix, and gateway). The "gateway" field of the first address will get the value of `gateway` (if non-`NULL`). In all of the other addresses, that field will be all 0s.

#### Parameters

addresses | an array of NMIPAddress objects. | [element-type NMIPAddress]
gateway | the gateway IP address. | [allow-none]

#### Returns

a new floating GVariant representing `addresses` .

[transfer none]

### nm_utils_ip6_addresses_from_variant ()

    GPtrArray *
    nm_utils_ip6_addresses_from_variant (GVariant *value,
                                         char **out_gateway);

Utility function to convert a GVariant of type 'a(ayuay)' representing a list of NetworkManager IPv6 addresses (which are tuples of address, prefix, and gateway) into a GPtrArray of NMIPAddress objects. The "gateway" field of the first address (if set) will be returned in `out_gateway` ; the "gateway" fields of the other addresses are ignored.

#### Parameters

value | a GVariant of type 'a(ayuay)' |
out_gateway | on return, will contain the IP gateway. | [out][allow-none][transfer full]

#### Returns

a newly allocated GPtrArray of NMIPAddress objects.

[transfer full][element-type NMIPAddress]

### nm_utils_ip6_routes_to_variant ()

    GVariant *
    nm_utils_ip6_routes_to_variant (GPtrArray *routes);

Utility function to convert a GPtrArray of NMIPRoute objects representing IPv6 routes into a GVariant of type 'a(ayuayu)' representing an array of NetworkManager IPv6 routes (which are tuples of route, prefix, next hop, and metric).

#### Parameters

routes | an array of NMIPRoute objects. | [element-type NMIPRoute]

#### Returns

a new floating GVariant representing `routes` .

[transfer none]

### nm_utils_ip6_routes_from_variant ()

    GPtrArray *
    nm_utils_ip6_routes_from_variant (GVariant *value);

Utility function to convert a GVariant of type 'a(ayuayu)' representing an array of NetworkManager IPv6 routes (which are tuples of route, prefix, next hop, and metric) into a GPtrArray of NMIPRoute objects.

#### Parameters

value | GVariant of type 'a(ayuayu)' |

#### Returns

a newly allocated GPtrArray of NMIPRoute objects.

[transfer full][element-type NMIPRoute]

### nm_utils_ip_addresses_to_variant ()

    GVariant *
    nm_utils_ip_addresses_to_variant (GPtrArray *addresses);

Utility function to convert a GPtrArray of NMIPAddress objects representing IPv4 or IPv6 addresses into a GVariant of type 'aa{sv}' representing an array of new-style NetworkManager IP addresses. All addresses will include "address" (an IP address string), and "prefix" (a uint). Some addresses may include additional attributes.

#### Parameters

addresses | an array of NMIPAddress objects. | [element-type NMIPAddress]

#### Returns

a new floating GVariant representing `addresses` .

[transfer none]

### nm_utils_ip_addresses_from_variant ()

    GPtrArray *
    nm_utils_ip_addresses_from_variant (GVariant *value,
                                        int family);

Utility function to convert a GVariant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (as described in the documentation for `nm_utils_ip_addresses_to_variant()`) into a GPtrArray of NMIPAddress objects.

#### Parameters

value | a GVariant of type 'aa{sv}' |
family | an IP address family |

#### Returns

a newly allocated GPtrArray of NMIPAddress objects.

[transfer full][element-type NMIPAddress]

### nm_utils_ip_routes_to_variant ()

    GVariant *
    nm_utils_ip_routes_to_variant (GPtrArray *routes);

Utility function to convert a GPtrArray of NMIPRoute objects representing IPv4 or IPv6 routes into a GVariant of type 'aa{sv}' representing an array of new-style NetworkManager IP routes (which are tuples of destination, prefix, next hop, metric, and additional attributes).

#### Parameters

routes | an array of NMIPRoute objects. | [element-type NMIPRoute]

#### Returns

a new floating GVariant representing `routes` .

[transfer none]

### nm_utils_ip_routes_from_variant ()

    GPtrArray *
    nm_utils_ip_routes_from_variant (GVariant *value,
                                     int family);

Utility function to convert a GVariant representing a list of new-style NetworkManager IPv4 or IPv6 addresses (which are tuples of destination, prefix, next hop, metric, and additional attributes) into a GPtrArray of NMIPRoute objects.

#### Parameters

value | a GVariant of type 'aa{sv}' |
family | an IP address family |

#### Returns

a newly allocated GPtrArray of NMIPRoute objects.

[transfer full][element-type NMIPRoute]

### nm_utils_uuid_generate ()

    char *
    nm_utils_uuid_generate (void);

#### Returns

a newly allocated UUID suitable for use as the NMSettingConnection object's “id”: property. Should be freed with `g_free()`

### nm_utils_file_is_certificate ()

    gboolean
    nm_utils_file_is_certificate (const char *filename);

Tests if `filename` has a valid extension for an X.509 certificate file (".cer", ".crt", ".der", or ".pem"), and contains a certificate in a format recognized by NetworkManager.

#### Parameters

filename | name of the file to test |

#### Returns

`TRUE` if the file is a certificate, `FALSE` if it is not

### nm_utils_file_is_private_key ()

    gboolean
    nm_utils_file_is_private_key (const char *filename,
                                  gboolean *out_encrypted);

Tests if `filename` has a valid extension for an X.509 private key file (".der", ".key", ".pem", or ".p12"), and contains a private key in a format recognized by NetworkManager.

#### Parameters

filename | name of the file to test |
out_encrypted | on return, whether the file is encrypted. | [out]

#### Returns

`TRUE` if the file is a private key, `FALSE` if it is not

### nm_utils_file_is_pkcs12 ()

    gboolean
    nm_utils_file_is_pkcs12 (const char *filename);

Tests if `filename` is a PKCS#12 file.

#### Parameters

filename | name of the file to test |

#### Returns

`TRUE` if the file is PKCS#12, `FALSE` if it is not

### NMUtilsFileSearchInPathsPredicate ()

    gboolean
    (*NMUtilsFileSearchInPathsPredicate) (const char *filename,
                                          gpointer user_data);

### NMUtilsCheckFilePredicate ()

    gboolean
    (*NMUtilsCheckFilePredicate) (const char *filename,
                                  const struct stat *stat,
                                  gpointer user_data,
                                  GError **error);

### nm_utils_file_search_in_paths ()

    const char *
    nm_utils_file_search_in_paths (const char *progname,
                                   const char *try_first,
                                   const char *const *paths,
                                   GFileTest file_test_flags,
                                   NMUtilsFileSearchInPathsPredicate predicate,
                                   gpointer user_data,
                                   GError **error);

Searches for a `progname` file in a list of search `paths` .

#### Parameters

progname | the helper program name, like "iptables" Must be a non-empty string, without path separator (/). |
try_first | a custom path to try first before searching. It is silently ignored if it is empty or not an absolute path. | [allow-none]
paths | a `NULL` terminated list of search paths. Can be empty or `NULL`, in which case only `try_first` is checked. | [allow-none]
file_test_flags | the flags passed to `g_file_test()` when searching for `progname` . Set it to 0 to skip the `g_file_test()`. |
predicate | if given, pass the file name to this function for additional checks. This check is performed after the check for `file_test_flags` . You cannot omit both `file_test_flags` and `predicate` . | [scope call]
user_data | user data for `predicate` function. | [closure][allow-none]
error | on failure, set a "not found" error `G_IO_ERROR` `G_IO_ERROR_NOT_FOUND`. | [allow-none]

#### Returns

the full path to the helper, if found, or `NULL` if not found. The returned string is not owned by the caller, but later invocations of the function might overwrite it.

[transfer none]

### nm_utils_wifi_freq_to_channel ()

    guint32
    nm_utils_wifi_freq_to_channel (guint32 freq);

Utility function to translate a Wi-Fi frequency to its corresponding channel.

#### Parameters

freq | frequency |

#### Returns

the channel represented by the frequency or 0

### nm_utils_wifi_channel_to_freq ()

    guint32
    nm_utils_wifi_channel_to_freq (guint32 channel,
                                   const char *band);

Utility function to translate a Wi-Fi channel to its corresponding frequency.

#### Parameters

channel | channel |
band | frequency band for wireless ("a" or "bg") |

#### Returns

the frequency represented by the channel of the band, or -1 when the freq is invalid, or 0 when the band is invalid

### nm_utils_wifi_find_next_channel ()

    guint32
    nm_utils_wifi_find_next_channel (guint32 channel,
                                     int direction,
                                     char *band);

Utility function to find out next/previous Wi-Fi channel for a channel.

#### Parameters

channel | current channel |
direction | whether going downward (0 or less) or upward (1 or more) |
band | frequency band for wireless ("a" or "bg") |

#### Returns

the next channel in the specified direction or 0

### nm_utils_wifi_is_channel_valid ()

    gboolean
    nm_utils_wifi_is_channel_valid (guint32 channel,
                                    const char *band);

Utility function to verify Wi-Fi channel validity.

#### Parameters

channel | channel |
band | frequency band for wireless ("a" or "bg") |

#### Returns

`TRUE` or `FALSE`

### nm_utils_wifi_2ghz_freqs ()

    const guint *
    nm_utils_wifi_2ghz_freqs (void);

Utility function to return 2.4 GHz Wi-Fi frequencies (802.11bg band).

#### Returns

zero-terminated array of frequencies numbers (in MHz)

Since: 1.2

### nm_utils_wifi_5ghz_freqs ()

    const guint *
    nm_utils_wifi_5ghz_freqs (void);

Utility function to return 5 GHz Wi-Fi frequencies (802.11a band).

#### Returns

zero-terminated array of frequencies numbers (in MHz)

Since: 1.2

### nm_utils_wifi_strength_bars ()

    const char *
    nm_utils_wifi_strength_bars (guint8 strength);

Converts `strength` into a 4-character-wide graphical representation of strength suitable for printing to stdout.

Previous versions used to take a guess at the terminal type and possibly return a wide UTF-8 encoded string. Now it always returns a 7-bit clean strings of one to 0 to 4 asterisks. Users that actually need the functionality are encouraged to make their implementations instead.

#### Parameters

strength | the access point strength, from 0 to 100 |

#### Returns

the graphical representation of the access point strength

### nm_utils_hwaddr_len ()

    gsize
    nm_utils_hwaddr_len (int type);

Returns the length in octets of a hardware address of type `type` .

It is an error to call this function with any value other than `ARPHRD_ETHER` or `ARPHRD_INFINIBAND`.

#### Parameters

type | the type of address; either `ARPHRD_ETHER` or `ARPHRD_INFINIBAND` |

#### Returns

the length.

### nm_utils_hwaddr_ntoa ()

    char *
    nm_utils_hwaddr_ntoa (gconstpointer addr,
                          gsize length);

Converts `addr` to textual form.

#### Parameters

addr | a binary hardware address. | [type guint8][array length=length]
length | the length of `addr` |

#### Returns

the textual form of `addr` .

[transfer full]

### nm_utils_hwaddr_atoba ()

    GByteArray *
    nm_utils_hwaddr_atoba (const char *asc,
                           gsize length);

Parses `asc` and converts it to binary form in a GByteArray. See `nm_utils_hwaddr_aton()` if you don't want a GByteArray.

#### Parameters

asc | the ASCII representation of a hardware address |
length | the expected length in bytes of the result |

#### Returns

a new GByteArray, or `NULL` if `asc` couldn't be parsed.

[transfer full]

### nm_utils_hwaddr_aton ()

    guint8 *
    nm_utils_hwaddr_aton (const char *asc,
                          gpointer buffer,
                          gsize length);

Parses `asc` and converts it to binary form in `buffer` . Bytes in `asc` can be sepatared by colons (:), or hyphens (-), but not mixed.

#### Parameters

asc | the ASCII representation of a hardware address |
buffer | buffer to store the result into. | [type guint8][array length=length]
length | the expected length in bytes of the result and the size of the buffer in bytes. |

#### Returns

`buffer` , or `NULL` if `asc` couldn't be parsed or would be shorter or longer than `length` .

### nm_utils_hwaddr_valid ()

    gboolean
    nm_utils_hwaddr_valid (const char *asc,
                           gssize length);

Parses `asc` to see if it is a valid hardware address of the given length.

#### Parameters

asc | the ASCII representation of a hardware address |
length | the length of address that `asc` is expected to convert to (or -1 to accept any length up to `NM_UTILS_HWADDR_LEN_MAX`) |

#### Returns

`TRUE` if `asc` appears to be a valid hardware address of the indicated length, `FALSE` if not.

### nm_utils_hwaddr_canonical ()

    char *
    nm_utils_hwaddr_canonical (const char *asc,
                               gssize length);

Parses `asc` to see if it is a valid hardware address of the given length, and if so, returns it in canonical form (uppercase, with leading 0s as needed, and with colons rather than hyphens).

#### Parameters

asc | the ASCII representation of a hardware address |
length | the length of address that `asc` is expected to convert to (or -1 to accept any length up to `NM_UTILS_HWADDR_LEN_MAX`) |

#### Returns

the canonicalized address if `asc` appears to be a valid hardware address of the indicated length, `NULL` if not.

[transfer full]

### nm_utils_hwaddr_matches ()

    gboolean
    nm_utils_hwaddr_matches (gconstpointer hwaddr1,
                             gssize hwaddr1_len,
                             gconstpointer hwaddr2,
                             gssize hwaddr2_len);

Generalized hardware address comparison function. Tests if `hwaddr1` and `hwaddr2` "equal" (or more precisely, "equivalent"), with several advantages over a simple `memcmp()`:

1. If `hwaddr1_len` or `hwaddr2_len` is -1, then the corresponding address is assumed to be ASCII rather than binary, and will be converted to binary before being compared.

2. If `hwaddr1` or `hwaddr2` is `NULL`, it is treated instead as though it was a zero-filled buffer `hwaddr1_len` or `hwaddr2_len` bytes long.

3. If `hwaddr1` and `hwaddr2` are InfiniBand hardware addresses (that is, if they are `INFINIBAND_ALEN` bytes long in binary form) then only the last 8 bytes are compared, since those are the only bytes that actually identify the hardware. (The other 12 bytes will change depending on the configuration of the InfiniBand fabric that the device is connected to.)

If a passed-in ASCII hardware address cannot be parsed, or would parse to an address larger than `NM_UTILS_HWADDR_LEN_MAX`, then it will silently fail to match. (This means that externally-provided address strings do not need to be sanity-checked before comparing them against known good addresses; they are guaranteed to not match if they are invalid.)

#### Parameters

hwaddr1 | pointer to a binary or ASCII hardware address, or `NULL`. | [nullable]
hwaddr1_len | size of `hwaddr1` , or -1 if `hwaddr1` is ASCII |
hwaddr2 | pointer to a binary or ASCII hardware address, or `NULL`. | [nullable]
hwaddr2_len | size of `hwaddr2` , or -1 if `hwaddr2` is ASCII |

#### Returns

`TRUE` if `hwaddr1` and `hwaddr2` are equivalent, `FALSE` if they are different (or either of them is invalid).

### nm_utils_bin2hexstr ()

    char *
    nm_utils_bin2hexstr (gconstpointer src,
                         gsize len,
                         int final_len);

Converts the byte array `src` into a hexadecimal string. If `final_len` is greater than -1, the returned string is terminated at that index (returned_string[final_len] == '\0'),

#### Parameters

src | an array of bytes. | [type guint8][array length=len]
len | the length of the `src` array |
final_len | an index where to cut off the returned string, or -1 |

#### Returns

the textual form of `bytes` .

[transfer full]

### nm_utils_hexstr2bin ()

    GBytes *
    nm_utils_hexstr2bin (const char *hex);

Converts a hexadecimal string `hex` into an array of bytes. The optional separator ':' may be used between single or pairs of hexadecimal characters, eg "00:11" or "0:1". Any "0x" at the beginning of `hex` is ignored. `hex` may not start or end with ':'.

#### Parameters

hex | a string of hexadecimal characters with optional ':' separators |

#### Returns

the converted bytes, or `NULL` on error.

[transfer full]

### nm_utils_iface_valid_name ()

    gboolean
    nm_utils_iface_valid_name (const char *name);

`nm_utils_iface_valid_name` has been deprecated since version 1.6 and should not be used in newly-written code.

use `nm_utils_is_valid_iface_name()` instead, with better error reporting.

Validate the network interface name.

#### Parameters

name | Name of interface. | [allow-none]

#### Returns

`TRUE` if interface name is valid, otherwise `FALSE` is returned.

Before 1.20, this function did not accept `NULL` as `name` argument. If you want to run against older versions of libnm, don't pass `NULL`.

### nm_utils_is_valid_iface_name ()

    gboolean
    nm_utils_is_valid_iface_name (const char *name,
                                  GError **error);

Validate the network interface name.

This function is a 1:1 copy of the kernel's interface validation function in net/core/dev.c.

#### Parameters

name | Name of interface. | [allow-none]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

`TRUE` if interface name is valid, otherwise `FALSE` is returned.

Before 1.20, this function did not accept `NULL` as `name` argument. If you want to run against older versions of libnm, don't pass `NULL`.

### nm_utils_is_uuid ()

    gboolean
    nm_utils_is_uuid (const char *str);

Checks if `str` is a UUID

#### Parameters

str | a string that might be a UUID. | [allow-none]

#### Returns

`TRUE` if `str` is a UUID, `FALSE` if not

In older versions, `nm_utils_is_uuid()` did not accept `NULL` as `str` argument. Don't pass `NULL` if you run against older versions of libnm.

### nm_utils_inet4_ntop ()

    const char *
    nm_utils_inet4_ntop (in_addr_t inaddr,
                         char *dst);

Wrapper for inet_ntop.

[skip]

#### Parameters

inaddr | the address that should be converted to string. |
dst | the destination buffer, it must contain at least `INET_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` characters. If set to `NULL`, it will return a pointer to an internal, static buffer (shared with `nm_utils_inet6_ntop()`). Beware, that the internal buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or `nm_utils_inet6_ntop()` that does not provide its own `dst` buffer. Also, using the internal buffer is not thread safe. When in doubt, pass your own `dst` buffer to avoid these issues. |

#### Returns

the input buffer `dst` , or a pointer to an internal, static buffer. This function cannot fail.

### nm_utils_inet6_ntop ()

    const char *
    nm_utils_inet6_ntop (const struct in6_addr *in6addr,
                         char *dst);

Wrapper for inet_ntop.

[skip]

#### Parameters

in6addr | the address that should be converted to string. |
dst | the destination buffer, it must contain at least `INET6_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` characters. If set to `NULL`, it will return a pointer to an internal, static buffer (shared with `nm_utils_inet4_ntop()`). Beware, that the internal buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or `nm_utils_inet6_ntop()` that does not provide its own `dst` buffer. Also, using the internal buffer is not thread safe. When in doubt, pass your own `dst` buffer to avoid these issues. |

#### Returns

the input buffer `dst` , or a pointer to an internal, static buffer. `NULL` is not allowed as `in6addr` , otherwise, this function cannot fail.

### nm_utils_ipaddr_valid ()

    gboolean
    nm_utils_ipaddr_valid (int family,
                           const char *ip);

Checks if `ip` contains a valid IP address of the given family.

#### Parameters

family | `AF_INET` or `AF_INET6`, or `AF_UNSPEC` to accept either |
ip | an IP address |

#### Returns

`TRUE` or `FALSE`

### nm_utils_check_virtual_device_compatibility ()

    gboolean
    nm_utils_check_virtual_device_compatibility
                                   (GType virtual_type,
                                    GType other_type);

Determines if a connection of type `virtual_type` can (in the general case) work with connections of type `other_type` .

If `virtual_type` is `NM_TYPE_SETTING_VLAN`, then this checks if `other_type` is a valid type for the parent of a VLAN.

If `virtual_type` is a "master" type (eg, `NM_TYPE_SETTING_BRIDGE`), then this checks if `other_type` is a valid type for a slave of that master.

Note that even if this returns `TRUE` it is not guaranteed that every connection of type `other_type` is compatible with `virtual_type` ; it may depend on the exact configuration of the two connections, or on the capabilities of an underlying device driver.

#### Parameters

virtual_type | a virtual connection type |
other_type | a connection type to test against `virtual_type` |

#### Returns

`TRUE` or `FALSE`

### nm_utils_bond_mode_string_to_int ()

    int
    nm_utils_bond_mode_string_to_int (const char *mode);

Convert bonding mode from string representation to numeric value. See https://www.kernel.org/doc/Documentation/networking/bonding.txt for available modes. The `mode` string can be either a descriptive name or a number (as string).

#### Parameters

mode | bonding mode as string |

#### Returns

numeric bond mode, or -1 on error

Since: 1.2

### nm_utils_bond_mode_int_to_string ()

    const char *
    nm_utils_bond_mode_int_to_string (int mode);

Convert bonding mode from integer value to descriptive name. See https://www.kernel.org/doc/Documentation/networking/bonding.txt for available modes.

#### Parameters

mode | bonding mode as a numeric value |

#### Returns

bonding mode string, or NULL on error

Since: 1.2

### nm_utils_enum_to_str ()

    char *
    nm_utils_enum_to_str (GType type,
                          int value);

Converts an enum value to its string representation. If the enum is a `G_TYPE_FLAGS` the function returns a comma-separated list of matching values. If the value has no corresponding string representation, it is converted to a number. For enums it is converted to a decimal number, for flags to an (unsigned) hex number.

#### Parameters

type | the `GType` of the enum |
value | the value to be translated |

#### Returns

a newly allocated string or `NULL`

Since: 1.2

### nm_utils_enum_from_str ()

    gboolean
    nm_utils_enum_from_str (GType type,
                            const char *str,
                            int *out_value,
                            char **err_token);

Converts a string to the matching enum value.

If the enum is a `G_TYPE_FLAGS` the function returns the logical OR of values matching the comma-separated tokens in the string; if an unknown token is found the function returns `FALSE` and stores a pointer to a newly allocated string containing the unrecognized token in `err_token` .

#### Parameters

type | the `GType` of the enum |
str | the input string |
out_value | the output value. | [out][allow-none]
err_token | location to store the first unrecognized token. | [out][allow-none][transfer full]

#### Returns

`TRUE` if the conversion was successful, `FALSE` otherwise

Since: 1.2

### nm_utils_enum_get_values ()

    const char **
    nm_utils_enum_get_values (GType type,
                              int from,
                              int to);

Returns the list of possible values for a given enum.

#### Parameters

type | the `GType` of the enum |
from | the first element to be returned |
to | the last element to be returned |

#### Returns

a NULL-terminated dynamically-allocated array of static strings or `NULL` on error.

[transfer container]

Since: 1.2

### nm_utils_version ()

    guint
    nm_utils_version (void);

#### Returns

the version ID of the libnm version. That is, the `NM_VERSION` at runtime.

Since: 1.6.0

### nm_utils_parse_variant_attributes ()

    GHashTable *
    nm_utils_parse_variant_attributes (const char *string,
                                       char attr_separator,
                                       char key_value_separator,
                                       gboolean ignore_unknown,
                                       const NMVariantAttributeSpec *const *spec,
                                       GError **error);

Parse attributes from a string.

#### Parameters

string | the input string |
attr_separator | the attribute separator character |
key_value_separator | character separating key and values |
ignore_unknown | whether unknown attributes should be ignored |
spec | the attribute format specifiers |
error | location to store the error on failure. | [out][allow-none]

#### Returns

a GHashTable mapping attribute names to GVariant values. Warning: the variant are still floating references, owned by the hash table. If you take a reference, ensure to sink the one of the hash table first.

[transfer full][element-type utf8 GVariant]

Since: 1.8

### nm_utils_format_variant_attributes ()

    char *
    nm_utils_format_variant_attributes (GHashTable *attributes,
                                        char attr_separator,
                                        char key_value_separator);

### nm_utils_tc_qdisc_from_str ()

    NMTCQdisc *
    nm_utils_tc_qdisc_from_str (const char *str,
                                GError **error);

Parses the tc style string qdisc representation of the queueing discipline to a `NMTCQdisc` instance. Supports a subset of the tc language.

#### Parameters

str | the string representation of a qdisc |
error | location of the error |

#### Returns

the `NMTCQdisc` or `NULL`

Since: 1.12

### nm_utils_tc_qdisc_to_str ()

    char *
    nm_utils_tc_qdisc_to_str (NMTCQdisc *qdisc,
                              GError **error);

Turns the `NMTCQdisc` into a tc style string representation of the queueing discipline.

#### Parameters

qdisc | the `NMTCQdisc` |
error | location of the error |

#### Returns

formatted string or `NULL`

Since: 1.12

### nm_utils_tc_action_from_str ()

    NMTCAction *
    nm_utils_tc_action_from_str (const char *str,
                                 GError **error);

Parses the tc style string action representation of the queueing discipline to a `NMTCAction` instance. Supports a subset of the tc language.

#### Parameters

str | the string representation of a action |
error | location of the error |

#### Returns

the `NMTCAction` or `NULL`

Since: 1.12

### nm_utils_tc_action_to_str ()

    char *
    nm_utils_tc_action_to_str (NMTCAction *action,
                               GError **error);

Turns the `NMTCAction` into a tc style string representation of the queueing discipline.

#### Parameters

action | the `NMTCAction` |
error | location of the error |

#### Returns

formatted string or `NULL`

Since: 1.12

### nm_utils_tc_tfilter_from_str ()

    NMTCTfilter *
    nm_utils_tc_tfilter_from_str (const char *str,
                                  GError **error);

Parses the tc style string tfilter representation of the queueing discipline to a `NMTCTfilter` instance. Supports a subset of the tc language.

#### Parameters

str | the string representation of a tfilter |
error | location of the error |

#### Returns

the `NMTCTfilter` or `NULL`

Since: 1.12

### nm_utils_tc_tfilter_to_str ()

    char *
    nm_utils_tc_tfilter_to_str (NMTCTfilter *tfilter,
                                GError **error);

Turns the `NMTCTfilter` into a tc style string representation of the queueing discipline.

#### Parameters

tfilter | the `NMTCTfilter` |
error | location of the error |

#### Returns

formatted string or `NULL`

Since: 1.12

### nm_utils_sriov_vf_to_str ()

    char *
    nm_utils_sriov_vf_to_str (const NMSriovVF *vf,
                              gboolean omit_index,
                              GError **error);

Converts a SR-IOV virtual function object to its string representation.

#### Parameters

vf | the `NMSriovVF` |
omit_index | if `TRUE`, the VF index will be omitted from output string |
error | location to store the error on failure. | [out][allow-none]

#### Returns

a newly allocated string or `NULL` on error

Since: 1.14

### nm_utils_sriov_vf_from_str ()

    NMSriovVF *
    nm_utils_sriov_vf_from_str (const char *str,
                                GError **error);

Converts a string to a SR-IOV virtual function object.

#### Parameters

str | the input string |
error | location to store the error on failure. | [out][allow-none]

#### Returns

the virtual function object.

[transfer full]

Since: 1.14

### nm_utils_get_timestamp_msec ()

    gint64
    nm_utils_get_timestamp_msec (void);

### nm_utils_base64secret_decode ()

    gboolean
    nm_utils_base64secret_decode (const char *base64_key,
                                  gsize required_key_len,
                                  guint8 *out_key);

#### Parameters

base64_key | the (possibly invalid) base64 encode key. |
required_key_len | the expected (binary) length of the key after decoding. If the length does not match, the validation fails. |
out_key | (out): an optional output buffer for the binary key. If given, it will be filled with exactly `required_key_len` bytes. | [allow-none]

#### Returns

`TRUE` if the input key is a valid base64 encoded key with `required_key_len` bytes.

Since: 1.16

## Types and Values

### enum NMUtilsSecurityType

Describes generic security mechanisms that 802.11 access points may offer. Used with `nm_utils_security_valid()` for checking whether a given access point is compatible with a network device.

#### Members

NMU_SEC_INVALID | unknown or invalid security, placeholder and not used |
NMU_SEC_NONE | unencrypted and open |
NMU_SEC_STATIC_WEP | static WEP keys are used for encryption |
NMU_SEC_LEAP | Cisco LEAP is used for authentication and for generating the dynamic WEP keys automatically |
NMU_SEC_DYNAMIC_WEP | standard 802.1x is used for authentication and generating the dynamic WEP keys automatically |
NMU_SEC_WPA_PSK | WPA1 is used with Pre-Shared Keys (PSK) |
NMU_SEC_WPA_ENTERPRISE | WPA1 is used with 802.1x authentication |
NMU_SEC_WPA2_PSK | WPA2/RSN is used with Pre-Shared Keys (PSK) |
NMU_SEC_WPA2_ENTERPRISE | WPA2 is used with 802.1x authentication |
NMU_SEC_SAE | is used with WPA3 Enterprise |

### NM_UTILS_HWADDR_LEN_MAX

    #define NM_UTILS_HWADDR_LEN_MAX 20 /* INFINIBAND_ALEN */

The maximum length of hardware addresses handled by NetworkManager itself, `nm_utils_hwaddr_len()`, and `nm_utils_hwaddr_aton()`.

### NM_UTILS_INET_ADDRSTRLEN

    #define NM_UTILS_INET_ADDRSTRLEN     INET6_ADDRSTRLEN

Defines the minimal length for a char buffer that is suitable as `dst` argument for both `nm_utils_inet4_ntop()` and `nm_utils_inet6_ntop()`.

### NMVariantAttributeSpec

    typedef struct _NMVariantAttributeSpec NMVariantAttributeSpec;

### struct stat

    struct stat;