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