Commit 7722938d authored by Martin Mareš's avatar Martin Mareš

Added library progdocs.

parent 102e3e0e
H Library
S checksum.c md5.c
H Library functions
S ip.c ipv4.c ipv6.c
S lists.c
S bitops.c
S patmatch.c
S printf.c
S unaligned.h
H Resource management
S checksum.c bitops.c patmatch.c printf.c xmalloc.c
H Resources
S resource.c
S mempool.c
S slab.c
......
......@@ -9,12 +9,27 @@
#include "nest/bird.h"
#include "bitops.h"
/**
* u32_mkmask - create a bit mask
* @n: number of bits
*
* u32_mkmask() returns an unsigned 32-bit integer which binary
* representation consists of @n ones followed by zeroes.
*/
u32
u32_mkmask(unsigned n)
{
return n ? ~((1 << (32 - n)) - 1) : 0;
}
/**
* u32_masklen - calculate length of a bit mask
* @x: bit mask
*
* 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.
*/
int
u32_masklen(u32 x)
{
......
/*
* BIRD Library -- IP One-Complement Checksum
*
* (c) 1999 Martin Mares <mj@ucw.cz>
* (c) 1999--2000 Martin Mares <mj@ucw.cz>
*
* Can be freely distributed and used under the terms of the GNU GPL.
*/
/**
* DOC: Miscellaneous functions.
*/
#include <stdarg.h>
#include "nest/bird.h"
......@@ -83,6 +87,20 @@ ipsum_calc(void *frag, unsigned len, va_list args)
return sum;
}
/**
* ipsum_verify - verify an IP checksum
* @frag: first packet fragment
* @len: length in bytes
*
* 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.
*/
int
ipsum_verify(void *frag, unsigned len, ...)
{
......@@ -95,6 +113,17 @@ ipsum_verify(void *frag, unsigned len, ...)
return sum == 0xffff;
}
/**
* ipsum_calculate - compute an IP checksum
* @frag: first packet fragment
* @len: length in bytes
*
* This function caculates 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.
*/
u16
ipsum_calculate(void *frag, unsigned len, ...)
{
......
/*
* BIRD Library -- IP address routines common for IPv4 and IPv6
*
* (c) 1998--1999 Martin Mares <mj@ucw.cz>
* (c) 1998--2000 Martin Mares <mj@ucw.cz>
*
* Can be freely distributed and used under the terms of the GNU GPL.
*/
......@@ -9,6 +9,21 @@
#include "nest/bird.h"
#include "lib/ip.h"
/**
* DOC: 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 should be manipulated using the following functions and macros.
*/
/**
* ip_scope_text - get texual representation of address scope
* @scope: scope (%SCOPE_xxx)
*
* Returns a pointer to a textual name of the scope given.
*/
char *
ip_scope_text(unsigned scope)
{
......@@ -19,3 +34,228 @@ ip_scope_text(unsigned scope)
else
return scope_table[scope];
}
#if 0
/**
* ipa_equal - compare two IP addresses for equality
* @x: IP address
* @y: IP address
*
* ipa_equal() returns 1 if @x and @y represent the same IP address, else 0.
*/
int ipa_equal(ip_addr x, ip_addr y) { DUMMY }
/**
* ipa_nonzero - test if an IP address is defined
* @x: IP address
*
* 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.
*/
int ipa_nonzero(ip_addr x) { DUMMY }
/**
* ipa_and - compute bitwise and of two IP addresses
* @x: IP address
* @y: IP address
*
* This function returns a bitwise and of @x and @y. It's primarily
* used for network masking.
*/
ip_addr ipa_and(ip_addr x, ip_addr y) { DUMMY }
/**
* ipa_or - compute bitwise or of two IP addresses
* @x: IP address
* @y: IP address
*
* This function returns a bitwise or of @x and @y.
*/
ip_addr ipa_or(ip_addr x, ip_addr y) { DUMMY }
/**
* ipa_xor - compute bitwise xor of two IP addresses
* @x: IP address
* @y: IP address
*
* This function returns a bitwise xor of @x and @y.
*/
ip_addr ipa_xor(ip_addr x, ip_addr y) { DUMMY }
/**
* ipa_not - compute bitwise negation of two IP addresses
* @x: IP address
*
* This function returns a bitwise negation of @x.
*/
ip_addr ipa_not(ip_addr x) { DUMMY }
/**
* ipa_mkmask - create a netmask
* @x: prefix length
*
* This function returns an &ip_addr corresponding of a netmask
* of an address prefix of size @x.
*/
ip_addr ipa_mkmask(int x) { DUMMY }
/**
* ipa_mkmask - calculate netmask length
* @x: IP address
*
* This function checks whether @x represents a valid netmask and
* returns the size of the associate network prefix or -1 for invalid
* mask.
*/
int ipa_mklen(ip_addr x) { DUMMY }
/**
* ipa_hash - hash IP addresses
* @x: IP address
*
* ipa_hash() returns a 16-bit hash value of the IP address @x.
*/
int ipa_hash(ip_addr x) { DUMMY }
/**
* ipa_hton - convert IP address to network order
* @x: IP address
*
* Converts the IP address @x to the network byte order.
*
* Beware, this is a macro and it alters the argument!
*/
void ipa_hton(ip_addr x) { DUMMY }
/**
* ipa_ntoh - convert IP address to host order
* @x: IP address
*
* Converts the IP address @x from the network byte order.
*
* Beware, this is a macro and it alters the argument!
*/
void ipa_ntoh(ip_addr x) { DUMMY }
/**
* ipa_classify - classify an IP address
* @x: IP address
*
* 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 adress scope (%SCOPE_HOST to %SCOPE_UNIVERSE) or -1 (%IADDR_INVALID)
* for an invalid address.
*/
int ipa_classify(ip_addr x) { DUMMY }
/**
* ipa_opposite - return address of point-to-point neighbor
* @x: IP address of our end of the link
*
* ipa_opposite() returns an address of the opposite end of a numbered
* point-to-point link.
*
* This function is available in IPv4 version only.
*/
ip_addr ipa_opposite(ip_addr x) { DUMMY }
/**
* ipa_class_mask - guess netmask according to address class
* @x: IP address
*
* 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.
*/
ip_addr ipa_classify(ip_addr x) { DUMMY }
/**
* ipa_from_u32 - convert IPv4 address to an integer
* @x: IP address
*
* This function takes an IPv4 address and returns its numeric
* representation.
*/
u32 ipa_from_u32(ip_addr x) { DUMMY }
/**
* ipa_to_u32 - convert integer to IPv4 address
* @x: a 32-bit integer
*
* ipa_to_u32() takes a numeric representation of an IPv4 address
* and converts it to the corresponding &ip_addr.
*/
ip_addr ipa_to_u32(u32 x) { DUMMY }
/**
* ipa_compare - compare two IP addresses for order
* @x: IP address
* @y: IP address
*
* 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.
*/
int ipa_compare(ip_addr x, ip_addr y) { DUMMY }
/**
* ipa_build - build an IPv6 address from parts
* @a1: part #1
* @a2: part #2
* @a3: part #3
* @a4: part #4
*
* 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.
*/
ip_addr ipa_build(u32 a1, u32 a2, u32 a3, u32 a4) { DUMMY }
/**
* ipa_absolutize - convert link scope IPv6 address to universe scope
* @x: link scope IPv6 address
* @y: universe scope IPv6 prefix of the interface
*
* 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.
*/
ip_addr ipa_absolutize(ip_addr x, ip_addr y) { DUMMY }
/**
* ip_ntop - convert IP address to textual representation
* @a: IP address
* @buf: buffer of size at least %STD_ADDRESS_P_LENGTH
*
* This function takes an IP address and creates its textual
* representation for presenting to the user.
*/
char *ip_ntop(ip_addr a, char *buf) { DUMMY }
/**
* ip_ntox - convert IP address to hexadecimal representation
* @a: IP address
* @buf: buffer of size at least %STD_ADDRESS_P_LENGTH
*
* This function takes an IP address and creates its hexadecimal
* textual representation. Primary use: debugging dumps.
*/
char *ip_ntox(ip_addr a, char *buf) { DUMMY }
/**
* ip_pton - parse textual representation of IP address
* @a: textual representation
* @o: where to put the resulting address
*
* 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 occured, else 0.
*/
int ip_pton(char *a, ip_addr *o) { DUMMY }
#endif
......@@ -6,11 +6,36 @@
* Can be freely distributed and used under the terms of the GNU GPL.
*/
/**
* DOC: 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.
*/
#define _BIRD_LISTS_C_
#include "nest/bird.h"
#include "lib/lists.h"
/**
* add_tail - append a node to a list
* @l: linked list
* @n: list node
*
* add_tail() takes a node @n and appends it at the end of the list @l.
*/
LIST_INLINE void
add_tail(list *l, node *n)
{
......@@ -22,6 +47,13 @@ add_tail(list *l, node *n)
l->tail = n;
}
/**
* add_head - prepend a node to a list
* @l: linked list
* @n: list node
*
* add_head() takes a node @n and prepends it at the start of the list @l.
*/
LIST_INLINE void
add_head(list *l, node *n)
{
......@@ -33,6 +65,14 @@ add_head(list *l, node *n)
l->head = n;
}
/**
* insert_node - insert a node to a list
* @n: a new list node
* @after: a node of a list
*
* Inserts a node @n to a linked list after an already inserted
* node @after.
*/
LIST_INLINE void
insert_node(node *n, node *after)
{
......@@ -44,6 +84,12 @@ insert_node(node *n, node *after)
z->prev = n;
}
/**
* rem_node - remove a node from a list
* @n: node to be removed
*
* Removes a node @n from the list it's linked in.
*/
LIST_INLINE void
rem_node(node *n)
{
......@@ -54,6 +100,13 @@ rem_node(node *n)
x->prev = z;
}
/**
* init_list - create an empty list
* @l: list
*
* init_list() takes a &list structure and initializes its
* fields, so that it represents an empty list.
*/
LIST_INLINE void
init_list(list *l)
{
......@@ -62,6 +115,14 @@ init_list(list *l)
l->tail = (node *) &l->head;
}
/**
* add_tail_list - concatenate two lists
* @to: destination list
* @l: source list
*
* This function appends all elements of the list @l to
* the list @to in constant time.
*/
LIST_INLINE void
add_tail_list(list *to, list *l)
{
......
/*
* BIRD Library -- Generic Shell-Like Pattern Matching (currently only '?' and '*')
*
* (c) 1998 Martin Mares, <mj@atrey.karlin.mff.cuni.cz>
* (c) 1998--2000 Martin Mares <mj@ucw.cz>
*/
#include "nest/bird.h"
......@@ -52,3 +52,23 @@ MATCH_FUNC_NAME(byte *p, byte *s)
}
return !*s;
}
#if 0
/**
* patmatch - match shell-like patterns
* @p: pattern
* @s: string
*
* 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.
*/
int
patmatch(byte *p, byte *s)
{ DUMMY; }
#endif
......@@ -109,6 +109,23 @@ static char * number(char * str, long num, int base, int size, int precision,
return str;
}
/**
* bvsnprintf - BIRD's vsnprintf()
* @buf: destination buffer
* @size: size of the buffer
* @fmt: format string
* @args: a list of arguments to be formatted
*
* 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 and |%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.
*/
int bvsnprintf(char *buf, int size, const char *fmt, va_list args)
{
int len;
......@@ -308,11 +325,31 @@ int bvsnprintf(char *buf, int size, const char *fmt, va_list args)
return str-buf;
}
/**
* bvsprintf - BIRD's vsprintf()
* @buf: buffer
* @fmt: format string
* @args: a list of arguments to be formatted
*
* 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.
*/
int bvsprintf(char *buf, const char *fmt, va_list args)
{
return bvsnprintf(buf, 1000000000, fmt, args);
}
/**
* bsprintf - BIRD's sprintf()
* @buf: buffer
* @fmt: format string
*
* 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.
*/
int bsprintf(char * buf, const char *fmt, ...)
{
va_list args;
......@@ -324,6 +361,14 @@ int bsprintf(char * buf, const char *fmt, ...)
return i;
}
/**
* bsnprintf - BIRD's snprintf()
* @buf: buffer
* @size: buffer size
* @fmt: format string
*
* This function is equivalent to bsnprintf() with variable arguments instead of a &va_list.
*/
int bsnprintf(char * buf, int size, const char *fmt, ...)
{
va_list args;
......
/*
* BIRD Library -- malloc() With Checking
*
* (c) 1998--1999 Martin Mares <mj@ucw.cz>
* (c) 1998--2000 Martin Mares <mj@ucw.cz>
*
* Can be freely distributed and used under the terms of the GNU GPL.
*/
......@@ -13,6 +13,16 @@
#ifndef HAVE_LIBDMALLOC
/**
* xmalloc - malloc with checking
* @size: block size
*
* 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.
*
* Whereever possible, please use the memory resources instead.
*/
void *
xmalloc(unsigned size)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment