embedaddon/bird/doc/prog-8.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-8.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (6 years, 10 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_8p3, v1_6_3p0, v1_6_3, HEAD

bird 1.6.3

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: Resources</TITLE> 6: <LINK HREF="prog-7.html" REL=previous> 7: <LINK HREF="prog.html#toc8" REL=contents> 8: </HEAD> 9: <BODY> 10: Next 11: <A HREF="prog-7.html">Previous</A> 12: <A HREF="prog.html#toc8">Contents</A> 13: <HR> 14: <H2><A NAME="s8">8.</A> <A HREF="prog.html#toc8">Resources</A></H2> 15: 16: <H2><A NAME="ss8.1">8.1</A> <A HREF="prog.html#toc8.1">Introduction</A> 17: </H2> 18: 19: <P>Most large software projects implemented in classical procedural 20: programming languages usually end up with lots of code taking care 21: of resource allocation and deallocation. Bugs in such code are often 22: very difficult to find, because they cause only `resource leakage', 23: that is keeping a lot of memory and other resources which nobody 24: references to. 25: <P> 26: <P>We've tried to solve this problem by employing a resource tracking 27: system which keeps track of all the resources allocated by all the 28: modules of BIRD, deallocates everything automatically when a module 29: shuts down and it is able to print out the list of resources and 30: the corresponding modules they are allocated by. 31: <P> 32: <P>Each allocated resource (from now we'll speak about allocated 33: resources only) is represented by a structure starting with a standard 34: header (struct <I>resource</I>) consisting of a list node (resources are 35: often linked to various lists) and a pointer to <I>resclass</I> -- a resource 36: class structure pointing to functions implementing generic resource 37: operations (such as freeing of the resource) for the particular resource 38: type. 39: <P> 40: <P>There exist the following types of resources: 41: <P> 42: <UL> 43: <LI><I>Resource pools</I> (<I>pool</I>)</LI> 44: <LI><I>Memory blocks</I></LI> 45: <LI><I>Linear memory pools</I> (<I>linpool</I>)</LI> 46: <LI><I>Slabs</I> (<I>slab</I>)</LI> 47: <LI><I>Events</I> (<I>event</I>) </LI> 48: <LI><I>Timers</I> (<I>timer</I>) </LI> 49: <LI><I>Sockets</I> (<I>socket</I>) </LI> 50: </UL> 51: <H2><A NAME="ss8.2">8.2</A> <A HREF="prog.html#toc8.2">Resource pools</A> 52: </H2> 53: 54: <P> 55: <P>Resource pools (<I>pool</I>) are just containers holding a list of 56: other resources. Freeing a pool causes all the listed resources 57: to be freed as well. Each existing <I>resource</I> is linked to some pool 58: except for a root pool which isn't linked anywhere, so all the 59: resources form a tree structure with internal nodes corresponding 60: to pools and leaves being the other resources. 61: <P>Example: Almost all modules of BIRD have their private pool which 62: is freed upon shutdown of the module. 63: <P> 64: <P><HR><H3>Function</H3> 65: <P><I>pool *</I> 66: <B>rp_new</B> 67: (<I>pool *</I> <B>p</B>, <I>char *</I> <B>name</B>) -- create a resource pool 68: <P> 69: <H3>Arguments</H3> 70: <P> 71: <DL> 72: <DT><I>pool *</I> <B>p</B><DD><P>parent pool 73: <DT><I>char *</I> <B>name</B><DD><P>pool name (to be included in debugging dumps) 74: </DL> 75: <H3>Description</H3> 76: <P><B>rp_new()</B> creates a new resource pool inside the specified 77: parent pool. 78: 79: 80: <HR><H3>Function</H3> 81: <P><I>void</I> 82: <B>rmove</B> 83: (<I>void *</I> <B>res</B>, <I>pool *</I> <B>p</B>) -- move a resource 84: <P> 85: <H3>Arguments</H3> 86: <P> 87: <DL> 88: <DT><I>void *</I> <B>res</B><DD><P>resource 89: <DT><I>pool *</I> <B>p</B><DD><P>pool to move the resource to 90: </DL> 91: <H3>Description</H3> 92: <P><B>rmove()</B> moves a resource from one pool to another. 93: 94: 95: <HR><H3>Function</H3> 96: <P><I>void</I> 97: <B>rfree</B> 98: (<I>void *</I> <B>res</B>) -- free a resource 99: <P> 100: <H3>Arguments</H3> 101: <P> 102: <DL> 103: <DT><I>void *</I> <B>res</B><DD><P>resource 104: </DL> 105: <H3>Description</H3> 106: <P><B>rfree()</B> frees the given resource and all information associated 107: with it. In case it's a resource pool, it also frees all the objects 108: living inside the pool. 109: <P>It works by calling a class-specific freeing function. 110: 111: 112: <HR><H3>Function</H3> 113: <P><I>void</I> 114: <B>rdump</B> 115: (<I>void *</I> <B>res</B>) -- dump a resource 116: <P> 117: <H3>Arguments</H3> 118: <P> 119: <DL> 120: <DT><I>void *</I> <B>res</B><DD><P>resource 121: </DL> 122: <H3>Description</H3> 123: <P>This function prints out all available information about the given 124: resource to the debugging output. 125: <P>It works by calling a class-specific dump function. 126: 127: 128: <HR><H3>Function</H3> 129: <P><I>void *</I> 130: <B>ralloc</B> 131: (<I>pool *</I> <B>p</B>, <I>struct resclass *</I> <B>c</B>) -- create a resource 132: <P> 133: <H3>Arguments</H3> 134: <P> 135: <DL> 136: <DT><I>pool *</I> <B>p</B><DD><P>pool to create the resource in 137: <DT><I>struct resclass *</I> <B>c</B><DD><P>class of the new resource 138: </DL> 139: <H3>Description</H3> 140: <P>This function is called by the resource classes to create a new 141: resource of the specified class and link it to the given pool. 142: Allocated memory is zeroed. Size of the resource structure is taken 143: from the <B>size</B> field of the <I>resclass</I>. 144: 145: 146: <HR><H3>Function</H3> 147: <P><I>void</I> 148: <B>rlookup</B> 149: (<I>unsigned long</I> <B>a</B>) -- look up a memory location 150: <P> 151: <H3>Arguments</H3> 152: <P> 153: <DL> 154: <DT><I>unsigned long</I> <B>a</B><DD><P>memory address 155: </DL> 156: <H3>Description</H3> 157: <P>This function examines all existing resources to see whether 158: the address <B>a</B> is inside any resource. It's used for debugging 159: purposes only. 160: <P>It works by calling a class-specific lookup function for each 161: resource. 162: 163: 164: <HR><H3>Function</H3> 165: <P><I>void</I> 166: <B>resource_init</B> 167: (<B>void</B>) -- initialize the resource manager 168: <P> 169: <H3>Description</H3> 170: <P> 171: <P>This function is called during BIRD startup. It initializes 172: all data structures of the resource manager and creates the 173: root pool. 174: 175: <H2><A NAME="ss8.3">8.3</A> <A HREF="prog.html#toc8.3">Memory blocks</A> 176: </H2> 177: 178: <P> 179: <P>Memory blocks are pieces of contiguous allocated memory. 180: They are a bit non-standard since they are represented not by a pointer 181: to <I>resource</I>, but by a void pointer to the start of data of the 182: memory block. All memory block functions know how to locate the header 183: given the data pointer. 184: <P>Example: All "unique" data structures such as hash tables are allocated 185: as memory blocks. 186: <P> 187: <P><HR><H3>Function</H3> 188: <P><I>void *</I> 189: <B>mb_alloc</B> 190: (<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) -- allocate a memory block 191: <P> 192: <H3>Arguments</H3> 193: <P> 194: <DL> 195: <DT><I>pool *</I> <B>p</B><DD><P>pool 196: <DT><I>unsigned</I> <B>size</B><DD><P>size of the block 197: </DL> 198: <H3>Description</H3> 199: <P><B>mb_alloc()</B> allocates memory of a given size and creates 200: a memory block resource representing this memory chunk 201: in the pool <B>p</B>. 202: <P>Please note that <B>mb_alloc()</B> returns a pointer to the memory 203: chunk, not to the resource, hence you have to free it using 204: <B>mb_free()</B>, not <B>rfree()</B>. 205: 206: 207: <HR><H3>Function</H3> 208: <P><I>void *</I> 209: <B>mb_allocz</B> 210: (<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) -- allocate and clear a memory block 211: <P> 212: <H3>Arguments</H3> 213: <P> 214: <DL> 215: <DT><I>pool *</I> <B>p</B><DD><P>pool 216: <DT><I>unsigned</I> <B>size</B><DD><P>size of the block 217: </DL> 218: <H3>Description</H3> 219: <P><B>mb_allocz()</B> allocates memory of a given size, initializes it to 220: zeroes and creates a memory block resource representing this memory 221: chunk in the pool <B>p</B>. 222: <P>Please note that <B>mb_allocz()</B> returns a pointer to the memory 223: chunk, not to the resource, hence you have to free it using 224: <B>mb_free()</B>, not <B>rfree()</B>. 225: 226: 227: <HR><H3>Function</H3> 228: <P><I>void *</I> 229: <B>mb_realloc</B> 230: (<I>void *</I> <B>m</B>, <I>unsigned</I> <B>size</B>) -- reallocate a memory block 231: <P> 232: <H3>Arguments</H3> 233: <P> 234: <DL> 235: <DT><I>void *</I> <B>m</B><DD><P>memory block 236: <DT><I>unsigned</I> <B>size</B><DD><P>new size of the block 237: </DL> 238: <H3>Description</H3> 239: <P><B>mb_realloc()</B> changes the size of the memory block <B>m</B> to a given size. 240: The contents will be unchanged to the minimum of the old and new sizes; 241: newly allocated memory will be uninitialized. Contrary to <B>realloc()</B> 242: behavior, <B>m</B> must be non-NULL, because the resource pool is inherited 243: from it. 244: <P>Like <B>mb_alloc()</B>, <B>mb_realloc()</B> also returns a pointer to the memory 245: chunk, not to the resource, hence you have to free it using 246: <B>mb_free()</B>, not <B>rfree()</B>. 247: 248: 249: <HR><H3>Function</H3> 250: <P><I>void</I> 251: <B>mb_free</B> 252: (<I>void *</I> <B>m</B>) -- free a memory block 253: <P> 254: <H3>Arguments</H3> 255: <P> 256: <DL> 257: <DT><I>void *</I> <B>m</B><DD><P>memory block 258: </DL> 259: <H3>Description</H3> 260: <P><B>mb_free()</B> frees all memory associated with the block <B>m</B>. 261: 262: <H2><A NAME="ss8.4">8.4</A> <A HREF="prog.html#toc8.4">Linear memory pools</A> 263: </H2> 264: 265: <P> 266: <P>Linear memory pools are collections of memory blocks which 267: support very fast allocation of new blocks, but are able to free only 268: the whole collection at once. 269: <P>Example: Each configuration is described by a complex system of structures, 270: linked lists and function trees which are all allocated from a single linear 271: pool, thus they can be freed at once when the configuration is no longer used. 272: <P> 273: <P><HR><H3>Function</H3> 274: <P><I>linpool *</I> 275: <B>lp_new</B> 276: (<I>pool *</I> <B>p</B>, <I>uint</I> <B>blk</B>) -- create a new linear memory pool 277: <P> 278: <H3>Arguments</H3> 279: <P> 280: <DL> 281: <DT><I>pool *</I> <B>p</B><DD><P>pool 282: <DT><I>uint</I> <B>blk</B><DD><P>block size 283: </DL> 284: <H3>Description</H3> 285: <P><B>lp_new()</B> creates a new linear memory pool resource inside the pool <B>p</B>. 286: The linear pool consists of a list of memory chunks of size at least 287: <B>blk</B>. 288: 289: 290: <HR><H3>Function</H3> 291: <P><I>void *</I> 292: <B>lp_alloc</B> 293: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate memory from a <I>linpool</I> 294: <P> 295: <H3>Arguments</H3> 296: <P> 297: <DL> 298: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool 299: <DT><I>uint</I> <B>size</B><DD><P>amount of memory 300: </DL> 301: <H3>Description</H3> 302: <P><B>lp_alloc()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B> 303: and it returns a pointer to the allocated memory. 304: <P>It works by trying to find free space in the last memory chunk 305: associated with the <I>linpool</I> and creating a new chunk of the standard 306: size (as specified during <B>lp_new()</B>) if the free space is too small 307: to satisfy the allocation. If <B>size</B> is too large to fit in a standard 308: size chunk, an "overflow" chunk is created for it instead. 309: 310: 311: <HR><H3>Function</H3> 312: <P><I>void *</I> 313: <B>lp_allocu</B> 314: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate unaligned memory from a <I>linpool</I> 315: <P> 316: <H3>Arguments</H3> 317: <P> 318: <DL> 319: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool 320: <DT><I>uint</I> <B>size</B><DD><P>amount of memory 321: </DL> 322: <H3>Description</H3> 323: <P><B>lp_allocu()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B> 324: and it returns a pointer to the allocated memory. It doesn't 325: attempt to align the memory block, giving a very efficient way 326: how to allocate strings without any space overhead. 327: 328: 329: <HR><H3>Function</H3> 330: <P><I>void *</I> 331: <B>lp_allocz</B> 332: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate cleared memory from a <I>linpool</I> 333: <P> 334: <H3>Arguments</H3> 335: <P> 336: <DL> 337: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool 338: <DT><I>uint</I> <B>size</B><DD><P>amount of memory 339: </DL> 340: <H3>Description</H3> 341: <P>This function is identical to <B>lp_alloc()</B> except that it 342: clears the allocated memory block. 343: 344: 345: <HR><H3>Function</H3> 346: <P><I>void</I> 347: <B>lp_flush</B> 348: (<I>linpool *</I> <B>m</B>) -- flush a linear memory pool 349: <P> 350: <H3>Arguments</H3> 351: <P> 352: <DL> 353: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool 354: </DL> 355: <H3>Description</H3> 356: <P>This function frees the whole contents of the given <I>linpool</I> <B>m</B>, 357: but leaves the pool itself. 358: 359: <H2><A NAME="ss8.5">8.5</A> <A HREF="prog.html#toc8.5">Slabs</A> 360: </H2> 361: 362: <P> 363: <P>Slabs are collections of memory blocks of a fixed size. 364: They support very fast allocation and freeing of such blocks, prevent memory 365: fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick 366: and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel 367: Memory Allocator'. Our implementation follows this article except that we don't use 368: constructors and destructors. 369: <P>When the <CODE>DEBUGGING</CODE> switch is turned on, we automatically fill all 370: newly allocated and freed blocks with a special pattern to make detection 371: of use of uninitialized or already freed memory easier. 372: <P>Example: Nodes of a FIB are allocated from a per-FIB Slab. 373: <P> 374: <P><HR><H3>Function</H3> 375: <P><I>slab *</I> 376: <B>sl_new</B> 377: (<I>pool *</I> <B>p</B>, <I>uint</I> <B>size</B>) -- create a new Slab 378: <P> 379: <H3>Arguments</H3> 380: <P> 381: <DL> 382: <DT><I>pool *</I> <B>p</B><DD><P>resource pool 383: <DT><I>uint</I> <B>size</B><DD><P>block size 384: </DL> 385: <H3>Description</H3> 386: <P>This function creates a new Slab resource from which 387: objects of size <B>size</B> can be allocated. 388: 389: 390: <HR><H3>Function</H3> 391: <P><I>void *</I> 392: <B>sl_alloc</B> 393: (<I>slab *</I> <B>s</B>) -- allocate an object from Slab 394: <P> 395: <H3>Arguments</H3> 396: <P> 397: <DL> 398: <DT><I>slab *</I> <B>s</B><DD><P>slab 399: </DL> 400: <H3>Description</H3> 401: <P><B>sl_alloc()</B> allocates space for a single object from the 402: Slab and returns a pointer to the object. 403: 404: 405: <HR><H3>Function</H3> 406: <P><I>void</I> 407: <B>sl_free</B> 408: (<I>slab *</I> <B>s</B>, <I>void *</I> <B>oo</B>) -- return a free object back to a Slab 409: <P> 410: <H3>Arguments</H3> 411: <P> 412: <DL> 413: <DT><I>slab *</I> <B>s</B><DD><P>slab 414: <DT><I>void *</I> <B>oo</B><DD><P>object returned by <B>sl_alloc()</B> 415: </DL> 416: <H3>Description</H3> 417: <P>This function frees memory associated with the object <B>oo</B> 418: and returns it back to the Slab <B>s</B>. 419: 420: <H2><A NAME="ss8.6">8.6</A> <A HREF="prog.html#toc8.6">Events</A> 421: </H2> 422: 423: <P> 424: <P>Events are there to keep track of deferred execution. 425: Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller 426: parts, so that no module can monopolize the CPU. To split such a task, just create 427: an <I>event</I> resource, point it to the function you want to have called and call <B>ev_schedule()</B> 428: to ask the core to run the event when nothing more important requires attention. 429: <P>You can also define your own event lists (the <I>event_list</I> structure), enqueue your 430: events in them and explicitly ask to run them. 431: <P> 432: <P><HR><H3>Function</H3> 433: <P><I>event *</I> 434: <B>ev_new</B> 435: (<I>pool *</I> <B>p</B>) -- create a new event 436: <P> 437: <H3>Arguments</H3> 438: <P> 439: <DL> 440: <DT><I>pool *</I> <B>p</B><DD><P>resource pool 441: </DL> 442: <H3>Description</H3> 443: <P>This function creates a new event resource. To use it, 444: you need to fill the structure fields and call <B>ev_schedule()</B>. 445: 446: 447: <HR><H3>Function</H3> 448: <P><I>void</I> 449: <B>ev_run</B> 450: (<I>event *</I> <B>e</B>) -- run an event 451: <P> 452: <H3>Arguments</H3> 453: <P> 454: <DL> 455: <DT><I>event *</I> <B>e</B><DD><P>an event 456: </DL> 457: <H3>Description</H3> 458: <P>This function explicitly runs the event <B>e</B> (calls its hook 459: function) and removes it from an event list if it's linked to any. 460: <P>From the hook function, you can call <B>ev_enqueue()</B> or <B>ev_schedule()</B> 461: to re-add the event. 462: 463: 464: <HR><H3>Function</H3> 465: <P><I>void</I> 466: <B>ev_enqueue</B> 467: (<I>event_list *</I> <B>l</B>, <I>event *</I> <B>e</B>) -- enqueue an event 468: <P> 469: <H3>Arguments</H3> 470: <P> 471: <DL> 472: <DT><I>event_list *</I> <B>l</B><DD><P>an event list 473: <DT><I>event *</I> <B>e</B><DD><P>an event 474: </DL> 475: <H3>Description</H3> 476: <P><B>ev_enqueue()</B> stores the event <B>e</B> to the specified event 477: list <B>l</B> which can be run by calling <B>ev_run_list()</B>. 478: 479: 480: <HR><H3>Function</H3> 481: <P><I>void</I> 482: <B>ev_schedule</B> 483: (<I>event *</I> <B>e</B>) -- schedule an event 484: <P> 485: <H3>Arguments</H3> 486: <P> 487: <DL> 488: <DT><I>event *</I> <B>e</B><DD><P>an event 489: </DL> 490: <H3>Description</H3> 491: <P>This function schedules an event by enqueueing it to a system-wide 492: event list which is run by the platform dependent code whenever 493: appropriate. 494: 495: 496: <HR><H3>Function</H3> 497: <P><I>int</I> 498: <B>ev_run_list</B> 499: (<I>event_list *</I> <B>l</B>) -- run an event list 500: <P> 501: <H3>Arguments</H3> 502: <P> 503: <DL> 504: <DT><I>event_list *</I> <B>l</B><DD><P>an event list 505: </DL> 506: <H3>Description</H3> 507: <P>This function calls <B>ev_run()</B> for all events enqueued in the list <B>l</B>. 508: 509: <H2><A NAME="ss8.7">8.7</A> <A HREF="prog.html#toc8.7">Timers</A> 510: </H2> 511: 512: <P> 513: <P>Timers are resources which represent a wish of a module to call 514: a function at the specified time. The platform dependent code 515: doesn't guarantee exact timing, only that a timer function 516: won't be called before the requested time. 517: <P>In BIRD, time is represented by values of the <I>bird_clock_t</I> type 518: which are integral numbers interpreted as a relative number of seconds since 519: some fixed time point in past. The current time can be read 520: from variable <B>now</B> with reasonable accuracy and is monotonic. There is also 521: a current 'absolute' time in variable <B>now_real</B> reported by OS. 522: <P>Each timer is described by a <I>timer</I> structure containing a pointer 523: to the handler function (<B>hook</B>), data private to this function (<B>data</B>), 524: time the function should be called at (<B>expires</B>, 0 for inactive timers), 525: for the other fields see <CODE>timer.h</CODE>. 526: <P> 527: <P><HR><H3>Function</H3> 528: <P><I>timer *</I> 529: <B>tm_new</B> 530: (<I>pool *</I> <B>p</B>) -- create a timer 531: <P> 532: <H3>Arguments</H3> 533: <P> 534: <DL> 535: <DT><I>pool *</I> <B>p</B><DD><P>pool 536: </DL> 537: <H3>Description</H3> 538: <P>This function creates a new timer resource and returns 539: a pointer to it. To use the timer, you need to fill in 540: the structure fields and call <B>tm_start()</B> to start timing. 541: 542: 543: <HR><H3>Function</H3> 544: <P><I>void</I> 545: <B>tm_start</B> 546: (<I>timer *</I> <B>t</B>, <I>unsigned</I> <B>after</B>) -- start a timer 547: <P> 548: <H3>Arguments</H3> 549: <P> 550: <DL> 551: <DT><I>timer *</I> <B>t</B><DD><P>timer 552: <DT><I>unsigned</I> <B>after</B><DD><P>number of seconds the timer should be run after 553: </DL> 554: <H3>Description</H3> 555: <P>This function schedules the hook function of the timer to 556: be called after <B>after</B> seconds. If the timer has been already 557: started, it's <B>expire</B> time is replaced by the new value. 558: <P>You can have set the <B>randomize</B> field of <B>t</B>, the timeout 559: will be increased by a random number of seconds chosen 560: uniformly from range 0 .. <B>randomize</B>. 561: <P>You can call <B>tm_start()</B> from the handler function of the timer 562: to request another run of the timer. Also, you can set the <B>recurrent</B> 563: field to have the timer re-added automatically with the same timeout. 564: 565: 566: <HR><H3>Function</H3> 567: <P><I>void</I> 568: <B>tm_stop</B> 569: (<I>timer *</I> <B>t</B>) -- stop a timer 570: <P> 571: <H3>Arguments</H3> 572: <P> 573: <DL> 574: <DT><I>timer *</I> <B>t</B><DD><P>timer 575: </DL> 576: <H3>Description</H3> 577: <P>This function stops a timer. If the timer is already stopped, 578: nothing happens. 579: 580: 581: <HR><H3>Function</H3> 582: <P><I>bird_clock_t</I> 583: <B>tm_parse_datetime</B> 584: (<I>char *</I> <B>x</B>) -- parse a date and time 585: <P> 586: <H3>Arguments</H3> 587: <P> 588: <DL> 589: <DT><I>char *</I> <B>x</B><DD><P>datetime string 590: </DL> 591: <H3>Description</H3> 592: <P><B>tm_parse_datetime()</B> takes a textual representation of 593: a date and time (dd-mm-yyyy hh:mm:ss) 594: and converts it to the corresponding value of type <I>bird_clock_t</I>. 595: 596: 597: <HR><H3>Function</H3> 598: <P><I>bird_clock_t</I> 599: <B>tm_parse_date</B> 600: (<I>char *</I> <B>x</B>) -- parse a date 601: <P> 602: <H3>Arguments</H3> 603: <P> 604: <DL> 605: <DT><I>char *</I> <B>x</B><DD><P>date string 606: </DL> 607: <H3>Description</H3> 608: <P><B>tm_parse_date()</B> takes a textual representation of a date (dd-mm-yyyy) 609: and converts it to the corresponding value of type <I>bird_clock_t</I>. 610: 611: 612: <HR><H3>Function</H3> 613: <P><I>void</I> 614: <B>tm_format_datetime</B> 615: (<I>char *</I> <B>x</B>, <I>struct timeformat *</I> <B>fmt_spec</B>, <I>bird_clock_t</I> <B>t</B>) -- convert date and time to textual representation 616: <P> 617: <H3>Arguments</H3> 618: <P> 619: <DL> 620: <DT><I>char *</I> <B>x</B><DD><P>destination buffer of size <I>TM_DATETIME_BUFFER_SIZE</I> 621: <DT><I>struct timeformat *</I> <B>fmt_spec</B><DD><P>specification of resulting textual representation of the time 622: <DT><I>bird_clock_t</I> <B>t</B><DD><P>time 623: </DL> 624: <H3>Description</H3> 625: <P>This function formats the given relative time value <B>t</B> to a textual 626: date/time representation (dd-mm-yyyy hh:mm:ss) in real time. 627: 628: <H2><A NAME="ss8.8">8.8</A> <A HREF="prog.html#toc8.8">Sockets</A> 629: </H2> 630: 631: <P> 632: <P>Socket resources represent network connections. Their data structure (<I>socket</I>) 633: contains a lot of fields defining the exact type of the socket, the local and 634: remote addresses and ports, pointers to socket buffers and finally pointers to 635: hook functions to be called when new data have arrived to the receive buffer 636: (<B>rx_hook</B>), when the contents of the transmit buffer have been transmitted 637: (<B>tx_hook</B>) and when an error or connection close occurs (<B>err_hook</B>). 638: <P>Freeing of sockets from inside socket hooks is perfectly safe. 639: <P> 640: <P><HR><H3>Function</H3> 641: <P><I>int</I> 642: <B>sk_setup_multicast</B> 643: (<I>sock *</I> <B>s</B>) -- enable multicast for given socket 644: <P> 645: <H3>Arguments</H3> 646: <P> 647: <DL> 648: <DT><I>sock *</I> <B>s</B><DD><P>socket 649: </DL> 650: <H3>Description</H3> 651: <P>Prepare transmission of multicast packets for given datagram socket. 652: The socket must have defined <B>iface</B>. 653: <H3>Result</H3> 654: <P>0 for success, -1 for an error. 655: 656: 657: <HR><H3>Function</H3> 658: <P><I>int</I> 659: <B>sk_join_group</B> 660: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) -- join multicast group for given socket 661: <P> 662: <H3>Arguments</H3> 663: <P> 664: <DL> 665: <DT><I>sock *</I> <B>s</B><DD><P>socket 666: <DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address 667: </DL> 668: <H3>Description</H3> 669: <P>Join multicast group for given datagram socket and associated interface. 670: The socket must have defined <B>iface</B>. 671: <H3>Result</H3> 672: <P>0 for success, -1 for an error. 673: 674: 675: <HR><H3>Function</H3> 676: <P><I>int</I> 677: <B>sk_leave_group</B> 678: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) -- leave multicast group for given socket 679: <P> 680: <H3>Arguments</H3> 681: <P> 682: <DL> 683: <DT><I>sock *</I> <B>s</B><DD><P>socket 684: <DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address 685: </DL> 686: <H3>Description</H3> 687: <P>Leave multicast group for given datagram socket and associated interface. 688: The socket must have defined <B>iface</B>. 689: <H3>Result</H3> 690: <P>0 for success, -1 for an error. 691: 692: 693: <HR><H3>Function</H3> 694: <P><I>int</I> 695: <B>sk_setup_broadcast</B> 696: (<I>sock *</I> <B>s</B>) -- enable broadcast for given socket 697: <P> 698: <H3>Arguments</H3> 699: <P> 700: <DL> 701: <DT><I>sock *</I> <B>s</B><DD><P>socket 702: </DL> 703: <H3>Description</H3> 704: <P>Allow reception and transmission of broadcast packets for given datagram 705: socket. The socket must have defined <B>iface</B>. For transmission, packets should 706: be send to <B>brd</B> address of <B>iface</B>. 707: <H3>Result</H3> 708: <P>0 for success, -1 for an error. 709: 710: 711: <HR><H3>Function</H3> 712: <P><I>int</I> 713: <B>sk_set_ttl</B> 714: (<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) -- set transmit TTL for given socket 715: <P> 716: <H3>Arguments</H3> 717: <P> 718: <DL> 719: <DT><I>sock *</I> <B>s</B><DD><P>socket 720: <DT><I>int</I> <B>ttl</B><DD><P>TTL value 721: </DL> 722: <H3>Description</H3> 723: <P>Set TTL for already opened connections when TTL was not set before. Useful 724: for accepted connections when different ones should have different TTL. 725: <H3>Result</H3> 726: <P>0 for success, -1 for an error. 727: 728: 729: <HR><H3>Function</H3> 730: <P><I>int</I> 731: <B>sk_set_min_ttl</B> 732: (<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) -- set minimal accepted TTL for given socket 733: <P> 734: <H3>Arguments</H3> 735: <P> 736: <DL> 737: <DT><I>sock *</I> <B>s</B><DD><P>socket 738: <DT><I>int</I> <B>ttl</B><DD><P>TTL value 739: </DL> 740: <H3>Description</H3> 741: <P>Set minimal accepted TTL for given socket. Can be used for TTL security. 742: implementations. 743: <H3>Result</H3> 744: <P>0 for success, -1 for an error. 745: 746: 747: <HR><H3>Function</H3> 748: <P><I>int</I> 749: <B>sk_set_md5_auth</B> 750: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>local</B>, <I>ip_addr</I> <B>remote</B>, <I>struct iface *</I> <B>ifa</B>, <I>char *</I> <B>passwd</B>, <I>int</I> <B>setkey</B>) -- add / remove MD5 security association for given socket 751: <P> 752: <H3>Arguments</H3> 753: <P> 754: <DL> 755: <DT><I>sock *</I> <B>s</B><DD><P>socket 756: <DT><I>ip_addr</I> <B>local</B><DD><P>IP address of local side 757: <DT><I>ip_addr</I> <B>remote</B><DD><P>IP address of remote side 758: <DT><I>struct iface *</I> <B>ifa</B><DD><P>Interface for link-local IP address 759: <DT><I>char *</I> <B>passwd</B><DD><P>Password used for MD5 authentication 760: <DT><I>int</I> <B>setkey</B><DD><P>Update also system SA/SP database 761: </DL> 762: <H3>Description</H3> 763: <P>In TCP MD5 handling code in kernel, there is a set of security associations 764: used for choosing password and other authentication parameters according to 765: the local and remote address. This function is useful for listening socket, 766: for active sockets it may be enough to set s->password field. 767: <P>When called with passwd != NULL, the new pair is added, 768: When called with passwd == NULL, the existing pair is removed. 769: <P>Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are 770: stored in global SA/SP database (but the behavior also must be enabled on 771: per-socket basis). In case of multiple sockets to the same neighbor, the 772: socket-specific state must be configured for each socket while global state 773: just once per src-dst pair. The <B>setkey</B> argument controls whether the global 774: state (SA/SP database) is also updated. 775: <H3>Result</H3> 776: <P>0 for success, -1 for an error. 777: 778: 779: <HR><H3>Function</H3> 780: <P><I>int</I> 781: <B>sk_set_ipv6_checksum</B> 782: (<I>sock *</I> <B>s</B>, <I>int</I> <B>offset</B>) -- specify IPv6 checksum offset for given socket 783: <P> 784: <H3>Arguments</H3> 785: <P> 786: <DL> 787: <DT><I>sock *</I> <B>s</B><DD><P>socket 788: <DT><I>int</I> <B>offset</B><DD><P>offset 789: </DL> 790: <H3>Description</H3> 791: <P>Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the 792: kernel will automatically fill it for outgoing packets and check it for 793: incoming packets. Should not be used on ICMPv6 sockets, where the position is 794: known to the kernel. 795: <H3>Result</H3> 796: <P>0 for success, -1 for an error. 797: 798: 799: <HR><H3>Function</H3> 800: <P><I>sock *</I> 801: <B>sock_new</B> 802: (<I>pool *</I> <B>p</B>) -- create a socket 803: <P> 804: <H3>Arguments</H3> 805: <P> 806: <DL> 807: <DT><I>pool *</I> <B>p</B><DD><P>pool 808: </DL> 809: <H3>Description</H3> 810: <P>This function creates a new socket resource. If you want to use it, 811: you need to fill in all the required fields of the structure and 812: call <B>sk_open()</B> to do the actual opening of the socket. 813: <P>The real function name is <B>sock_new()</B>, <B>sk_new()</B> is a macro wrapper 814: to avoid collision with OpenSSL. 815: 816: 817: <HR><H3>Function</H3> 818: <P><I>int</I> 819: <B>sk_open</B> 820: (<I>sock *</I> <B>s</B>) -- open a socket 821: <P> 822: <H3>Arguments</H3> 823: <P> 824: <DL> 825: <DT><I>sock *</I> <B>s</B><DD><P>socket 826: </DL> 827: <H3>Description</H3> 828: <P>This function takes a socket resource created by <B>sk_new()</B> and 829: initialized by the user and binds a corresponding network connection 830: to it. 831: <H3>Result</H3> 832: <P>0 for success, -1 for an error. 833: 834: 835: <HR><H3>Function</H3> 836: <P><I>int</I> 837: <B>sk_send</B> 838: (<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>) -- send data to a socket 839: <P> 840: <H3>Arguments</H3> 841: <P> 842: <DL> 843: <DT><I>sock *</I> <B>s</B><DD><P>socket 844: <DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send 845: </DL> 846: <H3>Description</H3> 847: <P>This function sends <B>len</B> bytes of data prepared in the 848: transmit buffer of the socket <B>s</B> to the network connection. 849: If the packet can be sent immediately, it does so and returns 850: 1, else it queues the packet for later processing, returns 0 851: and calls the <B>tx_hook</B> of the socket when the tranmission 852: takes place. 853: 854: 855: <HR><H3>Function</H3> 856: <P><I>int</I> 857: <B>sk_send_to</B> 858: (<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>port</B>) -- send data to a specific destination 859: <P> 860: <H3>Arguments</H3> 861: <P> 862: <DL> 863: <DT><I>sock *</I> <B>s</B><DD><P>socket 864: <DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send 865: <DT><I>ip_addr</I> <B>addr</B><DD><P>IP address to send the packet to 866: <DT><I>unsigned</I> <B>port</B><DD><P>port to send the packet to 867: </DL> 868: <H3>Description</H3> 869: <P>This is a <B>sk_send()</B> replacement for connection-less packet sockets 870: which allows destination of the packet to be chosen dynamically. 871: Raw IP sockets should use 0 for <B>port</B>. 872: 873: 874: <HR><H3>Function</H3> 875: <P><I>void</I> 876: <B>io_log_event</B> 877: (<I>void *</I> <B>hook</B>, <I>void *</I> <B>data</B>) -- mark approaching event into event log 878: <P> 879: <H3>Arguments</H3> 880: <P> 881: <DL> 882: <DT><I>void *</I> <B>hook</B><DD><P>event hook address 883: <DT><I>void *</I> <B>data</B><DD><P>event data address 884: </DL> 885: <H3>Description</H3> 886: <P>Store info (hook, data, timestamp) about the following internal event into 887: a circular event log (<B>event_log</B>). When latency tracking is enabled, the log 888: entry is kept open (in <B>event_open</B>) so the duration can be filled later. 889: 890: <P> 891: <HR> 892: Next 893: <A HREF="prog-7.html">Previous</A> 894: <A HREF="prog.html#toc8">Contents</A> 895: </BODY> 896: </HTML>