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);
gboolean            (*NMUtilsCheckFilePredicate)        (const char *filename,
                                                         const struct stat *stat,
                                                         gpointer user_data,
                                                         GError **error);
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 guint *       nm_utils_wifi_2ghz_freqs            (void);
const guint *       nm_utils_wifi_5ghz_freqs            (void);
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);
int                 nm_utils_bond_mode_string_to_int    (const char *mode);
const char *        nm_utils_bond_mode_int_to_string    (int mode);
char *              nm_utils_enum_to_str                (GType type,
                                                         int value);
gboolean            nm_utils_enum_from_str              (GType type,
                                                         const char *str,
                                                         int *out_value,
                                                         char **err_token);
const char **       nm_utils_enum_get_values            (GType type,
                                                         gint from,
                                                         gint to);
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.

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


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.

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

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

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

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.

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 enum is a G_TYPE_ENUM and the given value is not valid the function returns NULL.

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.

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]

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,
                                                         gint from,
                                                         gint to);

Returns the list of possible values for a given enum.

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 full]

Since 1.2


struct stat

struct stat;