Links (Interfaces)
[Routing Netlink]


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


Link Flags Translations

char * rtnl_link_flags2str (int flags, char *buf, size_t len)
 Convert link flags to a character string (Reentrant).
int rtnl_link_str2flags (const char *name)
 Convert a character string to a link flag.

Link Statistics Translations

char * rtnl_link_stat2str (int st, char *buf, size_t len)
 Convert a link statistic to a character string (Reentrant).
int rtnl_link_str2stat (const char *name)
 Convert a character string to a link statistic.

Link Object Allocation/Freeage

rtnl_link * rtnl_link_alloc (void)
 Allocate and initialize new link object.
void rtnl_link_put (struct rtnl_link *link)
 Give back reference on link object.
void rtnl_link_free (struct rtnl_link *link)
 Free link object.

Link Cache Management

nl_cache * rtnl_link_alloc_cache (struct nl_handle *handle)
 Allocate link cache and fill in all configured links.
rtnl_link * rtnl_link_get (struct nl_cache *cache, int ifindex)
 Look up link by interface index in the provided cache.
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

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.

Attribute Modification

void rtnl_link_set_qdisc (struct rtnl_link *link, const char *qdisc)
 Set QDisc name.
char * rtnl_link_get_qdisc (struct rtnl_link *link)
 Get QDisc name.
void rtnl_link_set_name (struct rtnl_link *link, const char *name)
 Set new link name.
char * rtnl_link_get_name (struct rtnl_link *link)
 Get link name.
void rtnl_link_set_addr (struct rtnl_link *link, struct nl_addr *addr)
 Set link layer address.
nl_addr * rtnl_link_get_addr (struct rtnl_link *link)
 Get link layer address.
void rtnl_link_set_broadcast (struct rtnl_link *link, struct nl_addr *brd)
 Set link layer broadcast address.
nl_addr * rtnl_link_get_broadcast (struct rtnl_link *link)
 Get link layer broadcast address.
void rtnl_link_set_flags (struct rtnl_link *link, unsigned int flags)
 Set flags.
void rtnl_link_unset_flags (struct rtnl_link *link, unsigned int flags)
 Unset flags.
unsigned int rtnl_link_get_flags (struct rtnl_link *link)
 Get flags.
void rtnl_link_set_family (struct rtnl_link *link, int family)
 Set link layer address family.
int rtnl_link_get_family (struct rtnl_link *link)
 Get link layer address family.
void rtnl_link_set_type (struct rtnl_link *link, unsigned int arptype)
 Set link layer type.
unsigned int rtnl_link_get_arptype (struct rtnl_link *link)
 Get link layer type.
void rtnl_link_set_ifindex (struct rtnl_link *link, int ifindex)
 Set interface index.
int rtnl_link_get_ifindex (struct rtnl_link *link)
 Get interface index.
void rtnl_link_set_mtu (struct rtnl_link *link, unsigned int mtu)
 Set Maximum Transmission Unit.
unsigned int rtnl_link_get_mtu (struct rtnl_link *link)
 Get Maximum Transmission Unit.
void rtnl_link_set_txqlen (struct rtnl_link *link, unsigned int txqlen)
 Set Transmission Queue Length.
unsigned int rtnl_link_get_txqlen (struct rtnl_link *link)
 Get Transmission Queue Length.
void rtnl_link_set_weight (struct rtnl_link *link, unsigned int weight)
 Set Weight.
unsigned int rtnl_link_get_weight (struct rtnl_link *link)
 Get Weight.
void rtnl_link_set_link (struct rtnl_link *link, int ifindex)
 Set parent interface index.
int rtnl_link_get_link (struct rtnl_link *link)
 Get parent interface index.
void rtnl_link_set_master (struct rtnl_link *link, int ifindex)
 Set master interface index.
int rtnl_link_get_master (struct rtnl_link *link)
 Get master interface index.
uint64_t rtnl_link_get_stat (struct rtnl_link *link, int id)
 Get the statistic specified by the id.

Defines

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


Define Documentation

#define RTNL_LINK_NOT_FOUND   -1

Special interface index stating the link was not found.

Definition at line 54 of file link.h.

Referenced by rtnl_addr_get_ifindex(), rtnl_link_get_ifindex(), rtnl_link_get_link(), rtnl_link_get_master(), rtnl_link_name2i(), rtnl_neigh_get_ifindex(), and rtnl_route_get_oif().


Function Documentation

struct rtnl_link* rtnl_link_alloc ( void   ) 

Allocate and initialize new link object.

Note:
Free the memory after usage using rtnl_link_put() or rtnl_link_free().
Returns:
Newly allocated link object or NULL if an error occured.

Definition at line 672 of file link.c.

References nl_object_alloc_from_ops().

void rtnl_link_put ( struct rtnl_link *  link  ) 

Give back reference on link object.

Parameters:
link Link object to be given back.
Decrements the reference counter and frees the object if the last reference has been released.

Definition at line 684 of file link.c.

References nl_object_put().

Referenced by rtnl_link_i2name(), and rtnl_link_name2i().

void rtnl_link_free ( struct rtnl_link *  link  ) 

Free link object.

Parameters:
link Link object to be freed.
Note:
Always use rtnl_link_put() unless you're absolutely sure that no other user may have a reference on this object.

Definition at line 695 of file link.c.

References nl_object_free().

struct nl_cache* rtnl_link_alloc_cache ( struct nl_handle *  handle  ) 

Allocate link cache and fill in all configured links.

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 718 of file link.c.

References nl_cache_alloc_from_ops(), nl_cache_free(), and nl_cache_update().

struct rtnl_link* rtnl_link_get ( struct nl_cache *  cache,
int  ifindex 
)

Look up link by interface index in the provided cache.

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 744 of file link.c.

References nl_object_get().

Referenced by rtnl_link_i2name().

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.

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 771 of file link.c.

References nl_object_get().

Referenced by rtnl_link_name2i().

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.

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 814 of file link.c.

References ifinfomsg::ifi_family, ifinfomsg::ifi_flags, NLA_PUT_ADDR, NLA_PUT_STRING, NLA_PUT_U32, nlmsg_append(), nlmsg_build_simple(), and nlmsg_free().

Referenced by rtnl_link_change().

int rtnl_link_change ( struct nl_handle *  handle,
struct rtnl_link *  old,
struct rtnl_link *  tmpl,
int  flags 
)

Change link attributes.

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 876 of file link.c.

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

char* rtnl_link_i2name ( struct nl_cache *  cache,
int  ifindex,
char *  dst,
size_t  len 
)

Translate an interface index to the corresponding link name.

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 913 of file link.c.

References rtnl_link_get(), and rtnl_link_put().

int rtnl_link_name2i ( struct nl_cache *  cache,
const char *  name 
)

Translate a link name to the corresponding interface index.

Parameters:
cache link cache
name link name
Returns:
interface index or RTNL_LINK_NOT_FOUND if no match was found.

Definition at line 934 of file link.c.

References rtnl_link_get_by_name(), RTNL_LINK_NOT_FOUND, and rtnl_link_put().

char* rtnl_link_flags2str ( int  flags,
char *  buf,
size_t  len 
)

Convert link flags to a character string (Reentrant).

Parameters:
flags link flags
buf destination buffer
len buffer length
Converts link flags to a character string separated by commands and stores it in the specified destination buffer.

Returns:
The destination buffer

Definition at line 987 of file link.c.

int rtnl_link_str2flags ( const char *  name  ) 

Convert a character string to a link flag.

Parameters:
name Name of link flag
Converts the provided character string specifying a link link the corresponding numeric value.

Returns:
Link flag or a negative value if none was found.

Definition at line 1002 of file link.c.

char* rtnl_link_stat2str ( int  st,
char *  buf,
size_t  len 
)

Convert a link statistic to a character string (Reentrant).

Parameters:
st link statistic
buf destination buffer
len buffer length
Converts a link statistic to a character string and stores it in the specified destination buffer.

Returns:
The destination buffer or the statistic encoded in hexidecimal form if no match was found.

Definition at line 1052 of file link.c.

int rtnl_link_str2stat ( const char *  name  ) 

Convert a character string to a link statistic.

Parameters:
name name of link statistic
Converts the provided character string specifying a link statistic to the corresponding numeric value.

Returns:
Link statistic or a negative value if none was found.

Definition at line 1066 of file link.c.

void rtnl_link_set_qdisc ( struct rtnl_link *  link,
const char *  qdisc 
)

Set QDisc name.

Parameters:
link link to change
qdisc qdisc name

Definition at line 1083 of file link.c.

char* rtnl_link_get_qdisc ( struct rtnl_link *  link  ) 

Get QDisc name.

Parameters:
link link handle
Returns:
Name of the qdisc or NULL if not set.

Definition at line 1094 of file link.c.

void rtnl_link_set_name ( struct rtnl_link *  link,
const char *  name 
)

Set new link name.

Parameters:
link link to change
name new link name

Definition at line 1107 of file link.c.

char* rtnl_link_get_name ( struct rtnl_link *  link  ) 

Get link name.

Parameters:
link link handle
Returns:
Name of the link or NULL if not set.

Definition at line 1118 of file link.c.

void rtnl_link_set_addr ( struct rtnl_link *  link,
struct nl_addr *  addr 
)

Set link layer address.

Parameters:
link link to change
addr new link layer address

Definition at line 1143 of file link.c.

struct nl_addr* rtnl_link_get_addr ( struct rtnl_link *  link  ) 

Get link layer address.

Parameters:
link link handle
Returns:
link layer address or NULL if not set

Definition at line 1153 of file link.c.

void rtnl_link_set_broadcast ( struct rtnl_link *  link,
struct nl_addr *  brd 
)

Set link layer broadcast address.

Parameters:
link link to change
brd new link layer broadcast address
Assigns the new broadcast address to the specified link handle.

Note:
The prefix length of the address will be ignored.

Definition at line 1170 of file link.c.

struct nl_addr* rtnl_link_get_broadcast ( struct rtnl_link *  link  ) 

Get link layer broadcast address.

Parameters:
link link handle
Returns:
Link layer broadcast address or NULL if not set

Definition at line 1180 of file link.c.

void rtnl_link_set_flags ( struct rtnl_link *  link,
unsigned int  flags 
)

Set flags.

Parameters:
link link to change
flags flags to set (see Link Flags)

Definition at line 1193 of file link.c.

void rtnl_link_unset_flags ( struct rtnl_link *  link,
unsigned int  flags 
)

Unset flags.

Parameters:
link link to change
flags flags to unset (see Link Flags)

Definition at line 1205 of file link.c.

unsigned int rtnl_link_get_flags ( struct rtnl_link *  link  ) 

Get flags.

Parameters:
link link handle
Returns:
Link flags

Definition at line 1217 of file link.c.

void rtnl_link_set_family ( struct rtnl_link *  link,
int  family 
)

Set link layer address family.

Parameters:
link link to change
family new address family

Definition at line 1227 of file link.c.

int rtnl_link_get_family ( struct rtnl_link *  link  ) 

Get link layer address family.

Parameters:
link link handle
Returns:
Link layer address family or AF_UNSPEC if not set.

Definition at line 1238 of file link.c.

void rtnl_link_set_type ( struct rtnl_link *  link,
unsigned int  arptype 
)

Set link layer type.

Parameters:
link link handle
arptype Link layer type.

Definition at line 1251 of file link.c.

unsigned int rtnl_link_get_arptype ( struct rtnl_link *  link  ) 

Get link layer type.

Parameters:
link link handle
Returns:
Link layer type.

Definition at line 1261 of file link.c.

void rtnl_link_set_ifindex ( struct rtnl_link *  link,
int  ifindex 
)

Set interface index.

Parameters:
link link to change
ifindex new interface index

Definition at line 1271 of file link.c.

int rtnl_link_get_ifindex ( struct rtnl_link *  link  ) 

Get interface index.

Parameters:
link link handle
Returns:
interface index or RTNL_LINK_NOT_FOUND if not set.

Definition at line 1282 of file link.c.

References RTNL_LINK_NOT_FOUND.

void rtnl_link_set_mtu ( struct rtnl_link *  link,
unsigned int  mtu 
)

Set Maximum Transmission Unit.

Parameters:
link link to change
mtu new MTU

Definition at line 1295 of file link.c.

unsigned int rtnl_link_get_mtu ( struct rtnl_link *  link  ) 

Get Maximum Transmission Unit.

Parameters:
link link handle
Returns:
Link MTU or 0 if MTU is not set.

Definition at line 1306 of file link.c.

void rtnl_link_set_txqlen ( struct rtnl_link *  link,
unsigned int  txqlen 
)

Set Transmission Queue Length.

Parameters:
link link to change
txqlen new TX queue length
Note:
The unit of the transmission queue length depends on the link type, a common unit is packets.

Definition at line 1321 of file link.c.

unsigned int rtnl_link_get_txqlen ( struct rtnl_link *  link  ) 

Get Transmission Queue Length.

Parameters:
link link handle
Returns:
Transmission Queue Length or UINT_MAX if not set.

Definition at line 1332 of file link.c.

void rtnl_link_set_weight ( struct rtnl_link *  link,
unsigned int  weight 
)

Set Weight.

Parameters:
link link to change
weight new weight

Definition at line 1345 of file link.c.

unsigned int rtnl_link_get_weight ( struct rtnl_link *  link  ) 

Get Weight.

Parameters:
link link handle
Returns:
Link weight or UINT_MAX if not set.

Definition at line 1356 of file link.c.

void rtnl_link_set_link ( struct rtnl_link *  link,
int  ifindex 
)

Set parent interface index.

Parameters:
link link to change
ifindex new parent's interface index

Definition at line 1369 of file link.c.

int rtnl_link_get_link ( struct rtnl_link *  link  ) 

Get parent interface index.

Parameters:
link link handle
Returns:
Parent interface index or RTNL_LINK_NOT_FOUND if not set

Definition at line 1380 of file link.c.

References RTNL_LINK_NOT_FOUND.

void rtnl_link_set_master ( struct rtnl_link *  link,
int  ifindex 
)

Set master interface index.

Parameters:
link link to change
ifindex new master's interface index

Definition at line 1393 of file link.c.

int rtnl_link_get_master ( struct rtnl_link *  link  ) 

Get master interface index.

Parameters:
link link handle
Returns:
Interface index of master or RTNL_LINK_NOT_FOUND if not set

Definition at line 1404 of file link.c.

References RTNL_LINK_NOT_FOUND.

uint64_t rtnl_link_get_stat ( struct rtnl_link *  link,
int  id 
)

Get the statistic specified by the id.

Parameters:
link link handle
id statistic id
Returns:
The current counter of the specified statistic

Definition at line 1418 of file link.c.


Generated on Fri Apr 27 14:14:07 2007 for libnl by  doxygen 1.5.1