Annotation of embedaddon/bird/doc/prog-7.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: 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