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.

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.

Warning: this function uses a static buffer. It is not thread-safe. Don't use 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.

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_.

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.

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.

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

nm_utils_wpa_psk_valid ()

gboolean
nm_utils_wpa_psk_valid (const char *psk);

Checks if psk is a valid WPA PSK

nm_utils_is_json_object ()

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

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.

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.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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.

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. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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).

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. Note that invalid routes are discarded but the valid routes are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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

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.

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.

If a string cannot be parsed, it will be silently ignored.

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.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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.

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. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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).

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. Note that invalid routes are ignored but the valid ones are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

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.

Since: 1.42

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. Note that invalid addresses are discarded but the valid addresses are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

Since: 1.42

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. All routes will include "dest" (an IP address string), "prefix" (an uint) and optionally "next-hop" (an IP address string) and "metric" (an uint). Some routes may include additional attributes. Note that invalid routes are discarded and only a warning is emitted, but the valid routes are still returned.

Since: 1.42

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 (as described in the documentation for nm_utils_ip_routes_to_variant()) into a GPtrArray of NMIPRoute objects. Invalid routes are discarded but the valid routes are still returned.

Since 1.46, an empty list is returned if the variant type is not valid (before it was checked as assertion)

Since: 1.42

nm_utils_uuid_generate ()

char *
nm_utils_uuid_generate (void);

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 .

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.

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.

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.

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.

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).

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).

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.

nm_utils_hwaddr_len ()

gsize
nm_utils_hwaddr_len (int type);

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

Before 1.28, it was an error to call this function with any value other than ARPHRD_ETHER or ARPHRD_INFINIBAND.

nm_utils_hwaddr_ntoa ()

char *
nm_utils_hwaddr_ntoa (gconstpointer addr,
                      gsize length);

Converts addr to textual form.

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.

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 separated by colons (:), or hyphens (-), but not mixed.

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.

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).

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():

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.)

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'),

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 ':'.

nm_utils_iface_valid_name ()

gboolean
nm_utils_iface_valid_name (const char *name);

Validate the network interface name.

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.

Since: 1.6

nm_utils_is_uuid ()

gboolean
nm_utils_is_uuid (const char *str);

Checks if str is a UUID

nm_utils_inet4_ntop ()

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

Wrapper for inet_ntop.

[skip]

nm_utils_inet6_ntop ()

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

Wrapper for inet_ntop.

[skip]

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.

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 "controller" type (eg, NM_TYPE_SETTING_BRIDGE), then this checks if other_type is a valid type for a port of that controller.

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.

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).

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.

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.

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 .

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.

Since: 1.2

nm_utils_version ()

guint
nm_utils_version (void);

Since: 1.6

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.

Since: 1.8

nm_utils_format_variant_attributes ()

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

Format attributes to a string.

Since: 1.8

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.

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.

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.

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.

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.

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.

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.

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.

Since: 1.14

nm_utils_get_timestamp_msec ()

gint64
nm_utils_get_timestamp_msec (void);

Gets current time in milliseconds of CLOCK_BOOTTIME.

Since: 1.12

nm_utils_base64secret_decode ()

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

Since: 1.16

nm_utils_ensure_gtypes ()

void
nm_utils_ensure_gtypes (void);

This ensures that all NMSetting GTypes are created. For example, after this call, g_type_from_name("NMSettingConnection") will work.

This cannot fail and does nothing if the type already exists.

Since: 1.42

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.

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;