contrib/file/magic.man

   1 .\" $File: magic.man,v 1.57 2008/08/30 09:50:20 christos Exp $
   2 .Dd August 30, 2008
   3 .Dt MAGIC __FSECTION__
   4 .Os
   5 .\" install as magic.4 on USG, magic.5 on V7, Berkeley and Linux systems.
   6 .Sh NAME
   7 .Nm magic
   8 .Nd file command's magic pattern file
   9 .Sh DESCRIPTION
  10 This manual page documents the format of the magic file as
  11 used by the
  12 .Xr file __CSECTION__
  13 command, version __VERSION__.
  14 The
  15 .Xr file __CSECTION__
  16 command identifies the type of a file using,
  17 among other tests,
  18 a test for whether the file contains certain
  19 .Dq "magic patterns" .
  20 The file
  21 .Pa __MAGIC__
  22 specifies what patterns are to be tested for, what message or
  23 MIME type to print if a particular pattern is found,
  24 and additional information to extract from the file.
  25 .Pp
  26 Each line of the file specifies a test to be performed.
  27 A test compares the data starting at a particular offset
  28 in the file with a byte value, a string or a numeric value.
  29 If the test succeeds, a message is printed.
  30 The line consists of the following fields:
  31 .Bl -tag -width ".Dv message"
  32 .It Dv offset
  33 A number specifying the offset, in bytes, into the file of the data
  34 which is to be tested.
  35 .It Dv type
  36 The type of the data to be tested.
  37 The possible values are:
  38 .Bl -tag -width ".Dv lestring16"
  39 .It Dv byte
  40 A one-byte value.
  41 .It Dv short
  42 A two-byte value in this machine's native byte order.
  43 .It Dv long
  44 A four-byte value in this machine's native byte order.
  45 .It Dv quad
  46 An eight-byte value in this machine's native byte order.
  47 .It Dv float
  48 A 32-bit single precision IEEE floating point number in this machine's native byte order.
  49 .It Dv double
  50 A 64-bit double precision IEEE floating point number in this machine's native byte order.
  51 .It Dv string
  52 A string of bytes.
  53 The string type specification can be optionally followed
  54 by /[Bbc]*.
  55 The
  56 .Dq B
  57 flag compacts whitespace in the target, which must
  58 contain at least one whitespace character.
  59 If the magic has
  60 .Dv n
  61 consecutive blanks, the target needs at least
  62 .Dv n
  63 consecutive blanks to match.
  64 The
  65 .Dq b
  66 flag treats every blank in the target as an optional blank.
  67 Finally the
  68 .Dq c
  69 flag, specifies case insensitive matching: lowercase
  70 characters in the magic match both lower and upper case characters in the
  71 target, whereas upper case characters in the magic only match uppercase
  72 characters in the target.
  73 .It Dv pstring
  74 A Pascal-style string where the first byte is interpreted as the an
  75 unsigned length.
  76 The string is not NUL terminated.
  77 .It Dv date
  78 A four-byte value interpreted as a UNIX date.
  79 .It Dv qdate
  80 A eight-byte value interpreted as a UNIX date.
  81 .It Dv ldate
  82 A four-byte value interpreted as a UNIX-style date, but interpreted as
  83 local time rather than UTC.
  84 .It Dv qldate
  85 An eight-byte value interpreted as a UNIX-style date, but interpreted as
  86 local time rather than UTC.
  87 .It Dv beshort
  88 A two-byte value in big-endian byte order.
  89 .It Dv belong
  90 A four-byte value in big-endian byte order.
  91 .It Dv bequad
  92 An eight-byte value in big-endian byte order.
  93 .It Dv befloat
  94 A 32-bit single precision IEEE floating point number in big-endian byte order.
  95 .It Dv bedouble
  96 A 64-bit double precision IEEE floating point number in big-endian byte order.
  97 .It Dv bedate
  98 A four-byte value in big-endian byte order,
  99 interpreted as a Unix date.
 100 .It Dv beqdate
 101 An eight-byte value in big-endian byte order,
 102 interpreted as a Unix date.
 103 .It Dv beldate
 104 A four-byte value in big-endian byte order,
 105 interpreted as a UNIX-style date, but interpreted as local time rather
 106 than UTC.
 107 .It Dv beqldate
 108 An eight-byte value in big-endian byte order,
 109 interpreted as a UNIX-style date, but interpreted as local time rather
 110 than UTC.
 111 .It Dv bestring16
 112 A two-byte unicode (UCS16) string in big-endian byte order.
 113 .It Dv leshort
 114 A two-byte value in little-endian byte order.
 115 .It Dv lelong
 116 A four-byte value in little-endian byte order.
 117 .It Dv lequad
 118 An eight-byte value in little-endian byte order.
 119 .It Dv lefloat
 120 A 32-bit single precision IEEE floating point number in little-endian byte order.
 121 .It Dv ledouble
 122 A 64-bit double precision IEEE floating point number in little-endian byte order.
 123 .It Dv ledate
 124 A four-byte value in little-endian byte order,
 125 interpreted as a UNIX date.
 126 .It Dv leqdate
 127 An eight-byte value in little-endian byte order,
 128 interpreted as a UNIX date.
 129 .It Dv leldate
 130 A four-byte value in little-endian byte order,
 131 interpreted as a UNIX-style date, but interpreted as local time rather
 132 than UTC.
 133 .It Dv leqldate
 134 An eight-byte value in little-endian byte order,
 135 interpreted as a UNIX-style date, but interpreted as local time rather
 136 than UTC.
 137 .It Dv lestring16
 138 A two-byte unicode (UCS16) string in little-endian byte order.
 139 .It Dv melong
 140 A four-byte value in middle-endian (PDP-11) byte order.
 141 .It Dv medate
 142 A four-byte value in middle-endian (PDP-11) byte order,
 143 interpreted as a UNIX date.
 144 .It Dv meldate
 145 A four-byte value in middle-endian (PDP-11) byte order,
 146 interpreted as a UNIX-style date, but interpreted as local time rather
 147 than UTC.
 148 .It Dv regex
 149 A regular expression match in extended POSIX regular expression syntax
 150 (like egrep). Regular expressions can take exponential time to
 151 process, and their performance is hard to predict, so their use is
 152 discouraged. When used in production environments, their performance
 153 should be carefully checked. The type specification can be optionally
 154 followed by
 155 .Dv /[c][s] .
 156 The
 157 .Dq c
 158 flag makes the match case insensitive, while the
 159 .Dq s
 160 flag update the offset to the start offset of the match, rather than the end.
 161 The regular expression is tested against line
 162 .Dv N + 1
 163 onwards, where
 164 .Dv N
 165 is the given offset.
 166 Line endings are assumed to be in the machine's native format.
 167 .Dv ^
 168 and
 169 .Dv $
 170 match the beginning and end of individual lines, respectively,
 171 not beginning and end of file.
 172 .It Dv search
 173 A literal string search starting at the given offset. The same
 174 modifier flags can be used as for string patterns. The modifier flags
 175 (if any) must be followed by
 176 .Dv /number
 177 the range, that is, the number of positions at which the match will be
 178 attempted, starting from the start offset. This is suitable for
 179 searching larger binary expressions with variable offsets, using
 180 .Dv \e
 181 escapes for special characters. The offset works as for regex.
 182 .It Dv default
 183 This is intended to be used with the test
 184 .Em x
 185 (which is always true) and a message that is to be used if there are
 186 no other matches.
 187 .El
 188 .Pp
 189 Each top-level magic pattern (see below for an explanation of levels)
 190 is classified as text or binary according to the types used. Types
 191 .Dq regex
 192 and
 193 .Dq search
 194 are classified as text tests, unless non-printable characters are used
 195 in the pattern. All other tests are classified as binary. A top-level
 196 pattern is considered to be a test text when all its patterns are text
 197 patterns; otherwise, it is considered to be a binary pattern. When
 198 matching a file, binary patterns are tried first; if no match is
 199 found, and the file looks like text, then its encoding is determined
 200 and the text patterns are tried.
 201 .Pp
 202 The numeric types may optionally be followed by
 203 .Dv \*[Am]
 204 and a numeric value,
 205 to specify that the value is to be AND'ed with the
 206 numeric value before any comparisons are done.
 207 Prepending a
 208 .Dv u
 209 to the type indicates that ordered comparisons should be unsigned.
 210 .It Dv test
 211 The value to be compared with the value from the file.
 212 If the type is
 213 numeric, this value
 214 is specified in C form; if it is a string, it is specified as a C string
 215 with the usual escapes permitted (e.g. \en for new-line).
 216 .Pp
 217 Numeric values
 218 may be preceded by a character indicating the operation to be performed.
 219 It may be
 220 .Dv = ,
 221 to specify that the value from the file must equal the specified value,
 222 .Dv \*[Lt] ,
 223 to specify that the value from the file must be less than the specified
 224 value,
 225 .Dv \*[Gt] ,
 226 to specify that the value from the file must be greater than the specified
 227 value,
 228 .Dv \*[Am] ,
 229 to specify that the value from the file must have set all of the bits
 230 that are set in the specified value,
 231 .Dv ^ ,
 232 to specify that the value from the file must have clear any of the bits
 233 that are set in the specified value, or
 234 .Dv ~ ,
 235 the value specified after is negated before tested.
 236 .Dv x ,
 237 to specify that any value will match.
 238 If the character is omitted, it is assumed to be
 239 .Dv = .
 240 Operators
 241 .Dv \*[Am] ,
 242 .Dv ^ ,
 243 and
 244 .Dv ~
 245 don't work with floats and doubles.
 246 The operator
 247 .Dv !\&
 248 specifies that the line matches if the test does
 249 .Em not
 250 succeed.
 251 .Pp
 252 Numeric values are specified in C form; e.g.
 253 .Dv 13
 254 is decimal,
 255 .Dv 013
 256 is octal, and
 257 .Dv 0x13
 258 is hexadecimal.
 259 .Pp
 260 For string values, the string from the
 261 file must match the specified string.
 262 The operators
 263 .Dv = ,
 264 .Dv \*[Lt]
 265 and
 266 .Dv \*[Gt]
 267 (but not
 268 .Dv \*[Am] )
 269 can be applied to strings.
 270 The length used for matching is that of the string argument
 271 in the magic file.
 272 This means that a line can match any non-empty string (usually used to
 273 then print the string), with
 274 .Em \*[Gt]\e0
 275 (because all non-empty strings are greater than the empty string).
 276 .Pp
 277 The special test
 278 .Em x
 279 always evaluates to true.
 280 .Dv message
 281 The message to be printed if the comparison succeeds.
 282 If the string contains a
 283 .Xr printf 3
 284 format specification, the value from the file (with any specified masking
 285 performed) is printed using the message as the format string.
 286 If the string begins with
 287 .Dq \eb ,
 288 the message printed is the remainder of the string with no whitespace
 289 added before it: multiple matches are normally separated by a single
 290 space.
 291 .El
 292 .Pp
 293 A MIME type is given on a separate line, which must be the next
 294 non-blank or comment line after the magic line that identifies the
 295 file type, and has the following format:
 296 .Bd -literal -offset indent
 297 !:mime  MIMETYPE
 298 .Ed
 299 .Pp
 300 i.e. the literal string
 301 .Dq !:mime
 302 followed by the MIME type.
 303 .Pp
 304 An optional strength can be supplied on a separate line which refers to
 305 the current magic description using the following format:
 306 .Bd -literal -offset indent
 307 !:strength OP VALUE
 308 .Ed
 309 .Pp
 310 The operand
 311 .Dv OP
 312 can be:
 313 .Dv + ,
 314 .Dv - ,
 315 .Dv * ,
 316 or
 317 .Dv /
 318 and
 319 .Dv VALUE
 320 is a constant between 0 and 255.
 321 This constant is applied using the specified operand
 322 to the currently computed default magic strength.
 323 .Pp
 324 Some file formats contain additional information which is to be printed
 325 along with the file type or need additional tests to determine the true
 326 file type.
 327 These additional tests are introduced by one or more
 328 .Em \*[Gt]
 329 characters preceding the offset.
 330 The number of
 331 .Em \*[Gt]
 332 on the line indicates the level of the test; a line with no
 333 .Em \*[Gt]
 334 at the beginning is considered to be at level 0.
 335 Tests are arranged in a tree-like hierarchy:
 336 If a the test on a line at level
 337 .Em n
 338 succeeds, all following tests at level
 339 .Em n+1
 340 are performed, and the messages printed if the tests succeed, untile a line
 341 with level
 342 .Em n
 343 (or less) appears.
 344 For more complex files, one can use empty messages to get just the
 345 "if/then" effect, in the following way:
 346 .Bd -literal -offset indent
 347 0      string   MZ
 348 \*[Gt]0x18  leshort  \*[Lt]0x40   MS-DOS executable
 349 \*[Gt]0x18  leshort  \*[Gt]0x3f   extended PC executable (e.g., MS Windows)
 350 .Ed
 351 .Pp
 352 Offsets do not need to be constant, but can also be read from the file
 353 being examined.
 354 If the first character following the last
 355 .Em \*[Gt]
 356 is a
 357 .Em (
 358 then the string after the parenthesis is interpreted as an indirect offset.
 359 That means that the number after the parenthesis is used as an offset in
 360 the file.
 361 The value at that offset is read, and is used again as an offset
 362 in the file.
 363 Indirect offsets are of the form:
 364 .Em (( x [.[bslBSL]][+\-][ y ]) .
 365 The value of
 366 .Em x
 367 is used as an offset in the file.
 368 A byte, short or long is read at that offset depending on the
 369 .Em [bslBSLm]
 370 type specifier.
 371 The capitalized types interpret the number as a big endian
 372 value, whereas the small letter versions interpret the number as a little
 373 endian value;
 374 the
 375 .Em m
 376 type interprets the number as a middle endian (PDP-11) value.
 377 To that number the value of
 378 .Em y
 379 is added and the result is used as an offset in the file.
 380 The default type if one is not specified is long.
 381 .Pp
 382 That way variable length structures can be examined:
 383 .Bd -literal -offset indent
 384 # MS Windows executables are also valid MS-DOS executables
 385 0           string  MZ
 386 \*[Gt]0x18       leshort \*[Lt]0x40   MZ executable (MS-DOS)
 387 # skip the whole block below if it is not an extended executable
 388 \*[Gt]0x18       leshort \*[Gt]0x3f
 389 \*[Gt]\*[Gt](0x3c.l)  string  PE\e0\e0  PE executable (MS-Windows)
 390 \*[Gt]\*[Gt](0x3c.l)  string  LX\e0\e0  LX executable (OS/2)
 391 .Ed
 392 .Pp
 393 This strategy of examining has a drawback: You must make sure that
 394 you eventually print something, or users may get empty output (like, when
 395 there is neither PE\e0\e0 nor LE\e0\e0 in the above example)
 396 .Pp
 397 If this indirect offset cannot be used directly, simple calculations are
 398 possible: appending
 399 .Em [+-*/%\*[Am]|^]number
 400 inside parentheses allows one to modify
 401 the value read from the file before it is used as an offset:
 402 .Bd -literal -offset indent
 403 # MS Windows executables are also valid MS-DOS executables
 404 0           string  MZ
 405 # sometimes, the value at 0x18 is less that 0x40 but there's still an
 406 # extended executable, simply appended to the file
 407 \*[Gt]0x18       leshort \*[Lt]0x40
 408 \*[Gt]\*[Gt](4.s*512) leshort 0x014c  COFF executable (MS-DOS, DJGPP)
 409 \*[Gt]\*[Gt](4.s*512) leshort !0x014c MZ executable (MS-DOS)
 410 .Ed
 411 .Pp
 412 Sometimes you do not know the exact offset as this depends on the length or
 413 position (when indirection was used before) of preceding fields.
 414 You can specify an offset relative to the end of the last up-level
 415 field using
 416 .Sq \*[Am]
 417 as a prefix to the offset:
 418 .Bd -literal -offset indent
 419 0           string  MZ
 420 \*[Gt]0x18       leshort \*[Gt]0x3f
 421 \*[Gt]\*[Gt](0x3c.l)  string  PE\e0\e0    PE executable (MS-Windows)
 422 # immediately following the PE signature is the CPU type
 423 \*[Gt]\*[Gt]\*[Gt]\*[Am]0       leshort 0x14c     for Intel 80386
 424 \*[Gt]\*[Gt]\*[Gt]\*[Am]0       leshort 0x184     for DEC Alpha
 425 .Ed
 426 .Pp
 427 Indirect and relative offsets can be combined:
 428 .Bd -literal -offset indent
 429 0             string  MZ
 430 \*[Gt]0x18         leshort \*[Lt]0x40
 431 \*[Gt]\*[Gt](4.s*512)   leshort !0x014c MZ executable (MS-DOS)
 432 # if it's not COFF, go back 512 bytes and add the offset taken
 433 # from byte 2/3, which is yet another way of finding the start
 434 # of the extended executable
 435 \*[Gt]\*[Gt]\*[Gt]\*[Am](2.s-514) string  LE      LE executable (MS Windows VxD driver)
 436 .Ed
 437 .Pp
 438 Or the other way around:
 439 .Bd -literal -offset indent
 440 0                 string  MZ
 441 \*[Gt]0x18             leshort \*[Gt]0x3f
 442 \*[Gt]\*[Gt](0x3c.l)        string  LE\e0\e0  LE executable (MS-Windows)
 443 # at offset 0x80 (-4, since relative offsets start at the end
 444 # of the up-level match) inside the LE header, we find the absolute
 445 # offset to the code area, where we look for a specific signature
 446 \*[Gt]\*[Gt]\*[Gt](\*[Am]0x7c.l+0x26) string  UPX     \eb, UPX compressed
 447 .Ed
 448 .Pp
 449 Or even both!
 450 .Bd -literal -offset indent
 451 0                string  MZ
 452 \*[Gt]0x18            leshort \*[Gt]0x3f
 453 \*[Gt]\*[Gt](0x3c.l)       string  LE\e0\e0 LE executable (MS-Windows)
 454 # at offset 0x58 inside the LE header, we find the relative offset
 455 # to a data area where we look for a specific signature
 456 \*[Gt]\*[Gt]\*[Gt]\*[Am](\*[Am]0x54.l-3)  string  UNACE  \eb, ACE self-extracting archive
 457 .Ed
 458 .Pp
 459 Finally, if you have to deal with offset/length pairs in your file, even the
 460 second value in a parenthesized expression can be taken from the file itself,
 461 using another set of parentheses.
 462 Note that this additional indirect offset is always relative to the
 463 start of the main indirect offset.
 464 .Bd -literal -offset indent
 465 0                 string       MZ
 466 \*[Gt]0x18             leshort      \*[Gt]0x3f
 467 \*[Gt]\*[Gt](0x3c.l)        string       PE\e0\e0 PE executable (MS-Windows)
 468 # search for the PE section called ".idata"...
 469 \*[Gt]\*[Gt]\*[Gt]\*[Am]0xf4          search/0x140 .idata
 470 # ...and go to the end of it, calculated from start+length;
 471 # these are located 14 and 10 bytes after the section name
 472 \*[Gt]\*[Gt]\*[Gt]\*[Gt](\*[Am]0xe.l+(-4)) string       PK\e3\e4 \eb, ZIP self-extracting archive
 473 .Ed
 474 .Sh SEE ALSO
 475 .Xr file __CSECTION__
 476 \- the command that reads this file.
 477 .Sh BUGS
 478 The formats
 479 .Dv long ,
 480 .Dv belong ,
 481 .Dv lelong ,
 482 .Dv melong ,
 483 .Dv short ,
 484 .Dv beshort ,
 485 .Dv leshort ,
 486 .Dv date ,
 487 .Dv bedate ,
 488 .Dv medate ,
 489 .Dv ledate ,
 490 .Dv beldate ,
 491 .Dv leldate ,
 492 and
 493 .Dv meldate
 494 are system-dependent; perhaps they should be specified as a number
 495 of bytes (2B, 4B, etc),
 496 since the files being recognized typically come from
 497 a system on which the lengths are invariant.
 498 .\"
 499 .\" From: guy@sun.uucp (Guy Harris)
 500 .\" Newsgroups: net.bugs.usg
 501 .\" Subject: /etc/magic's format isn't well documented
 502 .\" Message-ID: <2752@sun.uucp>
 503 .\" Date: 3 Sep 85 08:19:07 GMT
 504 .\" Organization: Sun Microsystems, Inc.
 505 .\" Lines: 136
 506 .\"
 507 .\" Here's a manual page for the format accepted by the "file" made by adding
 508 .\" the changes I posted to the S5R2 version.
 509 .\"
 510 .\" Modified for Ian Darwin's version of the file command.