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