Annotation of embedaddon/bird/doc/prog-7.html, revision 1.1
1.1 ! misho 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
! 2: <HTML>
! 3: <HEAD>
! 4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
! 5: <TITLE>BIRD Programmer's Documentation: Library functions</TITLE>
! 6: <LINK HREF="prog-8.html" REL=next>
! 7: <LINK HREF="prog-6.html" REL=previous>
! 8: <LINK HREF="prog.html#toc7" REL=contents>
! 9: </HEAD>
! 10: <BODY>
! 11: <A HREF="prog-8.html">Next</A>
! 12: <A HREF="prog-6.html">Previous</A>
! 13: <A HREF="prog.html#toc7">Contents</A>
! 14: <HR>
! 15: <H2><A NAME="s7">7.</A> <A HREF="prog.html#toc7">Library functions</A></H2>
! 16:
! 17: <H2><A NAME="ss7.1">7.1</A> <A HREF="prog.html#toc7.1">IP addresses</A>
! 18: </H2>
! 19:
! 20: <P>
! 21: <P>BIRD uses its own abstraction of IP address in order to share the same
! 22: code for both IPv4 and IPv6. IP addresses are represented as entities
! 23: of type <I>ip_addr</I> which are never to be treated as numbers and instead
! 24: they must be manipulated using the following functions and macros.
! 25: <P>
! 26: <P><HR><H3>Function</H3>
! 27: <P><I>char *</I>
! 28: <B>ip_scope_text</B>
! 29: (<I>uint</I> <B>scope</B>) -- get textual representation of address scope
! 30: <P>
! 31: <H3>Arguments</H3>
! 32: <P>
! 33: <DL>
! 34: <DT><I>uint</I> <B>scope</B><DD><P>scope (<I>SCOPE_xxx</I>)
! 35: </DL>
! 36: <H3>Description</H3>
! 37: <P>Returns a pointer to a textual name of the scope given.
! 38:
! 39:
! 40: <HR><H3>Function</H3>
! 41: <P><I>int</I>
! 42: <B>ipa_equal</B>
! 43: (<I>ip_addr</I> <B>x</B>, <I>ip_addr</I> <B>y</B>) -- compare two IP addresses for equality
! 44: <P>
! 45: <H3>Arguments</H3>
! 46: <P>
! 47: <DL>
! 48: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 49: <DT><I>ip_addr</I> <B>y</B><DD><P>IP address
! 50: </DL>
! 51: <H3>Description</H3>
! 52: <P><B>ipa_equal()</B> returns 1 if <B>x</B> and <B>y</B> represent the same IP address, else 0.
! 53:
! 54:
! 55: <HR><H3>Function</H3>
! 56: <P><I>int</I>
! 57: <B>ipa_nonzero</B>
! 58: (<I>ip_addr</I> <B>x</B>) -- test if an IP address is defined
! 59: <P>
! 60: <H3>Arguments</H3>
! 61: <P>
! 62: <DL>
! 63: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 64: </DL>
! 65: <H3>Description</H3>
! 66: <P>ipa_nonzero returns 1 if <B>x</B> is a defined IP address (not all bits are zero),
! 67: else 0.
! 68: <P>The undefined all-zero address is reachable as a <CODE>IPA_NONE</CODE> macro.
! 69:
! 70:
! 71: <HR><H3>Function</H3>
! 72: <P><I>ip_addr</I>
! 73: <B>ipa_and</B>
! 74: (<I>ip_addr</I> <B>x</B>, <I>ip_addr</I> <B>y</B>) -- compute bitwise and of two IP addresses
! 75: <P>
! 76: <H3>Arguments</H3>
! 77: <P>
! 78: <DL>
! 79: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 80: <DT><I>ip_addr</I> <B>y</B><DD><P>IP address
! 81: </DL>
! 82: <H3>Description</H3>
! 83: <P>This function returns a bitwise and of <B>x</B> and <B>y</B>. It's primarily
! 84: used for network masking.
! 85:
! 86:
! 87: <HR><H3>Function</H3>
! 88: <P><I>ip_addr</I>
! 89: <B>ipa_or</B>
! 90: (<I>ip_addr</I> <B>x</B>, <I>ip_addr</I> <B>y</B>) -- compute bitwise or of two IP addresses
! 91: <P>
! 92: <H3>Arguments</H3>
! 93: <P>
! 94: <DL>
! 95: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 96: <DT><I>ip_addr</I> <B>y</B><DD><P>IP address
! 97: </DL>
! 98: <H3>Description</H3>
! 99: <P>This function returns a bitwise or of <B>x</B> and <B>y</B>.
! 100:
! 101:
! 102: <HR><H3>Function</H3>
! 103: <P><I>ip_addr</I>
! 104: <B>ipa_xor</B>
! 105: (<I>ip_addr</I> <B>x</B>, <I>ip_addr</I> <B>y</B>) -- compute bitwise xor of two IP addresses
! 106: <P>
! 107: <H3>Arguments</H3>
! 108: <P>
! 109: <DL>
! 110: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 111: <DT><I>ip_addr</I> <B>y</B><DD><P>IP address
! 112: </DL>
! 113: <H3>Description</H3>
! 114: <P>This function returns a bitwise xor of <B>x</B> and <B>y</B>.
! 115:
! 116:
! 117: <HR><H3>Function</H3>
! 118: <P><I>ip_addr</I>
! 119: <B>ipa_not</B>
! 120: (<I>ip_addr</I> <B>x</B>) -- compute bitwise negation of two IP addresses
! 121: <P>
! 122: <H3>Arguments</H3>
! 123: <P>
! 124: <DL>
! 125: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 126: </DL>
! 127: <H3>Description</H3>
! 128: <P>This function returns a bitwise negation of <B>x</B>.
! 129:
! 130:
! 131: <HR><H3>Function</H3>
! 132: <P><I>ip_addr</I>
! 133: <B>ipa_mkmask</B>
! 134: (<I>int</I> <B>x</B>) -- create a netmask
! 135: <P>
! 136: <H3>Arguments</H3>
! 137: <P>
! 138: <DL>
! 139: <DT><I>int</I> <B>x</B><DD><P>prefix length
! 140: </DL>
! 141: <H3>Description</H3>
! 142: <P>This function returns an <I>ip_addr</I> corresponding of a netmask
! 143: of an address prefix of size <B>x</B>.
! 144:
! 145:
! 146: <HR><H3>Function</H3>
! 147: <P><I>int</I>
! 148: <B>ipa_masklen</B>
! 149: (<I>ip_addr</I> <B>x</B>) -- calculate netmask length
! 150: <P>
! 151: <H3>Arguments</H3>
! 152: <P>
! 153: <DL>
! 154: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 155: </DL>
! 156: <H3>Description</H3>
! 157: <P>This function checks whether <B>x</B> represents a valid netmask and
! 158: returns the size of the associate network prefix or -1 for invalid
! 159: mask.
! 160:
! 161:
! 162: <HR><H3>Function</H3>
! 163: <P><I>int</I>
! 164: <B>ipa_hash</B>
! 165: (<I>ip_addr</I> <B>x</B>) -- hash IP addresses
! 166: <P>
! 167: <H3>Arguments</H3>
! 168: <P>
! 169: <DL>
! 170: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 171: </DL>
! 172: <H3>Description</H3>
! 173: <P><B>ipa_hash()</B> returns a 16-bit hash value of the IP address <B>x</B>.
! 174:
! 175:
! 176: <HR><H3>Function</H3>
! 177: <P><I>void</I>
! 178: <B>ipa_hton</B>
! 179: (<I>ip_addr</I> <B>x</B>) -- convert IP address to network order
! 180: <P>
! 181: <H3>Arguments</H3>
! 182: <P>
! 183: <DL>
! 184: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 185: </DL>
! 186: <H3>Description</H3>
! 187: <P>Converts the IP address <B>x</B> to the network byte order.
! 188: <P>Beware, this is a macro and it alters the argument!
! 189:
! 190:
! 191: <HR><H3>Function</H3>
! 192: <P><I>void</I>
! 193: <B>ipa_ntoh</B>
! 194: (<I>ip_addr</I> <B>x</B>) -- convert IP address to host order
! 195: <P>
! 196: <H3>Arguments</H3>
! 197: <P>
! 198: <DL>
! 199: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 200: </DL>
! 201: <H3>Description</H3>
! 202: <P>Converts the IP address <B>x</B> from the network byte order.
! 203: <P>Beware, this is a macro and it alters the argument!
! 204:
! 205:
! 206: <HR><H3>Function</H3>
! 207: <P><I>int</I>
! 208: <B>ipa_classify</B>
! 209: (<I>ip_addr</I> <B>x</B>) -- classify an IP address
! 210: <P>
! 211: <H3>Arguments</H3>
! 212: <P>
! 213: <DL>
! 214: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 215: </DL>
! 216: <H3>Description</H3>
! 217: <P><B>ipa_classify()</B> returns an address class of <B>x</B>, that is a bitwise or
! 218: of address type (<I>IADDR_INVALID</I>, <I>IADDR_HOST</I>, <I>IADDR_BROADCAST</I>, <I>IADDR_MULTICAST</I>)
! 219: with address scope (<I>SCOPE_HOST</I> to <I>SCOPE_UNIVERSE</I>) or -1 (<I>IADDR_INVALID</I>)
! 220: for an invalid address.
! 221:
! 222:
! 223: <HR><H3>Function</H3>
! 224: <P><I>ip4_addr</I>
! 225: <B>ip4_class_mask</B>
! 226: (<I>ip4_addr</I> <B>x</B>) -- guess netmask according to address class
! 227: <P>
! 228: <H3>Arguments</H3>
! 229: <P>
! 230: <DL>
! 231: <DT><I>ip4_addr</I> <B>x</B><DD><P>IPv4 address
! 232: </DL>
! 233: <H3>Description</H3>
! 234: <P>This function (available in IPv4 version only) returns a
! 235: network mask according to the address class of <B>x</B>. Although
! 236: classful addressing is nowadays obsolete, there still live
! 237: routing protocols transferring no prefix lengths nor netmasks
! 238: and this function could be useful to them.
! 239:
! 240:
! 241: <HR><H3>Function</H3>
! 242: <P><I>u32</I>
! 243: <B>ipa_from_u32</B>
! 244: (<I>ip_addr</I> <B>x</B>) -- convert IPv4 address to an integer
! 245: <P>
! 246: <H3>Arguments</H3>
! 247: <P>
! 248: <DL>
! 249: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 250: </DL>
! 251: <H3>Description</H3>
! 252: <P>This function takes an IPv4 address and returns its numeric
! 253: representation.
! 254:
! 255:
! 256: <HR><H3>Function</H3>
! 257: <P><I>ip_addr</I>
! 258: <B>ipa_to_u32</B>
! 259: (<I>u32</I> <B>x</B>) -- convert integer to IPv4 address
! 260: <P>
! 261: <H3>Arguments</H3>
! 262: <P>
! 263: <DL>
! 264: <DT><I>u32</I> <B>x</B><DD><P>a 32-bit integer
! 265: </DL>
! 266: <H3>Description</H3>
! 267: <P><B>ipa_to_u32()</B> takes a numeric representation of an IPv4 address
! 268: and converts it to the corresponding <I>ip_addr</I>.
! 269:
! 270:
! 271: <HR><H3>Function</H3>
! 272: <P><I>int</I>
! 273: <B>ipa_compare</B>
! 274: (<I>ip_addr</I> <B>x</B>, <I>ip_addr</I> <B>y</B>) -- compare two IP addresses for order
! 275: <P>
! 276: <H3>Arguments</H3>
! 277: <P>
! 278: <DL>
! 279: <DT><I>ip_addr</I> <B>x</B><DD><P>IP address
! 280: <DT><I>ip_addr</I> <B>y</B><DD><P>IP address
! 281: </DL>
! 282: <H3>Description</H3>
! 283: <P>The <B>ipa_compare()</B> function takes two IP addresses and returns
! 284: -1 if <B>x</B> is less than <B>y</B> in canonical ordering (lexicographical
! 285: order of the bit strings), 1 if <B>x</B> is greater than <B>y</B> and 0
! 286: if they are the same.
! 287:
! 288:
! 289: <HR><H3>Function</H3>
! 290: <P><I>ip_addr</I>
! 291: <B>ipa_build6</B>
! 292: (<I>u32</I> <B>a1</B>, <I>u32</I> <B>a2</B>, <I>u32</I> <B>a3</B>, <I>u32</I> <B>a4</B>) -- build an IPv6 address from parts
! 293: <P>
! 294: <H3>Arguments</H3>
! 295: <P>
! 296: <DL>
! 297: <DT><I>u32</I> <B>a1</B><DD><P>part #1
! 298: <DT><I>u32</I> <B>a2</B><DD><P>part #2
! 299: <DT><I>u32</I> <B>a3</B><DD><P>part #3
! 300: <DT><I>u32</I> <B>a4</B><DD><P>part #4
! 301: </DL>
! 302: <H3>Description</H3>
! 303: <P><B>ipa_build()</B> takes <B>a1</B> to <B>a4</B> and assembles them to a single IPv6
! 304: address. It's used for example when a protocol wants to bind its
! 305: socket to a hard-wired multicast address.
! 306:
! 307:
! 308: <HR><H3>Function</H3>
! 309: <P><I>char *</I>
! 310: <B>ip_ntop</B>
! 311: (<I>ip_addr</I> <B>a</B>, <I>char *</I> <B>buf</B>) -- convert IP address to textual representation
! 312: <P>
! 313: <H3>Arguments</H3>
! 314: <P>
! 315: <DL>
! 316: <DT><I>ip_addr</I> <B>a</B><DD><P>IP address
! 317: <DT><I>char *</I> <B>buf</B><DD><P>buffer of size at least <I>STD_ADDRESS_P_LENGTH</I>
! 318: </DL>
! 319: <H3>Description</H3>
! 320: <P>This function takes an IP address and creates its textual
! 321: representation for presenting to the user.
! 322:
! 323:
! 324: <HR><H3>Function</H3>
! 325: <P><I>char *</I>
! 326: <B>ip_ntox</B>
! 327: (<I>ip_addr</I> <B>a</B>, <I>char *</I> <B>buf</B>) -- convert IP address to hexadecimal representation
! 328: <P>
! 329: <H3>Arguments</H3>
! 330: <P>
! 331: <DL>
! 332: <DT><I>ip_addr</I> <B>a</B><DD><P>IP address
! 333: <DT><I>char *</I> <B>buf</B><DD><P>buffer of size at least <I>STD_ADDRESS_P_LENGTH</I>
! 334: </DL>
! 335: <H3>Description</H3>
! 336: <P>This function takes an IP address and creates its hexadecimal
! 337: textual representation. Primary use: debugging dumps.
! 338:
! 339:
! 340: <HR><H3>Function</H3>
! 341: <P><I>int</I>
! 342: <B>ip_pton</B>
! 343: (<I>char *</I> <B>a</B>, <I>ip_addr *</I> <B>o</B>) -- parse textual representation of IP address
! 344: <P>
! 345: <H3>Arguments</H3>
! 346: <P>
! 347: <DL>
! 348: <DT><I>char *</I> <B>a</B><DD><P>textual representation
! 349: <DT><I>ip_addr *</I> <B>o</B><DD><P>where to put the resulting address
! 350: </DL>
! 351: <H3>Description</H3>
! 352: <P>This function parses a textual IP address representation and
! 353: stores the decoded address to a variable pointed to by <B>o</B>.
! 354: Returns 0 if a parse error has occurred, else 0.
! 355:
! 356: <H2><A NAME="ss7.2">7.2</A> <A HREF="prog.html#toc7.2">Linked lists</A>
! 357: </H2>
! 358:
! 359: <P>
! 360: <P>The BIRD library provides a set of functions for operating on linked
! 361: lists. The lists are internally represented as standard doubly linked
! 362: lists with synthetic head and tail which makes all the basic operations
! 363: run in constant time and contain no extra end-of-list checks. Each list
! 364: is described by a <I>list</I> structure, nodes can have any format as long
! 365: as they start with a <I>node</I> structure. If you want your nodes to belong
! 366: to multiple lists at once, you can embed multiple <I>node</I> structures in them
! 367: and use the <B>SKIP_BACK()</B> macro to calculate a pointer to the start of the
! 368: structure from a <I>node</I> pointer, but beware of obscurity.
! 369: <P>There also exist safe linked lists (<I>slist</I>, <I>snode</I> and all functions
! 370: being prefixed with <CODE>s_</CODE>) which support asynchronous walking very
! 371: similar to that used in the <I>fib</I> structure.
! 372: <P>
! 373: <P><HR><H3>Function</H3>
! 374: <P><I>LIST_INLINE void</I>
! 375: <B>add_tail</B>
! 376: (<I>list *</I> <B>l</B>, <I>node *</I> <B>n</B>) -- append a node to a list
! 377: <P>
! 378: <H3>Arguments</H3>
! 379: <P>
! 380: <DL>
! 381: <DT><I>list *</I> <B>l</B><DD><P>linked list
! 382: <DT><I>node *</I> <B>n</B><DD><P>list node
! 383: </DL>
! 384: <H3>Description</H3>
! 385: <P><B>add_tail()</B> takes a node <B>n</B> and appends it at the end of the list <B>l</B>.
! 386:
! 387:
! 388: <HR><H3>Function</H3>
! 389: <P><I>LIST_INLINE void</I>
! 390: <B>add_head</B>
! 391: (<I>list *</I> <B>l</B>, <I>node *</I> <B>n</B>) -- prepend a node to a list
! 392: <P>
! 393: <H3>Arguments</H3>
! 394: <P>
! 395: <DL>
! 396: <DT><I>list *</I> <B>l</B><DD><P>linked list
! 397: <DT><I>node *</I> <B>n</B><DD><P>list node
! 398: </DL>
! 399: <H3>Description</H3>
! 400: <P><B>add_head()</B> takes a node <B>n</B> and prepends it at the start of the list <B>l</B>.
! 401:
! 402:
! 403: <HR><H3>Function</H3>
! 404: <P><I>LIST_INLINE void</I>
! 405: <B>insert_node</B>
! 406: (<I>node *</I> <B>n</B>, <I>node *</I> <B>after</B>) -- insert a node to a list
! 407: <P>
! 408: <H3>Arguments</H3>
! 409: <P>
! 410: <DL>
! 411: <DT><I>node *</I> <B>n</B><DD><P>a new list node
! 412: <DT><I>node *</I> <B>after</B><DD><P>a node of a list
! 413: </DL>
! 414: <H3>Description</H3>
! 415: <P>Inserts a node <B>n</B> to a linked list after an already inserted
! 416: node <B>after</B>.
! 417:
! 418:
! 419: <HR><H3>Function</H3>
! 420: <P><I>LIST_INLINE void</I>
! 421: <B>rem_node</B>
! 422: (<I>node *</I> <B>n</B>) -- remove a node from a list
! 423: <P>
! 424: <H3>Arguments</H3>
! 425: <P>
! 426: <DL>
! 427: <DT><I>node *</I> <B>n</B><DD><P>node to be removed
! 428: </DL>
! 429: <H3>Description</H3>
! 430: <P>Removes a node <B>n</B> from the list it's linked in. Afterwards, node <B>n</B> is cleared.
! 431:
! 432:
! 433: <HR><H3>Function</H3>
! 434: <P><I>LIST_INLINE void</I>
! 435: <B>replace_node</B>
! 436: (<I>node *</I> <B>old</B>, <I>node *</I> <B>new</B>) -- replace a node in a list with another one
! 437: <P>
! 438: <H3>Arguments</H3>
! 439: <P>
! 440: <DL>
! 441: <DT><I>node *</I> <B>old</B><DD><P>node to be removed
! 442: <DT><I>node *</I> <B>new</B><DD><P>node to be inserted
! 443: </DL>
! 444: <H3>Description</H3>
! 445: <P>Replaces node <B>old</B> in the list it's linked in with node <B>new</B>. Node
! 446: <B>old</B> may be a copy of the original node, which is not accessed
! 447: through the list. The function could be called with <B>old</B> == <B>new</B>,
! 448: which just fixes neighbors' pointers in the case that the node
! 449: was reallocated.
! 450:
! 451:
! 452: <HR><H3>Function</H3>
! 453: <P><I>LIST_INLINE void</I>
! 454: <B>init_list</B>
! 455: (<I>list *</I> <B>l</B>) -- create an empty list
! 456: <P>
! 457: <H3>Arguments</H3>
! 458: <P>
! 459: <DL>
! 460: <DT><I>list *</I> <B>l</B><DD><P>list
! 461: </DL>
! 462: <H3>Description</H3>
! 463: <P><B>init_list()</B> takes a <I>list</I> structure and initializes its
! 464: fields, so that it represents an empty list.
! 465:
! 466:
! 467: <HR><H3>Function</H3>
! 468: <P><I>LIST_INLINE void</I>
! 469: <B>add_tail_list</B>
! 470: (<I>list *</I> <B>to</B>, <I>list *</I> <B>l</B>) -- concatenate two lists
! 471: <P>
! 472: <H3>Arguments</H3>
! 473: <P>
! 474: <DL>
! 475: <DT><I>list *</I> <B>to</B><DD><P>destination list
! 476: <DT><I>list *</I> <B>l</B><DD><P>source list
! 477: </DL>
! 478: <H3>Description</H3>
! 479: <P>This function appends all elements of the list <B>l</B> to
! 480: the list <B>to</B> in constant time.
! 481:
! 482: <H2><A NAME="ss7.3">7.3</A> <A HREF="prog.html#toc7.3">Miscellaneous functions.</A>
! 483: </H2>
! 484:
! 485: <P>
! 486: <P>
! 487: <P><HR><H3>Function</H3>
! 488: <P><I>int</I>
! 489: <B>ipsum_verify</B>
! 490: (<I>void *</I> <B>frag</B>, <I>uint</I> <B>len</B>, <I>...</I> <B>...</B>) -- verify an IP checksum
! 491: <P>
! 492: <H3>Arguments</H3>
! 493: <P>
! 494: <DL>
! 495: <DT><I>void *</I> <B>frag</B><DD><P>first packet fragment
! 496: <DT><I>uint</I> <B>len</B><DD><P>length in bytes
! 497: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 498: </DL>
! 499: <H3>Description</H3>
! 500: <P>This function verifies whether a given fragmented packet
! 501: has correct one's complement checksum as used by the IP
! 502: protocol.
! 503: <P>It uses all the clever tricks described in RFC 1071 to speed
! 504: up checksum calculation as much as possible.
! 505: <H3>Result</H3>
! 506: <P>1 if the checksum is correct, 0 else.
! 507:
! 508:
! 509: <HR><H3>Function</H3>
! 510: <P><I>u16</I>
! 511: <B>ipsum_calculate</B>
! 512: (<I>void *</I> <B>frag</B>, <I>uint</I> <B>len</B>, <I>...</I> <B>...</B>) -- compute an IP checksum
! 513: <P>
! 514: <H3>Arguments</H3>
! 515: <P>
! 516: <DL>
! 517: <DT><I>void *</I> <B>frag</B><DD><P>first packet fragment
! 518: <DT><I>uint</I> <B>len</B><DD><P>length in bytes
! 519: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 520: </DL>
! 521: <H3>Description</H3>
! 522: <P>This function calculates a one's complement checksum of a given fragmented
! 523: packet.
! 524: <P>It uses all the clever tricks described in RFC 1071 to speed
! 525: up checksum calculation as much as possible.
! 526:
! 527:
! 528: <HR><H3>Function</H3>
! 529: <P><I>u32</I>
! 530: <B>u32_mkmask</B>
! 531: (<I>uint</I> <B>n</B>) -- create a bit mask
! 532: <P>
! 533: <H3>Arguments</H3>
! 534: <P>
! 535: <DL>
! 536: <DT><I>uint</I> <B>n</B><DD><P>number of bits
! 537: </DL>
! 538: <H3>Description</H3>
! 539: <P><B>u32_mkmask()</B> returns an unsigned 32-bit integer which binary
! 540: representation consists of <B>n</B> ones followed by zeroes.
! 541:
! 542:
! 543: <HR><H3>Function</H3>
! 544: <P><I>int</I>
! 545: <B>u32_masklen</B>
! 546: (<I>u32</I> <B>x</B>) -- calculate length of a bit mask
! 547: <P>
! 548: <H3>Arguments</H3>
! 549: <P>
! 550: <DL>
! 551: <DT><I>u32</I> <B>x</B><DD><P>bit mask
! 552: </DL>
! 553: <H3>Description</H3>
! 554: <P>This function checks whether the given integer <B>x</B> represents
! 555: a valid bit mask (binary representation contains first ones, then
! 556: zeroes) and returns the number of ones or -1 if the mask is invalid.
! 557:
! 558:
! 559: <HR><H3>Function</H3>
! 560: <P><I>u32</I>
! 561: <B>u32_log2</B>
! 562: (<I>u32</I> <B>v</B>) -- compute a binary logarithm.
! 563: <P>
! 564: <H3>Arguments</H3>
! 565: <P>
! 566: <DL>
! 567: <DT><I>u32</I> <B>v</B><DD><P>number
! 568: </DL>
! 569: <H3>Description</H3>
! 570: <P>This function computes a integral part of binary logarithm of given
! 571: integer <B>v</B> and returns it. The computed value is also an index of the
! 572: most significant non-zero bit position.
! 573:
! 574:
! 575: <HR><H3>Function</H3>
! 576: <P><I>int</I>
! 577: <B>patmatch</B>
! 578: (<I>byte *</I> <B>p</B>, <I>byte *</I> <B>s</B>) -- match shell-like patterns
! 579: <P>
! 580: <H3>Arguments</H3>
! 581: <P>
! 582: <DL>
! 583: <DT><I>byte *</I> <B>p</B><DD><P>pattern
! 584: <DT><I>byte *</I> <B>s</B><DD><P>string
! 585: </DL>
! 586: <H3>Description</H3>
! 587: <P><B>patmatch()</B> returns whether given string <B>s</B> matches the given shell-like
! 588: pattern <B>p</B>. The patterns consist of characters (which are matched literally),
! 589: question marks which match any single character, asterisks which match any
! 590: (possibly empty) string of characters and backslashes which are used to
! 591: escape any special characters and force them to be treated literally.
! 592: <P>The matching process is not optimized with respect to time, so please
! 593: avoid using this function for complex patterns.
! 594:
! 595:
! 596: <HR><H3>Function</H3>
! 597: <P><I>int</I>
! 598: <B>bvsnprintf</B>
! 599: (<I>char *</I> <B>buf</B>, <I>int</I> <B>size</B>, <I>const char *</I> <B>fmt</B>, <I>va_list</I> <B>args</B>) -- BIRD's <B>vsnprintf()</B>
! 600: <P>
! 601: <H3>Arguments</H3>
! 602: <P>
! 603: <DL>
! 604: <DT><I>char *</I> <B>buf</B><DD><P>destination buffer
! 605: <DT><I>int</I> <B>size</B><DD><P>size of the buffer
! 606: <DT><I>const char *</I> <B>fmt</B><DD><P>format string
! 607: <DT><I>va_list</I> <B>args</B><DD><P>a list of arguments to be formatted
! 608: </DL>
! 609: <H3>Description</H3>
! 610: <P>This functions acts like ordinary <B>sprintf()</B> except that it checks
! 611: available space to avoid buffer overflows and it allows some more
! 612: <H3>format specifiers</H3>
! 613: <P><CODE><I>I</I></CODE> for formatting of IP addresses (any non-zero
! 614: width is automatically replaced by standard IP address width which
! 615: depends on whether we use IPv4 or IPv6; <CODE>%#I</CODE> gives hexadecimal format),
! 616: <CODE><I>R</I></CODE> for Router / Network ID (u32 value printed as IPv4 address)
! 617: <CODE><I>lR</I></CODE> for 64bit Router / Network ID (u64 value printed as eight :-separated octets)
! 618: and <CODE><I>m</I></CODE> resp. <CODE><I>M</I></CODE> for error messages (uses <B>strerror()</B> to translate <B>errno</B> code to
! 619: message text). On the other hand, it doesn't support floating
! 620: point numbers.
! 621: <H3>Result</H3>
! 622: <P>number of characters of the output string or -1 if
! 623: the buffer space was insufficient.
! 624:
! 625:
! 626: <HR><H3>Function</H3>
! 627: <P><I>int</I>
! 628: <B>bvsprintf</B>
! 629: (<I>char *</I> <B>buf</B>, <I>const char *</I> <B>fmt</B>, <I>va_list</I> <B>args</B>) -- BIRD's <B>vsprintf()</B>
! 630: <P>
! 631: <H3>Arguments</H3>
! 632: <P>
! 633: <DL>
! 634: <DT><I>char *</I> <B>buf</B><DD><P>buffer
! 635: <DT><I>const char *</I> <B>fmt</B><DD><P>format string
! 636: <DT><I>va_list</I> <B>args</B><DD><P>a list of arguments to be formatted
! 637: </DL>
! 638: <H3>Description</H3>
! 639: <P>This function is equivalent to <B>bvsnprintf()</B> with an infinite
! 640: buffer size. Please use carefully only when you are absolutely
! 641: sure the buffer won't overflow.
! 642:
! 643:
! 644: <HR><H3>Function</H3>
! 645: <P><I>int</I>
! 646: <B>bsprintf</B>
! 647: (<I>char *</I> <B>buf</B>, <I>const char *</I> <B>fmt</B>, <I>...</I> <B>...</B>) -- BIRD's <B>sprintf()</B>
! 648: <P>
! 649: <H3>Arguments</H3>
! 650: <P>
! 651: <DL>
! 652: <DT><I>char *</I> <B>buf</B><DD><P>buffer
! 653: <DT><I>const char *</I> <B>fmt</B><DD><P>format string
! 654: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 655: </DL>
! 656: <H3>Description</H3>
! 657: <P>This function is equivalent to <B>bvsnprintf()</B> with an infinite
! 658: buffer size and variable arguments instead of a <I>va_list</I>.
! 659: Please use carefully only when you are absolutely
! 660: sure the buffer won't overflow.
! 661:
! 662:
! 663: <HR><H3>Function</H3>
! 664: <P><I>int</I>
! 665: <B>bsnprintf</B>
! 666: (<I>char *</I> <B>buf</B>, <I>int</I> <B>size</B>, <I>const char *</I> <B>fmt</B>, <I>...</I> <B>...</B>) -- BIRD's <B>snprintf()</B>
! 667: <P>
! 668: <H3>Arguments</H3>
! 669: <P>
! 670: <DL>
! 671: <DT><I>char *</I> <B>buf</B><DD><P>buffer
! 672: <DT><I>int</I> <B>size</B><DD><P>buffer size
! 673: <DT><I>const char *</I> <B>fmt</B><DD><P>format string
! 674: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 675: </DL>
! 676: <H3>Description</H3>
! 677: <P>This function is equivalent to <B>bsnprintf()</B> with variable arguments instead of a <I>va_list</I>.
! 678:
! 679:
! 680: <HR><H3>Function</H3>
! 681: <P><I>void *</I>
! 682: <B>xmalloc</B>
! 683: (<I>uint</I> <B>size</B>) -- malloc with checking
! 684: <P>
! 685: <H3>Arguments</H3>
! 686: <P>
! 687: <DL>
! 688: <DT><I>uint</I> <B>size</B><DD><P>block size
! 689: </DL>
! 690: <H3>Description</H3>
! 691: <P>This function is equivalent to <B>malloc()</B> except that in case of
! 692: failure it calls <B>die()</B> to quit the program instead of returning
! 693: a <I>NULL</I> pointer.
! 694: <P>Wherever possible, please use the memory resources instead.
! 695:
! 696:
! 697: <HR><H3>Function</H3>
! 698: <P><I>void *</I>
! 699: <B>xrealloc</B>
! 700: (<I>void *</I> <B>ptr</B>, <I>uint</I> <B>size</B>) -- realloc with checking
! 701: <P>
! 702: <H3>Arguments</H3>
! 703: <P>
! 704: <DL>
! 705: <DT><I>void *</I> <B>ptr</B><DD><P>original memory block
! 706: <DT><I>uint</I> <B>size</B><DD><P>block size
! 707: </DL>
! 708: <H3>Description</H3>
! 709: <P>This function is equivalent to <B>realloc()</B> except that in case of
! 710: failure it calls <B>die()</B> to quit the program instead of returning
! 711: a <I>NULL</I> pointer.
! 712: <P>Wherever possible, please use the memory resources instead.
! 713:
! 714: <H2><A NAME="ss7.4">7.4</A> <A HREF="prog.html#toc7.4">Message authentication codes</A>
! 715: </H2>
! 716:
! 717: <P>
! 718: <P>MAC algorithms are simple cryptographic tools for message authentication.
! 719: They use shared a secret key a and message text to generate authentication
! 720: code, which is then passed with the message to the other side, where the code
! 721: is verified. There are multiple families of MAC algorithms based on different
! 722: cryptographic primitives, BIRD implements two MAC families which use hash
! 723: functions.
! 724: <P>The first family is simply a cryptographic hash camouflaged as MAC algorithm.
! 725: Originally supposed to be (m|k)-hash (message is concatenated with key, and
! 726: that is hashed), but later it turned out that a raw hash is more practical.
! 727: This is used for cryptographic authentication in OSPFv2, RIP and BFD.
! 728: <P>The second family is the standard HMAC (RFC 2104), using inner and outer hash
! 729: to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP
! 730: authentication (RFC 5709, RFC 4822).
! 731: <P>
! 732: <P><HR><H3>Function</H3>
! 733: <P><I>void</I>
! 734: <B>mac_init</B>
! 735: (<I>struct mac_context *</I> <B>ctx</B>, <I>uint</I> <B>id</B>, <I>const byte *</I> <B>key</B>, <I>uint</I> <B>keylen</B>) -- initialize MAC algorithm
! 736: <P>
! 737: <H3>Arguments</H3>
! 738: <P>
! 739: <DL>
! 740: <DT><I>struct mac_context *</I> <B>ctx</B><DD><P>context to initialize
! 741: <DT><I>uint</I> <B>id</B><DD><P>MAC algorithm ID
! 742: <DT><I>const byte *</I> <B>key</B><DD><P>MAC key
! 743: <DT><I>uint</I> <B>keylen</B><DD><P>MAC key length
! 744: </DL>
! 745: <H3>Description</H3>
! 746: <P>Initialize MAC context <B>ctx</B> for algorithm <B>id</B> (e.g., <I>ALG_HMAC_SHA1</I>), with
! 747: key <B>key</B> of length <B>keylen</B>. After that, message data could be added using
! 748: <B>mac_update()</B> function.
! 749:
! 750:
! 751: <HR><H3>Function</H3>
! 752: <P><I>void</I>
! 753: <B>mac_update</B>
! 754: (<I>struct mac_context *</I> <B>ctx</B>, <I>const byte *</I> <B>data</B>, <I>uint</I> <B>datalen</B>) -- add more data to MAC algorithm
! 755: <P>
! 756: <H3>Arguments</H3>
! 757: <P>
! 758: <DL>
! 759: <DT><I>struct mac_context *</I> <B>ctx</B><DD><P>MAC context
! 760: <DT><I>const byte *</I> <B>data</B><DD><P>data to add
! 761: <DT><I>uint</I> <B>datalen</B><DD><P>length of data
! 762: </DL>
! 763: <H3>Description</H3>
! 764: <P>Push another <B>datalen</B> bytes of data pointed to by <B>data</B> into the MAC
! 765: algorithm currently in <B>ctx</B>. Can be called multiple times for the same MAC
! 766: context. It has the same effect as concatenating all the data together and
! 767: passing them at once.
! 768:
! 769:
! 770: <HR><H3>Function</H3>
! 771: <P><I>byte *</I>
! 772: <B>mac_final</B>
! 773: (<I>struct mac_context *</I> <B>ctx</B>) -- finalize MAC algorithm
! 774: <P>
! 775: <H3>Arguments</H3>
! 776: <P>
! 777: <DL>
! 778: <DT><I>struct mac_context *</I> <B>ctx</B><DD><P>MAC context
! 779: </DL>
! 780: <H3>Description</H3>
! 781: <P>Finish MAC computation and return a pointer to the result. No more
! 782: <B>mac_update</B>() calls could be done, but the context may be reinitialized
! 783: later.
! 784: <P>Note that the returned pointer points into data in the <B>ctx</B> context. If it
! 785: ceases to exist, the pointer becomes invalid.
! 786:
! 787:
! 788: <HR><H3>Function</H3>
! 789: <P><I>void</I>
! 790: <B>mac_cleanup</B>
! 791: (<I>struct mac_context *</I> <B>ctx</B>) -- cleanup MAC context
! 792: <P>
! 793: <H3>Arguments</H3>
! 794: <P>
! 795: <DL>
! 796: <DT><I>struct mac_context *</I> <B>ctx</B><DD><P>MAC context
! 797: </DL>
! 798: <H3>Description</H3>
! 799: <P>Cleanup MAC context after computation (by filling with zeros). Not strictly
! 800: necessary, just to erase sensitive data from stack. This also invalidates the
! 801: pointer returned by <B>mac_final</B>().
! 802:
! 803:
! 804: <HR><H3>Function</H3>
! 805: <P><I>void</I>
! 806: <B>mac_fill</B>
! 807: (<I>uint</I> <B>id</B>, <I>const byte *</I> <B>key</B>, <I>uint</I> <B>keylen</B>, <I>const byte *</I> <B>data</B>, <I>uint</I> <B>datalen</B>, <I>byte *</I> <B>mac</B>) -- compute and fill MAC
! 808: <P>
! 809: <H3>Arguments</H3>
! 810: <P>
! 811: <DL>
! 812: <DT><I>uint</I> <B>id</B><DD><P>MAC algorithm ID
! 813: <DT><I>const byte *</I> <B>key</B><DD><P>secret key
! 814: <DT><I>uint</I> <B>keylen</B><DD><P>key length
! 815: <DT><I>const byte *</I> <B>data</B><DD><P>message data
! 816: <DT><I>uint</I> <B>datalen</B><DD><P>message length
! 817: <DT><I>byte *</I> <B>mac</B><DD><P>place to fill MAC
! 818: </DL>
! 819: <H3>Description</H3>
! 820: <P>Compute MAC for specified key <B>key</B> and message <B>data</B> using algorithm <B>id</B> and
! 821: copy it to buffer <B>mac</B>. <B>mac_fill()</B> is a shortcut function doing all usual
! 822: steps for transmitted messages.
! 823:
! 824:
! 825: <HR><H3>Function</H3>
! 826: <P><I>int</I>
! 827: <B>mac_verify</B>
! 828: (<I>uint</I> <B>id</B>, <I>const byte *</I> <B>key</B>, <I>uint</I> <B>keylen</B>, <I>const byte *</I> <B>data</B>, <I>uint</I> <B>datalen</B>, <I>const byte *</I> <B>mac</B>) -- compute and verify MAC
! 829: <P>
! 830: <H3>Arguments</H3>
! 831: <P>
! 832: <DL>
! 833: <DT><I>uint</I> <B>id</B><DD><P>MAC algorithm ID
! 834: <DT><I>const byte *</I> <B>key</B><DD><P>secret key
! 835: <DT><I>uint</I> <B>keylen</B><DD><P>key length
! 836: <DT><I>const byte *</I> <B>data</B><DD><P>message data
! 837: <DT><I>uint</I> <B>datalen</B><DD><P>message length
! 838: <DT><I>const byte *</I> <B>mac</B><DD><P>received MAC
! 839: </DL>
! 840: <H3>Description</H3>
! 841: <P>Compute MAC for specified key <B>key</B> and message <B>data</B> using algorithm <B>id</B> and
! 842: compare it with received <B>mac</B>, return whether they are the same. <B>mac_verify()</B>
! 843: is a shortcut function doing all usual steps for received messages.
! 844:
! 845: <P>
! 846: <HR>
! 847: <A HREF="prog-8.html">Next</A>
! 848: <A HREF="prog-6.html">Previous</A>
! 849: <A HREF="prog.html#toc7">Contents</A>
! 850: </BODY>
! 851: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-7.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc