Annotation of src/usr.bin/file/magic.5, Revision 1.1
1.1 ! deraadt 1: .TH MAGIC 5 "Public Domain"
! 2: .\" install as magic.5 on USG, magic.5 on V7 or Berkeley systems.
! 3: .SH NAME
! 4: magic \- file command's magic number file
! 5: .SH DESCRIPTION
! 6: The
! 7: .IR file (1)
! 8: command identifies the type of a file using,
! 9: among other tests,
! 10: a test for whether the file begins with a certain
! 11: .IR "magic number" .
! 12: The file
! 13: .B /etc/magic
! 14: specifies what magic numbers are to be tested for,
! 15: what message to print if a particular magic number is found,
! 16: and additional information to extract from the file.
! 17: .PP
! 18: Each line of the file specifies a test to be performed.
! 19: A test compares the data starting at a particular offset
! 20: in the file with a 1-byte, 2-byte, or 4-byte numeric value or
! 21: a string. If the test succeeds, a message is printed.
! 22: The line consists of the following fields:
! 23: .IP offset \w'message'u+2n
! 24: A number specifying the offset, in bytes, into the file of the data
! 25: which is to be tested.
! 26: .IP type
! 27: The type of the data to be tested. The possible values are:
! 28: .RS
! 29: .IP byte \w'message'u+2n
! 30: A one-byte value.
! 31: .IP short
! 32: A two-byte value (on most systems) in this machine's native byte order.
! 33: .IP long
! 34: A four-byte value (on most systems) in this machine's native byte order.
! 35: .IP string
! 36: A string of bytes.
! 37: .IP date
! 38: A four-byte value interpreted as a unix date.
! 39: .IP beshort
! 40: A two-byte value (on most systems) in big-endian byte order.
! 41: .IP belong
! 42: A four-byte value (on most systems) in big-endian byte order.
! 43: .IP bedate
! 44: A four-byte value (on most systems) in big-endian byte order,
! 45: interpreted as a unix date.
! 46: .IP leshort
! 47: A two-byte value (on most systems) in little-endian byte order.
! 48: .IP lelong
! 49: A four-byte value (on most systems) in little-endian byte order.
! 50: .IP ledate
! 51: A four-byte value (on most systems) in little-endian byte order,
! 52: interpreted as a unix date.
! 53: .RE
! 54: .PP
! 55: The numeric types may optionally be followed by
! 56: .B &
! 57: and a numeric value,
! 58: to specify that the value is to be AND'ed with the
! 59: numeric value before any comparisons are done. Prepending a
! 60: .B u
! 61: to the type indicates that ordered comparisons should be unsigned.
! 62: .IP test
! 63: The value to be compared with the value from the file. If the type is
! 64: numeric, this value
! 65: is specified in C form; if it is a string, it is specified as a C string
! 66: with the usual escapes permitted (e.g. \en for new-line).
! 67: .IP
! 68: Numeric values
! 69: may be preceded by a character indicating the operation to be performed.
! 70: It may be
! 71: .BR = ,
! 72: to specify that the value from the file must equal the specified value,
! 73: .BR < ,
! 74: to specify that the value from the file must be less than the specified
! 75: value,
! 76: .BR > ,
! 77: to specify that the value from the file must be greater than the specified
! 78: value,
! 79: .BR & ,
! 80: to specify that the value from the file must have set all of the bits
! 81: that are set in the specified value,
! 82: .BR ^ ,
! 83: to specify that the value from the file must have clear any of the bits
! 84: that are set in the specified value, or
! 85: .BR x ,
! 86: to specify that any value will match. If the character is omitted,
! 87: it is assumed to be
! 88: .BR = .
! 89: .IP
! 90: Numeric values are specified in C form; e.g.
! 91: .B 13
! 92: is decimal,
! 93: .B 013
! 94: is octal, and
! 95: .B 0x13
! 96: is hexadecimal.
! 97: .IP
! 98: For string values, the byte string from the
! 99: file must match the specified byte string.
! 100: The operators
! 101: .BR = ,
! 102: .B <
! 103: and
! 104: .B >
! 105: (but not
! 106: .BR & )
! 107: can be applied to strings.
! 108: The length used for matching is that of the string argument
! 109: in the magic file. This means that a line can match any string, and
! 110: then presumably print that string, by doing
! 111: .B >\e0
! 112: (because all strings are greater than the null string).
! 113: .IP message
! 114: The message to be printed if the comparison succeeds. If the string
! 115: contains a
! 116: .IR printf (3S)
! 117: format specification, the value from the file (with any specified masking
! 118: performed) is printed using the message as the format string.
! 119: .PP
! 120: Some file formats contain additional information which is to be printed
! 121: along with the file type. A line which begins with the character
! 122: .B >
! 123: indicates additional tests and messages to be printed. The number of
! 124: .B >
! 125: on the line indicates the level of the test; a line with no
! 126: .B >
! 127: at the beginning is considered to be at level 0.
! 128: Each line at level
! 129: .IB n \(pl1
! 130: is under the control of the line at level
! 131: .IB n
! 132: most closely preceding it in the magic file.
! 133: If the test on a line at level
! 134: .I n
! 135: succeeds, the tests specified in all the subsequent lines at level
! 136: .IB n \(pl1
! 137: are performed, and the messages printed if the tests succeed. The next
! 138: line at level
! 139: .I n
! 140: terminates this.
! 141: If the first character following the last
! 142: .B >
! 143: is a
! 144: .B (
! 145: then the string after the parenthesis is interpreted as an indirect offset.
! 146: That means that the number after the parenthesis is used as an offset in
! 147: the file. The value at that offset is read, and is used again as an offset
! 148: in the file. Indirect offsets are of the form:
! 149: .BI (( x [.[bsl]][+-][ y ]).
! 150: The value of
! 151: .I x
! 152: is used as an offset in the file. A byte, short or long is read at that offset
! 153: depending on the
! 154: .B [bsl]
! 155: type specifier. To that number the value of
! 156: .I y
! 157: is added and the result is used as an offset in the file. The default type
! 158: if one is not specified is long.
! 159: .SH BUGS
! 160: The formats
! 161: .IR long ,
! 162: .IR belong ,
! 163: .IR lelong ,
! 164: .IR short ,
! 165: .IR beshort ,
! 166: .IR leshort ,
! 167: .IR date ,
! 168: .IR bedate ,
! 169: and
! 170: .I ledate
! 171: are system-dependent; perhaps they should be specified as a number
! 172: of bytes (2B, 4B, etc),
! 173: since the files being recognized typically come from
! 174: a system on which the lengths are invariant.
! 175: .PP
! 176: There is (currently) no support for specified-endian data to be used in
! 177: indirect offsets.
! 178: .SH SEE ALSO
! 179: .IR file (1)
! 180: \- the command that reads this file.
! 181: .\"
! 182: .\" From: guy@sun.uucp (Guy Harris)
! 183: .\" Newsgroups: net.bugs.usg
! 184: .\" Subject: /etc/magic's format isn't well documented
! 185: .\" Message-ID: <2752@sun.uucp>
! 186: .\" Date: 3 Sep 85 08:19:07 GMT
! 187: .\" Organization: Sun Microsystems, Inc.
! 188: .\" Lines: 136
! 189: .\"
! 190: .\" Here's a manual page for the format accepted by the "file" made by adding
! 191: .\" the changes I posted to the S5R2 version.
! 192: .\"
! 193: .\" Modified for Ian Darwin's version of the file command.
! 194: .\" @(#)$Id: magic.5,v 1.8 1995/03/27 16:16:28 christos Exp $