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