NMSettingBond: libnm-util Reference Manual

## NMSettingBond NMSettingBond — Describes connection properties for bonds |

## Functions

GQuark | nm_setting_bond_error_quark ()
NMSetting * | nm_setting_bond_new ()
const char * | nm_setting_bond_get_interface_name ()
guint32 | nm_setting_bond_get_num_options ()
gboolean | nm_setting_bond_get_option ()
const char * | nm_setting_bond_get_option_by_name ()
gboolean | nm_setting_bond_add_option ()
gboolean | nm_setting_bond_remove_option ()
gboolean | nm_setting_bond_validate_option ()
const char ** | nm_setting_bond_get_valid_options ()
const char * | nm_setting_bond_get_option_default ()

## Properties

gchar * | interface-name | Read / Write
GHashTable_gchararray+gchararray_* | options | Read / Write

## Types and Values

#define | NM_SETTING_BOND_SETTING_NAME
enum | NMSettingBondError
#define | NM_SETTING_BOND_ERROR
#define | NM_SETTING_BOND_INTERFACE_NAME
#define | NM_SETTING_BOND_OPTIONS
#define | NM_SETTING_BOND_OPTION_MODE
#define | NM_SETTING_BOND_OPTION_MIIMON
#define | NM_SETTING_BOND_OPTION_DOWNDELAY
#define | NM_SETTING_BOND_OPTION_UPDELAY
#define | NM_SETTING_BOND_OPTION_ARP_INTERVAL
#define | NM_SETTING_BOND_OPTION_ARP_IP_TARGET
#define | NM_SETTING_BOND_OPTION_ARP_VALIDATE
#define | NM_SETTING_BOND_OPTION_PRIMARY
#define | NM_SETTING_BOND_OPTION_PRIMARY_RESELECT
#define | NM_SETTING_BOND_OPTION_FAIL_OVER_MAC
#define | NM_SETTING_BOND_OPTION_USE_CARRIER
#define | NM_SETTING_BOND_OPTION_AD_SELECT
#define | NM_SETTING_BOND_OPTION_XMIT_HASH_POLICY
#define | NM_SETTING_BOND_OPTION_RESEND_IGMP
#define | NM_SETTING_BOND_OPTION_LACP_RATE

## Object Hierarchy

        GEnum
        ╰── NMSettingBondError
        GObject
        ╰── NMSetting
            ╰── NMSettingBond

## Includes

    #include <nm-setting-bond.h>

## Description

The NMSettingBond object is a NMSetting subclass that describes properties necessary for bond connections.

## Functions

### nm_setting_bond_error_quark ()

    GQuark
    nm_setting_bond_error_quark (void);

Registers an error quark for NMSettingBond if necessary.

#### Returns

the error quark used for NMSettingBond errors.

### nm_setting_bond_new ()

    NMSetting *
    nm_setting_bond_new (void);

Creates a new NMSettingBond object with default values.

#### Returns

the new empty NMSettingBond object.

[transfer full]

### nm_setting_bond_get_interface_name ()

    const char *
    nm_setting_bond_get_interface_name (NMSettingBond *setting);

#### Parameters

setting | the NMSettingBond |

#### Returns

the “interface-name” property of the setting

### nm_setting_bond_get_num_options ()

    guint32
    nm_setting_bond_get_num_options (NMSettingBond *setting);

Returns the number of options that should be set for this bond when it is activated. This can be used to retrieve each option individually using `nm_setting_bond_get_option()`.

#### Parameters

setting | the NMSettingBond |

#### Returns

the number of bonding options

### nm_setting_bond_get_option ()

    gboolean
    nm_setting_bond_get_option (NMSettingBond *setting,
                                guint32 idx,
                                const char **out_name,
                                const char **out_value);

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

#### Parameters

setting | the NMSettingBond |
idx | index of the desired option, from 0 to `nm_setting_bond_get_num_options()` - 1 |
out_name | on return, the name of the bonding option; this value is owned by the setting and should not be modified. | [out]
out_value | on return, the value of the name of the bonding option; this value is owned by the setting and should not be modified. | [out]

#### 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_bond_get_option_by_name ()

    const char *
    nm_setting_bond_get_option_by_name (NMSettingBond *setting,
                                        const char *name);

Returns the value associated with the bonding option specified by `name` , if it exists.

#### Parameters

setting | the NMSettingBond |
name | the option name 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_bond_add_option ()

    gboolean
    nm_setting_bond_add_option (NMSettingBond *setting,
                                const char *name,
                                const char *value);

Add an option to the table. The option is compared to an internal list of allowed options. Option names may contain only alphanumeric characters (ie [a-zA-Z0-9]). Adding a new name replaces any existing name/value pair that may already exist.

The order of how to set several options is relevant because there are options that conflict with each other.

#### Parameters

setting | the NMSettingBond |
name | name for the option |
value | value for the option |

#### Returns

`TRUE` if the option was valid and was added to the internal option list, `FALSE` if it was not.

### nm_setting_bond_remove_option ()

    gboolean
    nm_setting_bond_remove_option (NMSettingBond *setting,
                                   const char *name);

Remove the bonding option referenced by `name` from the internal option list.

#### Parameters

setting | the NMSettingBond |
name | name of 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_bond_validate_option ()

    gboolean
    nm_setting_bond_validate_option (const char *name,
                                     const char *value);

Checks whether `name` is a valid bond option and `value` is a valid value for the `name` . If `value` is `NULL`, the function only validates the option name.

#### Parameters

name | the name of the option to validate |
value | the value of the option to validate |

#### Returns

`TRUE`, if the `value` is valid for the given name. If the `name` is not a valid option, `FALSE` will be returned.

Since: 0.9.10

### nm_setting_bond_get_valid_options ()

    const char **
    nm_setting_bond_get_valid_options (NMSettingBond *setting);

Returns a list of valid bond options.

#### Parameters

setting | the NMSettingBond |

#### Returns

a `NULL`-terminated array of strings of valid bond options.

[transfer none]

### nm_setting_bond_get_option_default ()

    const char *
    nm_setting_bond_get_option_default (NMSettingBond *setting,
                                        const char *name);

#### Parameters

setting | the NMSettingBond |
name | the name of the option |

#### Returns

the value of the bond option if not overridden by an entry in the “options” property.

## Types and Values

### NM_SETTING_BOND_SETTING_NAME

    #define NM_SETTING_BOND_SETTING_NAME "bond"

### enum NMSettingBondError

#### Members

NM_SETTING_BOND_ERROR_UNKNOWN | unknown or unclassified error |
NM_SETTING_BOND_ERROR_INVALID_PROPERTY | the property was invalid |
NM_SETTING_BOND_ERROR_MISSING_PROPERTY | the property was missing and is required |
NM_SETTING_BOND_ERROR_INVALID_OPTION |  |
NM_SETTING_BOND_ERROR_MISSING_OPTION |  |

### NM_SETTING_BOND_ERROR

    #define NM_SETTING_BOND_ERROR nm_setting_bond_error_quark ()

### NM_SETTING_BOND_INTERFACE_NAME

    #define NM_SETTING_BOND_INTERFACE_NAME "interface-name"

### NM_SETTING_BOND_OPTIONS

    #define NM_SETTING_BOND_OPTIONS "options"

### NM_SETTING_BOND_OPTION_MODE

    #define NM_SETTING_BOND_OPTION_MODE             "mode"

### NM_SETTING_BOND_OPTION_MIIMON

    #define NM_SETTING_BOND_OPTION_MIIMON           "miimon"

### NM_SETTING_BOND_OPTION_DOWNDELAY

    #define NM_SETTING_BOND_OPTION_DOWNDELAY        "downdelay"

### NM_SETTING_BOND_OPTION_UPDELAY

    #define NM_SETTING_BOND_OPTION_UPDELAY          "updelay"

### NM_SETTING_BOND_OPTION_ARP_INTERVAL

    #define NM_SETTING_BOND_OPTION_ARP_INTERVAL     "arp_interval"

### NM_SETTING_BOND_OPTION_ARP_IP_TARGET

    #define NM_SETTING_BOND_OPTION_ARP_IP_TARGET    "arp_ip_target"

### NM_SETTING_BOND_OPTION_ARP_VALIDATE

    #define NM_SETTING_BOND_OPTION_ARP_VALIDATE     "arp_validate"

### NM_SETTING_BOND_OPTION_PRIMARY

    #define NM_SETTING_BOND_OPTION_PRIMARY          "primary"

### NM_SETTING_BOND_OPTION_PRIMARY_RESELECT

    #define NM_SETTING_BOND_OPTION_PRIMARY_RESELECT "primary_reselect"

### NM_SETTING_BOND_OPTION_FAIL_OVER_MAC

    #define NM_SETTING_BOND_OPTION_FAIL_OVER_MAC    "fail_over_mac"

### NM_SETTING_BOND_OPTION_USE_CARRIER

    #define NM_SETTING_BOND_OPTION_USE_CARRIER      "use_carrier"

### NM_SETTING_BOND_OPTION_AD_SELECT

    #define NM_SETTING_BOND_OPTION_AD_SELECT        "ad_select"

### NM_SETTING_BOND_OPTION_XMIT_HASH_POLICY

    #define NM_SETTING_BOND_OPTION_XMIT_HASH_POLICY "xmit_hash_policy"

### NM_SETTING_BOND_OPTION_RESEND_IGMP

    #define NM_SETTING_BOND_OPTION_RESEND_IGMP      "resend_igmp"

### NM_SETTING_BOND_OPTION_LACP_RATE

    #define NM_SETTING_BOND_OPTION_LACP_RATE        "lacp_rate"

## Property Details

### The `“interface-name”` property

      “interface-name”           gchar *

The name of the virtual in-kernel bonding network interface

Flags: Read / Write

Default value: NULL

### The `“options”` property

      “options”                  GHashTable_gchararray+gchararray_*

Dictionary of key/value pairs of bonding options. Both keys and values must be strings. Option names must contain only alphanumeric characters (ie, [a-zA-Z0-9]).

Flags: Read / Write