1.\" $OpenBSD: file.1,v 1.28 2007/05/31 19:20:09 jmc Exp $ 2.\" $FreeBSD: src/usr.bin/file/file.1,v 1.16 2000/03/01 12:19:39 sheldonh Exp $ 3.\" 4.\" Copyright (c) Ian F. Darwin 1986-1995. 5.\" Software written by Ian F. Darwin and others; 6.\" maintained 1995-present by Christos Zoulas and others. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice immediately at the beginning of the file, without modification, 13.\" this list of conditions, and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 22.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: May 31 2007 $ 31.Dt FILE 1 32.Os 33.Sh NAME 34.Nm file 35.Nd determine file type 36.Sh SYNOPSIS 37.Nm file 38.Op Fl bckLNnrsvz 39.Op Fl F Ar separator 40.Op Fl f Ar namefile 41.Op Fl m Ar magicfiles 42.Bk -words 43.Ar file ... 44.Ek 45.Nm file 46.Op Fl m Ar magicfiles 47.Fl C 48.Sh DESCRIPTION 49The 50.Nm 51utility 52tests each argument in an attempt to classify it. 53There are three sets of tests, performed in this order: 54filesystem tests, magic number tests, and language tests. 55The first test that succeeds causes the file type to be printed. 56.Pp 57The type printed will usually contain one of the words 58.Dq text 59(the file contains only 60.Tn ASCII 61characters and is probably safe to read on an 62.Tn ASCII 63terminal), 64.Dq executable 65(the file contains the result of compiling a program 66in a form understandable to some 67.Ux 68kernel or another), 69or 70.Dq data 71meaning anything else (data is usually binary or non-printable). 72.Pp 73Exceptions are well-known file formats (core files, tar archives) 74that are known to contain binary data. 75When modifying the file 76.Pa /etc/magic 77or the program itself, 78.Em "preserve these keywords" . 79.Pp 80People depend on knowing that all the readable files in a directory 81have the word 82.Dq text 83printed. 84Don't do as Berkeley did; change 85.Dq shell commands text 86to 87.Dq shell script . 88.Pp 89The filesystem tests are based on examining the return from a 90.Xr stat 2 91system call. 92The program checks to see if the file is empty, 93or if it's some sort of special file. 94Any known file types appropriate to the system you are running on 95(sockets, symbolic links, or named pipes (FIFOs) on those systems that 96implement them) 97are intuited if they are defined in 98the system header file 99.Aq Pa sys/stat.h . 100.Pp 101The magic number tests are used to check for files with data in 102particular fixed formats. 103The canonical example of this is a binary executable (compiled program) 104.Pa a.out 105file, whose format is defined in 106.Aq Pa a.out.h 107and possibly 108.Aq Pa exec.h 109in the standard include directory and is explained in 110.Xr a.out 5 . 111These files have a 112.Dq magic number 113stored in a particular place 114near the beginning of the file that tells the 115.Ux 116operating system 117that the file is a binary executable, and which of several types thereof. 118.Pp 119The concept of magic number has been applied by extension to data files. 120Any file with some invariant identifier at a small fixed 121offset into the file can usually be described in this way. 122The information in these files is read from the magic file 123.Pa /etc/magic . 124.Pp 125If an argument appears to be an 126.Tn ASCII 127file, 128.Nm 129attempts to guess its language. 130The language tests look for particular strings (cf 131.Pa names.h ) 132that can appear anywhere in the first few blocks of a file. 133For example, the keyword 134.Em .br 135indicates that the file is most likely a 136.Xr troff 1 137input file, just as the keyword 138.Li struct 139indicates a C program. 140These tests are less reliable than the previous 141two groups, so they are performed last. 142The language test routines also test for some miscellany 143(such as 144.Xr tar 1 145archives) and determine whether an unknown file should be 146labelled as 147.Dq ASCII text 148or 149.Dq data . 150.Pp 151The options are as follows: 152.Bl -tag -width Ds 153.It Fl b 154Do not prepend filenames to output lines (brief mode). 155.It Fl C 156For each magic number file, write a 157.Pa magic.mgc 158output file that contains a preparsed (compiled) version of it. 159.It Fl c 160Cause a checking printout of the parsed form of the magic file. 161This is usually used in conjunction with 162.Fl m 163to debug a new magic file before installing it. 164.It Fl F Ar separator 165Use the specified string as the separator between the filename and 166the file result returned. 167Defaults to 168.Sq \&: . 169.It Fl f Ar namefile 170Read the names of the files to be examined from 171.Ar namefile 172(one per line) 173before the argument list. 174Either 175.Ar namefile 176or at least one filename argument must be present; 177to test the standard input, use 178.Sq - 179as a filename argument. 180.It Fl k 181Don't stop at the first match, keep going. 182.It Fl L 183Cause symlinks to be followed, as the like-named option in 184.Xr ls 1 185(on systems that support symbolic links). 186.It Fl m Ar magicfiles 187Specify an alternate list, 188.Ar magicfiles , 189of files containing magic numbers. 190This can be a single file or a colon-separated list of files. 191If a compiled magic file is found alongside, it will be used instead. 192.It Fl N 193Don't pad filenames so that they align in the output. 194.It Fl n 195Force 196.Em stdout 197to be flushed after checking each file. 198This is only useful if checking a list of files. 199It is intended to be used by programs that want filetype output from a 200pipe. 201.It Fl r 202Don't translate unprintable characters to 203.Sq \e Ns Em ooo . 204Normally 205.Nm 206translates unprintable characters to their octal representation 207(raw mode). 208.It Fl s 209Normally, 210.Nm 211only attempts to read and determine the type of argument files which 212.Xr stat 2 213reports are ordinary files. 214This prevents problems, because reading special files may have peculiar 215consequences. 216Specifying the 217.Fl s 218option causes 219.Nm 220to also read argument files which are block or character special files. 221This is useful for determining the filesystem types of the data in raw 222disk partitions, which are block special files. 223This option also causes 224.Nm 225to disregard the file size as reported by 226.Xr stat 2 , 227since on some systems it reports a zero size for raw disk partitions. 228.It Fl v 229Print the version of the program and exit. 230.It Fl z 231Try to look inside files that have been run through 232.Xr compress 1 . 233.El 234.Sh ENVIRONMENT 235.Bl -tag -width indent 236.It Ev MAGIC 237Default magic number files, separated by colon characters. 238.Nm 239adds 240.Dq .mgc 241to the value of this variable as appropriate. 242.El 243.Sh FILES 244.Bl -tag -width /etc/magic -compact 245.It Pa /etc/magic 246default list of magic numbers 247.El 248.Sh SEE ALSO 249.Xr compress 1 , 250.Xr hexdump 1 , 251.Xr ls 1 , 252.Xr od 1 , 253.Xr strings 1 , 254.Xr a.out 5 , 255.Xr magic 5 256.Sh STANDARDS CONFORMANCE 257This program is believed to exceed the System V Interface Definition 258of FILE(CMD), as near as one can determine from the vague language 259contained therein. 260Its behaviour is mostly compatible with the System V program of the same name. 261This version knows more magic, however, so it will produce 262different (albeit more accurate) output in many cases. 263.Pp 264The one significant difference 265between this version and System V 266is that this version treats any white space 267as a delimiter, so that spaces in pattern strings must be escaped. 268For example, 269.Pp 270>10 string language impress\ (imPRESS data) 271.Pp 272in an existing magic file would have to be changed to 273.Pp 274>10 string language\e impress (imPRESS data) 275.Pp 276In addition, in this version, if a pattern string contains a backslash, 277it must be escaped. 278For example 279.Pp 2800 string \ebegindata Andrew Toolkit document 281.Pp 282in an existing magic file would have to be changed to 283.Pp 2840 string \e\ebegindata Andrew Toolkit document 285.Pp 286SunOS releases 3.2 and later from Sun Microsystems include a 287.Nm file 288command derived from the System V one, but with some extensions. 289My version differs from Sun's only in minor ways. 290It includes the extension of the 291.Ql & 292operator, used as, 293for example, 294.Pp 295>16 long&0x7fffffff >0 not stripped 296.Sh MAGIC DIRECTORY 297The magic file entries have been collected from various sources, 298mainly USENET, and contributed by various authors. 299.An Christos Zoulas 300(address below) will collect additional 301or corrected magic file entries. 302A consolidation of magic file entries 303will be distributed periodically. 304The order of entries in the magic file is significant. 305Depending on what system you are using, the order that 306they are put together may be incorrect. 307If your old 308.Nm 309command uses a magic file, 310keep the old magic file around for comparison purposes 311(rename it to 312.Pa /etc/magic.orig ) . 313.Sh HISTORY 314There has been a 315.Nm 316command in every 317.Ux 318since at least Research Version 4 319(man page dated November, 1973). 320The System V version introduced one significant major change: 321the external list of magic number types. 322This slowed the program down slightly but made it a lot more flexible. 323.Pp 324This program, based on the System V version, was written by 325.An Ian F. Darwin 326without looking at anybody else's source code. 327.Pp 328.An John Gilmore 329revised the code extensively, making it better than 330the first version. 331.An Geoff Collyer 332found several inadequacies 333and provided some magic file entries. 334Contributions to the 335.Ql & 336operator by 337.An Rob McMahon , 3381989. 339.Pp 340.An Guy Harris 341made many changes from 1993 to the present. 342.Pp 343Primary development and maintenance from 1990 to the present by 344.An Christos Zoulas Aq christos@zoulas.com . 345.Pp 346Altered by 347.An Chris Lowth , 3482000, to optionally report MIME types. 349This required an alternative magic file, and is not available in 350.Ox . 351.Pp 352Altered by 353.An Eric Fischer , 354July, 2000, to identify character codes and attempt to identify the 355languages of non-ASCII files. 356.Pp 357The list of contributors to the 358.Dq magdir 359directory (source for the 360.Pa /etc/magic 361file) is too long to include here. 362You know who you are; thank you. 363.Sh LEGAL NOTICE 364Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999. 365Covered by the standard Berkeley Software Distribution copyright; see the file 366LEGAL.NOTICE in the distribution. 367.Pp 368The files 369.Pa tar.h 370and 371.Pa is_tar.c 372were written by 373.An John Gilmore 374from his public-domain 375.Nm tar 376program, and are not covered by the above license. 377.Sh BUGS 378There must be a better way to automate the construction of the Magic 379file from all the glop in Magdir. 380What is it? 381Better yet, the magic file should be compiled into binary (say, 382.Xr ndbm 3 383or, better yet, fixed-length 384.Tn ASCII 385strings for use in heterogenous network environments) for faster startup. 386Then the program would run as fast as the Version 7 program of the same name, 387with the flexibility of the System V version. 388.Pp 389.Nm 390uses several algorithms that favor speed over accuracy; 391thus it can be misled about the contents of 392.Tn ASCII 393files. 394.Pp 395The support for 396.Tn ASCII 397files (primarily for programming languages) 398is simplistic, inefficient and requires recompilation to update. 399.Pp 400There should be an 401.Dq else 402clause to follow a series of continuation lines. 403.Pp 404The magic file and keywords should have regular expression support. 405Their use of 406.Tn ASCII TAB 407as a field delimiter is ugly and makes 408it hard to edit the files, but is entrenched. 409.Pp 410It might be advisable to allow upper-case letters in keywords 411for e.g., 412.Xr troff 1 413commands vs man page macros. 414Regular expression support would make this easy. 415.Pp 416The program doesn't grok \s-2FORTRAN\s0. 417It should be able to figure \s-2FORTRAN\s0 by seeing some keywords which 418appear indented at the start of line. 419Regular expression support would make this easy. 420.Pp 421The list of keywords in 422.Em ascmagic 423probably belongs in the Magic file. 424This could be done by using some keyword like 425.Ql * 426for the offset value. 427.Pp 428Another optimization would be to sort 429the magic file so that we can just run down all the 430tests for the first byte, first word, first long, etc, once we 431have fetched it. 432Complain about conflicts in the magic file entries. 433Make a rule that the magic entries sort based on file offset rather 434than position within the magic file? 435.Pp 436The program should provide a way to give an estimate 437of 438.Dq how good 439a guess is. 440We end up removing guesses (e.g., 441.Dq From\ \& 442as first 5 chars of file) because 443they are not as good as other guesses (e.g., 444.Dq Newsgroups: 445versus 446.Qq Return-Path: ) . 447Still, if the others don't pan out, it should be 448possible to use the first guess. 449.Pp 450This program is slower than some vendors' 451.Nm 452commands. 453.Pp 454This manual page, and particularly this section, is too long. 455.Sh AVAILABILITY 456You can obtain the original author's latest version by anonymous FTP 457on 458.Em ftp.astron.com 459in the directory 460.Pa /pub/file/file-X.YY.tar.gz . 461