ching - the Book of Changes


ching [-n] [-r] [-h] [-p program] [hexagram-lines]


The I Ching or Book of Changes is an ancient Chinese oracle that has been in use for centuries as a source of wisdom and advice.

The text of the oracle (as it is sometimes known) consists of sixty-four hexagrams, each symbolized by a particular arrangement of six straight (---) and broken (- -) lines.

Each hexagram consists of two major sections. The Judgement relates specifically to the matter at hand (For instance, "It furthers one to have somewhere to go.") while the Image describes the general attributes of the hexagram and how they apply to one's own life ("Thus the superior man makes himself strong and untiring.").

The Lines

The lines are associated with numeric values ranging from six through nine. The even values (6 and 8) indicate broken lines, while the odd values (7 and 9) indicate solid lines.

When the value is six or nine, the line is said to be moving; for any such line there is an appended judgement which becomes significant. Furthermore, the moving lines are inherently unstable and change into their opposites; a second hexagram (and thus an additional judgement) is formed.

The numeric value of a hexagram is constructed by listing the digits corresponding to each of the lines, going from the bottom upward.

Consulting the Oracle

Normally, one consults the oracle by fixing the desired question firmly in mind and then casting a set of changes (lines) using yarrow-stalks or tossed coins. The resulting hexagram will be the answer to the question.

This oracle simply reads a question from the standard input (up to an EOF, or a period on a line by itself) and hashes the individual characters in combination with the time of day, process ID and the user's user and group IDs. The resulting value is used as the seed of a random number generator which drives a simulated coin-toss divination. The answer is then formatted and written to the standard output.


The -n option will cause *ROFF commands to be piped through nroff(1) for output formatting, as they were in original BSD implementation. By default, the formatting is done by the ching program itself.

The -r option will cause *ROFF formatting commands to be sent to the standard output. You probably won't find this very useful unless you're debugging the -n switch.

The -p option specifies the command to use to display the output. The default is the value of the environment variable CHING_PAGER, or of PAGER, or none if neither environment variable is set.

For those who wish to remain steadfast in the old traditions, the oracle will also accept the results of a personal divination using yarrow sticks or coins. To do this, cast the change and then type the resulting line values as an argument.

Conversely, the -h option can be used to display the line values from a divination cast by the computer.


The Perl code is copyright (c) 1995, 1999 Albert Dvornik <>.

The hexagram text and ROFF macros are Copyright (c) 1988 The Regents of the University of California. All rights reserved. This product includes software developed by the University of California, Berkeley and its contributors.

In the original BSD version, the macros and the hexagram text resided in separate files from the program source, and neither of these files contained a copyright notice. I'm working under the assumption that they were intended to be covered by the same copyright as the program source, which is the copyright displayed above. If you have reason to believe otherwise, please let me know.

Also, please drop me a line if you know of a freely available I Ching text that's not encumbered by the Obnoxious BSD Advertising Clause.


  It furthers one to see the great man.


  Thus the superior man at nightfall
  Goes indoors for rest and recuperation.


The program does not support simulated tossing of yarrow stalks as a way of consulting the oracle.