Initial revision

diff --git a/doc/magic.man b/doc/magic.man
new file mode 100644 (file)
index 0000000..c142d29
--- /dev/null
+++ b/doc/magic.man
@@ -0,0 +1,148 @@
+.\" From: guy@sun.uucp (Guy Harris)
+.\" Newsgroups: net.bugs.usg
+.\" Subject: /etc/magic's format isn't well documented
+.\" Message-ID: <2752@sun.uucp>
+.\" Date: 3 Sep 85 08:19:07 GMT
+.\" Date-Received: 4 Sep 85 18:11:43 GMT
+.\" Distribution: net
+.\" Organization: Sun Microsystems, Inc.
+.\" Lines: 136
+.\" 
+.\" Here's a manual page for the format accepted by the "file" made by adding
+.\" the changes I posted to the S5R2 version.
+.\"
+.de TH
+.PD
+.nr IN \\n()Mu
+.if t .ds ]H \\$1\^(\^\\$2\^)
+.if n .ds ]H \\$1(\\$2)
+.if \\n()s .ds ]D
+.if \\n()t .ds ]D UNIX System V
+.if n .ds ]D UNIX System V
+.ds ]L
+.if !\\$3 .ds ]L (\^\\$3\^)
+.if !\\$4 .ds ]D \\$4
+.wh 0 }H
+.wh -\\n(:mu }F
+.em }M
+.if \\n(nl .bp
+.nr )I \\n()Mu
+.nr )R 0
+.}E
+.DT
+.if n \{.na
+.nh \}
+.if t \{.bd S 3 3
+.hy 14 \}
+..
+.TH MAGIC 4
+.SH NAME
+magic \- file command's magic number file
+.SH DESCRIPTION
+The
+.IR file (1)
+command identifies the type of a file using,
+among other tests,
+a test for whether the file begins with a certain
+.IR "magic number" .
+The file
+.B /etc/magic
+specifies what magic numbers are to be tested for,
+what message to print if a particular magic number is found,
+and additional information to extract from the file.
+.PP
+Each line of the file specifies a test to be performed.
+A test compares the data starting at a particular offset
+in the file with a 1-byte, 2-byte, or 4-byte numeric value or
+a string.  If the test succeeds, a message is printed.
+The line consists of the following fields:
+.IP offset \w'message'u+2n
+A number specifying the offset, in bytes, into the file of the data
+which is to be tested.
+.IP type
+The type of the data to be tested.  The possible values are:
+.RS
+.IP byte \w'message'u+2n
+A one-byte value.
+.IP short
+A two-byte value.
+.IP long
+A four-byte value.
+.IP string
+A string of bytes.
+.RE
+.IP
+The types
+.BR byte ,
+.BR short ,
+and
+.B long
+may optionally be followed by a mask specifier of the form
+.BI & number\fR.
+If a mask specifier is given, the value is AND'ed with the
+.I number
+before any comparisons are done.  The
+.I number
+is specified in C form; e.g.
+.B 13
+is decimal,
+.B 013
+is octal, and
+.B 0x13
+is hexadecimal.
+.IP test
+The value to be compared with the value from the file.  If the type is
+numeric, this value
+is specified in C form; if it is a string, it is specified as a C string
+with the usual escapes permitted (e.g. \en for new-line).
+.IP
+Numeric values
+may be preceded by a character indicating the operation to be performed.
+It may be
+.BR = ,
+to specify that the value from the file must equal the specified value,
+.BR < ,
+to specify that the value from the file must be less than the specified
+value,
+.BR > ,
+to specify that the value from the file must be greater than the specified
+value,
+or
+.B x
+to specify that any value will match.  If the character
+is omitted, it is assumed to be
+.BR = .
+.IP
+For string values, the byte string from the
+file must match the specified byte string; the byte string from the file
+which is matched is the same length as the specified byte string.
+.IP message
+The message to be printed if the comparison succeeds.  If the string
+contains a
+.IR printf (3S)
+format specification, the value from the file (with any specified masking
+performed) is printed using the message as the format string.
+.PP
+Some file formats contain additional information which is to be printed
+along with the file type.  A line which begins with the character
+.B >
+indicates additional tests and messages to be printed.  If the test on the
+line preceding the first line with a
+.B >
+succeeds, the tests specified in all the subsequent lines beginning with
+.B >
+are performed, and the messages printed if the tests succeed.  The next
+line which does not begin with a
+.B >
+terminates this.
+.SH BUGS
+There should be more than one level of subtests, with the level indicated by
+the number of
+.B >
+at the beginning of the line.
+.SH SEE ALSO
+file(1) in the
+\f2\s-1UNIX\s+1 System User Reference Manual\fR.
+.\"    %W% of %G%
+
+