BIRD Programmer's Documentation: Library functions

Next Previous Contents

## 7. Library functions

## 7.1 IP addresses

BIRD uses its own abstraction of IP address in order to share the same code for both IPv4 and IPv6. IP addresses are represented as entities of type ip_addr which are never to be treated as numbers and instead they must be manipulated using the following functions and macros.

### Function

char * ip_scope_text (unsigned scope) -- get textual representation of address scope

### Arguments

unsigned scope

  scope (SCOPE_xxx)

### Description

Returns a pointer to a textual name of the scope given.

### Function

int ipa_equal (ip_addr x, ip_addr y) -- compare two IP addresses for equality

### Arguments

ip_addr x

  IP address

ip_addr y

  IP address

### Description

ipa_equal() returns 1 if x and y represent the same IP address, else 0.

### Function

int ipa_nonzero (ip_addr x) -- test if an IP address is defined

### Arguments

ip_addr x

  IP address

### Description

ipa_nonzero returns 1 if x is a defined IP address (not all bits are zero), else 0.

The undefined all-zero address is reachable as a `IPA_NONE` macro.

### Function

ip_addr ipa_and (ip_addr x, ip_addr y) -- compute bitwise and of two IP addresses

### Arguments

ip_addr x

  IP address

ip_addr y

  IP address

### Description

This function returns a bitwise and of x and y. It's primarily used for network masking.

### Function

ip_addr ipa_or (ip_addr x, ip_addr y) -- compute bitwise or of two IP addresses

### Arguments

ip_addr x

  IP address

ip_addr y

  IP address

### Description

This function returns a bitwise or of x and y.

### Function

ip_addr ipa_xor (ip_addr x, ip_addr y) -- compute bitwise xor of two IP addresses

### Arguments

ip_addr x

  IP address

ip_addr y

  IP address

### Description

This function returns a bitwise xor of x and y.

### Function

ip_addr ipa_not (ip_addr x) -- compute bitwise negation of two IP addresses

### Arguments

ip_addr x

  IP address

### Description

This function returns a bitwise negation of x.

### Function

ip_addr ipa_mkmask (int x) -- create a netmask

### Arguments

int x

  prefix length

### Description

This function returns an ip_addr corresponding of a netmask of an address prefix of size x.

### Function

int ipa_mklen (ip_addr x) -- calculate netmask length

### Arguments

ip_addr x

  IP address

### Description

This function checks whether x represents a valid netmask and returns the size of the associate network prefix or -1 for invalid mask.

### Function

int ipa_hash (ip_addr x) -- hash IP addresses

### Arguments

ip_addr x

  IP address

### Description

ipa_hash() returns a 16-bit hash value of the IP address x.

### Function

void ipa_hton (ip_addr x) -- convert IP address to network order

### Arguments

ip_addr x

  IP address

### Description

Converts the IP address x to the network byte order.

Beware, this is a macro and it alters the argument!

### Function

void ipa_ntoh (ip_addr x) -- convert IP address to host order

### Arguments

ip_addr x

  IP address

### Description

Converts the IP address x from the network byte order.

Beware, this is a macro and it alters the argument!

### Function

int ipa_classify (ip_addr x) -- classify an IP address

### Arguments

ip_addr x

  IP address

### Description

ipa_classify() returns an address class of x, that is a bitwise or of address type (IADDR_INVALID, IADDR_HOST, IADDR_BROADCAST, IADDR_MULTICAST) with address scope (SCOPE_HOST to SCOPE_UNIVERSE) or -1 (IADDR_INVALID) for an invalid address.

### Function

ip_addr ipa_opposite (ip_addr x, int pxlen) -- return address of point-to-point neighbor

### Arguments

ip_addr x

  IP address of our end of the link

int pxlen

  network prefix length

### Description

ipa_opposite() returns an address of the opposite end of a numbered point-to-point link.

This function is available in IPv4 version only.

### Function

ip_addr ipa_classify (ip_addr x) -- guess netmask according to address class

### Arguments

ip_addr x

  IP address

### Description

This function (available in IPv4 version only) returns a network mask according to the address class of x. Although classful addressing is nowadays obsolete, there still live routing protocols transferring no prefix lengths nor netmasks and this function could be useful to them.

### Function

u32 ipa_from_u32 (ip_addr x) -- convert IPv4 address to an integer

### Arguments

ip_addr x

  IP address

### Description

This function takes an IPv4 address and returns its numeric representation.

### Function

ip_addr ipa_to_u32 (u32 x) -- convert integer to IPv4 address

### Arguments

u32 x

  a 32-bit integer

### Description

ipa_to_u32() takes a numeric representation of an IPv4 address and converts it to the corresponding ip_addr.

### Function

int ipa_compare (ip_addr x, ip_addr y) -- compare two IP addresses for order

### Arguments

ip_addr x

  IP address

ip_addr y

  IP address

### Description

The ipa_compare() function takes two IP addresses and returns -1 if x is less than y in canonical ordering (lexicographical order of the bit strings), 1 if x is greater than y and 0 if they are the same.

### Function

ip_addr ipa_build (u32 a1, u32 a2, u32 a3, u32 a4) -- build an IPv6 address from parts

### Arguments

u32 a1

  part #1

u32 a2

  part #2

u32 a3

  part #3

u32 a4

  part #4

### Description

ipa_build() takes a1 to a4 and assembles them to a single IPv6 address. It's used for example when a protocol wants to bind its socket to a hard-wired multicast address.

### Function

ip_addr ipa_absolutize (ip_addr x, ip_addr y) -- convert link scope IPv6 address to universe scope

### Arguments

ip_addr x

  link scope IPv6 address

ip_addr y

  universe scope IPv6 prefix of the interface

### Description

This function combines a link-scope IPv6 address x with the universe scope prefix x of the network assigned to an interface to get a universe scope form of x.

### Function

char * ip_ntop (ip_addr a, char * buf) -- convert IP address to textual representation

### Arguments

ip_addr a

  IP address

char * buf

  buffer of size at least STD_ADDRESS_P_LENGTH

### Description

This function takes an IP address and creates its textual representation for presenting to the user.

### Function

char * ip_ntox (ip_addr a, char * buf) -- convert IP address to hexadecimal representation

### Arguments

ip_addr a

  IP address

char * buf

  buffer of size at least STD_ADDRESS_P_LENGTH

### Description

This function takes an IP address and creates its hexadecimal textual representation. Primary use: debugging dumps.

### Function

int ip_pton (char * a, ip_addr * o) -- parse textual representation of IP address

### Arguments

char * a

  textual representation

ip_addr * o

  where to put the resulting address

### Description

This function parses a textual IP address representation and stores the decoded address to a variable pointed to by o. Returns 0 if a parse error has occurred, else 0.

## 7.2 Linked lists

The BIRD library provides a set of functions for operating on linked lists. The lists are internally represented as standard doubly linked lists with synthetic head and tail which makes all the basic operations run in constant time and contain no extra end-of-list checks. Each list is described by a list structure, nodes can have any format as long as they start with a node structure. If you want your nodes to belong to multiple lists at once, you can embed multiple node structures in them and use the SKIP_BACK() macro to calculate a pointer to the start of the structure from a node pointer, but beware of obscurity.

There also exist safe linked lists (slist, snode and all functions being prefixed with `s_`) which support asynchronous walking very similar to that used in the fib structure.

### Function

LIST_INLINE void add_tail (list * l, node * n) -- append a node to a list

### Arguments

list * l

  linked list

node * n

  list node

### Description

add_tail() takes a node n and appends it at the end of the list l.

### Function

LIST_INLINE void add_head (list * l, node * n) -- prepend a node to a list

### Arguments

list * l

  linked list

node * n

  list node

### Description

add_head() takes a node n and prepends it at the start of the list l.

### Function

LIST_INLINE void insert_node (node * n, node * after) -- insert a node to a list

### Arguments

node * n

  a new list node

node * after

  a node of a list

### Description

Inserts a node n to a linked list after an already inserted node after.

### Function

LIST_INLINE void rem_node (node * n) -- remove a node from a list

### Arguments

node * n

  node to be removed

### Description

Removes a node n from the list it's linked in.

### Function

LIST_INLINE void init_list (list * l) -- create an empty list

### Arguments

list * l

  list

### Description

init_list() takes a list structure and initializes its fields, so that it represents an empty list.

### Function

LIST_INLINE void add_tail_list (list * to, list * l) -- concatenate two lists

### Arguments

list * to

  destination list

list * l

  source list

### Description

This function appends all elements of the list l to the list to in constant time.

## 7.3 Miscellaneous functions.

### Function

int ipsum_verify (void * frag, unsigned len, ... ...) -- verify an IP checksum

### Arguments

void * frag

  first packet fragment

unsigned len

  length in bytes

... ...

  variable arguments

### Description

This function verifies whether a given fragmented packet has correct one's complement checksum as used by the IP protocol.

It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible.

### Result

1 if the checksum is correct, 0 else.

### Function

u16 ipsum_calculate (void * frag, unsigned len, ... ...) -- compute an IP checksum

### Arguments

void * frag

  first packet fragment

unsigned len

  length in bytes

... ...

  variable arguments

### Description

This function calculates a one's complement checksum of a given fragmented packet.

It uses all the clever tricks described in RFC 1071 to speed up checksum calculation as much as possible.

### Function

u32 u32_mkmask (unsigned n) -- create a bit mask

### Arguments

unsigned n

  number of bits

### Description

u32_mkmask() returns an unsigned 32-bit integer which binary representation consists of n ones followed by zeroes.

### Function

int u32_masklen (u32 x) -- calculate length of a bit mask

### Arguments

u32 x

  bit mask

### Description

This function checks whether the given integer x represents a valid bit mask (binary representation contains first ones, then zeroes) and returns the number of ones or -1 if the mask is invalid.

### Function

u32 u32_log2 (u32 v) -- compute a binary logarithm.

### Arguments

u32 v

  number

### Description

This function computes a integral part of binary logarithm of given integer v and returns it. The computed value is also an index of the most significant non-zero bit position.

### Function

int patmatch (byte * p, byte * s) -- match shell-like patterns

### Arguments

byte * p

  pattern

byte * s

  string

### Description

patmatch() returns whether given string s matches the given shell-like pattern p. The patterns consist of characters (which are matched literally), question marks which match any single character, asterisks which match any (possibly empty) string of characters and backslashes which are used to escape any special characters and force them to be treated literally.

The matching process is not optimized with respect to time, so please avoid using this function for complex patterns.

### Function

int bvsnprintf (char * buf, int size, const char * fmt, va_list args) -- BIRD's vsnprintf()

### Arguments

char * buf

  destination buffer

int size

  size of the buffer

const char * fmt

  format string

va_list args

  a list of arguments to be formatted

### Description

This functions acts like ordinary sprintf() except that it checks available space to avoid buffer overflows and it allows some more

### format specifiers

`I` for formatting of IP addresses (any non-zero width is automatically replaced by standard IP address width which depends on whether we use IPv4 or IPv6; `%#I` gives hexadecimal format), `R` for Router / Network ID (u32 value printed as IPv4 address) and `m` resp. `M` for error messages (uses strerror() to translate errno code to message text). On the other hand, it doesn't support floating point numbers.

### Result

number of characters of the output string or -1 if the buffer space was insufficient.

### Function

int bvsprintf (char * buf, const char * fmt, va_list args) -- BIRD's vsprintf()

### Arguments

char * buf

  buffer

const char * fmt

  format string

va_list args

  a list of arguments to be formatted

### Description

This function is equivalent to bvsnprintf() with an infinite buffer size. Please use carefully only when you are absolutely sure the buffer won't overflow.

### Function

int bsprintf (char * buf, const char * fmt, ... ...) -- BIRD's sprintf()

### Arguments

char * buf

  buffer

const char * fmt

  format string

... ...

  variable arguments

### Description

This function is equivalent to bvsnprintf() with an infinite buffer size and variable arguments instead of a va_list. Please use carefully only when you are absolutely sure the buffer won't overflow.

### Function

int bsnprintf (char * buf, int size, const char * fmt, ... ...) -- BIRD's snprintf()

### Arguments

char * buf

  buffer

int size

  buffer size

const char * fmt

  format string

... ...

  variable arguments

### Description

This function is equivalent to bsnprintf() with variable arguments instead of a va_list.

### Function

void * xmalloc (unsigned size) -- malloc with checking

### Arguments

unsigned size

  block size

### Description

This function is equivalent to malloc() except that in case of failure it calls die() to quit the program instead of returning a NULL pointer.

Wherever possible, please use the memory resources instead.

### Function

void * xrealloc (void * ptr, unsigned size) -- realloc with checking

### Arguments

void * ptr

  original memory block

unsigned size

  block size

### Description

This function is equivalent to realloc() except that in case of failure it calls die() to quit the program instead of returning a NULL pointer.

Wherever possible, please use the memory resources instead.

Next Previous Contents