NMSettingWired: libnm Reference Manual

NMSettingWired

NMSettingWired — Describes connection properties for Ethernet-based networks

Functions

NMSetting *	nm_setting_wired_new ()
const char *	nm_setting_wired_get_port ()
guint32	nm_setting_wired_get_speed ()
const char *	nm_setting_wired_get_duplex ()
gboolean	nm_setting_wired_get_auto_negotiate ()
const char *	nm_setting_wired_get_mac_address ()
const char *	nm_setting_wired_get_cloned_mac_address ()
NMTernary	nm_setting_wired_get_accept_all_mac_addresses ()
const char *	nm_setting_wired_get_generate_mac_address_mask ()
const char const	nm_setting_wired_get_mac_address_blacklist ()
guint32	nm_setting_wired_get_num_mac_blacklist_items ()
const char *	nm_setting_wired_get_mac_blacklist_item ()
gboolean	nm_setting_wired_add_mac_blacklist_item ()
void	nm_setting_wired_remove_mac_blacklist_item ()
gboolean	nm_setting_wired_remove_mac_blacklist_item_by_value ()
void	nm_setting_wired_clear_mac_blacklist_items ()
const char const	nm_setting_wired_get_mac_address_denylist ()
guint32	nm_setting_wired_get_num_mac_denylist_items ()
const char *	nm_setting_wired_get_mac_denylist_item ()
gboolean	nm_setting_wired_add_mac_denylist_item ()
void	nm_setting_wired_remove_mac_denylist_item ()
gboolean	nm_setting_wired_remove_mac_denylist_item_by_value ()
void	nm_setting_wired_clear_mac_denylist_items ()
guint32	nm_setting_wired_get_mtu ()
const char const	nm_setting_wired_get_s390_subchannels ()
const char *	nm_setting_wired_get_s390_nettype ()
guint32	nm_setting_wired_get_num_s390_options ()
gboolean	nm_setting_wired_get_s390_option ()
const char *	nm_setting_wired_get_s390_option_by_key ()
gboolean	nm_setting_wired_add_s390_option ()
gboolean	nm_setting_wired_remove_s390_option ()
const char **	nm_setting_wired_get_valid_s390_options ()
NMSettingWiredWakeOnLan	nm_setting_wired_get_wake_on_lan ()
const char *	nm_setting_wired_get_wake_on_lan_password ()

Types and Values

#define	NM_SETTING_WIRED_SETTING_NAME
enum	NMSettingWiredWakeOnLan
#define	NM_SETTING_WIRED_PORT
#define	NM_SETTING_WIRED_SPEED
#define	NM_SETTING_WIRED_DUPLEX
#define	NM_SETTING_WIRED_AUTO_NEGOTIATE
#define	NM_SETTING_WIRED_MAC_ADDRESS
#define	NM_SETTING_WIRED_CLONED_MAC_ADDRESS
#define	NM_SETTING_WIRED_GENERATE_MAC_ADDRESS_MASK
#define	NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST
#define	NM_SETTING_WIRED_MAC_ADDRESS_DENYLIST
#define	NM_SETTING_WIRED_MTU
#define	NM_SETTING_WIRED_S390_SUBCHANNELS
#define	NM_SETTING_WIRED_S390_NETTYPE
#define	NM_SETTING_WIRED_S390_OPTIONS
#define	NM_SETTING_WIRED_WAKE_ON_LAN
#define	NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD
#define	NM_SETTING_WIRED_ACCEPT_ALL_MAC_ADDRESSES

Object Hierarchy

    GFlags
    ╰── NMSettingWiredWakeOnLan

Description

The NMSettingWired object is a NMSetting subclass that describes properties necessary for connection to Ethernet networks.

Functions

nm_setting_wired_new ()

NMSetting *
nm_setting_wired_new (void);

Creates a new NMSettingWired object with default values.

Returns

the new empty NMSettingWired object.

[transfer full]

nm_setting_wired_get_port ()

const char *
nm_setting_wired_get_port (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “port” property of the setting

nm_setting_wired_get_speed ()

guint32
nm_setting_wired_get_speed (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “speed” property of the setting

nm_setting_wired_get_duplex ()

const char *
nm_setting_wired_get_duplex (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “duplex” property of the setting

nm_setting_wired_get_auto_negotiate ()

gboolean
nm_setting_wired_get_auto_negotiate (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “auto-negotiate” property of the setting

nm_setting_wired_get_mac_address ()

const char *
nm_setting_wired_get_mac_address (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “mac-address” property of the setting

nm_setting_wired_get_cloned_mac_address ()

const char *
nm_setting_wired_get_cloned_mac_address
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “cloned-mac-address” property of the setting

nm_setting_wired_get_accept_all_mac_addresses ()

NMTernary
nm_setting_wired_get_accept_all_mac_addresses
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “accept-all-mac-addresses” property of the setting

Since: 1.32

nm_setting_wired_get_generate_mac_address_mask ()

const char *
nm_setting_wired_get_generate_mac_address_mask
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “generate-mac-address-mask” property of the setting

Since: 1.4

nm_setting_wired_get_mac_address_blacklist ()

const char *const *
nm_setting_wired_get_mac_address_blacklist
                               (NMSettingWired *setting);

nm_setting_wired_get_mac_address_blacklist has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_get_mac_address_denylist() instead.

Parameters

setting

the NMSettingWired

Returns

the “mac-address-blacklist” property of the setting

nm_setting_wired_get_num_mac_blacklist_items ()

guint32
nm_setting_wired_get_num_mac_blacklist_items
                               (NMSettingWired *setting);

nm_setting_wired_get_num_mac_blacklist_items has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_get_num_mac_denylist_items() instead.

Parameters

setting

the NMSettingWired

Returns

the number of blacklisted MAC addresses

nm_setting_wired_get_mac_blacklist_item ()

const char *
nm_setting_wired_get_mac_blacklist_item
                               (NMSettingWired *setting,
                                guint32 idx);

nm_setting_wired_get_mac_blacklist_item has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_get_mac_denylist_item() instead.

Since 1.48, access at index "len" is allowed and returns NULL.

Parameters

setting	the NMSettingWired
idx	the zero-based index of the MAC address entry

Returns

the blacklisted MAC address string (hex-digits-and-colons notation) at index idx

nm_setting_wired_add_mac_blacklist_item ()

gboolean
nm_setting_wired_add_mac_blacklist_item
                               (NMSettingWired *setting,
                                const char *mac);

nm_setting_wired_add_mac_blacklist_item has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_add_mac_denylist_item() instead.

Adds a new MAC address to the “mac-address-blacklist” property.

Parameters

setting	the NMSettingWired
mac	the MAC address string (hex-digits-and-colons notation) to blacklist

Returns

TRUE if the MAC address was added; FALSE if the MAC address is invalid or was already present

nm_setting_wired_remove_mac_blacklist_item ()

void
nm_setting_wired_remove_mac_blacklist_item
                               (NMSettingWired *setting,
                                guint32 idx);

nm_setting_wired_remove_mac_blacklist_item has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_remove_mac_denylist_item() instead.

Removes the MAC address at index idx from the blacklist.

Parameters

setting	the NMSettingWired
idx	index number of the MAC address

nm_setting_wired_remove_mac_blacklist_item_by_value ()

gboolean
nm_setting_wired_remove_mac_blacklist_item_by_value
                               (NMSettingWired *setting,
                                const char *mac);

nm_setting_wired_remove_mac_blacklist_item_by_value has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_remove_mac_denylist_item_by_value() instead.

Removes the MAC address mac from the blacklist.

Parameters

setting	the NMSettingWired
mac	the MAC address string (hex-digits-and-colons notation) to remove from the blacklist

Returns

TRUE if the MAC address was found and removed; FALSE if it was not.

nm_setting_wired_clear_mac_blacklist_items ()

void
nm_setting_wired_clear_mac_blacklist_items
                               (NMSettingWired *setting);

nm_setting_wired_clear_mac_blacklist_items has been deprecated since version 1.48. and should not be used in newly-written code.

Use nm_setting_wired_clear_mac_denylist_items() instead.

Removes all blacklisted MAC addresses.

Parameters

setting

the NMSettingWired

nm_setting_wired_get_mac_address_denylist ()

const char *const *
nm_setting_wired_get_mac_address_denylist
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “mac-address-denylist” property of the setting

Since: 1.48

nm_setting_wired_get_num_mac_denylist_items ()

guint32
nm_setting_wired_get_num_mac_denylist_items
                               (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the number of denylisted MAC addresses

Since: 1.48

nm_setting_wired_get_mac_denylist_item ()

const char *
nm_setting_wired_get_mac_denylist_item
                               (NMSettingWired *setting,
                                guint32 idx);

Parameters

setting	the NMSettingWired
idx	the zero-based index of the MAC address entry

Returns

the denylisted MAC address string (hex-digits-and-colons notation) at index idx

Since: 1.48

nm_setting_wired_add_mac_denylist_item ()

gboolean
nm_setting_wired_add_mac_denylist_item
                               (NMSettingWired *setting,
                                const char *mac);

Adds a new MAC address to the “mac-address-denylist” property.

Parameters

setting	the NMSettingWired
mac	the MAC address string (hex-digits-and-colons notation) to denylist

Returns

TRUE if the MAC address was added; FALSE if the MAC address is invalid or was already present

Since: 1.48

nm_setting_wired_remove_mac_denylist_item ()

void
nm_setting_wired_remove_mac_denylist_item
                               (NMSettingWired *setting,
                                guint32 idx);

Removes the MAC address at index idx from the denylist.

Parameters

setting	the NMSettingWired
idx	index number of the MAC address

Since: 1.48

nm_setting_wired_remove_mac_denylist_item_by_value ()

gboolean
nm_setting_wired_remove_mac_denylist_item_by_value
                               (NMSettingWired *setting,
                                const char *mac);

Removes the MAC address mac from the denylist.

Parameters

setting	the NMSettingWired
mac	the MAC address string (hex-digits-and-colons notation) to remove from the denylist

Returns

TRUE if the MAC address was found and removed; FALSE if it was not.

Since: 1.48

nm_setting_wired_clear_mac_denylist_items ()

void
nm_setting_wired_clear_mac_denylist_items
                               (NMSettingWired *setting);

Removes all denylisted MAC addresses.

Parameters

setting

the NMSettingWired

Since: 1.48

nm_setting_wired_get_mtu ()

guint32
nm_setting_wired_get_mtu (NMSettingWired *setting);

Parameters

setting

the NMSettingWired

Returns

the “mtu” property of the setting

nm_setting_wired_get_s390_subchannels ()

const char *const *
nm_setting_wired_get_s390_subchannels (NMSettingWired *setting);

Return the list of s390 subchannels that identify the device that this connection is applicable to. The connection should only be used in conjunction with that device.

Parameters

setting

the NMSettingWired

Returns

array of strings, each specifying one subchannel the s390 device uses to communicate to the host.

[transfer none][element-type utf8]

nm_setting_wired_get_s390_nettype ()

const char *
nm_setting_wired_get_s390_nettype (NMSettingWired *setting);

Returns the s390 device type this connection should apply to. Will be one of 'qeth', 'lcs', or 'ctc'.

Parameters

setting

the NMSettingWired

Returns

the s390 device type

nm_setting_wired_get_num_s390_options ()

guint32
nm_setting_wired_get_num_s390_options (NMSettingWired *setting);

Returns the number of s390-specific options that should be set for this device when it is activated. This can be used to retrieve each s390 option individually using nm_setting_wired_get_s390_option().

Parameters

setting

the NMSettingWired

Returns

the number of s390-specific device options

nm_setting_wired_get_s390_option ()

gboolean
nm_setting_wired_get_s390_option (NMSettingWired *setting,
                                  guint32 idx,
                                  const char **out_key,
                                  const char **out_value);

Given an index, return the value of the s390 option at that index. indexes are *not* guaranteed to be static across modifications to options done by nm_setting_wired_add_s390_option() and nm_setting_wired_remove_s390_option(), and should not be used to refer to options except for short periods of time such as during option iteration.

Parameters

setting	the NMSettingWired
idx	index of the desired option, from 0 to `nm_setting_wired_get_num_s390_options()` - 1
out_key	on return, the key name of the s390 specific option; this value is owned by the setting and should not be modified.	[out][optional][nullable][transfer none]
out_value	on return, the value of the key of the s390 specific option; this value is owned by the setting and should not be modified.	[out][optional][nullable][transfer none]

Returns

TRUE on success if the index was valid and an option was found, FALSE if the index was invalid (ie, greater than the number of options currently held by the setting)

nm_setting_wired_get_s390_option_by_key ()

const char *
nm_setting_wired_get_s390_option_by_key
                               (NMSettingWired *setting,
                                const char *key);

Returns the value associated with the s390-specific option specified by key , if it exists.

Parameters

setting	the NMSettingWired
key	the key for which to retrieve the value

Returns

the value, or NULL if the key/value pair was never added to the setting; the value is owned by the setting and must not be modified

nm_setting_wired_add_s390_option ()

gboolean
nm_setting_wired_add_s390_option (NMSettingWired *setting,
                                  const char *key,
                                  const char *value);

Add an option to the table. If the key already exists, the value gets replaced.

Before 1.32, the function would assert that the key is valid. Since then, an invalid key gets silently added but renders the profile as invalid.

Parameters

setting	the NMSettingWired
key	key name for the option
value	value for the option

Returns

since 1.32 this always returns TRUE.

nm_setting_wired_remove_s390_option ()

gboolean
nm_setting_wired_remove_s390_option (NMSettingWired *setting,
                                     const char *key);

Remove the s390-specific option referenced by key from the internal option list.

Parameters

setting	the NMSettingWired
key	key name for the option to remove

Returns

TRUE if the option was found and removed from the internal option list, FALSE if it was not.

nm_setting_wired_get_valid_s390_options ()

const char **
nm_setting_wired_get_valid_s390_options
                               (NMSettingWired *setting);

Returns a list of valid s390 options.

The setting argument is unused and NULL may be passed instead.

Parameters

setting

the NMSettingWired. This argument is unused and you may pass NULL.

[nullable]

Returns

a NULL-terminated array of strings of valid s390 options.

[transfer none]

nm_setting_wired_get_wake_on_lan ()

NMSettingWiredWakeOnLan
nm_setting_wired_get_wake_on_lan (NMSettingWired *setting);

Returns the Wake-on-LAN options enabled for the connection

Parameters

setting

the NMSettingWired

Returns

the Wake-on-LAN options

Since: 1.2

nm_setting_wired_get_wake_on_lan_password ()

const char *
nm_setting_wired_get_wake_on_lan_password
                               (NMSettingWired *setting);

Returns the Wake-on-LAN password. This only applies to NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC.

Parameters

setting

the NMSettingWired

Returns

the Wake-on-LAN setting password, or NULL if there is no password.

Since: 1.2

Types and Values

NM_SETTING_WIRED_SETTING_NAME

#define NM_SETTING_WIRED_SETTING_NAME "802-3-ethernet"

enum NMSettingWiredWakeOnLan

Options for “wake-on-lan”. Note that not all options are supported by all devices.

Members

NM_SETTING_WIRED_WAKE_ON_LAN_NONE	Wake-on-LAN disabled
NM_SETTING_WIRED_WAKE_ON_LAN_PHY	Wake on PHY activity
NM_SETTING_WIRED_WAKE_ON_LAN_UNICAST	Wake on unicast messages
NM_SETTING_WIRED_WAKE_ON_LAN_MULTICAST	Wake on multicast messages
NM_SETTING_WIRED_WAKE_ON_LAN_BROADCAST	Wake on broadcast messages
NM_SETTING_WIRED_WAKE_ON_LAN_ARP	Wake on ARP
NM_SETTING_WIRED_WAKE_ON_LAN_MAGIC	Wake on magic packet
NM_SETTING_WIRED_WAKE_ON_LAN_ALL	Wake on all events. This does not include the exclusive flags `NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT` or `NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE` .
NM_SETTING_WIRED_WAKE_ON_LAN_DEFAULT	Use the default value
NM_SETTING_WIRED_WAKE_ON_LAN_IGNORE	Don't change configured settings
NM_SETTING_WIRED_WAKE_ON_LAN_EXCLUSIVE_FLAGS	Mask of flags that are incompatible with other flags

Since: 1.2

NM_SETTING_WIRED_PORT

#define NM_SETTING_WIRED_PORT                      "port"

NM_SETTING_WIRED_SPEED

#define NM_SETTING_WIRED_SPEED                     "speed"

NM_SETTING_WIRED_DUPLEX

#define NM_SETTING_WIRED_DUPLEX                    "duplex"

NM_SETTING_WIRED_AUTO_NEGOTIATE

#define NM_SETTING_WIRED_AUTO_NEGOTIATE            "auto-negotiate"

NM_SETTING_WIRED_MAC_ADDRESS

#define NM_SETTING_WIRED_MAC_ADDRESS               "mac-address"

NM_SETTING_WIRED_CLONED_MAC_ADDRESS

#define NM_SETTING_WIRED_CLONED_MAC_ADDRESS        "cloned-mac-address"

NM_SETTING_WIRED_GENERATE_MAC_ADDRESS_MASK

#define NM_SETTING_WIRED_GENERATE_MAC_ADDRESS_MASK "generate-mac-address-mask"

NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST

#define NM_SETTING_WIRED_MAC_ADDRESS_BLACKLIST     "mac-address-blacklist"

NM_SETTING_WIRED_MAC_ADDRESS_DENYLIST

#define NM_SETTING_WIRED_MAC_ADDRESS_DENYLIST      "mac-address-denylist"

NM_SETTING_WIRED_MTU

#define NM_SETTING_WIRED_MTU                       "mtu"

NM_SETTING_WIRED_S390_SUBCHANNELS

#define NM_SETTING_WIRED_S390_SUBCHANNELS          "s390-subchannels"

NM_SETTING_WIRED_S390_NETTYPE

#define NM_SETTING_WIRED_S390_NETTYPE              "s390-nettype"

NM_SETTING_WIRED_S390_OPTIONS

#define NM_SETTING_WIRED_S390_OPTIONS              "s390-options"

NM_SETTING_WIRED_WAKE_ON_LAN

#define NM_SETTING_WIRED_WAKE_ON_LAN               "wake-on-lan"

NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD

#define NM_SETTING_WIRED_WAKE_ON_LAN_PASSWORD      "wake-on-lan-password"

NM_SETTING_WIRED_ACCEPT_ALL_MAC_ADDRESSES

#define NM_SETTING_WIRED_ACCEPT_ALL_MAC_ADDRESSES  "accept-all-mac-addresses"