1 .\" $File: file.man,v 1.111 2014/12/16 23:18:40 christos Exp $
7 .Nd determine file type
11 .Op Fl bcEhiklLNnprsvz0
13 .Op Fl Fl mime-encoding
18 .Op Fl m Ar magicfiles
19 .Op Fl P Ar name=value
24 .Op Fl m Ar magicfiles
28 This manual page documents version __VERSION__ of the
33 tests each argument in an attempt to classify it.
34 There are three sets of tests, performed in this order:
35 filesystem tests, magic tests, and language tests.
38 test that succeeds causes the file type to be printed.
40 The type printed will usually contain one of the words
42 (the file contains only
43 printing characters and a few common control
44 characters and is probably safe to read on an
48 (the file contains the result of compiling a program
49 in a form understandable to some
54 meaning anything else (data is usually
57 Exceptions are well-known file formats (core files, tar archives)
58 that are known to contain binary data.
59 When modifying magic files or the program itself, make sure to
60 .Em "preserve these keywords" .
61 Users depend on knowing that all the readable files in a directory
65 Don't do as Berkeley did and change
66 .Dq shell commands text
70 The filesystem tests are based on examining the return from a
73 The program checks to see if the file is empty,
74 or if it's some sort of special file.
75 Any known file types appropriate to the system you are running on
76 (sockets, symbolic links, or named pipes (FIFOs) on those systems that
78 are intuited if they are defined in the system header file
81 The magic tests are used to check for files with data in
82 particular fixed formats.
83 The canonical example of this is a binary executable (compiled program)
85 file, whose format is defined in
90 in the standard include directory.
93 stored in a particular place
94 near the beginning of the file that tells the
97 that the file is a binary executable, and which of several types thereof.
100 has been applied by extension to data files.
101 Any file with some invariant identifier at a small fixed
102 offset into the file can usually be described in this way.
103 The information identifying these files is read from the compiled
106 or the files in the directory
108 if the compiled file does not exist.
113 exists, it will be used in preference to the system magic files.
115 If a file does not match any of the entries in the magic file,
116 it is examined to see if it seems to be a text file.
117 ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets
118 (such as those used on Macintosh and IBM PC systems),
119 UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC
120 character sets can be distinguished by the different
121 ranges and sequences of bytes that constitute printable text
123 If a file passes any of these tests, its character set is reported.
124 ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified
127 because they will be mostly readable on nearly any terminal;
128 UTF-16 and EBCDIC are only
131 they contain text, it is text that will require translation
132 before it can be read.
135 will attempt to determine other characteristics of text-type files.
136 If the lines of a file are terminated by CR, CRLF, or NEL, instead
137 of the Unix-standard LF, this will be reported.
138 Files that contain embedded escape sequences or overstriking
139 will also be identified.
143 has determined the character set used in a text-type file,
145 attempt to determine in what language the file is written.
146 The language tests look for particular strings (cf.
148 that can appear anywhere in the first few blocks of a file.
149 For example, the keyword
151 indicates that the file is most likely a
153 input file, just as the keyword
155 indicates a C program.
156 These tests are less reliable than the previous
157 two groups, so they are performed last.
158 The language test routines also test for some miscellany
163 Any file that cannot be identified as having been written
164 in any of the character sets listed above is simply said to be
167 .Bl -tag -width indent
169 Causes the file command to output the file type and creator code as
170 used by older MacOS versions. The code consists of eight letters,
171 the first describing the file type, the latter the creator.
172 .It Fl b , Fl Fl brief
173 Do not prepend filenames to output lines (brief mode).
174 .It Fl C , Fl Fl compile
177 output file that contains a pre-parsed version of the magic file or directory.
178 .It Fl c , Fl Fl checking-printout
179 Cause a checking printout of the parsed form of the magic file.
180 This is usually used in conjunction with the
182 flag to debug a new magic file before installing it.
184 On filesystem errors (file not found etc), instead of handling the error
185 as regular output as POSIX mandates and keep going, issue an error message
187 .It Fl e , Fl Fl exclude Ar testname
188 Exclude the test named in
190 from the list of tests made to determine the file type.
191 Valid test names are:
192 .Bl -tag -width compress
195 application type (only on EMX).
197 Various types of text files (this test will try to guess the text
198 encoding, irrespective of the setting of the
202 Different text encodings for soft magic tests.
204 Ignored for backwards compatibility.
206 Prints details of Compound Document Files.
208 Checks for, and looks inside, compressed files.
210 Prints ELF file details.
212 Consults magic files.
216 .It Fl F , Fl Fl separator Ar separator
217 Use the specified string as the separator between the filename and the
218 file result returned.
221 .It Fl f , Fl Fl files-from Ar namefile
222 Read the names of the files to be examined from
225 before the argument list.
228 or at least one filename argument must be present;
229 to test the standard input, use
231 as a filename argument.
234 is unwrapped and the enclosed filenames are processed when this option is
235 encountered and before any further options processing is done.
236 This allows one to process multiple lists of files with different command line
237 arguments on the same
240 Thus if you want to set the delimiter, you need to do it before you specify
241 the list of files, like:
242 .Dq Fl F Ar @ Fl f Ar namefile ,
244 .Dq Fl f Ar namefile Fl F Ar @ .
245 .It Fl h , Fl Fl no-dereference
246 option causes symlinks not to be followed
247 (on systems that support symbolic links).
248 This is the default if the environment variable
251 .It Fl i , Fl Fl mime
252 Causes the file command to output mime type strings rather than the more
253 traditional human readable ones.
255 .Sq text/plain; charset=us-ascii
258 .It Fl Fl mime-type , Fl Fl mime-encoding
261 but print only the specified element(s).
262 .It Fl k , Fl Fl keep-going
263 Don't stop at the first match, keep going.
264 Subsequent matches will be
268 (If you want a newline, see the
271 The magic pattern with the highest strength (see the
274 .It Fl l , Fl Fl list
275 Shows a list of patterns and their strength sorted descending by
278 which is used for the matching (see also the
281 .It Fl L , Fl Fl dereference
282 option causes symlinks to be followed, as the like-named option in
284 (on systems that support symbolic links).
285 This is the default if the environment variable
288 .It Fl m , Fl Fl magic-file Ar magicfiles
289 Specify an alternate list of files and directories containing magic.
290 This can be a single item, or a colon-separated list.
291 If a compiled magic file is found alongside a file or directory,
292 it will be used instead.
293 .It Fl N , Fl Fl no-pad
294 Don't pad filenames so that they align in the output.
295 .It Fl n , Fl Fl no-buffer
296 Force stdout to be flushed after checking each file.
297 This is only useful if checking a list of files.
298 It is intended to be used by programs that want filetype output from a pipe.
299 .It Fl p , Fl Fl preserve-date
300 On systems that support
304 attempt to preserve the access time of files analyzed, to pretend that
307 .It Fl P , Fl Fl parameter Ar name=value
308 Set various parameter limits.
309 .Bl -column "elf_phnum" "Default" "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
310 .It Sy "Name" Ta Sy "Default" Ta Sy "Explanation"
311 .It Li indir Ta 15 Ta recursion limit for indirect magic
312 .It Li name Ta 30 Ta use count limit for name/use magic
313 .It Li elf_notes Ta 256 Ta max ELF notes processed
314 .It Li elf_phnum Ta 128 Ta max ELF program sections processed
315 .It Li elf_shnum Ta 32768 Ta max ELF sections processed
318 Don't translate unprintable characters to \eooo.
321 translates unprintable characters to their octal representation.
322 .It Fl s , Fl Fl special-files
325 only attempts to read and determine the type of argument files which
327 reports are ordinary files.
328 This prevents problems, because reading special files may have peculiar
334 to also read argument files which are block or character special files.
335 This is useful for determining the filesystem types of the data in raw
336 disk partitions, which are block special files.
337 This option also causes
339 to disregard the file size as reported by
341 since on some systems it reports a zero size for raw disk partitions.
342 .It Fl v , Fl Fl version
343 Print the version of the program and exit.
344 .It Fl z , Fl Fl uncompress
345 Try to look inside compressed files.
346 .It Fl 0 , Fl Fl print0
347 Output a null character
349 after the end of the filename.
353 This does not affect the separator, which is still printed.
355 Print a help message and exit.
358 .Bl -tag -width __MAGIC__.mgc -compact
360 Default compiled list of magic.
362 Directory containing default magic files.
365 The environment variable
367 can be used to set the default magic file name.
368 If that variable is set, then
370 will not attempt to open
375 to the value of this variable as appropriate.
378 has to exist in order for
381 The environment variable
383 controls (on systems that support symbolic links), whether
385 will attempt to follow symlinks or not.
388 follows symlink, otherwise it does not.
389 This is also controlled by the
395 .Xr magic __FSECTION__ ,
399 .Sh STANDARDS CONFORMANCE
400 This program is believed to exceed the System V Interface Definition
401 of FILE(CMD), as near as one can determine from the vague language
403 Its behavior is mostly compatible with the System V program of the same name.
404 This version knows more magic, however, so it will produce
405 different (albeit more accurate) output in many cases.
406 .\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html
408 The one significant difference
409 between this version and System V
410 is that this version treats any white space
411 as a delimiter, so that spaces in pattern strings must be escaped.
413 .Bd -literal -offset indent
414 \*[Gt]10 string language impress\ (imPRESS data)
417 in an existing magic file would have to be changed to
418 .Bd -literal -offset indent
419 \*[Gt]10 string language\e impress (imPRESS data)
422 In addition, in this version, if a pattern string contains a backslash,
425 .Bd -literal -offset indent
426 0 string \ebegindata Andrew Toolkit document
429 in an existing magic file would have to be changed to
430 .Bd -literal -offset indent
431 0 string \e\ebegindata Andrew Toolkit document
434 SunOS releases 3.2 and later from Sun Microsystems include a
436 command derived from the System V one, but with some extensions.
437 This version differs from Sun's only in minor ways.
438 It includes the extension of the
442 .Bd -literal -offset indent
443 \*[Gt]16 long\*[Am]0x7fffffff \*[Gt]0 not stripped
446 The magic file entries have been collected from various sources,
447 mainly USENET, and contributed by various authors.
448 Christos Zoulas (address below) will collect additional
449 or corrected magic file entries.
450 A consolidation of magic file entries
451 will be distributed periodically.
453 The order of entries in the magic file is significant.
454 Depending on what system you are using, the order that
455 they are put together may be incorrect.
458 command uses a magic file,
459 keep the old magic file around for comparison purposes
461 .Pa __MAGIC__.orig ) .
463 .Bd -literal -offset indent
464 $ file file.c file /dev/{wd0a,hda}
465 file.c: C program text
466 file: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV),
467 dynamically linked (uses shared libs), stripped
468 /dev/wd0a: block special (0/0)
469 /dev/hda: block special (3/0)
471 $ file -s /dev/wd0{b,d}
473 /dev/wd0d: x86 boot sector
475 $ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10}
476 /dev/hda: x86 boot sector
477 /dev/hda1: Linux/i386 ext2 filesystem
478 /dev/hda2: x86 boot sector
479 /dev/hda3: x86 boot sector, extended partition table
480 /dev/hda4: Linux/i386 ext2 filesystem
481 /dev/hda5: Linux/i386 swap file
482 /dev/hda6: Linux/i386 swap file
483 /dev/hda7: Linux/i386 swap file
484 /dev/hda8: Linux/i386 swap file
488 $ file -i file.c file /dev/{wd0a,hda}
490 file: application/x-executable
491 /dev/hda: application/x-not-regular-file
492 /dev/wd0a: application/x-not-regular-file
499 .Dv UNIX since at least Research Version 4
500 (man page dated November, 1973).
501 The System V version introduced one significant major change:
502 the external list of magic types.
503 This slowed the program down slightly but made it a lot more flexible.
505 This program, based on the System V version,
506 was written by Ian Darwin
507 .Aq ian@darwinsys.com
508 without looking at anybody else's source code.
510 John Gilmore revised the code extensively, making it better than
512 Geoff Collyer found several inadequacies
513 and provided some magic file entries.
516 operator by Rob McMahon,
517 .Aq cudcv@warwick.ac.uk ,
522 made many changes from 1993 to the present.
525 Primary development and maintenance from 1990 to the present by
527 .Aq christos@astron.com .
529 Altered by Chris Lowth
530 .Aq chris@lowth.com ,
533 option to output mime type strings, using an alternative
534 magic file and internal logic.
536 Altered by Eric Fischer
539 to identify character codes and attempt to identify the languages
542 Altered by Reuben Thomas
544 2007-2011, to improve MIME support, merge MIME and non-MIME magic,
545 support directories as well as files of magic, apply many bug fixes,
546 update and fix a lot of magic, improve the build system, improve the
547 documentation, and rewrite the Python bindings in pure Python.
549 The list of contributors to the
551 directory (magic files)
552 is too long to include here.
553 You know who you are; thank you.
554 Many contributors are listed in the source files.
556 Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999.
557 Covered by the standard Berkeley Software Distribution copyright; see the file
558 COPYING in the source distribution.
564 were written by John Gilmore from his public-domain
566 program, and are not covered by the above license.
569 returns 0 on success, and non-zero on error.
572 Please report bugs and send patches to the bug tracker at
573 .Pa http://bugs.gw.com/
574 or the mailing list at
577 .Pa http://mx.gw.com/mailman/listinfo/file
581 Fix output so that tests for MIME and APPLE flags are not needed all
582 over the place, and actual output is only done in one place.
584 Suggestion: push possible outputs on to a list, then pick the
585 last-pushed (most specific, one hopes) value at the end, or
586 use a default if the list is empty.
587 This should not slow down evaluation.
589 Continue to squash all magic bugs.
590 See Debian BTS for a good source.
592 Store arbitrarily long strings, for example for %s patterns, so that
593 they can be printed out.
594 Fixes Debian bug #271672.
595 Would require more complex store/load code in apprentice.
597 Add syntax for relative offsets after current level (Debian bug #466037).
599 Make file -ki work, i.e. give multiple MIME types.
601 Add a zip library so we can peek inside Office2007 documents to
602 figure out what they are.
604 Add an option to print URLs for the sources of the file descriptions.
606 Combine script searches and add a way to map executable names to MIME
607 types (e.g. have a magic value for !:mime which causes the resulting
608 string to be looked up in a table).
609 This would avoid adding the same magic repeatedly for each new
610 hash-bang interpreter.
616 to check for consistency at compile time (duplicate
619 pointing to undefined
626 more efficient by keeping a sorted list of names.
627 Special-case ^ to flip endianness in the parser so that it does not
628 have to be escaped, and document it.
630 You can obtain the original author's latest version by anonymous FTP
634 .Pa /pub/file/file-X.YZ.tar.gz .