1 /*
2 ** Copyright (C) 2006-2020 by Carnegie Mellon University.
3 **
4 ** @OPENSOURCE_LICENSE_START@
5 ** See license information in ../../LICENSE.txt
6 ** @OPENSOURCE_LICENSE_END@
7 */
8 
9 /*
10 **  skheader.h
11 **
12 **    API to read, write, and manipulate the header of a SiLK file
13 **
14 **    Mark Thomas
15 **    November 2006
16 **
17 */
18 #ifndef _SKHEADER_H
19 #define _SKHEADER_H
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 #include <silk/silk.h>
25 
26 RCSIDENTVAR(rcsID_SKHEADER_H, "$SiLK: skheader.h ef14e54179be 2020-04-14 21:57:45Z mthomas $");
27 
28 #include <silk/silk_types.h>
29 
30 /**
31  *  @file
32  *
33  *    The API to read, write, and manipulate the header of a binary
34  *    SiLK file.
35  *
36  *    This file is part of libsilk.
37  */
38 
39 
40 /**
41  *    A SiLK file has a header-section and a data-section.  The header
42  *    section is called an 'sk_file_header_t'.
43  *
44  *    The sk_file_header_t is split into two sections, a fixed size
45  *    'sk_header_start_t' and a variable number of variable-sized
46  *    'sk_header_entry_t'.
47  */
48 typedef struct sk_file_header_st sk_file_header_t;
49 
50 /**
51  *    The first section of an sk_file_header_t is called the
52  *    sk_header_start_t, and it has a fixed size of 16 bytes.
53  *
54  *    The first four bytes of an sk_header_start_t is the SiLK magic
55  *    number, 0xDEADBEEF.
56  *
57  *    The next four bytes of the sk_header_start_t denote the file's
58  *    byte order, the file's format (that is, the type of data it
59  *    contains, the file version, and the type of compression unsed
60  *    for the data section.
61  *
62  *    The final eight bytes contain the version of SiLK that wrote
63  *    the file, the bytes per record, and the version of the record.
64  */
65 typedef struct sk_header_start_st sk_header_start_t;
66 
67 /**
68  *    The second part of the sk_file_header_t contains a variable
69  *    number of sk_header_entry_t's.
70  */
71 typedef struct sk_header_entry_st sk_header_entry_t;
72 
73 /**
74  *    In core, the sk_header_entry_t's are stored in a circular
75  *    doubly-linked-linked list of sk_hentry_node_t's.
76  */
77 typedef struct sk_hentry_node_st sk_hentry_node_t;
78 
79 /**
80  *    An sk_hentry_iterator_t is used to visit each of the
81  *    header-entries in the header.
82  */
83 typedef struct sk_hentry_iterator_st sk_hentry_iterator_t;
84 
85 /**
86  *    Each sk_header_entry_t is made up of an sk_header_entry_spec_t
87  *    and a variable size data section---which may contain 0 bytes.
88  */
89 typedef struct sk_header_entry_spec_st sk_header_entry_spec_t;
90 
91 /**
92  *    The current sk_header_entry_spec_t has four-bytes that specify
93  *    its hentry-type-ID, and four-bytes giving the
94  *    sk_header_entry_t's complete length---including the length of
95  *    the sk_header_entry_spec_t.
96  */
97 typedef uint32_t sk_hentry_type_id_t;
98 
99 /**
100  *    The hentry-type-ID "\0\0\0\0" is used to mark the end of the
101  *    header entries.  The length of this header-entry should still be
102  *    valid.  In particular, any header padding must be accounted for
103  *    in this entry.
104  *
105  *    The minimum sized header is 24 bytes.  The data section, if
106  *    present, begins immediately after the header-entry whose ID is
107  *    "\0\0\0\0".
108  *
109  *    Note that in the new headers, all values are in network (big)
110  *    byte order, so use ntohs() and ntohl() to read them.
111  *
112  *    To avoid clashes with existing files, the file_version value for
113  *    all files with this new header will be >= 16.
114  */
115 
116 /**
117  *    The minimum file version that may be specified to
118  *    skHeaderSetFileVersion().  A SiLK tool may accept a lower
119  *    version number when reading data, but the version number may not
120  *    be lower than this when creating a file.
121  */
122 #define SK_FILE_VERSION_MINIMUM 16
123 
124 /**
125  *    The maximum file version that may be specified to
126  *    skHeaderSetFileVersion().
127  */
128 #define SK_FILE_VERSION_MAXIMUM SK_FILE_VERSION_MINIMUM
129 
130 /**
131  *    The file version to use as the default.
132  */
133 #define SK_FILE_VERSION_DEFAULT SK_FILE_VERSION_MINIMUM
134 
135 /**
136  *    Values returned by the skHeader*() functions.
137  */
138 typedef enum skHeaderErrorCodes_en {
139     /** Command succeeded. */
140     SKHEADER_OK = 0,
141 
142     /** Memory allocation failed */
143     SKHEADER_ERR_ALLOC,
144 
145     /** Programmer or allocation error: NULL passed as argument to
146      * function */
147     SKHEADER_ERR_NULL_ARGUMENT,
148 
149     /** The file format is not supported */
150     SKHEADER_ERR_BAD_FORMAT,
151 
152     /** The file version is not supported */
153     SKHEADER_ERR_BAD_VERSION,
154 
155     /** Attempt to replace an entry that does not exist */
156     SKHEADER_ERR_ENTRY_NOTFOUND,
157 
158     /** Error in packing an entry */
159     SKHEADER_ERR_ENTRY_PACK,
160 
161     /** Error in reading an entry from disk */
162     SKHEADER_ERR_ENTRY_READ,
163 
164     /** Error in unpacking an entry */
165     SKHEADER_ERR_ENTRY_UNPACK,
166 
167     /** The entry ID is invalid */
168     SKHEADER_ERR_INVALID_ID,
169 
170     /** Attempt to modify a locked header */
171     SKHEADER_ERR_IS_LOCKED,
172 
173     /** Error handling a legacy header */
174     SKHEADER_ERR_LEGACY,
175 
176     /** Header compression value is invalid */
177     SKHEADER_ERR_BAD_COMPRESSION,
178 
179     /** Read fewer bytes than that required to read the header */
180     SKHEADER_ERR_SHORTREAD,
181 
182     /** Header length is longer than expected */
183     SKHEADER_ERR_TOOLONG
184 } skHeaderErrorCodes_t;
185 
186 
187 /**
188  *    Settings for the header locks
189  */
190 typedef enum sk_header_lock_en {
191     /** Header is completely modifable */
192     SKHDR_LOCK_MODIFIABLE,
193     /** Header is completely locked: nothing can be changed nor new
194      * entries added */
195     SKHDR_LOCK_FIXED,
196     /** Header cannot be changed, but new header entries may be
197      * added. */
198     SKHDR_LOCK_ENTRY_OK
199 } sk_header_lock_t;
200 
201 
202 /**
203  *    sk_header_entry_spec_t: The header-entries have a
204  *    header-entry-spec and a data section.
205  */
206 struct sk_header_entry_spec_st {
207     /** The ID for this header-entry.  0 marks the final entry */
208     sk_hentry_type_id_t     hes_id;
209     /** Total length of this header entry, including the
210      * header-entry-spec */
211     uint32_t                hes_len;
212 };
213 
214 /**
215  *    sk_header_entry_t
216  */
217 struct sk_header_entry_st {
218     sk_header_entry_spec_t  he_spec;
219     void                   *he_data;
220 };
221 
222 /**
223  *    sk_hentry_iterator_t: The hentry-iterator is used to visit the
224  *    header-entries.
225  */
226 struct sk_hentry_iterator_st {
227     const sk_file_header_t     *hdr;
228     sk_hentry_node_t           *node;
229     sk_hentry_type_id_t         htype_filter;
230 };
231 
232 
233 /**
234  *    The 'sk_hentry_pack_fn_t' is used to write an in-core
235  *    header-entry to a binary data file.
236  *
237  *    It take pointers to a header entry data structure, 'hentry_in'
238  *    and to a byte-array, 'packed_entry_out' of 'packed_avail_size'
239  *    bytes, and it fills 'packed_entry_out' with the data in the
240  *    'hentry_in' suitable for writing to a binary stream.  The
241  *    function returns the number of bytes in 'packed_entry_out' that
242  *    were used, i.e., the number of bytes to be written.  If
243  *    'packed_entry_out' is too small, the function should return the
244  *    number of bytes that would be required to hold all of
245  *    'hentry_in'.  The caller will likely grow 'packed_entry_out' and
246  *    invoke this function again.
247  *
248  *    This function should make certain that the values in the
249  *    sk_header_entry_spec_t section of 'packed_entry_out' are in
250  *    network (big-endian) byte order.  The other values may have any
251  *    meaning, as long as the 'sk_hentry_unpack_fn_t' knows how to
252  *    decode them.
253  */
254 typedef ssize_t
255 (*sk_hentry_pack_fn_t)(
256     const sk_header_entry_t    *hentry_in,
257     uint8_t                    *packed_entry_out,
258     size_t                      packed_avail_size);
259 
260 /**
261  *    When a binary SiLK file is read, the 'sk_hentry_unpack_fn_t' is
262  *    called to convert the bytes to an in-core data structure.
263  *
264  *    It takes a pointer to a sk_header_entry_t, 'packed_in'---as read
265  *    from a binary stream and packed by the
266  *    'sk_hentry_pack_fn_t'---and allocates and returns a pointer to
267  *    the expanded version of the data.
268  */
269 typedef sk_header_entry_t *
270 (*sk_hentry_unpack_fn_t)(
271     uint8_t                *packed_in);
272 
273 /**
274  *    The 'sk_hentry_copy_fn_t' is used to do a complete (deep) copy
275  *    of a header-entry.
276  *
277  */
278 typedef sk_header_entry_t *
279 (*sk_hentry_copy_fn_t)(
280     const sk_header_entry_t    *hentry_in);
281 
282 /**
283  *    To produce a human-readable form of the header,
284  *    'sk_hentry_print_fn_t' is used.
285  *
286  *    It prints the header, 'hentry', to the specified stream, 'fh',
287  *    as text.
288  */
289 typedef void
290 (*sk_hentry_print_fn_t)(
291     const sk_header_entry_t  *hentry,
292     FILE                     *fh);
293 
294 /**
295  *    A generic callback function for the header entry 'hentry'.  One
296  *    such use is as function to free() the memory allocated by the
297  *    'sk_hentry_unpack_fn_t'.
298  */
299 typedef void
300 (*sk_hentry_callback_fn_t)(
301     sk_header_entry_t      *hentry);
302 
303 /**
304  *    When defined and set to a non-empty string, use 0 as the SiLK
305  *    version number in the header of files we create.
306  */
307 #define SILK_HEADER_NOVERSION_ENV  "SILK_HEADER_NOVERSION"
308 
309 
310 /*
311  *    **********************************************************************
312  *
313  *    Functions for handling the header and header entries.
314  *
315  *    **********************************************************************
316  */
317 
318 
319 /**
320  *    Add the Header Entry 'hentry' to the File Header 'hdr'.  Return
321  *    0 on sucess, or -1 for the following error conditions: if the
322  *    'hentry' is NULL or if it has a reserved ID, or on memory
323  *    allocation error.
324  */
325 int
326 skHeaderAddEntry(
327     sk_file_header_t   *hdr,
328     sk_header_entry_t  *hentry);
329 
330 
331 /**
332  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
333  *    indicating that the entire header should be copied.
334  */
335 #define SKHDR_CP_ALL           0xFFFFFFFFu
336 
337 /**
338  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
339  *    indicating that the byte order value should be copied.
340  */
341 #define SKHDR_CP_ENDIAN        (1u <<  7)
342 
343 /**
344  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
345  *    indicating that the file format value should be copied.
346  */
347 #define SKHDR_CP_FORMAT        (1u <<  8)
348 
349 /**
350  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
351  *    indicating that the file version value should be copied.
352  */
353 #define SKHDR_CP_FILE_VERS     (1u <<  9)
354 
355 /**
356  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
357  *    indicating that the compression method value should be copied.
358  */
359 #define SKHDR_CP_COMPMETHOD    (1u << 10)
360 
361 /**
362  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
363  *    indicating that the record length value should be copied.
364  */
365 #define SKHDR_CP_REC_LEN       (1u << 11)
366 
367 /**
368  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
369  *    indicating that the record version value should be copied.
370  */
371 #define SKHDR_CP_REC_VERS      (1u << 12)
372 
373 /**
374  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
375  *    indicating that all header entries should be copied.
376  */
377 #define SKHDR_CP_ENTRIES       (1u << 31)
378 
379 /**
380  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
381  *    indicating that the file parameter values should be copied.
382  */
383 #define SKHDR_CP_FILE_FLAGS    0x000000FFu
384 
385 /**
386  *    Possible value for 'copy_flags' parameter of skHeaderCopy()
387  *    indicating that the entire header except the header entries
388  *    should be copied.
389  */
390 #define SKHDR_CP_START         0x00FFFFFFu
391 
392 /**
393  *    Copy the header 'src_hdr' to 'dst_hdr'.  The parts of the header
394  *    to copy are specified by the 'copy_flags' value.
395  */
396 int
397 skHeaderCopy(
398     sk_file_header_t       *dst_hdr,
399     const sk_file_header_t *src_hdr,
400     uint32_t                copy_flags);
401 
402 
403 /**
404  *    Copy all the header entries whose ID is 'entry_id' from
405  *    'src_hdr' to 'dst_hdr'.
406  */
407 int
408 skHeaderCopyEntries(
409     sk_file_header_t       *dst_hdr,
410     const sk_file_header_t *src_hdr,
411     sk_hentry_type_id_t     entry_id);
412 
413 
414 /**
415  *    Create and return a new entry that is a (deep) copy of the
416  *    header entry 'src_hentry'.  Return NULL on failure or if the
417  *    'src_header' refers to the root node.
418  */
419 sk_header_entry_t *
420 skHeaderEntryCopy(
421     const sk_header_entry_t    *src_hentry);
422 
423 
424 /**
425  *    Return the type ID for a header entry.
426  */
427 #if 0
428 sk_hentry_type_id_t
429 skHeaderEntryGetTypeId(
430     const sk_header_entry_t    *hentry);
431 #else
432 #  define skHeaderEntryGetTypeId(hentry)  ((hentry)->he_spec.hes_id)
433 #endif
434 
435 
436 /**
437  *    Print a textual representation of the Header Entry 'hentry' to
438  *    the stream 'fp'.
439  */
440 void
441 skHeaderEntryPrint(
442     const sk_header_entry_t  *hentry,
443     FILE               *fp);
444 
445 
446 /**
447  *    Pack the header entry spec 'he_spec' into the octet array
448  *    'out_packed' whose size is 'bufsize'.  If 'bufsize' is smaller
449  *    than required, write nothing to the buffer.  Return the number
450  *    of bytes written to the buffer or that would be written to the
451  *    buffer if the buffer were large enough.
452  */
453 size_t
454 skHeaderEntrySpecPack(
455     const sk_header_entry_spec_t   *he_spec,
456     uint8_t                        *out_packed,
457     size_t                          bufsize);
458 
459 
460 /**
461  *    Unpack the header entry spec from the octet array 'in_packed'
462  *    into the 'he_spec' structure.  The function assumes the length
463  *    of 'in_packed' is at least sizeof(sk_header_entry_spec_t).
464  */
465 void
466 skHeaderEntrySpecUnpack(
467     sk_header_entry_spec_t *he_spec,
468     const uint8_t          *in_packed);
469 
470 
471 /**
472  *    Get the byte order of the records in the file for which 'hdr' is
473  *    the header.
474  */
475 silk_endian_t
476 skHeaderGetByteOrder(
477     const sk_file_header_t *hdr);
478 
479 
480 /**
481  *    Return the compression method used on 'stream'.
482  */
483 sk_compmethod_t
484 skHeaderGetCompressionMethod(
485     const sk_file_header_t *hdr);
486 
487 
488 /**
489  *    Given the File Header 'hdr', return a pointer to the first
490  *    Header Entry that has the given ID, 'entry_id'.
491  */
492 sk_header_entry_t *
493 skHeaderGetFirstMatch(
494     const sk_file_header_t *hdr,
495     sk_hentry_type_id_t     entry_id);
496 
497 
498 /**
499  *    Return the SiLK file output format for the header.  Return
500  *    SK_INVALID_FILE_FORMAT when header is NULL.
501  */
502 sk_file_format_t
503 skHeaderGetFileFormat(
504     const sk_file_header_t *header);
505 
506 
507 /**
508  *    Return the version of the file.  As of SK_EXPAND_HDR_INIT_VERS,
509  *    this is different than the record version.
510  */
511 sk_file_version_t
512 skHeaderGetFileVersion(
513     const sk_file_header_t *hdr);
514 
515 
516 /**
517  *    Return the complete length of the header, in bytes.
518  */
519 size_t
520 skHeaderGetLength(
521     const sk_file_header_t *header);
522 
523 
524 /**
525  *    Return the length of the records as defined in the header.
526  */
527 size_t
528 skHeaderGetRecordLength(
529     const sk_file_header_t *header);
530 
531 
532 /**
533  *    Return the version number of the SiLK file associated with the
534  *    header.
535  */
536 sk_file_version_t
537 skHeaderGetRecordVersion(
538     const sk_file_header_t *header);
539 
540 
541 /**
542  *    Return a value representing the version of silk that wrote this file.
543  */
544 uint32_t
545 skHeaderGetSilkVersion(
546     const sk_file_header_t *hdr);
547 
548 
549 /**
550  *    Return 1 if the stream associated with 'header' is in native
551  *    byte order, or 0 if it is not.
552  */
553 int
554 skHeaderIsNativeByteOrder(
555     const sk_file_header_t *header);
556 
557 
558 /**
559  *    Bind the Header Entry Iterator 'iter' to the Header Entries in
560  *    the File Header 'hdr'.
561  */
562 void
563 skHeaderIteratorBind(
564     sk_hentry_iterator_t   *iter,
565     const sk_file_header_t *hdr);
566 
567 
568 /**
569  *    Bind the Header Entry Iterator 'iter' to the Header Entries
570  *    whose type is 'htype' in the File Header 'hdr'.
571  */
572 void
573 skHeaderIteratorBindType(
574     sk_hentry_iterator_t   *iter,
575     const sk_file_header_t *hdr,
576     sk_hentry_type_id_t     htype);
577 
578 
579 /**
580  *    For a Header Entry Iterator 'iter' that has been bound to a file
581  *    header, return a pointer to the next Header Entry.  Returns NULL
582  *    if all Header Entries have been processed.
583  */
584 sk_header_entry_t *
585 skHeaderIteratorNext(
586     sk_hentry_iterator_t   *iter);
587 
588 
589 /**
590  *    On the File Header 'hdr', remove every Header Entry whose Header
591  *    Entry Type is 'entry_id'.
592  *
593  *    Each Header Entry of the specified Type will be passed to the
594  *    free function for that Type.
595  *
596  *    Return SKHEADER_OK on success.  Return SKHEADER_ERR_INVALID_ID
597  *    if 'entry_id' is a restricted ID.  Return SKHEADER_ERR_IS_LOCKED
598  *    if the 'hdr' is locked.
599  */
600 int
601 skHeaderRemoveAllMatching(
602     sk_file_header_t       *hdr,
603     sk_hentry_type_id_t     entry_id);
604 
605 
606 /**
607  *    Set the byte order of the records in the file for which 'hdr' is
608  *    the header to 'byte_order'.
609  */
610 int
611 skHeaderSetByteOrder(
612     sk_file_header_t   *hdr,
613     silk_endian_t       byte_order);
614 
615 
616 /**
617  *    Set the compression method of the records in the file for which
618  *    'hdr' is the header to 'comp_method'.
619  */
620 int
621 skHeaderSetCompressionMethod(
622     sk_file_header_t   *hdr,
623     uint8_t             comp_method);
624 
625 
626 /**
627  *    Set the format of the file this header references to
628  *    'file_format'.
629  */
630 int
631 skHeaderSetFileFormat(
632     sk_file_header_t   *hdr,
633     sk_file_format_t    file_format);
634 
635 
636 /**
637  *    Set the file version.  The value must be between
638  *    SK_FILE_VERSION_MINIMUM and SK_FILE_VERSION_MAXIMUM inclusive.
639  *    When this function is not called, the file version is that
640  *    specified by SK_FILE_VERSION_DEFAULT.
641  *
642  *    Return SKHEADER_OK on success.  Return
643  *    SKHEADER_ERR_NULL_ARGUMENT if 'hdr' is NULL.  Return
644  *    SKHEADER_ERR_IS_LOCKED if the header is locked.  Return
645  *    SKHEADER_ERR_BAD_VERSION if 'file_version' is not legal.
646  */
647 int
648 skHeaderSetFileVersion(
649     sk_file_header_t   *hdr,
650     sk_file_version_t   file_version);
651 
652 
653 /**
654  *    Set the length of the records in the file for which 'hdr' is the
655  *    header to 'rec_len' octets.
656  */
657 int
658 skHeaderSetRecordLength(
659     sk_file_header_t   *hdr,
660     size_t              rec_len);
661 
662 
663 /**
664  *    Set the version of the records in the file for which 'hdr' is
665  *    the header to 'version'.
666  */
667 int
668 skHeaderSetRecordVersion(
669     sk_file_header_t   *hdr,
670     sk_file_version_t   record_version);
671 
672 /**
673  *    Return a string explaining the error code 'err_code'.
674  */
675 const char *
676 skHeaderStrerror(
677     ssize_t             err_code);
678 
679 
680 /*
681  *    **********************************************************************
682  *
683  *    Functions for handling the header entry types.
684  *
685  *    **********************************************************************
686  */
687 
688 
689 /**
690  *    Register a Header Type.
691  */
692 int
693 skHentryTypeRegister(
694     sk_hentry_type_id_t     entry_id,
695     sk_hentry_pack_fn_t     pack_fn,
696     sk_hentry_unpack_fn_t   unpack_fn,
697     sk_hentry_copy_fn_t     copy_fn,
698     sk_hentry_callback_fn_t free_fn,
699     sk_hentry_print_fn_t    print_fn);
700 
701 
702 /*
703  *    **********************************************************************
704  *
705  *    The 'packedfile' header entry type is used on data files
706  *    generated by rwflowpack.  It specifies the start-time,
707  *    flow-type, and sensor for a packed data * file, e.g. FT_RWSPLIT,
708  *    FT_RWWWW.
709  *
710  *    **********************************************************************
711  */
712 
713 #define SK_HENTRY_PACKEDFILE_ID 1
714 
715 int
716 skHeaderAddPackedfile(
717     sk_file_header_t   *hdr,
718     sktime_t            start_time,
719     sk_flowtype_id_t    flowtype_id,
720     sk_sensor_id_t      sensor_id);
721 
722 /**
723  *    Return the hour at which data in this file begins.  Return 0 if
724  *    the header entry is not the correct type.
725  */
726 sktime_t
727 skHentryPackedfileGetStartTime(
728     const sk_header_entry_t    *hentry);
729 
730 /**
731  *    Return the sensor ID for data in this file.  Return
732  *    SK_INVALID_SENSOR if header is not the correct type.
733  */
734 sk_sensor_id_t
735 skHentryPackedfileGetSensorID(
736     const sk_header_entry_t    *hentry);
737 
738 /**
739  *    Return the flowtype for data in this file.  Return
740  *    SK_INVALID_FLOWTYPE if header is not the correct type.
741  */
742 sk_flowtype_id_t
743 skHentryPackedfileGetFlowtypeID(
744     const sk_header_entry_t    *hentry);
745 
746 
747 
748 /*
749  *    **********************************************************************
750  *
751  *    The 'invocation' header entry type is used to store the command
752  *    line history, with one 'invocation' structure per command
753  *    invocation.
754  *
755  *    The current plan is to have one of these per invocation.  I
756  *    suppose we could think about joining them into a single
757  *    header.
758  *
759  *    **********************************************************************
760  */
761 
762 #define SK_HENTRY_INVOCATION_ID 2
763 
764 /**
765  *    Append a single command line invocation to the header.
766  *
767  *    Add the invocation to 'hdr', where 'argc' and 'argv' are the
768  *    arguments to main().  If 'strip_path' is non-zero, the basename
769  *    of the first value in 'argv' is used.
770  */
771 int
772 skHeaderAddInvocation(
773     sk_file_header_t   *hdr,
774     int                 strip_path,
775     int                 argc,
776     char              **argv);
777 
778 /**
779  *    Return the invocation string from this header entry.  The caller
780  *    must treat the string as read-only.  Return NULL if header entry
781  *    is the wrong type.  Since SiLK 3.17.0.
782  */
783 const char *
784 skHentryInvocationGetInvocation(
785     const sk_header_entry_t    *hentry);
786 
787 
788 
789 /*
790  *    **********************************************************************
791  *
792  *    The 'annotation' header entry type is used to store a generic
793  *    comment or annotation about the file.
794  *
795  *    We should think about making the size of these larger, or have
796  *    them allocated in 256 or 512 chunks, so that minor modification
797  *    to the annotation can be done on a file without completely
798  *    rewriting it.
799  *
800  *    **********************************************************************
801  */
802 
803 #define SK_HENTRY_ANNOTATION_ID 3
804 
805 /**
806  *    Append a string as a new annotation header.
807  *
808  *    Create a new annotation header from the string 'annotation' and
809  *    append it to the file header 'hdr'.
810  */
811 int
812 skHeaderAddAnnotation(
813     sk_file_header_t   *hdr,
814     const char         *annotation);
815 
816 /**
817  *    Append a file's contents as a new annotation header.
818  *
819  *    Create a new annotation header from the contents of the file
820  *    'pathname' and append it to the file header 'hdr'.
821  */
822 int
823 skHeaderAddAnnotationFromFile(
824     sk_file_header_t   *hdr,
825     const char         *pathname);
826 
827 /**
828  *    Return the annotation string from this header entry.  The caller
829  *    must treat the string as read-only.  Return NULL if header entry
830  *    is the wrong type.  Since SiLK 3.17.0.
831  */
832 const char *
833 skHentryAnnotationGetNote(
834     const sk_header_entry_t    *hentry);
835 
836 
837 
838 /*
839  *    **********************************************************************
840  *
841  *    The 'probename' header entry type is used to store the name of
842  *    the probe where flow data was collected.
843  *
844  *    flowcap adds this header entry to the files it creates.  When
845  *    those files are processed by rwflowpack, it reads the probe name
846  *    from the header and then searches the sensor.conf file for the
847  *    sensor(s) that are able to pack data from that probe.
848  *
849  *    **********************************************************************
850  */
851 
852 #define SK_HENTRY_PROBENAME_ID  4
853 
854 /**
855  *    Add a header entry containing the name of the probe.
856  */
857 int
858 skHeaderAddProbename(
859     sk_file_header_t   *hdr,
860     const char         *probe_name);
861 
862 /**
863  *    Return the probe name from this header entry.  The caller must
864  *    treat the string as read-only.  Return NULL if header entry is
865  *    the wrong type.
866  */
867 const char *
868 skHentryProbenameGetProbeName(
869     const sk_header_entry_t    *hentry);
870 
871 
872 
873 /*
874  *    **********************************************************************
875  *
876  *    The 'prefixmap' header entry type is used to store information
877  *    particular to prefix maps (pmaps).
878  *
879  *    **********************************************************************
880  */
881 
882 #define SK_HENTRY_PREFIXMAP_ID  5
883 
884 
885 
886 /*
887  *    **********************************************************************
888  *
889  *    The 'bag' header entry type is used to store information
890  *    particular to binary Bag files.
891  *
892  *    **********************************************************************
893  */
894 
895 #define SK_HENTRY_BAG_ID        6
896 
897 
898 
899 /*
900  *    **********************************************************************
901  *
902  *    The 'ipset' header entry type is used to store information
903  *    particular to IPSets
904  *
905  *    **********************************************************************
906  */
907 
908 #define SK_HENTRY_IPSET_ID      7
909 
910 
911 
912 /*
913  *    **********************************************************************
914  *
915  *    The 'aggbag' header entry type is used to store information
916  *    particular to binary Aggregate Bag files.
917  *
918  *    **********************************************************************
919  */
920 
921 #define SK_HENTRY_AGGBAG_ID     8
922 
923 
924 
925 /*
926  *    **********************************************************************
927  *
928  *    The 'sidecar' header entry type is used to store information
929  *    about additional fields available for each record.
930  *
931  *    This is for SiLK 4 and appears here as a placeholder.
932  *
933  *    **********************************************************************
934  */
935 
936 #define SK_HENTRY_SIDECAR_ID    9
937 
938 
939 
940 /*
941  *    **********************************************************************
942  *
943  *    The 'tombstone' header entry type stores an identifier from the
944  *    YAF or super_mediator process that generated the record.
945  *
946  *    **********************************************************************
947  */
948 
949 #define SK_HENTRY_TOMBSTONE_ID  10
950 
951 /**
952  *    Append a new tombstone header.
953  *
954  *    Create a new tombstone header containing the identifier
955  *    'tombstone_count' and append it to 'hdr'.
956  */
957 int
958 skHeaderAddTombstone(
959     sk_file_header_t   *hdr,
960     uint32_t            tombstone_count);
961 
962 /**
963  *    Return the count value for this tombstone header.  Returns
964  *    UINT32_MAX if the header is the wrong version.
965  */
966 uint32_t
967 skHentryTombstoneGetCount(
968     const sk_header_entry_t    *hentry);
969 
970 
971 #ifndef SKHEADER_SOURCE
972 /* Define aliases required for consistency with previous releases of
973  * SiLK. */
974 
975 /**
976  *    Replace uses of sk_hentry_packedfile_t with sk_header_entry_t.
977  *    Deprecated since SiLK 3.17.0.
978  */
979 typedef sk_header_entry_t sk_hentry_packedfile_t    SK_GCC_DEPRECATED;
980 
981 /**
982  *    Replace uses of sk_hentry_invocation_t with sk_header_entry_t.
983  *    Deprecated since SiLK 3.17.0.
984  */
985 typedef sk_header_entry_t sk_hentry_probename_t     SK_GCC_DEPRECATED;
986 
987 #endif  /* SKHEADER_SOURCE */
988 
989 
990 #ifdef __cplusplus
991 }
992 #endif
993 #endif /* _SKHEADER_H */
994 
995 /*
996 ** Local Variables:
997 ** mode:c
998 ** indent-tabs-mode:nil
999 ** c-basic-offset:4
1000 ** End:
1001 */
1002