nm-utils

+ + +

nm-utils

nm-utils — Utility functions

Synopsis

gboolean            nm_utils_is_empty_ssid              (const guint8 *ssid,
+                                                         gsize len);
+const char *        nm_utils_escape_ssid                (const guint8 *ssid,
+                                                         gsize len);
+gboolean            nm_utils_same_ssid                  (const guint8 *ssid1,
+                                                         gsize len1,
+                                                         const guint8 *ssid2,
+                                                         gsize len2,
+                                                         gboolean ignore_trailing_null);
+char *              nm_utils_ssid_to_utf8               (const guint8 *ssid,
+                                                         gsize len);
+enum                NMUtilsSecurityType;
+gboolean            nm_utils_security_valid             (NMUtilsSecurityType type,
+                                                         NMDeviceWifiCapabilities wifi_caps,
+                                                         gboolean have_ap,
+                                                         gboolean adhoc,
+                                                         NM80211ApFlags ap_flags,
+                                                         NM80211ApSecurityFlags ap_wpa,
+                                                         NM80211ApSecurityFlags ap_rsn);
+gboolean            nm_utils_ap_mode_security_valid     (NMUtilsSecurityType type,
+                                                         NMDeviceWifiCapabilities wifi_caps);
+gboolean            nm_utils_wep_key_valid              (const char *key,
+                                                         NMWepKeyType wep_type);
+gboolean            nm_utils_wpa_psk_valid              (const char *psk);
+GVariant *          nm_utils_ip4_dns_to_variant         (char **dns);
+char **             nm_utils_ip4_dns_from_variant       (GVariant *value);
+GVariant *          nm_utils_ip4_addresses_to_variant   (GPtrArray *addresses,
+                                                         const char *gateway);
+GPtrArray *         nm_utils_ip4_addresses_from_variant (GVariant *value,
+                                                         char **out_gateway);
+GVariant *          nm_utils_ip4_routes_to_variant      (GPtrArray *routes);
+GPtrArray *         nm_utils_ip4_routes_from_variant    (GVariant *value);
+guint32             nm_utils_ip4_netmask_to_prefix      (guint32 netmask);
+guint32             nm_utils_ip4_prefix_to_netmask      (guint32 prefix);
+guint32             nm_utils_ip4_get_default_prefix     (guint32 ip);
+GVariant *          nm_utils_ip6_dns_to_variant         (char **dns);
+char **             nm_utils_ip6_dns_from_variant       (GVariant *value);
+GVariant *          nm_utils_ip6_addresses_to_variant   (GPtrArray *addresses,
+                                                         const char *gateway);
+GPtrArray *         nm_utils_ip6_addresses_from_variant (GVariant *value,
+                                                         char **out_gateway);
+GVariant *          nm_utils_ip6_routes_to_variant      (GPtrArray *routes);
+GPtrArray *         nm_utils_ip6_routes_from_variant    (GVariant *value);
+GVariant *          nm_utils_ip_addresses_to_variant    (GPtrArray *addresses);
+GPtrArray *         nm_utils_ip_addresses_from_variant  (GVariant *value,
+                                                         int family);
+GVariant *          nm_utils_ip_routes_to_variant       (GPtrArray *routes);
+GPtrArray *         nm_utils_ip_routes_from_variant     (GVariant *value,
+                                                         int family);
+char *              nm_utils_uuid_generate              (void);
+gboolean            nm_utils_file_is_certificate        (const char *filename);
+gboolean            nm_utils_file_is_private_key        (const char *filename,
+                                                         gboolean *out_encrypted);
+gboolean            nm_utils_file_is_pkcs12             (const char *filename);
+gboolean            (*NMUtilsFileSearchInPathsPredicate)
+                                                        (const char *filename,
+                                                         gpointer user_data);
+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);
+guint32             nm_utils_wifi_freq_to_channel       (guint32 freq);
+guint32             nm_utils_wifi_channel_to_freq       (guint32 channel,
+                                                         const char *band);
+guint32             nm_utils_wifi_find_next_channel     (guint32 channel,
+                                                         int direction,
+                                                         char *band);
+gboolean            nm_utils_wifi_is_channel_valid      (guint32 channel,
+                                                         const char *band);
+const char *        nm_utils_wifi_strength_bars         (guint8 strength);
+#define             NM_UTILS_HWADDR_LEN_MAX
+gsize               nm_utils_hwaddr_len                 (int type);
+char *              nm_utils_hwaddr_ntoa                (gconstpointer addr,
+                                                         gsize length);
+GByteArray *        nm_utils_hwaddr_atoba               (const char *asc,
+                                                         gsize length);
+guint8 *            nm_utils_hwaddr_aton                (const char *asc,
+                                                         gpointer buffer,
+                                                         gsize length);
+gboolean            nm_utils_hwaddr_valid               (const char *asc,
+                                                         gssize length);
+char *              nm_utils_hwaddr_canonical           (const char *asc,
+                                                         gssize length);
+gboolean            nm_utils_hwaddr_matches             (gconstpointer hwaddr1,
+                                                         gssize hwaddr1_len,
+                                                         gconstpointer hwaddr2,
+                                                         gssize hwaddr2_len);
+char *              nm_utils_bin2hexstr                 (gconstpointer src,
+                                                         gsize len,
+                                                         int final_len);
+GBytes *            nm_utils_hexstr2bin                 (const char *hex);
+gboolean            nm_utils_iface_valid_name           (const char *name);
+gboolean            nm_utils_is_uuid                    (const char *str);
+#define             NM_UTILS_INET_ADDRSTRLEN
+const char *        nm_utils_inet4_ntop                 (in_addr_t inaddr,
+                                                         char *dst);
+const char *        nm_utils_inet6_ntop                 (const struct in6_addr *in6addr,
+                                                         char *dst);
+gboolean            nm_utils_ipaddr_valid               (int family,
+                                                         const char *ip);
+gboolean            nm_utils_check_virtual_device_compatibility
+                                                        (GType virtual_type,
+                                                         GType other_type);
+

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

Details

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

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + + + + + +

`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] +

enum NMUtilsSecurityType

typedef enum {
+	NMU_SEC_INVALID = 0,
+	NMU_SEC_NONE,
+	NMU_SEC_STATIC_WEP,
+	NMU_SEC_LEAP,
+	NMU_SEC_DYNAMIC_WEP,
+	NMU_SEC_WPA_PSK,
+	NMU_SEC_WPA_ENTERPRISE,
+	NMU_SEC_WPA2_PSK,
+	NMU_SEC_WPA2_ENTERPRISE
+} 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. +

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`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 +

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

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`type` :	the security type to check AP flags and device capabilties 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 capabilties 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 capabilties 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 capabilties 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. +

++++ + + + + + + + + + + + + + + +

`type` :	the security type to check device capabilties 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 +

++++ + + + + + + + + + + + + + + +

`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 +

++++ + + + + + + + + + + +

`psk` :	a string that might be a WPA PSK
Returns :	+`TRUE` if `psk` is a WPA PSK, `FALSE` if not

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

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

++++ + + + + + + + + + + +

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + +

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

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

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`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` :	(allow-none): user data for `predicate` function. [closure] +
`error` :	on failure, a "not found" error using `error_domain` and `error_code` +
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. +

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`channel` :	channel
`band` :	frequency band for wireless ("a" or "bg")
Returns :	+`TRUE` or `FALSE` +

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. If the current locale and terminal +support it, this will use unicode graphics characters to represent +"bars". Otherwise it will use 0 to 4 asterisks. +

++++ + + + + + + + + + + +

`strength` :	the access point strength, from 0 to 100
Returns :	the graphical representation of the access point strength

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

++++ + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + + + + + +

`asc` :	the ASCII representation of a hardware address
`buffer` :	buffer to store the result into
`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. +

++++ + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + + + + + + + + + + + + + +

`hwaddr1` :	pointer to a binary or ASCII hardware address, or `NULL` +
`hwaddr1_len` :	size of `hwaddr1`, or -1 if `hwaddr1` is ASCII
`hwaddr2` :	pointer to a binary or ASCII hardware address, or `NULL` +
`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'), +

++++ + + + + + + + + + + + + + + + + + + +

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

++++ + + + + + + + + + + +

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

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

++++ + + + + + + + + + + +

`name` :	Name of interface
Returns :	+`TRUE` if interface name is valid, otherwise `FALSE` is returned.

nm_utils_is_uuid ()

gboolean            nm_utils_is_uuid                    (const char *str);

+Checks if str is a UUID +

++++ + + + + + + + + + + +

`str` :	a string that might be a UUID
Returns :	+`TRUE` if `str` is a UUID, `FALSE` if not

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

nm_utils_inet4_ntop ()

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

+Wrapper for inet_ntop. +

++++ + + + + + + + + + + + + + + +

`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 provied it's 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. +

++++ + + + + + + + + + + + + + + +

`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 provied it's 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. +

++++ + + + + + + + + + + + + + + +

`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. +

++++ + + + + + + + + + + + + + + +

`virtual_type` :	a virtual connection type
`other_type` :	a connection type to test against `virtual_type` +
Returns :	+`TRUE` or `FALSE` +

			libnm Reference Manual
+Top + \| + Description + \| + Object Hierarchy +