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