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