1.\" $OpenBSD: file.1,v 1.34 2013/01/17 21:29:14 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: January 17 2013 $ 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 162troff input file, just as the keyword 163.Em struct 164indicates a C program. 165These tests are less reliable than the previous 166two groups, so they are performed last. 167The language test routines also test for some miscellany 168(such as 169.Xr tar 1 170archives). 171.Pp 172Any file that cannot be identified as having been written 173in any of the character sets listed above is simply said to be 174.Dq data . 175.Sh OPTIONS 176.Bl -tag -width indent 177.It Fl 0 , -print0 178Output a null character 179.Sq \e0 180after the end of the filename. 181Nice to 182.Xr cut 1 183the output. 184This does not affect the separator which is still printed. 185.It Fl b , -brief 186Do not prepend filenames to output lines (brief mode). 187.It Fl C , -compile 188Write a 189.Pa magic.mgc 190output file that contains a pre-parsed version of the magic file or directory. 191.It Fl c , -checking-printout 192Cause a checking printout of the parsed form of the magic file. 193This is usually used in conjunction with the 194.Fl m 195flag to debug a new magic file before installing it. 196.It Fl e , -exclude Ar testname 197Exclude the test named in 198.Ar testname 199from the list of tests made to determine the file type. 200Valid test names are: 201.Bl -tag -width compress 202.It apptype 203Check for 204.Dv EMX 205application type (only on EMX). 206.It ascii 207Check for various types of ASCII files. 208.It compress 209Don't look for, or inside, compressed files. 210.It elf 211Don't print elf details. 212.It fortran 213Don't look for fortran sequences inside ASCII files. 214.It soft 215Don't consult magic files. 216.It tar 217Don't examine tar files. 218.It token 219Don't look for known tokens inside ASCII files. 220.It troff 221Don't look for troff sequences inside ASCII files. 222.El 223.It Fl F , -separator Ar separator 224Use the specified string as the separator between the filename and the 225file result returned. 226Defaults to 227.Sq \&: . 228.It Fl f , -files-from Ar namefile 229Read the names of the files to be examined from 230.Ar namefile 231(one per line) 232before the argument list. 233Either 234.Ar namefile 235or at least one filename argument must be present; 236to test the standard input, use 237.Sq - 238as a filename argument. 239.It Fl h , -no-dereference 240Causes symlinks not to be followed. 241This is the default if the environment variable 242.Dv POSIXLY_CORRECT 243is not defined. 244.It Fl -help 245Print a help message and exit. 246.It Fl i , -mime 247Causes the file command to output mime type strings rather than the more 248traditional human readable ones. 249Thus it may say 250.Dq text/plain charset=us-ascii 251rather than 252.Dq ASCII text . 253In order for this option to work, 254.Nm 255changes the way it handles files recognized by the command itself 256(such as many of the text file types, directories etc.), 257and makes use of an alternative 258.Dq magic 259file. 260See also 261.Sx FILES , 262below. 263.It Fl -mime-encoding , -mime-type 264Like 265.Fl i , 266but print only the specified element(s). 267.It Fl k , -keep-going 268Don't stop at the first match, keep going. 269Subsequent matches will have the string 270.Dq "\[rs]012\- " 271prepended. 272(If a newline is required, see the 273.Fl r 274option.) 275.It Fl L , -dereference 276Causes symlinks to be followed; 277analogous to the option of the same name in 278.Xr ls 1 . 279This is the default if the environment variable 280.Dv POSIXLY_CORRECT 281is defined. 282.It Fl m , -magic-file Ar magicfiles 283Specify an alternate list of files and directories containing magic. 284This can be a single item, or a colon-separated list. 285If a compiled magic file is found alongside a file or directory, 286it will be used instead. 287.It Fl N , -no-pad 288Don't pad filenames so that they align in the output. 289.It Fl n , -no-buffer 290Force stdout to be flushed after checking each file. 291This is only useful if checking a list of files. 292It is intended to be used by programs that want filetype output from a pipe. 293.It Fl p , -preserve-date 294On systems that support 295.Xr utime 3 296or 297.Xr utimes 2 , 298attempt to preserve the access time of files analyzed, to pretend that 299.Nm 300never read them. 301.It Fl r , -raw 302Don't translate unprintable characters to \eooo. 303Normally 304.Nm 305translates unprintable characters to their octal representation. 306.It Fl s , -special-files 307Normally, 308.Nm 309only attempts to read and determine the type of argument files which 310.Xr stat 2 311reports are ordinary files. 312This prevents problems, because reading special files may have peculiar 313consequences. 314Specifying the 315.Fl s 316option causes 317.Nm 318to also read argument files which are block or character special files. 319This is useful for determining the filesystem types of the data in raw 320disk partitions, which are block special files. 321This option also causes 322.Nm 323to disregard the file size as reported by 324.Xr stat 2 325since on some systems it reports a zero size for raw disk partitions. 326.It Fl v , -version 327Print the version of the program and exit. 328.It Fl z , -uncompress 329Try to look inside compressed files. 330.El 331.Sh ENVIRONMENT 332The environment variable 333.Dv MAGIC 334can be used to set the default magic file name. 335If that variable is set, then 336.Nm 337will not attempt to open 338.Pa $HOME/.magic . 339.Nm 340adds 341.Dq .mgc 342to the value of this variable as appropriate. 343The environment variable 344.Dv POSIXLY_CORRECT 345controls whether 346.Nm 347will attempt to follow symlinks or not. 348If set, then 349.Nm 350follows symlinks; otherwise it does not. 351This is also controlled by the 352.Fl L 353and 354.Fl h 355options. 356.Sh FILES 357.Bl -tag -width /etc/magic -compact 358.It Pa /etc/magic 359default list of magic numbers 360.El 361.Sh EXIT STATUS 362.Ex -std file 363.Sh SEE ALSO 364.Xr hexdump 1 , 365.Xr od 1 , 366.Xr strings 1 , 367.Xr magic 5 368.Sh STANDARDS CONFORMANCE 369This program is believed to exceed the System V Interface Definition 370of FILE(CMD), as near as one can determine from the vague language 371contained therein. 372Its behavior is mostly compatible with the System V program of the same name. 373This version knows more magic, however, so it will produce 374different (albeit more accurate) output in many cases. 375.\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html 376.Pp 377The one significant difference 378between this version and System V 379is that this version treats any whitespace 380as a delimiter, so that spaces in pattern strings must be escaped. 381For example, 382.Bd -literal -offset indent 383\*(Gt10 string language impress\ (imPRESS data) 384.Ed 385.Pp 386in an existing magic file would have to be changed to 387.Bd -literal -offset indent 388\*(Gt10 string language\e impress (imPRESS data) 389.Ed 390.Pp 391In addition, in this version, if a pattern string contains a backslash, 392it must be escaped. 393For example 394.Bd -literal -offset indent 3950 string \ebegindata Andrew Toolkit document 396.Ed 397.Pp 398in an existing magic file would have to be changed to 399.Bd -literal -offset indent 4000 string \e\ebegindata Andrew Toolkit document 401.Ed 402.Pp 403SunOS releases 3.2 and later from Sun Microsystems include a 404.Nm 405command derived from the System V one, but with some extensions. 406This version differs from Sun's only in minor ways. 407It includes the extension of the 408.Sq & 409operator, used as, 410for example, 411.Bd -literal -offset indent 412\*(Gt16 long&0x7fffffff \*(Gt0 not stripped 413.Ed 414.Sh HISTORY 415There has been a 416.Nm 417command in every 418.Ux 419since at least Research Version 4 420(man page dated November, 1973). 421The System V version introduced one significant major change: 422the external list of magic types. 423This slowed the program down slightly but made it a lot more flexible. 424.Pp 425This program, based on the System V version, 426was written by Ian Darwin 427without looking at anybody else's source code. 428.Pp 429John Gilmore revised the code extensively, making it better than 430the first version. 431Geoff Collyer found several inadequacies 432and provided some magic file entries. 433Contributions by the `&' operator by Rob McMahon, 1989. 434.Pp 435Guy Harris, made many changes from 1993 to the present. 436.Pp 437Primary development and maintenance from 1990 to the present by 438Christos Zoulas. 439.Pp 440Altered by Chris Lowth, 2000: 441Handle the 442.Fl i 443option to output mime type strings, using an alternative 444magic file and internal logic. 445.Pp 446Altered by Eric Fischer, July, 2000, 447to identify character codes and attempt to identify the languages 448of non-ASCII files. 449.Pp 450Altered by Reuben Thomas, 2007 to 2008, to improve MIME 451support and merge MIME and non-MIME magic, support directories as well 452as files of magic, apply many bug fixes and improve the build system. 453.Pp 454The list of contributors to the 455.Dq magic 456directory (magic files) 457is too long to include here. 458You know who you are; thank you. 459Many contributors are listed in the source files. 460.Sh BUGS 461There must be a better way to automate the construction of the Magic 462file from all the glop in Magdir. 463What is it? 464.Pp 465.Nm 466uses several algorithms that favor speed over accuracy, 467thus it can be misled about the contents of 468text 469files. 470.Pp 471The support for text files (primarily for programming languages) 472is simplistic, inefficient and requires recompilation to update. 473.Pp 474The list of keywords in 475.Pa ascmagic 476probably belongs in the Magic file. 477This could be done by using some keyword like 478.Sq * 479for the offset value. 480.Pp 481Complain about conflicts in the magic file entries. 482Make a rule that the magic entries sort based on file offset rather 483than position within the magic file? 484.Pp 485The program should provide a way to give an estimate 486of 487.Dq how good 488a guess is. 489We end up removing guesses (e.g. 490.Dq From\ 491as first 5 chars of file) because 492they are not as good as other guesses (e.g.\& 493.Dq Newsgroups: 494versus 495.Dq Return-Path: ) . 496Still, if the others don't pan out, it should be possible to use the 497first guess. 498.Pp 499This manual page, and particularly this section, is too long. 500