nm-utils: libnm Reference Manual

## nm-utils nm-utils |

## 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 | in6_addr
struct | stat

## Object Hierarchy

        GEnum
        ╰── NMUtilsSecurityType

## Description

## Functions

### nm_utils_is_empty_ssid ()

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

### nm_utils_escape_ssid ()

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

### nm_utils_same_ssid ()

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

### nm_utils_ssid_to_utf8 ()

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

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

### nm_utils_ap_mode_security_valid ()

    gboolean
    nm_utils_ap_mode_security_valid (NMUtilsSecurityType type,
                                     NMDeviceWifiCapabilities wifi_caps);

### nm_utils_wep_key_valid ()

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

### nm_utils_wpa_psk_valid ()

    gboolean
    nm_utils_wpa_psk_valid (const char *psk);

### nm_utils_is_json_object ()

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

### nm_utils_ip4_dns_to_variant ()

    GVariant *
    nm_utils_ip4_dns_to_variant (char **dns);

### nm_utils_ip4_dns_from_variant ()

    char **
    nm_utils_ip4_dns_from_variant (GVariant *value);

### nm_utils_ip4_addresses_to_variant ()

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

### nm_utils_ip4_addresses_from_variant ()

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

### nm_utils_ip4_routes_to_variant ()

    GVariant *
    nm_utils_ip4_routes_to_variant (GPtrArray *routes);

### nm_utils_ip4_routes_from_variant ()

    GPtrArray *
    nm_utils_ip4_routes_from_variant (GVariant *value);

### nm_utils_ip4_netmask_to_prefix ()

    guint32
    nm_utils_ip4_netmask_to_prefix (guint32 netmask);

### nm_utils_ip4_prefix_to_netmask ()

    guint32
    nm_utils_ip4_prefix_to_netmask (guint32 prefix);

### nm_utils_ip4_get_default_prefix ()

    guint32
    nm_utils_ip4_get_default_prefix (guint32 ip);

### nm_utils_ip6_dns_to_variant ()

    GVariant *
    nm_utils_ip6_dns_to_variant (char **dns);

### nm_utils_ip6_dns_from_variant ()

    char **
    nm_utils_ip6_dns_from_variant (GVariant *value);

### nm_utils_ip6_addresses_to_variant ()

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

### nm_utils_ip6_addresses_from_variant ()

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

### nm_utils_ip6_routes_to_variant ()

    GVariant *
    nm_utils_ip6_routes_to_variant (GPtrArray *routes);

### nm_utils_ip6_routes_from_variant ()

    GPtrArray *
    nm_utils_ip6_routes_from_variant (GVariant *value);

### nm_utils_ip_addresses_to_variant ()

    GVariant *
    nm_utils_ip_addresses_to_variant (GPtrArray *addresses);

### nm_utils_ip_addresses_from_variant ()

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

### nm_utils_ip_routes_to_variant ()

    GVariant *
    nm_utils_ip_routes_to_variant (GPtrArray *routes);

### nm_utils_ip_routes_from_variant ()

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

### nm_utils_uuid_generate ()

    char *
    nm_utils_uuid_generate (void);

### nm_utils_file_is_certificate ()

    gboolean
    nm_utils_file_is_certificate (const char *filename);

### nm_utils_file_is_private_key ()

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

### nm_utils_file_is_pkcs12 ()

    gboolean
    nm_utils_file_is_pkcs12 (const char *filename);

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

### nm_utils_wifi_freq_to_channel ()

    guint32
    nm_utils_wifi_freq_to_channel (guint32 freq);

### nm_utils_wifi_channel_to_freq ()

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

### nm_utils_wifi_find_next_channel ()

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

### nm_utils_wifi_is_channel_valid ()

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

### nm_utils_wifi_2ghz_freqs ()

    const guint *
    nm_utils_wifi_2ghz_freqs (void);

### nm_utils_wifi_5ghz_freqs ()

    const guint *
    nm_utils_wifi_5ghz_freqs (void);

### nm_utils_wifi_strength_bars ()

    const char *
    nm_utils_wifi_strength_bars (guint8 strength);

### nm_utils_hwaddr_len ()

    gsize
    nm_utils_hwaddr_len (int type);

### nm_utils_hwaddr_ntoa ()

    char *
    nm_utils_hwaddr_ntoa (gconstpointer addr,
                          gsize length);

### nm_utils_hwaddr_atoba ()

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

### nm_utils_hwaddr_aton ()

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

### nm_utils_hwaddr_valid ()

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

### nm_utils_hwaddr_canonical ()

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

### nm_utils_hwaddr_matches ()

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

### nm_utils_bin2hexstr ()

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

### nm_utils_hexstr2bin ()

    GBytes *
    nm_utils_hexstr2bin (const char *hex);

### nm_utils_iface_valid_name ()

    gboolean
    nm_utils_iface_valid_name (const char *name);

`nm_utils_iface_valid_name` is deprecated and should not be used in newly-written code.

### nm_utils_is_valid_iface_name ()

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

### nm_utils_is_uuid ()

    gboolean
    nm_utils_is_uuid (const char *str);

### nm_utils_inet4_ntop ()

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

### nm_utils_inet6_ntop ()

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

### nm_utils_ipaddr_valid ()

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

### nm_utils_check_virtual_device_compatibility ()

    gboolean
    nm_utils_check_virtual_device_compatibility
                                   (GType virtual_type,
                                    GType other_type);

### nm_utils_bond_mode_string_to_int ()

    int
    nm_utils_bond_mode_string_to_int (const char *mode);

### nm_utils_bond_mode_int_to_string ()

    const char *
    nm_utils_bond_mode_int_to_string (int mode);

### nm_utils_enum_to_str ()

    char *
    nm_utils_enum_to_str (GType type,
                          int value);

### nm_utils_enum_from_str ()

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

### nm_utils_enum_get_values ()

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

### nm_utils_version ()

    guint
    nm_utils_version (void);

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

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

### nm_utils_tc_qdisc_to_str ()

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

### nm_utils_tc_action_from_str ()

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

### nm_utils_tc_action_to_str ()

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

### nm_utils_tc_tfilter_from_str ()

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

### nm_utils_tc_tfilter_to_str ()

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

### nm_utils_sriov_vf_to_str ()

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

### nm_utils_sriov_vf_from_str ()

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

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

## 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 |
NMU_SEC_OWE | is used with Enhanced Open |
NMU_SEC_WPA3_SUITE_B_192 | is used with WPA3 Enterprise Suite-B 192 bit mode. Since: 1.30. |

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

    struct in6_addr;

### struct stat

    struct stat;