Annotation of embedaddon/bird/doc/prog-8.html, revision 1.1.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: 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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-8.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