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