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