Cyrus::IndexFile(3p)

NAME
Cyrus::IndexFile - A pure perl interface to the "cyrus.index" file format as generated by Cyrus IMAPd.

EXAMPLES
 use Cyrus::IndexFile;

 # Note: requires IO::File::fcntl module installed for locking support
 my $index = Cyrus::IndexFile->new_file("$path/cyrus.index", ['lock_ex', 5]);

 print "EXISTS: " . $index->header('Exists') . "\n";
 while (my $record = $index->next_record_hash()) {
   print "$record->{Uid}: $record->{MessageGuid} $record->{Size}\n";
 }

SUPPORTED FORMAT VERSIONS
 Definitions:
 ============

 * int32 4 - 32 bit value taking 4 octets on disk.  Visible in perl as an integer
 * int64 8 - 64 bit value taking 8 octets on disk.  Visible in perl as an integer
 * time_t 4 - same as int32
 * time64 8 - same as int64
 * bitmap N - a bitmap taking up N octets on disk.  Visible in perl as a string of 1s and 0s.
 * hex N - a big value taking up N octets on disk.  Visible in perl as a hexadecimal string (0-9a-f)

 These values can be referenced by name using the hash API, or by index using the array API.
 You can also use the 'raw' API to get the record in on-disk format.

 All numbers are in network byte order as per Cyrus standard encoding.  Bitmap and hex values are
 layed out as octets on disk and encoded directly in order.

 Version 9:
 ==========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: Spare0                int32  4
 18: Spare1                int32  4
 19: Spare2                int32  4
 20: Spare3                int32  4
 21: Spare4                int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: ContentOffset         int32  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: ContentLines          int32  4
 11: CacheVersion          int32  4
 12: MessageUuid           hex    12
 13: Modseq                int64  8

 Version 10:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: Spare0                int32  4
 18: Spare1                int32  4
 19: Spare2                int32  4
 20: Spare3                int32  4
 21: Spare4                int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: ContentOffset         int32  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: ContentLines          int32  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8

SKIPPED VERSION 11 - Fastmail internal only

 Version 12:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Spare0                int32  4
 26: Spare1                int32  4
 27: Spare2                int32  4
 28: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: ContentLines          int32  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CacheCRC              int32  4
 15: RecordCRC             int32  4

 Version 13:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRCsBasic         int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: ContentLines          int32  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CacheCRC              int32  4
 16: RecordCRC             int32  4

 Version 14:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: Spare0                int32  4
 30: Spare1                int32  4
 31: Spare2                int32  4
 32: Spare3                int32  4
 33: Spare4                int32  4
 34: Spare5                int32  4
 34: Spare6                int32  4
 35: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: ContentLines          int32  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CacheCRC              int32  4
 16: RecordCRC             int32  4

 Version 15:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: Spare0                int32  4
 30: Spare1                int32  4
 31: Spare2                int32  4
 32: Spare3                int32  4
 33: Spare4                int32  4
 34: Spare5                int32  4
 34: Spare6                int32  4
 35: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: SaveDate              time_t  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CacheCRC              int32  4
 16: RecordCRC             int32  4

 Version 16:
 ===========

 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: CreatedModseq         int32  4
 30: Spare0                int32  4
 31: Spare1                int32  4
 32: Spare2                int32  4
 33: Spare3                int32  4
 34: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: SaveDate              time_t  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CreatedModseq         int64  8
 16: CacheCRC              int32  4
 17: RecordCRC             int32  4

 Version 17:
 ===========
 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: CreatedModseq         int64  8
 30: ChangesEpoch          int32  4
 31: Spare1                int32  4
 32: Spare2                int32  4
 33: Spare3                int32  4
 34: Spare3                int32  4
 35: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: SaveDate              time_t  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CreatedModseq         int64  8
 16: CacheCRC              int32  4
 17: RecordCRC             int32  4

 Version 18:
 ===========
 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Options               bitmap 4
 15: LeakedCache           int32  4
 16: HighestModseq         int64  8
 17: DeletedModseq         int64  8
 18: Exists                int32  4
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: CreatedModseq         int64  8
 30: ChangesEpoch          int32  4
 31: QuotaDeletedUsed      int64  8
 32: QuotaExpungedUsed     int64  8
 33: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: SaveDate              time_t  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CreatedModseq         int64  8
 16: CacheCRC              int32  4
 17: RecordCRC             int32  4

 Version 19:
 ===========
 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 4
  7: LastUid               int32  4
  8: QuotaUsed             int64  8
  9: Pop3LastLogin         time_t 4
 10: UidValidity           int32  4
 11: Deleted               int32  4
 12: Answered              int32  4
 13: Flagged               int32  4
 14: Exists                int32  4
 15: Options               bitmap 4
 16: LeakedCache           int32  4
 17: HighestModseq         int64  8
 18: DeletedModseq         int64  8
 19: FirstExpunged         time_t 4
 20: LastCleanup           time_t 4
 21: HeaderFileCRC         int32  4
 22: SyncCRC               int32  4
 23: RecentUid             int32  4
 24: RecentTime            time_t 4
 25: Pop3ShowAfter         int32  4
 26: QuotaAnnotUsed        int32  4
 27: SyncCRCsAnnot         int32  4
 28: Unseen                int32  4
 29: CreatedModseq         int64  8
 30: QuotaDeletedUsed      int64  8
 31: QuotaExpungedUsed     int64  8
 32: ChangesEpoch          int32  4
 33: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: InternalDate          time_t 4
  2: SentDate              time_t 4
  3: Size                  int32  4
  4: HeaderSize            int32  4
  5: GmTime                time_t  4
  6: CacheOffset           int32  4
  7: LastUpdated           time_t 4
  8: SystemFlags           bitmap 4
  9: UserFlags             bitmap 16
 10: SaveDate              time_t  4
 11: CacheVersion          int32  4
 12: MessageGuid           hex    20
 13: Modseq                int64  8
 14: CID                   hex    8
 15: CreatedModseq         int64  8
 16: CacheCRC              int32  4
 17: RecordCRC             int32  4

 Version 20:
 ===========
 Header:
  0: Generation            int32  4
  1: Format                int32  4
  2: MinorVersion          int32  4
  3: StartOffset           int32  4
  4: RecordSize            int32  4
  5: Exists                int32  4
  6: LastAppenddate        time_t 8
  7: QuotaUsed             int64  8
  8: Pop3LastLogin         time_t 8
  9: Deleted               int32  4
 10: Answered              int32  4
 11: Flagged               int32  4
 12: Exists                int32  4
 13: Options               bitmap 4
 14: LeakedCache           int32  4
 15: HighestModseq         int64  8
 16: DeletedModseq         int64  8
 17: LastUid               int32  4
 18: UidValidity           int32  4
 19: HeaderFileCRC         int32  4
 20: SyncCRC               int32  4
 21: RecentTime            time_t 8
 22: Pop3ShowAfter         time_t 8
 23: SyncCRCsAnnot         int32  4
 24: Unseen                int32  4
 25: CreatedModseq         int64  8
 26: QuotaDeletedUsed      int64  8
 27: QuotaExpungedUsed     int64  8
 28: QuotaAnnotUsed        int64  8
 29: ChangesEpoch          time_t 8
 30: FirstExpunged         time_t 8
 31: LastCleanup           time_t 8
 32: RecentUid             int32  4
 33: HeaderCRC             int32  4

 Record:
  0: Uid                   int32  4
  1: CacheOffset           int32  4
  2: InternalDate          time_t 8
  3: SentDate              time_t 8
  4: Size                  int64  8
  5: HeaderSize            int32  4
  6: SystemFlags           bitmap 4
  7: UserFlags             bitmap 16
  8: CacheVersion          int32  4
  9: MessageGuid           hex    20
 10: Modseq                int64  8
 11: CID                   hex    8
 12: CreatedModseq         int64  8
 13: GmTime                time_t 8
 14: LastUpdated           time_t 8
 15: SaveDate              time_t 8
 11: BaseCID               hex    8
 16: CacheCRC              int32  4
 17: RecordCRC             int32  4

PUBLIC API

Cyrus::IndexFile->new($fh)
    Build a new Cyrus::IndexFile object from a filehandle. The handle is not required to be seekable, so make sure you have rewound it before use.

     seek($fh, 0, 0);
     my $index = Cyrus::IndexFile->new($fh);

    This function reads the header from the file and returns a Cyrus::IndexFile object. The filehandle will be pointing at the start of the first record.

    If there is a problem, then the position of the filehandle is undefined (though probably either at 12 bytes or the end of the header) and the function will "die".

    Causes of death:

     * unable to read a full header's length of data from the file
     * version of the file is not one of the supported versions

Cyrus::IndexFile->new_file($filename, $lockopts)
    Open the file to read, optionally locking it with IO::File::fcntl. If you pass a scalar for lockopts then it will be locked with ['lock_ex'], otherwise you can pass a tuple, e.g. ['lock_ex', 5] for a 5 second timeout.

    This function will die if it can't open or lock the file. On success, it calls $class->new() with the filehandle.

Cyrus::IndexFile->new_empty($version)
    Create a new empty index file with the specified version. This is useful when you want to generate a new index file, as you can use the write_record function and set header fields on the new object.

$index->stream_copy($outfh, $decider, %Opts)
    Currently broken! Supposed to copy this file into the output filehandle.

    NOTE: outfh must be seekable, as we write an initial header record with Exists == 0, then update the header at the end with a new Exists and a new LastUpdated.

$index->header()
$index->header_hash()
    Returns a hash reference of the entire header

$index->header($field)
    Returns just the single named field from the header. Dies if there is no field with that name in the header.

$index->header_array($field)
    Returns an array reference with the values in the order given in the version information above.

$index->header_raw()
    Returns the raw packed header as it is on disk.

$index->header_copy()
    Returns a hashref the same as header_hash, but it's "non live", so you can make destructive changes without affecting the original.

$index->reset($num)
    Deletes the cached 'current record' and seeks back to the given record number, or the end of the header (record 0) if no number given.

    Requires the input filehandle to be seekable.

$index->next_record() =item $index->next_record_hash()
    Read the next record from the file and parse it in to a hash reference per the format of the index file.

    This works even on non-seekable files.

    Returns undef when there are no more records (until you call reset)

$index->next_record_array()
    As above, but returns the array in the format order.

    More efficient, as the hash doesn't need to be created.

$index->next_record_raw()
    Returns the raw bytes of the index file. Most efficient, as no unpacking is done, but then you have to deal with all the version checking and offsets yourself.

$index->record() =item $index->record_hash()
    Returns the "current" record, i.e. the last record returned by next_record_*() as a hash reference.

    Returns undef if there is no current record (either next_record has never been called, reset has just been called, or the file is finished)

$index->record_array()
    As above, but return the version-dependant arrayref or undef

$index->record_raw()
    As above, but return just the raw record bytes as a string or undef

$index->record($field)
    If a field name is given, return that field only from the record, or die if it doesn't exist in this version.

    Returns undef if there is no current record. No legitimate field ever returns undef, because there's no such concept in the datastructure.

$index->field_number($Field)
    Return the field number in a record array for the named field, or die if there isn't one.

$index->write_header($fh, $header)
    Writes a header to $fh - you need to make sure it's seeked to the start (can be used on a non-seekable filehandle)

    $header can be in array, hash or buffer format

$index->append_record($record)
    Appends the record (can be hash, array or buf) to the current file. Needs the filehandle to be seekable. Uses "Exists" from the header to find the position, so don't mess it up!

    Also seeks back to the header and rewrites it with exists incremented by one.

$index->rewrite_record($record, $num)
    Rewrite the record at position given by $num with the record (hash, array or buf) passed.

$index->write_record($fh, $record, $num)
    Write the record to the new filehandle $fh. If $num is not given then it doesn't need to be seekable.

    XXX - $num support not done yet

$index->merge_indexes($target, @extras)
    XXX - broken anyway. The purpose of this function is to allow multiple index files to combined into one (say, an expunged file and an index file)

$index->header_dump()
$index->record_dump()
$index->header_longdump()
$index->record_longdump()
$index->header_undump()
$index->record_undump()
    Dump the headers and records in either space separated fields or named lines with a blank line between for long.

    The "undump" option is able to parse the space separated format, allowing pipe to a standard unix tool to process the records, and then re-parse them back into a binary index file.

Cyrus::IndexFile->latest_version()
$index->latest_version()
    Returns the latest (highest) version supported by Cyrus::IndexFile

$index->header_offset_for($field)
    Return the byte offset for $field in the header at the version of this index file.

$index->record_offset_for($field)
    Return the byte offset for $field in the record at the version of this index file.

$index->tv_sec($time)
    Return the seconds portion of a time_t or time64 field. (Prior to version 20 all time fields were time_t and only had seconds).

    Must only be called on an instantiated object because the mailbox version is required to know the size of time fields.

$index->tv_nsec($ns)
    Return the nanoseconds portion of a time64 field, or 0 for time_t fields. (Prior to version 20 all time fields were time_t and only had seconds).

    Must only be called on an instantiated object because the mailbox version is required to know the size of time fields.