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

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

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

Since 1.46, 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);

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

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

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

Removes all blacklisted MAC addresses.

#### Parameters

setting | the NMSettingWired |

### 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_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"