nm-utils: libnm-util Reference Manual

- - -

nm-utils

nm-utils — Utility functions

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-gboolean -	-nm_utils_init () -
-void -	-nm_utils_deinit () -
-gboolean -	-nm_utils_is_empty_ssid () -
const char * -	-nm_utils_escape_ssid () -
-gboolean -	-nm_utils_same_ssid () -
-char * -	-nm_utils_ssid_to_utf8 () -
-GHashTable * -	-nm_utils_gvalue_hash_dup () -
-void -	-nm_utils_slist_free () -
-gboolean -	-nm_utils_security_valid () -
-gboolean -	-nm_utils_ap_mode_security_valid () -
-gboolean -	-nm_utils_wep_key_valid () -
-gboolean -	-nm_utils_wpa_psk_valid () -
-GSList * -	-nm_utils_ip4_addresses_from_gvalue () -
-void -	-nm_utils_ip4_addresses_to_gvalue () -
-GSList * -	-nm_utils_ip4_routes_from_gvalue () -
-void -	-nm_utils_ip4_routes_to_gvalue () -
-guint32 -	-nm_utils_ip4_netmask_to_prefix () -
-guint32 -	-nm_utils_ip4_prefix_to_netmask () -
-guint32 -	-nm_utils_ip4_get_default_prefix () -
-GSList * -	-nm_utils_ip6_addresses_from_gvalue () -
-void -	-nm_utils_ip6_addresses_to_gvalue () -
-GSList * -	-nm_utils_ip6_routes_from_gvalue () -
-void -	-nm_utils_ip6_routes_to_gvalue () -
-GSList * -	-nm_utils_ip6_dns_from_gvalue () -
-void -	-nm_utils_ip6_dns_to_gvalue () -
-char * -	-nm_utils_uuid_generate () -
-char * -	-nm_utils_uuid_generate_from_string () -
-GByteArray * -	-nm_utils_rsa_key_encrypt () -
-GByteArray * -	-nm_utils_rsa_key_encrypt_aes () -
-gboolean -	-nm_utils_file_is_pkcs12 () -
-gboolean -	-(*NMUtilsFileSearchInPathsPredicate) () -
const char * -	-nm_utils_file_search_in_paths () -
-guint32 -	-nm_utils_wifi_freq_to_channel () -
-guint32 -	-nm_utils_wifi_channel_to_freq () -
-guint32 -	-nm_utils_wifi_find_next_channel () -
-gboolean -	-nm_utils_wifi_is_channel_valid () -
-int -	-nm_utils_hwaddr_len () -
-int -	-nm_utils_hwaddr_type () -
-char * -	-nm_utils_hwaddr_ntoa () -
-GByteArray * -	-nm_utils_hwaddr_atoba () -
-guint8 * -	-nm_utils_hwaddr_aton () -
-char * -	-nm_utils_hwaddr_ntoa_len () -
-guint8 * -	-nm_utils_hwaddr_aton_len () -
-gboolean -	-nm_utils_hwaddr_valid () -
-char * -	-nm_utils_bin2hexstr () -
-int -	-nm_utils_hex2byte () -
-char * -	-nm_utils_hexstr2bin () -
-gboolean -	-nm_utils_iface_valid_name () -
-gboolean -	-nm_utils_is_uuid () -
const char * -	-nm_utils_inet4_ntop () -
const char * -	-nm_utils_inet6_ntop () -
-gboolean -	-nm_utils_check_virtual_device_compatibility () -

Types and Values

---- - - - - - - - - - - - - - - -

enum	NMUtilsSecurityType
#define	NM_UTILS_HWADDR_LEN_MAX
#define	NM_UTILS_INET_ADDRSTRLEN

Object Hierarchy

    GEnum
-    ╰── NMUtilsSecurityType
-

Includes

#include <nm-utils.h>
-

Description

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

Functions

nm_utils_init ()

gboolean
-nm_utils_init (GError **error);

Initializes libnm-util; should be called when starting any program that -uses libnm-util. This function can be called more than once.

Parameters

----- - - - - - -

error

location to store error, or NULL

Returns

TRUE if the initialization was successful, FALSE on failure.

nm_utils_deinit ()

void
-nm_utils_deinit (void);

No-op. Although this function still exists for ABI compatibility reasons, it -does not have any effect, and does not ever need to be called.

nm_utils_is_empty_ssid ()

gboolean
-nm_utils_is_empty_ssid (const guint8 *ssid,
-                        int len);

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

Parameters

----- - - - - - - - - - - - - -

ssid	pointer to a buffer containing the SSID data
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,
-                      guint32 len);

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

Parameters

----- - - - - - - - - - - - - -

ssid	pointer to a buffer containing the SSID data
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 GByteArray *ssid1,
-                    const GByteArray *ssid2,
-                    gboolean ignore_trailing_null);

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

Parameters

----- - - - - - - - - - - - - - - - - - -

ssid1	first SSID data to compare
ssid2	second SSID data to compare
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 GByteArray *ssid);

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

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

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

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

Parameters

----- - - - - - -

ssid

a byte array containing the SSID data

Returns

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

[transfer full]

nm_utils_gvalue_hash_dup ()

GHashTable *
-nm_utils_gvalue_hash_dup (GHashTable *hash);

Utility function to duplicate a hash table of GValues.

Parameters

----- - - - - - -

hash

a GHashTable mapping string:GValue

Returns

a newly allocated duplicated GHashTable, caller must free the -returned hash with g_hash_table_unref() or g_hash_table_destroy().

[transfer container][element-type utf8 GObject.Value]

nm_utils_slist_free ()

void
-nm_utils_slist_free (GSList *list,
-                     GDestroyNotify elem_destroy_fn);

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

use g_slist_free_full().

Utility function to free a GSList.

[skip]

Parameters

----- - - - - - - - - - - - - -

list	a GSList
elem_destroy_fn	user function called for each element in `list` -

nm_utils_security_valid ()

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

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

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

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Returns

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

nm_utils_ap_mode_security_valid ()

gboolean
-nm_utils_ap_mode_security_valid (NMUtilsSecurityType type,
-                                 NMDeviceWifiCapabilities wifi_caps);

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

Parameters

----- - - - - - - - - - - - - -

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

Returns

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

Since: 0.9.8

nm_utils_wep_key_valid ()

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

Checks if key - is a valid WEP key

Parameters

----- - - - - - - - - - - - - -

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

Returns

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

Since: 0.9.8

nm_utils_wpa_psk_valid ()

gboolean
-nm_utils_wpa_psk_valid (const char *psk);

Checks if psk - is a valid WPA PSK

Parameters

----- - - - - - -

psk

a string that might be a WPA PSK

Returns

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

Since: 0.9.8

nm_utils_ip4_addresses_from_gvalue ()

GSList *
-nm_utils_ip4_addresses_from_gvalue (const GValue *value);

Utility function to convert a GPtrArray of GArrays of guint32s representing -a list of NetworkManager IPv4 addresses (which is a tuple of address, gateway, -and prefix) into a GSList of NMIP4Address objects. The specific format of -this serialization is not guaranteed to be stable and the GArray may be -extended in the future.

Parameters

----- - - - - - -

value

GValue containing a GPtrArray of GArrays of guint32s

Returns

a newly allocated GSList of NMIP4Address objects.

[transfer full][element-type NMIP4Address]

nm_utils_ip4_addresses_to_gvalue ()

void
-nm_utils_ip4_addresses_to_gvalue (GSList *list,
-                                  GValue *value);

Utility function to convert a GSList of NMIP4Address objects into a -GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 -addresses (which is a tuple of address, gateway, and prefix). The specific -format of this serialization is not guaranteed to be stable and may be -extended in the future.

Parameters

----- - - - - - - - - - - - - -

list	a list of NMIP4Address objects.	[element-type NMIP4Address]
value	a pointer to a GValue into which to place the converted addresses, -which should be unset by the caller (when no longer needed) with -`g_value_unset()`.

nm_utils_ip4_routes_from_gvalue ()

GSList *
-nm_utils_ip4_routes_from_gvalue (const GValue *value);

Utility function to convert a GPtrArray of GArrays of guint32s representing -a list of NetworkManager IPv4 routes (which is a tuple of route, next hop, -prefix, and metric) into a GSList of NMIP4Route objects. The specific -format of this serialization is not guaranteed to be stable and may be -extended in the future.

Parameters

----- - - - - - -

value

GValue containing a GPtrArray of GArrays of guint32s

Returns

a newly allocated GSList of NMIP4Route objects.

[transfer full][element-type NMIP4Route]

nm_utils_ip4_routes_to_gvalue ()

void
-nm_utils_ip4_routes_to_gvalue (GSList *list,
-                               GValue *value);

Utility function to convert a GSList of NMIP4Route objects into a -GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4 -routes (which is a tuple of route, next hop, prefix, and metric). The -specific format of this serialization is not guaranteed to be stable and may -be extended in the future.

Parameters

----- - - - - - - - - - - - - -

list	a list of NMIP4Route objects.	[element-type NMIP4Route]
value	a pointer to a GValue into which to place the converted routes, -which should be unset by the caller (when no longer needed) with -`g_value_unset()`.

nm_utils_ip4_netmask_to_prefix ()

guint32
-nm_utils_ip4_netmask_to_prefix (guint32 netmask);

Parameters

----- - - - - - -

netmask

an IPv4 netmask in network byte order

Returns

the CIDR prefix represented by the netmask

nm_utils_ip4_prefix_to_netmask ()

guint32
-nm_utils_ip4_prefix_to_netmask (guint32 prefix);

Parameters

----- - - - - - -

prefix

a CIDR prefix

Returns

the netmask represented by the prefix, in network byte order

nm_utils_ip4_get_default_prefix ()

guint32
-nm_utils_ip4_get_default_prefix (guint32 ip);

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

Parameters

----- - - - - - -

an IPv4 address (in network byte order)

Returns

the default class prefix for the given IP

nm_utils_ip6_addresses_from_gvalue ()

GSList *
-nm_utils_ip6_addresses_from_gvalue (const GValue *value);

Utility function to convert a GPtrArray of GValueArrays of (GArray of guchars) and guint32 -representing a list of NetworkManager IPv6 addresses (which is a tuple of address, -prefix, and gateway), into a GSList of NMIP6Address objects. The specific format of -this serialization is not guaranteed to be stable and the GValueArray may be -extended in the future.

Parameters

----- - - - - - -

value

gvalue containing a GPtrArray of GValueArrays of (GArray of guchars) and guint32

Returns

a newly allocated GSList of NMIP6Address objects.

[transfer full][element-type NMIP6Address]

nm_utils_ip6_addresses_to_gvalue ()

void
-nm_utils_ip6_addresses_to_gvalue (GSList *list,
-                                  GValue *value);

Utility function to convert a GSList of NMIP6Address objects into a -GPtrArray of GValueArrays representing a list of NetworkManager IPv6 addresses -(which is a tuple of address, prefix, and gateway). The specific format of -this serialization is not guaranteed to be stable and may be extended in the -future.

Parameters

----- - - - - - - - - - - - - -

list	a list of NMIP6Address objects.	[element-type NMIP6Address]
value	a pointer to a GValue into which to place the converted addresses, -which should be unset by the caller (when no longer needed) with -`g_value_unset()`.

nm_utils_ip6_routes_from_gvalue ()

GSList *
-nm_utils_ip6_routes_from_gvalue (const GValue *value);

Utility function GPtrArray of GValueArrays of (GArray of guchars), guint32, -(GArray of guchars), and guint32 representing a list of NetworkManager IPv6 -routes (which is a tuple of destination, prefix, next hop, and metric) -into a GSList of NMIP6Route objects. The specific format of this serialization -is not guaranteed to be stable and may be extended in the future.

Parameters

----- - - - - - -

value

GValue containing a GPtrArray of GValueArrays of (GArray of guchars), guint32, -(GArray of guchars), and guint32

Returns

a newly allocated GSList of NMIP6Route objects.

[transfer full][element-type NMIP6Route]

nm_utils_ip6_routes_to_gvalue ()

void
-nm_utils_ip6_routes_to_gvalue (GSList *list,
-                               GValue *value);

Utility function to convert a GSList of NMIP6Route objects into a GPtrArray of -GValueArrays of (GArray of guchars), guint32, (GArray of guchars), and guint32 -representing a list of NetworkManager IPv6 routes (which is a tuple of destination, -prefix, next hop, and metric). The specific format of this serialization is not -guaranteed to be stable and may be extended in the future.

Parameters

----- - - - - - - - - - - - - -

list	a list of NMIP6Route objects.	[element-type NMIP6Route]
value	a pointer to a GValue into which to place the converted routes, -which should be unset by the caller (when no longer needed) with -`g_value_unset()`.

nm_utils_ip6_dns_from_gvalue ()

GSList *
-nm_utils_ip6_dns_from_gvalue (const GValue *value);

Converts a GValue containing a GPtrArray of IP6 DNS, represented as -GByteArrays into a GSList of struct in6_addrs.

[skip]

Parameters

----- - - - - - -

value

a GValue

Returns

a GSList of IP6 addresses.

nm_utils_ip6_dns_to_gvalue ()

void
-nm_utils_ip6_dns_to_gvalue (GSList *list,
-                            GValue *value);

Utility function to convert a GSList of struct -in6_addr structs into a GPtrArray of GByteArrays -representing each server's IPv6 addresses in network byte order. -The specific format of this serialization is not guaranteed to be -stable and may be extended in the future.

[skip]

Parameters

----- - - - - - - - - - - - - -

list	a list of NMIP6Route objects
value	a pointer to a GValue into which to place the converted DNS server -addresses, which should be unset by the caller (when no longer needed) with -`g_value_unset()`.

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

char *
-nm_utils_uuid_generate_from_string (const char *s);

For a given s -, this function will always return the same UUID.

Parameters

----- - - - - - -

a string to use as the seed for the UUID

Returns

a newly allocated UUID suitable for use as the NMSettingConnection -object's “id”: property

nm_utils_rsa_key_encrypt ()

GByteArray *
-nm_utils_rsa_key_encrypt (const GByteArray *data,
-                          const char *in_password,
-                          char **out_password,
-                          GError **error);

Encrypts the given RSA private key data with the given password (or generates -a password if no password was given) and converts the data to PEM format -suitable for writing to a file. It uses Triple DES cipher for the encryption.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

data	RSA private key data to be encrypted
in_password	existing password to use, if any.	[allow-none]
out_password	if `in_password` -was `NULL`, a random password will be generated -and returned in this argument.	[out][allow-none]
error	detailed error information on return, if an error occurred

Returns

on success, PEM-formatted data suitable for writing to a PEM-formatted -certificate/private key file.

[transfer full]

nm_utils_rsa_key_encrypt_aes ()

GByteArray *
-nm_utils_rsa_key_encrypt_aes (const GByteArray *data,
-                              const char *in_password,
-                              char **out_password,
-                              GError **error);

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

data	RSA private key data to be encrypted
in_password	existing password to use, if any.	[allow-none]
out_password	if `in_password` -was `NULL`, a random password will be generated -and returned in this argument.	[out][allow-none]
error	detailed error information on return, if an error occurred

Returns

on success, PEM-formatted data suitable for writing to a PEM-formatted -certificate/private key file.

[transfer full]

nm_utils_file_is_pkcs12 ()

gboolean
-nm_utils_file_is_pkcs12 (const char *filename);

Utility function to find out if the filename - is in PKCS#12 format.

Parameters

----- - - - - - -

filename

name of the file to test

Returns

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

NMUtilsFileSearchInPathsPredicate ()

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

nm_utils_file_search_in_paths ()

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

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

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Returns

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

[transfer none]

nm_utils_wifi_freq_to_channel ()

guint32
-nm_utils_wifi_freq_to_channel (guint32 freq);

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

Parameters

----- - - - - - -

freq

frequency

Returns

the channel represented by the frequency or 0

nm_utils_wifi_channel_to_freq ()

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

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

Parameters

----- - - - - - - - - - - - - -

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

Returns

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

nm_utils_wifi_find_next_channel ()

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

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

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Returns

the next channel in the specified direction or 0

nm_utils_wifi_is_channel_valid ()

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

Utility function to verify Wi-Fi channel validity.

Parameters

----- - - - - - - - - - - - - -

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

Returns

TRUE or FALSE

nm_utils_hwaddr_len ()

int
-nm_utils_hwaddr_len (int type);

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

Parameters

----- - - - - - -

type

the type of address; either ARPHRD_ETHER or -ARPHRD_INFINIBAND

Returns

the positive length, or -1 if the type is unknown/unsupported.

nm_utils_hwaddr_type ()

int
-nm_utils_hwaddr_type (int len);

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

This could not be extended to cover other types, since -there is not a one-to-one mapping between types and lengths. This -was mostly only used to get a type to pass to -nm_utils_hwaddr_ntoa() or nm_utils_hwaddr_aton() when you only had -a length; but you can just use nm_utils_hwaddr_ntoa_len() or -nm_utils_hwaddr_aton_len() now instead.

Returns the type (either ARPHRD_ETHER or -ARPHRD_INFINIBAND) of the raw address given its length.

Parameters

----- - - - - - -

len

the length of hardware address in bytes

Returns

the type, either ARPHRD_ETHER or -ARPHRD_INFINIBAND. If the length is unexpected, return -1 -(unsupported type/length).

nm_utils_hwaddr_ntoa ()

char *
-nm_utils_hwaddr_ntoa (gconstpointer addr,
-                      int type);

Converts addr - to textual form.

See also nm_utils_hwaddr_ntoa_len(), which takes a length instead of -a type.

Parameters

----- - - - - - - - - - - - - -

addr	a binary hardware address
type	the type of address; either `ARPHRD_ETHER` or -`ARPHRD_INFINIBAND`

Returns

the textual form of addr -.

[transfer full]

nm_utils_hwaddr_atoba ()

GByteArray *
-nm_utils_hwaddr_atoba (const char *asc,
-                       int type);

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

Parameters

----- - - - - - - - - - - - - -

asc	the ASCII representation of a hardware address
type	the type of address; either `ARPHRD_ETHER` or -`ARPHRD_INFINIBAND`

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,
-                      int type,
-                      gpointer buffer);

Parses asc - and converts it to binary form in buffer -. See -nm_utils_hwaddr_atoba() if you'd rather have the result in a -GByteArray.

See also nm_utils_hwaddr_aton_len(), which takes an output length -instead of a type.

Parameters

----- - - - - - - - - - - - - - - - - - -

asc	the ASCII representation of a hardware address
type	the type of address; either `ARPHRD_ETHER` or -`ARPHRD_INFINIBAND`
buffer	buffer to store the result into

Returns

buffer -, or NULL if asc -couldn't be parsed

nm_utils_hwaddr_ntoa_len ()

char *
-nm_utils_hwaddr_ntoa_len (gconstpointer addr,
-                          gsize length);

Converts addr - to textual form.

Parameters

----- - - - - - - - - - - - - -

addr	a binary hardware address
length	the length of `addr` -

Returns

the textual form of addr -.

[transfer full]

Since: 0.9.10

nm_utils_hwaddr_aton_len ()

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

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

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Since: 0.9.10

nm_utils_hwaddr_valid ()

gboolean
-nm_utils_hwaddr_valid (const char *asc);

Parses asc - to see if it is a valid hardware address of some type.

Parameters

----- - - - - - -

asc

the ASCII representation of a hardware address

Returns

TRUE if asc -appears to be a valid hardware address -of some type, FALSE if not.

Since: 0.9.10

nm_utils_bin2hexstr ()

char *
-nm_utils_bin2hexstr (const char *bytes,
-                     int len,
-                     int final_len);

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

Parameters

----- - - - - - - - - - - - - - - - - - -

bytes	an array of bytes
len	the length of the `bytes` -array
final_len	an index where to cut off the returned string, or -1

Returns

the textual form of bytes -.

[transfer full]

Since: 0.9.10

nm_utils_hex2byte ()

int
-nm_utils_hex2byte (const char *hex);

Converts a hex string (2 characters) into its byte representation.

Parameters

----- - - - - - -

hex

a string representing a hex byte

Returns

a byte, or -1 if hex -doesn't represent a hex byte

Since: 0.9.10

nm_utils_hexstr2bin ()

char *
-nm_utils_hexstr2bin (const char *hex,
-                     size_t len);

Converts a hexadecimal string hex - into a byte-array. The returned array -length is len -/2.

Parameters

----- - - - - - - - - - - - - -

hex	an hex string
len	the length of the `hex` -string (it has to be even)

Returns

a array of bytes, or NULL on error.

[transfer full]

Since: 0.9.10

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.

Parameters

----- - - - - - -

name

Name of interface

Returns

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

Since: 0.9.8

nm_utils_is_uuid ()

gboolean
-nm_utils_is_uuid (const char *str);

Checks if str - is a UUID

Parameters

----- - - - - - -

str

a string that might be a UUID

Returns

TRUE if str -is a UUID, FALSE if not

Since: 0.9.8

nm_utils_inet4_ntop ()

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

Wrapper for inet_ntop.

[skip]

Parameters

----- - - - - - - - - - - - - -

inaddr	the address that should be converted to string.
dst	the destination buffer, it must contain at least -`INET_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` -characters. If set to `NULL`, it will return a pointer to an internal, static -buffer (shared with `nm_utils_inet6_ntop()`). Beware, that the internal -buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or -`nm_utils_inet6_ntop()` that does not 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.

Since: 0.9.10

nm_utils_inet6_ntop ()

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

Wrapper for inet_ntop.

[skip]

Parameters

----- - - - - - - - - - - - - -

in6addr	the address that should be converted to string.
dst	the destination buffer, it must contain at least -`INET6_ADDRSTRLEN` or `NM_UTILS_INET_ADDRSTRLEN` -characters. If set to `NULL`, it will return a pointer to an internal, static -buffer (shared with `nm_utils_inet4_ntop()`). Beware, that the internal -buffer will be overwritten with ever new call of `nm_utils_inet4_ntop()` or -`nm_utils_inet6_ntop()` that does not 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.

Since: 0.9.10

nm_utils_check_virtual_device_compatibility ()

gboolean
-nm_utils_check_virtual_device_compatibility
-                               (GType virtual_type,
-                                GType other_type);

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

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

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

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

Parameters

----- - - - - - - - - - - - - -

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

Returns

TRUE or FALSE

Since: 0.9.10

Types and Values

enum NMUtilsSecurityType

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

Members

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

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