Links (Interfaces)
[Routing Netlink]

Modules

 Link Info API

Defines

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

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)

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.
struct rtnl_link * rtnl_link_get (struct nl_cache *cache, int ifindex)
 Look up link by interface index in the provided cache.
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.

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.
int rtnl_link_change (struct nl_handle *handle, struct rtnl_link *old, struct rtnl_link *tmpl, int flags)
 Change link attributes.

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.
int rtnl_link_name2i (struct nl_cache *cache, const char *name)
 Translate a link name to the corresponding interface index.

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.
char * rtnl_link_get_info_type (struct rtnl_link *link)
 Return info type of a link.

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);
 nl_send_auto_complete(nl_handle, nlmsg_hdr(msg));
 nlmsg_free(msg);

 // 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

struct nl_cache* rtnl_link_alloc_cache ( struct nl_handle *  handle  )  [read]
Parameters:
handle Netlink 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 874 of file link.c.

References nl_cache_alloc(), nl_cache_free(), and nl_cache_refill().

00875 {
00876         struct nl_cache * cache;
00877         
00878         cache = nl_cache_alloc(&rtnl_link_ops);
00879         if (cache == NULL)
00880                 return NULL;
00881         
00882         if (handle && nl_cache_refill(handle, cache) < 0) {
00883                 nl_cache_free(cache);
00884                 return NULL;
00885         }
00886 
00887         return cache;
00888 }

struct rtnl_link* rtnl_link_get ( struct nl_cache *  cache,
int  ifindex 
) [read]
Parameters:
cache link cache
ifindex link 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 900 of file link.c.

References nl_object_get().

Referenced by rtnl_link_i2name().

00901 {
00902         struct rtnl_link *link;
00903 
00904         if (cache->c_ops != &rtnl_link_ops)
00905                 return NULL;
00906 
00907         nl_list_for_each_entry(link, &cache->c_items, ce_list) {
00908                 if (link->l_index == ifindex) {
00909                         nl_object_get((struct nl_object *) link);
00910                         return link;
00911                 }
00912         }
00913 
00914         return NULL;
00915 }

struct rtnl_link* rtnl_link_get_by_name ( struct nl_cache *  cache,
const char *  name 
) [read]
Parameters:
cache link cache
name link 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 927 of file link.c.

References nl_object_get().

Referenced by rtnl_link_name2i().

00929 {
00930         struct rtnl_link *link;
00931 
00932         if (cache->c_ops != &rtnl_link_ops)
00933                 return NULL;
00934 
00935         nl_list_for_each_entry(link, &cache->c_items, ce_list) {
00936                 if (!strcmp(name, link->l_name)) {
00937                         nl_object_get((struct nl_object *) link);
00938                         return link;
00939                 }
00940         }
00941 
00942         return NULL;
00943 }

struct nl_msg* rtnl_link_build_change_request ( struct rtnl_link *  old,
struct rtnl_link *  tmpl,
int  flags 
) [read]
Parameters:
old link to be changed
tmpl template with requested changes
flags additional 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 970 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().

00973 {
00974         struct nl_msg *msg;
00975         struct ifinfomsg ifi = {
00976                 .ifi_family = old->l_family,
00977                 .ifi_index = old->l_index,
00978         };
00979 
00980         if (tmpl->ce_mask & LINK_ATTR_FLAGS) {
00981                 ifi.ifi_flags = old->l_flags & ~tmpl->l_flag_mask;
00982                 ifi.ifi_flags |= tmpl->l_flags;
00983         }
00984 
00985         msg = nlmsg_alloc_simple(RTM_SETLINK, flags);
00986         if (!msg)
00987                 goto nla_put_failure;
00988 
00989         if (nlmsg_append(msg, &ifi, sizeof(ifi), NLMSG_ALIGNTO) < 0)
00990                 goto nla_put_failure;
00991 
00992         if (tmpl->ce_mask & LINK_ATTR_ADDR)
00993                 NLA_PUT_ADDR(msg, IFLA_ADDRESS, tmpl->l_addr);
00994 
00995         if (tmpl->ce_mask & LINK_ATTR_BRD)
00996                 NLA_PUT_ADDR(msg, IFLA_BROADCAST, tmpl->l_bcast);
00997 
00998         if (tmpl->ce_mask & LINK_ATTR_MTU)
00999                 NLA_PUT_U32(msg, IFLA_MTU, tmpl->l_mtu);
01000 
01001         if (tmpl->ce_mask & LINK_ATTR_TXQLEN)
01002                 NLA_PUT_U32(msg, IFLA_TXQLEN, tmpl->l_txqlen);
01003 
01004         if (tmpl->ce_mask & LINK_ATTR_WEIGHT)
01005                 NLA_PUT_U32(msg, IFLA_WEIGHT, tmpl->l_weight);
01006 
01007         if (tmpl->ce_mask & LINK_ATTR_IFNAME)
01008                 NLA_PUT_STRING(msg, IFLA_IFNAME, tmpl->l_name);
01009 
01010         if (tmpl->ce_mask & LINK_ATTR_OPERSTATE)
01011                 NLA_PUT_U8(msg, IFLA_OPERSTATE, tmpl->l_operstate);
01012 
01013         if (tmpl->ce_mask & LINK_ATTR_LINKMODE)
01014                 NLA_PUT_U8(msg, IFLA_LINKMODE, tmpl->l_linkmode);
01015 
01016         if ((tmpl->ce_mask & LINK_ATTR_LINKINFO) && tmpl->l_info_ops &&
01017             tmpl->l_info_ops->io_put_attrs) {
01018                 struct nlattr *info;
01019 
01020                 if (!(info = nla_nest_start(msg, IFLA_LINKINFO)))
01021                         goto nla_put_failure;
01022 
01023                 NLA_PUT_STRING(msg, IFLA_INFO_KIND, tmpl->l_info_ops->io_name);
01024 
01025                 if (tmpl->l_info_ops->io_put_attrs(msg, tmpl) < 0)
01026                         goto nla_put_failure;
01027 
01028                 nla_nest_end(msg, info);
01029         }
01030 
01031         return msg;
01032 
01033 nla_put_failure:
01034         nlmsg_free(msg);
01035         return NULL;
01036 }

int rtnl_link_change ( struct nl_handle *  handle,
struct rtnl_link *  old,
struct rtnl_link *  tmpl,
int  flags 
)
Parameters:
handle netlink handle
old link to be changed
tmpl template with requested changes
flags additional 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 1053 of file link.c.

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

01055 {
01056         int err;
01057         struct nl_msg *msg;
01058         
01059         msg = rtnl_link_build_change_request(old, tmpl, flags);
01060         if (!msg)
01061                 return nl_errno(ENOMEM);
01062         
01063         err = nl_send_auto_complete(handle, msg);
01064         if (err < 0)
01065                 return err;
01066 
01067         nlmsg_free(msg);
01068         return nl_wait_for_ack(handle);
01069 }

char* rtnl_link_i2name ( struct nl_cache *  cache,
int  ifindex,
char *  dst,
size_t  len 
)
Parameters:
cache link cache
ifindex link interface index
dst destination buffer
len length 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 1090 of file link.c.

References rtnl_link_get().

01092 {
01093         struct rtnl_link *link = rtnl_link_get(cache, ifindex);
01094 
01095         if (link) {
01096                 strncpy(dst, link->l_name, len - 1);
01097                 rtnl_link_put(link);
01098                 return dst;
01099         }
01100 
01101         return NULL;
01102 }

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

Definition at line 1111 of file link.c.

References rtnl_link_get_by_name(), and RTNL_LINK_NOT_FOUND.

01112 {
01113         int ifindex = RTNL_LINK_NOT_FOUND;
01114         struct rtnl_link *link;
01115         
01116         link = rtnl_link_get_by_name(cache, name);
01117         if (link) {
01118                 ifindex = link->l_index;
01119                 rtnl_link_put(link);
01120         }
01121 
01122         return ifindex;
01123 }

int rtnl_link_set_info_type ( struct rtnl_link *  link,
const char *  type 
)
Parameters:
link link object
type info 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 1506 of file link.c.

References rtnl_link_info_ops::io_alloc.

01507 {
01508         struct rtnl_link_info_ops *io;
01509         int err;
01510 
01511         if ((io = rtnl_link_info_ops_lookup(type)) == NULL)
01512                 return nl_error(ENOENT, "No such link info type exists");
01513 
01514         if (link->l_info_ops)
01515                 release_link_info(link);
01516 
01517         if ((err = io->io_alloc(link)) < 0)
01518                 return err;
01519 
01520         link->l_info_ops = io;
01521 
01522         return 0;
01523 }

char* rtnl_link_get_info_type ( struct rtnl_link *  link  ) 
Parameters:
link link 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 1532 of file link.c.

01533 {
01534         if (link->l_info_ops)
01535                 return link->l_info_ops->io_name;
01536         else
01537                 return NULL;
01538 }


Generated on 30 Oct 2009 for libnl by  doxygen 1.6.1