libnl  1.1.4
Modules | Macros
Links (Interfaces)

Modules

 

Macros

#define RTNL_LINK_NOT_FOUND   -1
 Special interface index stating the link was not found.
 

Allocation/Freeing

struct rtnl_link * rtnl_link_alloc (void)
 
void rtnl_link_put (struct rtnl_link *link)
 

Cache Management

struct nl_cache * rtnl_link_alloc_cache (struct nl_handle *handle)
 Allocate link cache and fill in all configured links. More...
 
struct rtnl_link * rtnl_link_get (struct nl_cache *cache, int ifindex)
 Look up link by interface index in the provided cache. More...
 
struct rtnl_link * rtnl_link_get_by_name (struct nl_cache *cache, const char *name)
 Look up link by link name in the provided cache. More...
 

Link Modifications

struct nl_msg * rtnl_link_build_change_request (struct rtnl_link *old, struct rtnl_link *tmpl, int flags)
 Builds a netlink change request message to change link attributes. More...
 
int rtnl_link_change (struct nl_handle *handle, struct rtnl_link *old, struct rtnl_link *tmpl, int flags)
 Change link attributes. More...
 

Name <-> Index Translations

char * rtnl_link_i2name (struct nl_cache *cache, int ifindex, char *dst, size_t len)
 Translate an interface index to the corresponding link name. More...
 
int rtnl_link_name2i (struct nl_cache *cache, const char *name)
 Translate a link name to the corresponding interface index. More...
 

Link Flags Translations

char * rtnl_link_flags2str (int flags, char *buf, size_t len)
 
int rtnl_link_str2flags (const char *name)
 

Link Statistics Translations

char * rtnl_link_stat2str (int st, char *buf, size_t len)
 
int rtnl_link_str2stat (const char *name)
 

Link Operstate Translations

char * rtnl_link_operstate2str (int st, char *buf, size_t len)
 
int rtnl_link_str2operstate (const char *name)
 

Link Mode Translations

char * rtnl_link_mode2str (int st, char *buf, size_t len)
 
int rtnl_link_str2mode (const char *name)
 

Attributes

void rtnl_link_set_qdisc (struct rtnl_link *link, const char *qdisc)
 
char * rtnl_link_get_qdisc (struct rtnl_link *link)
 
void rtnl_link_set_name (struct rtnl_link *link, const char *name)
 
char * rtnl_link_get_name (struct rtnl_link *link)
 
void rtnl_link_set_addr (struct rtnl_link *link, struct nl_addr *addr)
 
struct nl_addr * rtnl_link_get_addr (struct rtnl_link *link)
 
void rtnl_link_set_broadcast (struct rtnl_link *link, struct nl_addr *brd)
 
struct nl_addr * rtnl_link_get_broadcast (struct rtnl_link *link)
 
void rtnl_link_set_flags (struct rtnl_link *link, unsigned int flags)
 
void rtnl_link_unset_flags (struct rtnl_link *link, unsigned int flags)
 
unsigned int rtnl_link_get_flags (struct rtnl_link *link)
 
void rtnl_link_set_family (struct rtnl_link *link, int family)
 
int rtnl_link_get_family (struct rtnl_link *link)
 
void rtnl_link_set_arptype (struct rtnl_link *link, unsigned int arptype)
 
unsigned int rtnl_link_get_arptype (struct rtnl_link *link)
 
void rtnl_link_set_ifindex (struct rtnl_link *link, int ifindex)
 
int rtnl_link_get_ifindex (struct rtnl_link *link)
 
void rtnl_link_set_mtu (struct rtnl_link *link, unsigned int mtu)
 
unsigned int rtnl_link_get_mtu (struct rtnl_link *link)
 
void rtnl_link_set_txqlen (struct rtnl_link *link, unsigned int txqlen)
 
unsigned int rtnl_link_get_txqlen (struct rtnl_link *link)
 
void rtnl_link_set_weight (struct rtnl_link *link, unsigned int weight)
 
unsigned int rtnl_link_get_weight (struct rtnl_link *link)
 
void rtnl_link_set_link (struct rtnl_link *link, int ifindex)
 
int rtnl_link_get_link (struct rtnl_link *link)
 
void rtnl_link_set_master (struct rtnl_link *link, int ifindex)
 
int rtnl_link_get_master (struct rtnl_link *link)
 
void rtnl_link_set_operstate (struct rtnl_link *link, uint8_t operstate)
 
uint8_t rtnl_link_get_operstate (struct rtnl_link *link)
 
void rtnl_link_set_linkmode (struct rtnl_link *link, uint8_t linkmode)
 
uint8_t rtnl_link_get_linkmode (struct rtnl_link *link)
 
uint64_t rtnl_link_get_stat (struct rtnl_link *link, int id)
 
int rtnl_link_set_info_type (struct rtnl_link *link, const char *type)
 Specify the info type of a link. More...
 
char * rtnl_link_get_info_type (struct rtnl_link *link)
 Return info type of a link. More...
 

Detailed Description

Link Identification
A link can be identified by either its interface index or by its name. The kernel favours the interface index but falls back to the interface name if the interface index is lesser-than 0 for kernels >= 2.6.11. Therefore you can request changes without mapping a interface name to the corresponding index first.
Changeable Attributes
  • Link layer address
  • Link layer broadcast address
  • device mapping (ifmap) (>= 2.6.9)
  • MTU (>= 2.6.9)
  • Transmission queue length (>= 2.6.9)
  • Weight (>= 2.6.9)
  • Link name (only via access through interface index) (>= 2.6.9)
  • Flags (>= 2.6.9)
    • IFF_DEBUG
    • IFF_NOTRAILERS
    • IFF_NOARP
    • IFF_DYNAMIC
    • IFF_MULTICAST
    • IFF_PORTSEL
    • IFF_AUTOMEDIA
    • IFF_UP
    • IFF_PROMISC
    • IFF_ALLMULTI
Link Flags (linux/if.h)
IFF_UP Status of link (up|down)
IFF_BROADCAST Indicates this link allows broadcasting
IFF_MULTICAST Indicates this link allows multicasting
IFF_ALLMULTI Indicates this link is doing multicast routing
IFF_DEBUG Tell the driver to do debugging (currently unused)
IFF_LOOPBACK This is the loopback link
IFF_POINTOPOINT Point-to-point link
IFF_NOARP Link is unable to perform ARP
IFF_PROMISC Status of promiscious mode flag
IFF_MASTER Used by teql
IFF_SLAVE Used by teql
IFF_PORTSEL Indicates this link allows port selection
IFF_AUTOMEDIA Indicates this link selects port automatically
IFF_DYNAMIC Indicates the address of this link is dynamic
IFF_RUNNING Link is running and carrier is ok.
IFF_NOTRAILERS Unused, BSD compat.
Notes on IFF_PROMISC and IFF_ALLMULTI flags
Although you can query the status of IFF_PROMISC and IFF_ALLMULTI they do not represent the actual state in the kernel but rather whether the flag has been enabled/disabled by userspace. The link may be in promiscious mode even if IFF_PROMISC is not set in a link dump request response because promiscity might be needed by the driver for a period of time.
Note
The unit of the transmission queue length depends on the link type, a common unit is packets.
1) Retrieving information about available links
// The first step is to retrieve a list of all available interfaces within
// the kernel and put them into a cache.
struct nl_cache *cache = rtnl_link_alloc_cache(nl_handle);
// In a second step, a specific link may be looked up by either interface
// index or interface name.
struct rtnl_link *link = rtnl_link_get_by_name(cache, "lo");
// rtnl_link_get_by_name() is the short version for translating the
// interface name to an interface index first like this:
int ifindex = rtnl_link_name2i(cache, "lo");
struct rtnl_link *link = rtnl_link_get(cache, ifindex);
// After successful usage, the object must be given back to the cache
rtnl_link_put(link);
2) Changing link attributes
// In order to change any attributes of an existing link, we must allocate
// a new link to hold the change requests:
struct rtnl_link *request = rtnl_link_alloc();
// Now we can go on and specify the attributes we want to change:
rtnl_link_set_weight(request, 300);
rtnl_link_set_mtu(request, 1360);
// We can also shut an interface down administratively
rtnl_link_unset_flags(request, rtnl_link_str2flags("up"));
// Actually, we should know which link to change, so let's look it up
struct rtnl_link *old = rtnl_link_get(cache, "eth0");
// Two ways exist to commit this change request, the first one is to
// build the required netlink message and send it out in one single
// step:
rtnl_link_change(nl_handle, old, request);
// An alternative way is to build the netlink message and send it
// out yourself using nl_send_auto_complete()
struct nl_msg *msg = rtnl_link_build_change_request(old, request);
// Don't forget to give back the link object ;->
rtnl_link_put(old);
3) Link Type Specific Attributes
// Some link types offer additional parameters and statistics specific
// to their type. F.e. a VLAN link can be configured like this:
//
// Allocate a new link and set the info type to "vlan". This is required
// to prepare the link to hold vlan specific attributes.
struct rtnl_link *request = rtnl_link_alloc();
rtnl_link_set_info_type(request, "vlan");
// Now vlan specific attributes can be set:
rtnl_link_vlan_set_id(request, 10);
rtnl_link_vlan_set_ingress_map(request, 2, 8);
// Of course the attributes can also be read, check the info type
// to make sure you are using the right access functions:
char *type = rtnl_link_get_info_type(link);
if (!strcmp(type, "vlan"))
int id = rtnl_link_vlan_get_id(link);

Function Documentation

◆ rtnl_link_alloc_cache()

struct nl_cache* rtnl_link_alloc_cache ( struct nl_handle *  handle)
Parameters
handleNetlink handle.

Allocates a new link cache, initializes it properly and updates it to include all links currently configured in the kernel.

Note
Free the memory after usage.
Returns
Newly allocated cache or NULL if an error occured.

Definition at line 869 of file link.c.

References nl_cache_alloc().

870 {
871  struct nl_cache * cache;
872 
873  cache = nl_cache_alloc(&rtnl_link_ops);
874  if (cache == NULL)
875  return NULL;
876 
877  if (handle && nl_cache_refill(handle, cache) < 0) {
878  nl_cache_free(cache);
879  return NULL;
880  }
881 
882  return cache;
883 }
void nl_cache_free(struct nl_cache *cache)
Free a cache.
Definition: cache.c:277
int nl_cache_refill(struct nl_handle *handle, struct nl_cache *cache)
(Re)fill a cache with the contents in the kernel.
Definition: cache.c:680
struct nl_cache * nl_cache_alloc(struct nl_cache_ops *ops)
Allocate an empty cache.
Definition: cache.c:170

◆ rtnl_link_get()

struct rtnl_link* rtnl_link_get ( struct nl_cache *  cache,
int  ifindex 
)
Parameters
cachelink cache
ifindexlink interface index

The caller owns a reference on the returned object and must give the object back via rtnl_link_put().

Returns
pointer to link inside the cache or NULL if no match was found.

Definition at line 895 of file link.c.

Referenced by rtnl_link_i2name().

896 {
897  struct rtnl_link *link;
898 
899  if (cache->c_ops != &rtnl_link_ops)
900  return NULL;
901 
902  nl_list_for_each_entry(link, &cache->c_items, ce_list) {
903  if (link->l_index == ifindex) {
904  nl_object_get((struct nl_object *) link);
905  return link;
906  }
907  }
908 
909  return NULL;
910 }
void nl_object_get(struct nl_object *obj)
Acquire a reference on a object.
Definition: object.c:167

◆ rtnl_link_get_by_name()

struct rtnl_link* rtnl_link_get_by_name ( struct nl_cache *  cache,
const char *  name 
)
Parameters
cachelink cache
namelink name

The caller owns a reference on the returned object and must give the object back via rtnl_link_put().

Returns
pointer to link inside the cache or NULL if no match was found.

Definition at line 922 of file link.c.

Referenced by rtnl_link_name2i().

924 {
925  struct rtnl_link *link;
926 
927  if (cache->c_ops != &rtnl_link_ops)
928  return NULL;
929 
930  nl_list_for_each_entry(link, &cache->c_items, ce_list) {
931  if (!strcmp(name, link->l_name)) {
932  nl_object_get((struct nl_object *) link);
933  return link;
934  }
935  }
936 
937  return NULL;
938 }
void nl_object_get(struct nl_object *obj)
Acquire a reference on a object.
Definition: object.c:167

◆ rtnl_link_build_change_request()

struct nl_msg* rtnl_link_build_change_request ( struct rtnl_link *  old,
struct rtnl_link *  tmpl,
int  flags 
)
Parameters
oldlink to be changed
tmpltemplate with requested changes
flagsadditional netlink message flags

Builds a new netlink message requesting a change of link attributes. The netlink message header isn't fully equipped with all relevant fields and must be sent out via nl_send_auto_complete() or supplemented as needed. old must point to a link currently configured in the kernel and tmpl must contain the attributes to be changed set via rtnl_link_set_* functions.

Returns
New netlink message
Note
Not all attributes can be changed, see Changeable Attributes for more details.

Definition at line 965 of file link.c.

References nla_nest_end(), nla_nest_start(), NLA_PUT_ADDR, NLA_PUT_STRING, NLA_PUT_U32, NLA_PUT_U8, nlmsg_alloc_simple(), nlmsg_append(), and nlmsg_free().

Referenced by rtnl_link_change().

968 {
969  struct nl_msg *msg;
970  struct ifinfomsg ifi = {
971  .ifi_family = old->l_family,
972  .ifi_index = old->l_index,
973  };
974 
975  if (tmpl->ce_mask & LINK_ATTR_FLAGS) {
976  ifi.ifi_flags = old->l_flags & ~tmpl->l_flag_mask;
977  ifi.ifi_flags |= tmpl->l_flags;
978  }
979 
980  msg = nlmsg_alloc_simple(RTM_SETLINK, flags);
981  if (!msg)
982  goto nla_put_failure;
983 
984  if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0)
985  goto nla_put_failure;
986 
987  if (tmpl->ce_mask & LINK_ATTR_ADDR)
988  NLA_PUT_ADDR(msg, IFLA_ADDRESS, tmpl->l_addr);
989 
990  if (tmpl->ce_mask & LINK_ATTR_BRD)
991  NLA_PUT_ADDR(msg, IFLA_BROADCAST, tmpl->l_bcast);
992 
993  if (tmpl->ce_mask & LINK_ATTR_MTU)
994  NLA_PUT_U32(msg, IFLA_MTU, tmpl->l_mtu);
995 
996  if (tmpl->ce_mask & LINK_ATTR_TXQLEN)
997  NLA_PUT_U32(msg, IFLA_TXQLEN, tmpl->l_txqlen);
998 
999  if (tmpl->ce_mask & LINK_ATTR_WEIGHT)
1000  NLA_PUT_U32(msg, IFLA_WEIGHT, tmpl->l_weight);
1001 
1002  if (tmpl->ce_mask & LINK_ATTR_IFNAME)
1003  NLA_PUT_STRING(msg, IFLA_IFNAME, tmpl->l_name);
1004 
1005  if (tmpl->ce_mask & LINK_ATTR_OPERSTATE)
1006  NLA_PUT_U8(msg, IFLA_OPERSTATE, tmpl->l_operstate);
1007 
1008  if (tmpl->ce_mask & LINK_ATTR_LINKMODE)
1009  NLA_PUT_U8(msg, IFLA_LINKMODE, tmpl->l_linkmode);
1010 
1011  if ((tmpl->ce_mask & LINK_ATTR_LINKINFO) && tmpl->l_info_ops &&
1012  tmpl->l_info_ops->io_put_attrs) {
1013  struct nlattr *info;
1014 
1015  if (!(info = nla_nest_start(msg, IFLA_LINKINFO)))
1016  goto nla_put_failure;
1017 
1018  NLA_PUT_STRING(msg, IFLA_INFO_KIND, tmpl->l_info_ops->io_name);
1019 
1020  if (tmpl->l_info_ops->io_put_attrs(msg, tmpl) < 0)
1021  goto nla_put_failure;
1022 
1023  nla_nest_end(msg, info);
1024  }
1025 
1026  return msg;
1027 
1028 nla_put_failure:
1029  nlmsg_free(msg);
1030  return NULL;
1031 }
void nlmsg_free(struct nl_msg *n)
Free a netlink message.
Definition: msg.c:656
int nla_nest_end(struct nl_msg *n, struct nlattr *start)
Finalize nesting of attributes.
Definition: attr.c:675
#define NLA_PUT_STRING(n, attrtype, value)
Add a character string netlink attribute to a netlink message.
Definition: attr.h:219
#define NLA_PUT_U8(n, attrtype, value)
Add a u8 netlink attribute to a netlink message.
Definition: attr.h:183
#define NLA_PUT_ADDR(n, attrtype, addr)
Add a address attribute to a netlink message.
Definition: attr.h:245
int nlmsg_append(struct nl_msg *n, void *data, size_t len, int pad)
Append data to tail of a netlink message.
Definition: msg.c:549
struct nl_msg * nlmsg_alloc_simple(int nlmsgtype, int flags)
Allocate a new netlink message.
Definition: msg.c:448
struct nlattr * nla_nest_start(struct nl_msg *n, int attrtype)
Start a new level of nested attributes.
Definition: attr.c:655
#define NLA_PUT_U32(n, attrtype, value)
Add a u32 netlink attribute to a netlink message.
Definition: attr.h:201

◆ rtnl_link_change()

int rtnl_link_change ( struct nl_handle *  handle,
struct rtnl_link *  old,
struct rtnl_link *  tmpl,
int  flags 
)
Parameters
handlenetlink handle
oldlink to be changed
tmpltemplate with requested changes
flagsadditional netlink message flags

Builds a new netlink message by calling rtnl_link_build_change_request(), sends the request to the kernel and waits for the next ACK to be received, i.e. blocks until the request has been processed.

Returns
0 on success or a negative error code
Note
Not all attributes can be changed, see Changeable Attributes for more details.

Definition at line 1048 of file link.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_link_build_change_request().

1050 {
1051  int err;
1052  struct nl_msg *msg;
1053 
1054  msg = rtnl_link_build_change_request(old, tmpl, flags);
1055  if (!msg)
1056  return nl_errno(ENOMEM);
1057 
1058  err = nl_send_auto_complete(handle, msg);
1059  nlmsg_free(msg);
1060  if (err < 0)
1061  return err;
1062 
1063  return nl_wait_for_ack(handle);
1064 }
int nl_wait_for_ack(struct nl_handle *handle)
Wait for ACK.
Definition: nl.c:801
void nlmsg_free(struct nl_msg *n)
Free a netlink message.
Definition: msg.c:656
int nl_send_auto_complete(struct nl_handle *handle, struct nl_msg *msg)
Send netlink message and check & extend header values as needed.
Definition: nl.c:373

◆ rtnl_link_i2name()

char* rtnl_link_i2name ( struct nl_cache *  cache,
int  ifindex,
char *  dst,
size_t  len 
)
Parameters
cachelink cache
ifindexlink interface index
dstdestination buffer
lenlength of destination buffer

Translates the specified interface index to the corresponding link name and stores the name in the destination buffer.

Returns
link name or NULL if no match was found.

Definition at line 1085 of file link.c.

References rtnl_link_get().

1087 {
1088  struct rtnl_link *link = rtnl_link_get(cache, ifindex);
1089 
1090  if (link) {
1091  strncpy(dst, link->l_name, len - 1);
1092  rtnl_link_put(link);
1093  return dst;
1094  }
1095 
1096  return NULL;
1097 }

◆ rtnl_link_name2i()

int rtnl_link_name2i ( struct nl_cache *  cache,
const char *  name 
)
Parameters
cachelink cache
namelink name
Returns
interface index or RTNL_LINK_NOT_FOUND if no match was found.

Definition at line 1106 of file link.c.

References rtnl_link_get_by_name(), and RTNL_LINK_NOT_FOUND.

1107 {
1108  int ifindex = RTNL_LINK_NOT_FOUND;
1109  struct rtnl_link *link;
1110 
1111  link = rtnl_link_get_by_name(cache, name);
1112  if (link) {
1113  ifindex = link->l_index;
1114  rtnl_link_put(link);
1115  }
1116 
1117  return ifindex;
1118 }

◆ rtnl_link_set_info_type()

int rtnl_link_set_info_type ( struct rtnl_link *  link,
const char *  type 
)
Parameters
linklink object
typeinfo type

Looks up the info type and prepares the link to store info type specific attributes. If an info type has been assigned already it will be released with all changes lost.

Returns
0 on success or a negative errror code.

Definition at line 1501 of file link.c.

1502 {
1503  struct rtnl_link_info_ops *io;
1504  int err;
1505 
1506  if ((io = rtnl_link_info_ops_lookup(type)) == NULL)
1507  return nl_error(ENOENT, "No such link info type exists");
1508 
1509  if (link->l_info_ops)
1510  release_link_info(link);
1511 
1512  if ((err = io->io_alloc(link)) < 0)
1513  return err;
1514 
1515  link->l_info_ops = io;
1516 
1517  return 0;
1518 }

◆ rtnl_link_get_info_type()

char* rtnl_link_get_info_type ( struct rtnl_link *  link)
Parameters
linklink object
Note
The returned pointer is only valid as long as the link exists
Returns
Info type name or NULL if unknown.

Definition at line 1527 of file link.c.

1528 {
1529  if (link->l_info_ops)
1530  return link->l_info_ops->io_name;
1531  else
1532  return NULL;
1533 }