Omikuji File Formats

Omikuji is a replacement for the venerable fortune command and strfile. Omikuji consists of two programs: omikuji and omifile. Omikuji works like the fortune program. It reads an omikuji file and outputs a “fortune” to the screen. Omifile is used to parse a delimited text file and output a properly formatted omikuji input file. This file describes the file formats used by omikuji and omifile.

Fortune Input File

The fortune file format is fairly well documented elsewhere. It consists of a series of text entries separated by lines containing one or two delimiter characters. Single line comment entries traditionally begin with two delimiters, generally followed by a space character. Omifile, however, assumes that any line beginning with one or two delimiters is to be treated specially. If the delimiters are followed by a horizontal space character or text other than a line break sequence, then omifile processes the remainder of the line as a comment. If the delimiter is followed immediately by a line break sequence, then omifile processes the text up to the next delimiter sequence as a fortune entry.

When parsing these files, omifile assumes that the first entry is preceded by a delimiter and that the last record is followed by one. That is, if an opening delimiter is missing from the file, then the first entry will be skipped by omifile. Likewise, if the file does not end with a delimiter line, then the last entry will be skipped. Thus, omifile expects fortune files to be well-formed.

Traditionally, the percent sign (%) is used as the delimiter. However, any character may be used provided that it is representable in the file's character encoding and does not appear at the beginning of a line other than when serving as a delimiter. Typically, one would limit this to any of the punctuation or symbol characters.

Omikuji File, Version 0

The omikuji file consists of a 24-byte header followed by two, multidimensional index tables and the text of the comment and fortune entries. The comment and fortune entries all run one after the other with no delineation.


Data Type


Filetype indicator

7 byte string

Literal string “omikuji” in lower case.


1 binary byte

0 to 255 to indicate version of the omikuji file. Version for this release is 0

Comment table offset

4 byte unsigned integer

Offset of the comment header table from the start of the file. Set to 0 if no comment entries exist.

Comment count

4 byte unsigned integer

Count of comment entries. 0 if no comments.

Fortune table offset

4 byte unsigned integer

Offset of the fortune header table from the start of the file.

Fortune count

4 byte unsigned integer

Count of fortune entries.

Omifile Version 0 Header Layout

The comment and fortune index tables have the same layout. There will be one, two field entry in either file for each type of entry:


Data Type



4 byte unsigned integer

Offset to the entry from the start of the file.


4 byte unsigned integer

Length of the entry in bytes.

Comment and Fortune Table Layout

All binary fields are to be stored in big-endian byte order. The content of all comment and fortune fields are to be stored in UTF-8.