Annotation of src/usr.bin/file/magic.5, Revision 1.3
1.3 ! millert 1: .\" $OpenBSD: magic.5,v 1.2 1996/06/26 05:32:59 deraadt Exp $
! 2: .\" install as magic.4 on USG, magic.5 on V7 or Berkeley systems.
1.1 deraadt 3: .TH MAGIC 5 "Public Domain"
4: .SH NAME
5: magic \- file command's magic number file
6: .SH DESCRIPTION
1.3 ! millert 7: This manual page documents the format of the magic file as
! 8: used by the
! 9: .BR file (1)
! 10: command, version 3.22. The
! 11: .B file
1.1 deraadt 12: command identifies the type of a file using,
13: among other tests,
14: a test for whether the file begins with a certain
15: .IR "magic number" .
16: The file
1.3 ! millert 17: .I /etc/magic
1.1 deraadt 18: specifies what magic numbers are to be tested for,
19: what message to print if a particular magic number is found,
20: and additional information to extract from the file.
21: .PP
22: Each line of the file specifies a test to be performed.
23: A test compares the data starting at a particular offset
24: in the file with a 1-byte, 2-byte, or 4-byte numeric value or
25: a string. If the test succeeds, a message is printed.
26: The line consists of the following fields:
27: .IP offset \w'message'u+2n
28: A number specifying the offset, in bytes, into the file of the data
29: which is to be tested.
30: .IP type
31: The type of the data to be tested. The possible values are:
32: .RS
33: .IP byte \w'message'u+2n
34: A one-byte value.
35: .IP short
36: A two-byte value (on most systems) in this machine's native byte order.
37: .IP long
38: A four-byte value (on most systems) in this machine's native byte order.
39: .IP string
40: A string of bytes.
41: .IP date
42: A four-byte value interpreted as a unix date.
43: .IP beshort
44: A two-byte value (on most systems) in big-endian byte order.
45: .IP belong
46: A four-byte value (on most systems) in big-endian byte order.
47: .IP bedate
48: A four-byte value (on most systems) in big-endian byte order,
49: interpreted as a unix date.
50: .IP leshort
51: A two-byte value (on most systems) in little-endian byte order.
52: .IP lelong
53: A four-byte value (on most systems) in little-endian byte order.
54: .IP ledate
55: A four-byte value (on most systems) in little-endian byte order,
56: interpreted as a unix date.
57: .RE
58: .PP
59: The numeric types may optionally be followed by
60: .B &
61: and a numeric value,
62: to specify that the value is to be AND'ed with the
63: numeric value before any comparisons are done. Prepending a
64: .B u
65: to the type indicates that ordered comparisons should be unsigned.
66: .IP test
67: The value to be compared with the value from the file. If the type is
68: numeric, this value
69: is specified in C form; if it is a string, it is specified as a C string
70: with the usual escapes permitted (e.g. \en for new-line).
71: .IP
72: Numeric values
73: may be preceded by a character indicating the operation to be performed.
74: It may be
75: .BR = ,
76: to specify that the value from the file must equal the specified value,
77: .BR < ,
78: to specify that the value from the file must be less than the specified
79: value,
80: .BR > ,
81: to specify that the value from the file must be greater than the specified
82: value,
83: .BR & ,
84: to specify that the value from the file must have set all of the bits
85: that are set in the specified value,
86: .BR ^ ,
87: to specify that the value from the file must have clear any of the bits
88: that are set in the specified value, or
89: .BR x ,
90: to specify that any value will match. If the character is omitted,
91: it is assumed to be
92: .BR = .
93: .IP
94: Numeric values are specified in C form; e.g.
95: .B 13
96: is decimal,
97: .B 013
98: is octal, and
99: .B 0x13
100: is hexadecimal.
101: .IP
102: For string values, the byte string from the
103: file must match the specified byte string.
104: The operators
105: .BR = ,
106: .B <
107: and
108: .B >
109: (but not
110: .BR & )
111: can be applied to strings.
112: The length used for matching is that of the string argument
113: in the magic file. This means that a line can match any string, and
114: then presumably print that string, by doing
115: .B >\e0
116: (because all strings are greater than the null string).
117: .IP message
118: The message to be printed if the comparison succeeds. If the string
119: contains a
1.3 ! millert 120: .BR printf (3S)
1.1 deraadt 121: format specification, the value from the file (with any specified masking
122: performed) is printed using the message as the format string.
123: .PP
124: Some file formats contain additional information which is to be printed
125: along with the file type. A line which begins with the character
126: .B >
127: indicates additional tests and messages to be printed. The number of
128: .B >
129: on the line indicates the level of the test; a line with no
130: .B >
131: at the beginning is considered to be at level 0.
132: Each line at level
133: .IB n \(pl1
134: is under the control of the line at level
135: .IB n
136: most closely preceding it in the magic file.
137: If the test on a line at level
138: .I n
139: succeeds, the tests specified in all the subsequent lines at level
140: .IB n \(pl1
141: are performed, and the messages printed if the tests succeed. The next
142: line at level
143: .I n
144: terminates this.
145: If the first character following the last
146: .B >
147: is a
148: .B (
149: then the string after the parenthesis is interpreted as an indirect offset.
150: That means that the number after the parenthesis is used as an offset in
151: the file. The value at that offset is read, and is used again as an offset
152: in the file. Indirect offsets are of the form:
153: .BI (( x [.[bsl]][+-][ y ]).
154: The value of
155: .I x
156: is used as an offset in the file. A byte, short or long is read at that offset
157: depending on the
158: .B [bsl]
159: type specifier. To that number the value of
160: .I y
161: is added and the result is used as an offset in the file. The default type
162: if one is not specified is long.
1.3 ! millert 163: .PP
! 164: Sometimes you do not know the exact offset as this depends on the length of
! 165: preceding fields. You can specify an offset relative to the end of the
! 166: last uplevel field (of course this may only be done for sublevel tests, i.e.
! 167: test beginning with
! 168: .B >
! 169: ). Such a relative offset is specified using
! 170: .B &
! 171: as a prefix to the offset.
1.1 deraadt 172: .SH BUGS
173: The formats
174: .IR long ,
175: .IR belong ,
176: .IR lelong ,
177: .IR short ,
178: .IR beshort ,
179: .IR leshort ,
180: .IR date ,
181: .IR bedate ,
182: and
183: .I ledate
184: are system-dependent; perhaps they should be specified as a number
185: of bytes (2B, 4B, etc),
186: since the files being recognized typically come from
187: a system on which the lengths are invariant.
188: .PP
189: There is (currently) no support for specified-endian data to be used in
190: indirect offsets.
191: .SH SEE ALSO
1.3 ! millert 192: .BR file (1)
1.1 deraadt 193: \- the command that reads this file.
194: .\"
195: .\" From: guy@sun.uucp (Guy Harris)
196: .\" Newsgroups: net.bugs.usg
197: .\" Subject: /etc/magic's format isn't well documented
198: .\" Message-ID: <2752@sun.uucp>
199: .\" Date: 3 Sep 85 08:19:07 GMT
200: .\" Organization: Sun Microsystems, Inc.
201: .\" Lines: 136
202: .\"
203: .\" Here's a manual page for the format accepted by the "file" made by adding
204: .\" the changes I posted to the S5R2 version.
205: .\"
206: .\" Modified for Ian Darwin's version of the file command.