===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/file/magic.5,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- src/usr.bin/file/magic.5	1997/02/09 23:58:28	1.3
+++ src/usr.bin/file/magic.5	2000/03/06 02:38:19	1.4
@@ -1,196 +1,238 @@
-.\" $OpenBSD: magic.5,v 1.3 1997/02/09 23:58:28 millert Exp $
+.\" $OpenBSD: magic.5,v 1.4 2000/03/06 02:38:19 aaron Exp $
+.\"
+.\" @(#)$FreeBSD: src/usr.bin/file/magic.5,v 1.11 2000/03/01 12:19:39 sheldonh Exp $
+.\"
 .\" install as magic.4 on USG, magic.5 on V7 or Berkeley systems.
-.TH MAGIC 5 "Public Domain"
-.SH NAME
-magic \- file command's magic number file
-.SH DESCRIPTION
+.\"
+.Dd September 3, 1994
+.Dt MAGIC 5
+.Os
+.Sh NAME
+.Nm magic
+.Nd file command's magic number file
+.Sh DESCRIPTION
 This manual page documents the format of the magic file as
 used by the
-.BR file (1)
+.Xr file 1
 command, version 3.22. The
-.B file
+.Nm file
 command identifies the type of a file using,
 among other tests,
 a test for whether the file begins with a certain
-.IR "magic number" .
+.Dq magic number .
+.Pp
 The file
-.I /etc/magic
+.Pa /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
+.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.
+a string.
+If the test succeeds, a message is printed.
 The line consists of the following fields:
-.IP offset \w'message'u+2n
+.Bl -tag -width indent
+.It Sy offset
 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
+.It Sy type
+The type of the data to be tested.
+The possible values are:
+.Bl -tag -width beshort
+.It Sy byte
 A one-byte value.
-.IP short
+.It Sy short
 A two-byte value (on most systems) in this machine's native byte order.
-.IP long
+.It Sy long
 A four-byte value (on most systems) in this machine's native byte order.
-.IP string
+.It Sy string
 A string of bytes.
-.IP date
-A four-byte value interpreted as a unix date.
-.IP beshort
+.It Sy date
+A four-byte value interpreted as a
+.Ux
+date.
+.It Sy beshort
 A two-byte value (on most systems) in big-endian byte order.
-.IP belong
+.It Sy belong
 A four-byte value (on most systems) in big-endian byte order.
-.IP bedate
+.It Sy bedate
 A four-byte value (on most systems) in big-endian byte order,
-interpreted as a unix date.
-.IP leshort
+interpreted as a
+.Ux
+date.
+.It Sy leshort
 A two-byte value (on most systems) in little-endian byte order.
-.IP lelong
+.It Sy lelong
 A four-byte value (on most systems) in little-endian byte order.
-.IP ledate
+.It Sy ledate
 A four-byte value (on most systems) in little-endian byte order,
-interpreted as a unix date.
-.RE
-.PP
+interpreted as a
+.Ux
+date.
+.El
+.El
+.Pp
 The numeric types may optionally be followed by
-.B &
+.Ql &
 and a numeric value,
 to specify that the value is to be AND'ed with the
-numeric value before any comparisons are done.  Prepending a
-.B u
+numeric value before any comparisons are done.
+Prepending a
+.Sq u
 to the type indicates that ordered comparisons should be unsigned.
-.IP test
-The value to be compared with the value from the file.  If the type is
+.Bl -tag -width indent
+.It Sy 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
+with the usual escapes permitted (e.g.,
+.Ql \en
+for newline).
+.It Sy ""
 Numeric values
 may be preceded by a character indicating the operation to be performed.
 It may be
-.BR = ,
+.Ql =
 to specify that the value from the file must equal the specified value,
-.BR < ,
+.Ql <
 to specify that the value from the file must be less than the specified
 value,
-.BR > ,
+.Ql >
 to specify that the value from the file must be greater than the specified
 value,
-.BR & ,
+.Ql &
 to specify that the value from the file must have set all of the bits 
 that are set in the specified value,
-.BR ^ ,
+.Ql ^
 to specify that the value from the file must have clear any of the bits 
 that are set in the specified value, or
-.BR x ,
-to specify that any value will match. If the character is omitted,
+.Sq x
+to specify that any value will match.
+If the character is omitted,
 it is assumed to be
-.BR = .
-.IP
-Numeric values are specified in C form; e.g.
-.B 13
+.Ql = .
+.It Sy ""
+Numeric values are specified in C form; e.g.,
+.Dq 13
 is decimal,
-.B 013
+.Dq 013
 is octal, and
-.B 0x13
+.Dq 0x13
 is hexadecimal.
-.IP
+.It Sy ""
 For string values, the byte string from the
 file must match the specified byte string. 
 The operators
-.BR = ,
-.B <
+.Ql = ,
+.Ql < ,
 and
-.B >
+.Ql >
 (but not
-.BR & )
+.Ql & )
 can be applied to strings.
 The length used for matching is that of the string argument
-in the magic file.  This means that a line can match any string, and
+in the magic file.
+This means that a line can match any string, and
 then presumably print that string, by doing
-.B >\e0
+.Ql >\e0
 (because all strings are greater than the null string).
-.IP message
-The message to be printed if the comparison succeeds.  If the string
+.It Sy message
+The message to be printed if the comparison succeeds.
+If the string
 contains a
-.BR printf (3S)
+.Xr printf 3
 format specification, the value from the file (with any specified masking
 performed) is printed using the message as the format string.
-.PP
+.El
+.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.  The number of
-.B >
+along with the file type.
+A line which begins with the character
+.Ql >
+indicates additional tests and messages to be printed.
+The number of
+.Ql >
 on the line indicates the level of the test; a line with no
-.B >
+.Ql >
 at the beginning is considered to be at level 0.
+.Pp
 Each line at level
-.IB n \(pl1
+.Em n+1
 is under the control of the line at level
-.IB n
+.Em n
 most closely preceding it in the magic file.
 If the test on a line at level
-.I n
+.Em n
 succeeds, the tests specified in all the subsequent lines at level
-.IB n \(pl1
-are performed, and the messages printed if the tests succeed.  The next
+.Em n+1
+are performed, and the messages printed if the tests succeed.
+The next
 line at level
-.I n
+.Em n
 terminates this.
+.Pp
 If the first character following the last
-.B >
+.Ql >
 is a
-.B (
+.Ql (
 then the string after the parenthesis is interpreted as an indirect offset.
 That means that the number after the parenthesis is used as an offset in
-the file. The value at that offset is read, and is used again as an offset
-in the file. Indirect offsets are of the form:
-.BI (( x [.[bsl]][+-][ y ]).
+the file.
+The value at that offset is read, and is used again as an offset
+in the file.
+.Pp
+Indirect offsets are of the form:
+.Dq (x[.[bsl]][+-][y]) .
 The value of 
-.I x
-is used as an offset in the file. A byte, short or long is read at that offset
+.Sq x
+is used as an offset in the file.
+A byte, short or long is read at that offset
 depending on the 
-.B [bsl] 
-type specifier. To that number the value of
-.I y
-is added and the result is used as an offset in the file. The default type
+.Dq [bsl]
+type specifier.
+To that number the value of
+.Sq y
+is added and the result is used as an offset in the file.
+The default type
 if one is not specified is long.
-.PP
+.Pp
 Sometimes you do not know the exact offset as this depends on the length of
-preceding fields. You can specify an offset relative to the end of the
-last uplevel field (of course this may only be done for sublevel tests, i.e.
+preceding fields.
+You can specify an offset relative to the end of the
+last uplevel field (of course this may only be done for sublevel tests, i.e.,
 test beginning with 
-.B >
-). Such a relative offset is specified using
-.B &
+.Ql > ) .
+Such a relative offset is specified using
+.Ql &
 as a prefix to the offset.
-.SH BUGS
+.Sh BUGS
 The formats 
-.IR long ,
-.IR belong ,
-.IR lelong ,
-.IR short ,
-.IR beshort ,
-.IR leshort ,
-.IR date ,
-.IR bedate ,
+.Li long ,
+.Li belong ,
+.Li lelong ,
+.Li short ,
+.Li beshort ,
+.Li leshort ,
+.Li date ,
+.Li bedate ,
 and
-.I ledate
+.Li ledate
 are system-dependent; perhaps they should be specified as a number
 of bytes (2B, 4B, etc), 
 since the files being recognized typically come from
 a system on which the lengths are invariant.
-.PP
+.Pp
 There is (currently) no support for specified-endian data to be used in
 indirect offsets.
-.SH SEE ALSO
-.BR file (1)
-\- the command that reads this file.
+.Sh FILES
+.Bl -tag -width /etc/magic
+.It Pa /etc/magic
+.El
+.Sh SEE ALSO
+.Xr file 1
 .\"
 .\" From: guy@sun.uucp (Guy Harris)
 .\" Newsgroups: net.bugs.usg