Annotation of src/usr.bin/file/magic.5, Revision 1.10
1.10 ! deraadt 1: .\" $OpenBSD: magic.5,v 1.9 2003/06/10 09:12:10 jmc 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.7 jmc 6: .\"
1.8 ian 7: .\" Copyright (c) Ian F. Darwin 1986-1995.
8: .\" Software written by Ian F. Darwin and others;
9: .\" maintained 1995-present by Christos Zoulas and others.
1.9 jmc 10: .\"
1.8 ian 11: .\" Redistribution and use in source and binary forms, with or without
12: .\" modification, are permitted provided that the following conditions
13: .\" are met:
14: .\" 1. Redistributions of source code must retain the above copyright
15: .\" notice immediately at the beginning of the file, without modification,
16: .\" this list of conditions, and the following disclaimer.
17: .\" 2. Redistributions in binary form must reproduce the above copyright
18: .\" notice, this list of conditions and the following disclaimer in the
19: .\" documentation and/or other materials provided with the distribution.
1.9 jmc 20: .\"
1.8 ian 21: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
22: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
25: .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31: .\" SUCH DAMAGE.
1.4 aaron 32: .\"
33: .Dd September 3, 1994
34: .Dt MAGIC 5
35: .Os
36: .Sh NAME
37: .Nm magic
38: .Nd file command's magic number file
39: .Sh DESCRIPTION
1.3 millert 40: This manual page documents the format of the magic file as
41: used by the
1.4 aaron 42: .Xr file 1
1.5 aaron 43: command, version 3.22.
44: The
1.4 aaron 45: .Nm file
1.1 deraadt 46: command identifies the type of a file using,
47: among other tests,
48: a test for whether the file begins with a certain
1.4 aaron 49: .Dq magic number .
50: .Pp
1.1 deraadt 51: The file
1.4 aaron 52: .Pa /etc/magic
1.1 deraadt 53: specifies what magic numbers are to be tested for,
54: what message to print if a particular magic number is found,
55: and additional information to extract from the file.
1.4 aaron 56: .Pp
1.1 deraadt 57: Each line of the file specifies a test to be performed.
58: A test compares the data starting at a particular offset
59: in the file with a 1-byte, 2-byte, or 4-byte numeric value or
1.4 aaron 60: a string.
61: If the test succeeds, a message is printed.
1.1 deraadt 62: The line consists of the following fields:
1.4 aaron 63: .Bl -tag -width indent
64: .It Sy offset
1.1 deraadt 65: A number specifying the offset, in bytes, into the file of the data
66: which is to be tested.
1.4 aaron 67: .It Sy type
68: The type of the data to be tested.
69: The possible values are:
70: .Bl -tag -width beshort
71: .It Sy byte
1.1 deraadt 72: A one-byte value.
1.4 aaron 73: .It Sy short
1.1 deraadt 74: A two-byte value (on most systems) in this machine's native byte order.
1.4 aaron 75: .It Sy long
1.1 deraadt 76: A four-byte value (on most systems) in this machine's native byte order.
1.4 aaron 77: .It Sy string
1.1 deraadt 78: A string of bytes.
1.4 aaron 79: .It Sy date
80: A four-byte value interpreted as a
81: .Ux
82: date.
83: .It Sy beshort
1.1 deraadt 84: A two-byte value (on most systems) in big-endian byte order.
1.4 aaron 85: .It Sy belong
1.1 deraadt 86: A four-byte value (on most systems) in big-endian byte order.
1.4 aaron 87: .It Sy bedate
1.1 deraadt 88: A four-byte value (on most systems) in big-endian byte order,
1.4 aaron 89: interpreted as a
90: .Ux
91: date.
92: .It Sy leshort
1.1 deraadt 93: A two-byte value (on most systems) in little-endian byte order.
1.4 aaron 94: .It Sy lelong
1.1 deraadt 95: A four-byte value (on most systems) in little-endian byte order.
1.4 aaron 96: .It Sy ledate
1.1 deraadt 97: A four-byte value (on most systems) in little-endian byte order,
1.4 aaron 98: interpreted as a
99: .Ux
100: date.
101: .El
102: .El
103: .Pp
1.1 deraadt 104: The numeric types may optionally be followed by
1.4 aaron 105: .Ql &
1.1 deraadt 106: and a numeric value,
107: to specify that the value is to be AND'ed with the
1.4 aaron 108: numeric value before any comparisons are done.
109: Prepending a
110: .Sq u
1.1 deraadt 111: to the type indicates that ordered comparisons should be unsigned.
1.4 aaron 112: .Bl -tag -width indent
113: .It Sy test
114: The value to be compared with the value from the file.
115: If the type is
1.1 deraadt 116: numeric, this value
117: is specified in C form; if it is a string, it is specified as a C string
1.4 aaron 118: with the usual escapes permitted (e.g.,
119: .Ql \en
120: for newline).
121: .It Sy ""
1.1 deraadt 122: Numeric values
123: may be preceded by a character indicating the operation to be performed.
124: It may be
1.4 aaron 125: .Ql =
1.1 deraadt 126: to specify that the value from the file must equal the specified value,
1.4 aaron 127: .Ql <
1.1 deraadt 128: to specify that the value from the file must be less than the specified
129: value,
1.4 aaron 130: .Ql >
1.1 deraadt 131: to specify that the value from the file must be greater than the specified
132: value,
1.4 aaron 133: .Ql &
1.6 aaron 134: to specify that the value from the file must have set all of the bits
1.1 deraadt 135: that are set in the specified value,
1.4 aaron 136: .Ql ^
1.6 aaron 137: to specify that the value from the file must have clear any of the bits
1.1 deraadt 138: that are set in the specified value, or
1.4 aaron 139: .Sq x
140: to specify that any value will match.
141: If the character is omitted,
1.1 deraadt 142: it is assumed to be
1.4 aaron 143: .Ql = .
144: .It Sy ""
145: Numeric values are specified in C form; e.g.,
146: .Dq 13
1.1 deraadt 147: is decimal,
1.4 aaron 148: .Dq 013
1.1 deraadt 149: is octal, and
1.4 aaron 150: .Dq 0x13
1.1 deraadt 151: is hexadecimal.
1.4 aaron 152: .It Sy ""
1.1 deraadt 153: For string values, the byte string from the
1.6 aaron 154: file must match the specified byte string.
1.1 deraadt 155: The operators
1.4 aaron 156: .Ql = ,
157: .Ql < ,
1.1 deraadt 158: and
1.4 aaron 159: .Ql >
1.1 deraadt 160: (but not
1.4 aaron 161: .Ql & )
1.1 deraadt 162: can be applied to strings.
163: The length used for matching is that of the string argument
1.4 aaron 164: in the magic file.
165: This means that a line can match any string, and
1.1 deraadt 166: then presumably print that string, by doing
1.4 aaron 167: .Ql >\e0
1.1 deraadt 168: (because all strings are greater than the null string).
1.4 aaron 169: .It Sy message
170: The message to be printed if the comparison succeeds.
171: If the string
1.1 deraadt 172: contains a
1.4 aaron 173: .Xr printf 3
1.1 deraadt 174: format specification, the value from the file (with any specified masking
175: performed) is printed using the message as the format string.
1.4 aaron 176: .El
177: .Pp
1.1 deraadt 178: Some file formats contain additional information which is to be printed
1.4 aaron 179: along with the file type.
180: A line which begins with the character
181: .Ql >
182: indicates additional tests and messages to be printed.
183: The number of
184: .Ql >
1.1 deraadt 185: on the line indicates the level of the test; a line with no
1.4 aaron 186: .Ql >
1.1 deraadt 187: at the beginning is considered to be at level 0.
1.4 aaron 188: .Pp
1.1 deraadt 189: Each line at level
1.4 aaron 190: .Em n+1
1.1 deraadt 191: is under the control of the line at level
1.4 aaron 192: .Em n
1.1 deraadt 193: most closely preceding it in the magic file.
194: If the test on a line at level
1.4 aaron 195: .Em n
1.1 deraadt 196: succeeds, the tests specified in all the subsequent lines at level
1.4 aaron 197: .Em n+1
198: are performed, and the messages printed if the tests succeed.
199: The next
1.1 deraadt 200: line at level
1.4 aaron 201: .Em n
1.1 deraadt 202: terminates this.
1.4 aaron 203: .Pp
1.1 deraadt 204: If the first character following the last
1.4 aaron 205: .Ql >
1.1 deraadt 206: is a
1.4 aaron 207: .Ql (
1.1 deraadt 208: then the string after the parenthesis is interpreted as an indirect offset.
209: That means that the number after the parenthesis is used as an offset in
1.4 aaron 210: the file.
211: The value at that offset is read, and is used again as an offset
212: in the file.
213: .Pp
214: Indirect offsets are of the form:
215: .Dq (x[.[bsl]][+-][y]) .
1.6 aaron 216: The value of
1.4 aaron 217: .Sq x
218: is used as an offset in the file.
219: A byte, short or long is read at that offset
1.6 aaron 220: depending on the
1.4 aaron 221: .Dq [bsl]
222: type specifier.
223: To that number the value of
224: .Sq y
225: is added and the result is used as an offset in the file.
226: The default type
1.1 deraadt 227: if one is not specified is long.
1.4 aaron 228: .Pp
1.3 millert 229: Sometimes you do not know the exact offset as this depends on the length of
1.4 aaron 230: preceding fields.
231: You can specify an offset relative to the end of the
232: last uplevel field (of course this may only be done for sublevel tests, i.e.,
1.6 aaron 233: test beginning with
1.4 aaron 234: .Ql > ) .
235: Such a relative offset is specified using
236: .Ql &
1.3 millert 237: as a prefix to the offset.
1.9 jmc 238: .Sh FILES
239: .Bl -tag -width /etc/magic
240: .It Pa /etc/magic
241: .El
242: .Sh SEE ALSO
243: .Xr file 1
1.4 aaron 244: .Sh BUGS
1.6 aaron 245: The formats
1.4 aaron 246: .Li long ,
247: .Li belong ,
248: .Li lelong ,
249: .Li short ,
250: .Li beshort ,
251: .Li leshort ,
252: .Li date ,
253: .Li bedate ,
1.1 deraadt 254: and
1.4 aaron 255: .Li ledate
1.1 deraadt 256: are system-dependent; perhaps they should be specified as a number
1.6 aaron 257: of bytes (2B, 4B, etc),
1.1 deraadt 258: since the files being recognized typically come from
259: a system on which the lengths are invariant.
1.4 aaron 260: .Pp
1.1 deraadt 261: There is (currently) no support for specified-endian data to be used in
262: indirect offsets.
263: .\"
264: .\" From: guy@sun.uucp (Guy Harris)
265: .\" Newsgroups: net.bugs.usg
266: .\" Subject: /etc/magic's format isn't well documented
267: .\" Message-ID: <2752@sun.uucp>
268: .\" Date: 3 Sep 85 08:19:07 GMT
269: .\" Organization: Sun Microsystems, Inc.
270: .\" Lines: 136
1.6 aaron 271: .\"
1.1 deraadt 272: .\" Here's a manual page for the format accepted by the "file" made by adding
273: .\" the changes I posted to the S5R2 version.
274: .\"
275: .\" Modified for Ian Darwin's version of the file command.