1.\" $OpenBSD: file.1,v 1.30 2009/10/26 21:03:03 ajacoutot 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: October 26 2009 $ 31.Dt FILE 1 32.Os 33.Sh NAME 34.Nm file 35.Nd determine file type 36.Sh SYNOPSIS 37.Nm 38.Bk -words 39.Op Fl 0bCcehikLNnprsvz 40.Op Fl -help 41.Op Fl -mime-encoding 42.Op Fl -mime-type 43.Op Fl F Ar separator 44.Op Fl f Ar namefile 45.Op Fl m Ar magicfiles 46.Ar file 47.Ek 48.Sh DESCRIPTION 49The 50.Nm 51utility tests each argument in an attempt to classify it. 52There are three sets of tests, performed in this order: 53filesystem tests, magic tests, and language tests. 54The first test that succeeds causes the file type to be printed. 55.Pp 56The type printed will usually contain one of the words 57.Em text 58(the file contains only 59printing characters and a few common control 60characters and is probably safe to read on an 61ASCII terminal), 62.Em executable 63(the file contains the result of compiling a program 64in a form understandable to some 65.Ux 66kernel or another), 67or 68.Em data 69meaning anything else (data is usually 70.Dq binary 71or non-printable). 72Exceptions are well-known file formats (core files, tar archives) 73that are known to contain binary data. 74When modifying magic files or the program itself, make sure to 75.Em preserve these keywords . 76Users depend on knowing that all the readable files in a directory 77have the word 78.Dq text 79printed. 80Don't do as Berkeley did and change 81.Dq shell commands text 82to 83.Dq shell script . 84.Pp 85The filesystem tests are based on examining the return from a 86.Xr stat 2 87system call. 88The program checks to see if the file is empty, 89or if it's some sort of special file. 90Any known file types, 91such as sockets, symbolic links, and named pipes (FIFOs), 92are intuited if they are defined in 93the system header file 94.Aq Pa sys/stat.h . 95.Pp 96The magic tests are used to check for files with data in 97particular fixed formats. 98The canonical example of this is a binary executable (compiled program) 99a.out file, whose format is defined in 100.Aq Pa elf.h , 101.Aq Pa a.out.h , 102and possibly 103.Aq Pa exec.h 104in the standard include directory. 105These files have a 106.Dq magic number 107stored in a particular place 108near the beginning of the file that tells the 109.Ux 110operating system 111that the file is a binary executable, and which of several types thereof. 112The concept of a 113.Dq magic 114has been applied by extension to data files. 115Any file with some invariant identifier at a small fixed 116offset into the file can usually be described in this way. 117The information identifying these files is read from the magic file 118.Pa /etc/magic . 119In addition, if 120.Pa $HOME/.magic.mgc 121or 122.Pa $HOME/.magic 123exists, it will be used in preference to the system magic files. 124.Pp 125If a file does not match any of the entries in the magic file, 126it is examined to see if it seems to be a text file. 127ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets 128(such as those used on Macintosh and IBM PC systems), 129UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC 130character sets can be distinguished by the different 131ranges and sequences of bytes that constitute printable text 132in each set. 133If a file passes any of these tests, its character set is reported. 134ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified 135as 136.Dq text 137because they will be mostly readable on nearly any terminal; 138UTF-16 and EBCDIC are only 139.Dq character data 140because, while 141they contain text, it is text that will require translation 142before it can be read. 143In addition, 144.Nm 145will attempt to determine other characteristics of text-type files. 146If the lines of a file are terminated by CR, CRLF, or NEL, instead 147of the Unix-standard LF, this will be reported. 148Files that contain embedded escape sequences or overstriking 149will also be identified. 150.Pp 151Once 152.Nm 153has determined the character set used in a text-type file, 154it will 155attempt to determine in what language the file is written. 156The language tests look for particular strings (cf.\& 157.Aq Pa names.h ) 158that can appear anywhere in the first few blocks of a file. 159For example, the keyword 160.Em .br 161indicates that the file is most likely a 162.Xr troff 1 163input file, just as the keyword 164.Em struct 165indicates a C program. 166These tests are less reliable than the previous 167two groups, so they are performed last. 168The language test routines also test for some miscellany 169(such as 170.Xr tar 1 171archives). 172.Pp 173Any file that cannot be identified as having been written 174in any of the character sets listed above is simply said to be 175.Dq data . 176.Sh OPTIONS 177.Bl -tag -width indent 178.It Fl 0 , -print0 179Output a null character 180.Sq \e0 181after the end of the filename. 182Nice to 183.Xr cut 1 184the output. 185This does not affect the separator which is still printed. 186.It Fl b , -brief 187Do not prepend filenames to output lines (brief mode). 188.It Fl C , -compile 189Write a 190.Pa magic.mgc 191output file that contains a pre-parsed version of the magic file or directory. 192.It Fl c , -checking-printout 193Cause a checking printout of the parsed form of the magic file. 194This is usually used in conjunction with the 195.Fl m 196flag to debug a new magic file before installing it. 197.It Fl e , -exclude Ar testname 198Exclude the test named in 199.Ar testname 200from the list of tests made to determine the file type. 201Valid test names are: 202.Bl -tag -width 203.It apptype 204Check for 205.Dv EMX 206application type (only on EMX). 207.It ascii 208Check for various types of ASCII files. 209.It compress 210Don't look for, or inside, compressed files. 211.It elf 212Don't print elf details. 213.It fortran 214Don't look for fortran sequences inside ASCII files. 215.It soft 216Don't consult magic files. 217.It tar 218Don't examine tar files. 219.It token 220Don't look for known tokens inside ASCII files. 221.It troff 222Don't look for troff sequences inside ASCII files. 223.El 224.It Fl F , -separator Ar separator 225Use the specified string as the separator between the filename and the 226file result returned. 227Defaults to 228.Sq \&: . 229.It Fl f , -files-from Ar namefile 230Read the names of the files to be examined from 231.Ar namefile 232(one per line) 233before the argument list. 234Either 235.Ar namefile 236or at least one filename argument must be present; 237to test the standard input, use 238.Sq - 239as a filename argument. 240.It Fl h , -no-dereference 241Causes symlinks not to be followed. 242This is the default if the environment variable 243.Dv POSIXLY_CORRECT 244is not defined. 245.It Fl -help 246Print a help message and exit. 247.It Fl i , -mime 248Causes the file command to output mime type strings rather than the more 249traditional human readable ones. 250Thus it may say 251.Dq text/plain charset=us-ascii 252rather than 253.Dq ASCII text . 254In order for this option to work, 255.Nm 256changes the way it handles files recognized by the command itself 257(such as many of the text file types, directories etc.), 258and makes use of an alternative 259.Dq magic 260file. 261See also 262.Sx FILES , 263below. 264.It Fl -mime-encoding , -mime-type 265Like 266.Fl i , 267but print only the specified element(s). 268.It Fl k , -keep-going 269Don't stop at the first match, keep going. 270Subsequent matches will have the string 271.Dq "\[rs]012\- " 272prepended. 273(If a newline is required, see the 274.Fl r 275option.) 276.It Fl L , -dereference 277Causes symlinks to be followed; 278analogous to the option of the same name in 279.Xr ls 1 . 280This is the default if the environment variable 281.Dv POSIXLY_CORRECT 282is defined. 283.It Fl m , -magic-file Ar magicfiles 284Specify an alternate list of files and directories containing magic. 285This can be a single item, or a colon-separated list. 286If a compiled magic file is found alongside a file or directory, 287it will be used instead. 288.It Fl N , -no-pad 289Don't pad filenames so that they align in the output. 290.It Fl n , -no-buffer 291Force stdout to be flushed after checking each file. 292This is only useful if checking a list of files. 293It is intended to be used by programs that want filetype output from a pipe. 294.It Fl p , -preserve-date 295On systems that support 296.Xr utime 3 297or 298.Xr utimes 2 , 299attempt to preserve the access time of files analyzed, to pretend that 300.Nm 301never read them. 302.It Fl r , -raw 303Don't translate unprintable characters to \eooo. 304Normally 305.Nm 306translates unprintable characters to their octal representation. 307.It Fl s , -special-files 308Normally, 309.Nm 310only attempts to read and determine the type of argument files which 311.Xr stat 2 312reports are ordinary files. 313This prevents problems, because reading special files may have peculiar 314consequences. 315Specifying the 316.Fl s 317option causes 318.Nm 319to also read argument files which are block or character special files. 320This is useful for determining the filesystem types of the data in raw 321disk partitions, which are block special files. 322This option also causes 323.Nm 324to disregard the file size as reported by 325.Xr stat 2 326since on some systems it reports a zero size for raw disk partitions. 327.It Fl v , -version 328Print the version of the program and exit. 329.It Fl z , -uncompress 330Try to look inside compressed files. 331.El 332.Pp 333.Ex -std file 334.Sh ENVIRONMENT 335The environment variable 336.Dv MAGIC 337can be used to set the default magic file name. 338If that variable is set, then 339.Nm 340will not attempt to open 341.Pa $HOME/.magic . 342.Nm 343adds 344.Dq .mgc 345to the value of this variable as appropriate. 346The environment variable 347.Dv POSIXLY_CORRECT 348controls whether 349.Nm 350will attempt to follow symlinks or not. 351If set, then 352.Nm 353follows symlinks; otherwise it does not. 354This is also controlled by the 355.Fl L 356and 357.Fl h 358options. 359.Sh FILES 360.Bl -tag -width /etc/magic -compact 361.It Pa /etc/magic 362default list of magic numbers 363.El 364.Sh SEE ALSO 365.Xr hexdump 1 , 366.Xr od 1 , 367.Xr strings 1 , 368.Xr magic 5 369.Sh STANDARDS CONFORMANCE 370This program is believed to exceed the System V Interface Definition 371of FILE(CMD), as near as one can determine from the vague language 372contained therein. 373Its behavior is mostly compatible with the System V program of the same name. 374This version knows more magic, however, so it will produce 375different (albeit more accurate) output in many cases. 376.\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html 377.Pp 378The one significant difference 379between this version and System V 380is that this version treats any whitespace 381as a delimiter, so that spaces in pattern strings must be escaped. 382For example, 383.Bd -literal -offset indent 384\*(Gt10 string language impress\ (imPRESS data) 385.Ed 386.Pp 387in an existing magic file would have to be changed to 388.Bd -literal -offset indent 389\*(Gt10 string language\e impress (imPRESS data) 390.Ed 391.Pp 392In addition, in this version, if a pattern string contains a backslash, 393it must be escaped. 394For example 395.Bd -literal -offset indent 3960 string \ebegindata Andrew Toolkit document 397.Ed 398.Pp 399in an existing magic file would have to be changed to 400.Bd -literal -offset indent 4010 string \e\ebegindata Andrew Toolkit document 402.Ed 403.Pp 404SunOS releases 3.2 and later from Sun Microsystems include a 405.Nm 406command derived from the System V one, but with some extensions. 407This version differs from Sun's only in minor ways. 408It includes the extension of the 409.Sq & 410operator, used as, 411for example, 412.Bd -literal -offset indent 413\*(Gt16 long&0x7fffffff \*(Gt0 not stripped 414.Ed 415.Sh HISTORY 416There has been a 417.Nm 418command in every 419.Ux 420since at least Research Version 4 421(man page dated November, 1973). 422The System V version introduced one significant major change: 423the external list of magic types. 424This slowed the program down slightly but made it a lot more flexible. 425.Pp 426This program, based on the System V version, 427was written by Ian Darwin 428without looking at anybody else's source code. 429.Pp 430John Gilmore revised the code extensively, making it better than 431the first version. 432Geoff Collyer found several inadequacies 433and provided some magic file entries. 434Contributions by the `&' operator by Rob McMahon, 1989. 435.Pp 436Guy Harris, made many changes from 1993 to the present. 437.Pp 438Primary development and maintenance from 1990 to the present by 439Christos Zoulas. 440.Pp 441Altered by Chris Lowth, 2000: 442Handle the 443.Fl i 444option to output mime type strings, using an alternative 445magic file and internal logic. 446.Pp 447Altered by Eric Fischer, July, 2000, 448to identify character codes and attempt to identify the languages 449of non-ASCII files. 450.Pp 451Altered by Reuben Thomas, 2007 to 2008, to improve MIME 452support and merge MIME and non-MIME magic, support directories as well 453as files of magic, apply many bug fixes and improve the build system. 454.Pp 455The list of contributors to the 456.Dq magic 457directory (magic files) 458is too long to include here. 459You know who you are; thank you. 460Many contributors are listed in the source files. 461.Sh BUGS 462.Pp 463There must be a better way to automate the construction of the Magic 464file from all the glop in Magdir. 465What is it? 466.Pp 467.Nm 468uses several algorithms that favor speed over accuracy, 469thus it can be misled about the contents of 470text 471files. 472.Pp 473The support for text files (primarily for programming languages) 474is simplistic, inefficient and requires recompilation to update. 475.Pp 476The list of keywords in 477.Pa ascmagic 478probably belongs in the Magic file. 479This could be done by using some keyword like 480.Sq * 481for the offset value. 482.Pp 483Complain about conflicts in the magic file entries. 484Make a rule that the magic entries sort based on file offset rather 485than position within the magic file? 486.Pp 487The program should provide a way to give an estimate 488of 489.Dq how good 490a guess is. 491We end up removing guesses (e.g. 492.Dq From\ 493as first 5 chars of file) because 494they are not as good as other guesses (e.g.\& 495.Dq Newsgroups: 496versus 497.Dq Return-Path: ) . 498Still, if the others don't pan out, it should be possible to use the 499first guess. 500.Pp 501This manual page, and particularly this section, is too long. 502