diff options
| -rw-r--r-- | lib/Doc | 10 | ||||
| -rw-r--r-- | lib/bitops.c | 15 | ||||
| -rw-r--r-- | lib/checksum.c | 31 | ||||
| -rw-r--r-- | lib/ip.c | 242 | ||||
| -rw-r--r-- | lib/lists.c | 61 | ||||
| -rw-r--r-- | lib/patmatch.c | 22 | ||||
| -rw-r--r-- | lib/printf.c | 45 | ||||
| -rw-r--r-- | lib/xmalloc.c | 12 |
8 files changed, 427 insertions, 11 deletions
@@ -1,12 +1,8 @@ -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 diff --git a/lib/bitops.c b/lib/bitops.c index 10bca047..6ca05050 100644 --- a/lib/bitops.c +++ b/lib/bitops.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) { diff --git a/lib/checksum.c b/lib/checksum.c index 94cf71e8..2ffc1770 100644 --- a/lib/checksum.c +++ b/lib/checksum.c @@ -1,11 +1,15 @@ /* * 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, ...) { @@ -1,7 +1,7 @@ /* * 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 diff --git a/lib/lists.c b/lib/lists.c index c14eb4c7..6d97ff50 100644 --- a/lib/lists.c +++ b/lib/lists.c @@ -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) { diff --git a/lib/patmatch.c b/lib/patmatch.c index 15d5007a..923e8f86 100644 --- a/lib/patmatch.c +++ b/lib/patmatch.c @@ -1,7 +1,7 @@ /* * 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 diff --git a/lib/printf.c b/lib/printf.c index a668aeaf..4bcffe56 100644 --- a/lib/printf.c +++ b/lib/printf.c @@ -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; diff --git a/lib/xmalloc.c b/lib/xmalloc.c index 2bec260c..369d4201 100644 --- a/lib/xmalloc.c +++ b/lib/xmalloc.c @@ -1,7 +1,7 @@ /* * 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) { |