2 .\" $Id: file.man,v 1.42 2002/07/03 18:26:37 christos Exp $
4 .Dt FILE 1 "Copyright but distributable"
8 .Nd determine file type
13 .Op Fl m Ar magicfiles
19 This manual page documents version 3.39 of the
21 utility which tests each argument in an attempt to classify it.
22 There are three sets of tests, performed in this order:
23 file system tests, magic number tests, and language tests.
26 test that succeeds causes the file type to be printed.
28 The type printed will usually contain one of the words
30 (the file contains only
31 printing characters and a few common control
32 characters and is probably safe to read on an
36 (the file contains the result of compiling a program
37 in a form understandable to some
42 meaning anything else (data is usually
45 Exceptions are well-known file formats (core files, tar archives)
46 that are known to contain binary data.
47 When modifying the file
48 .Pa /usr/share/misc/magic
49 or the program itself,
50 .Em "preserve these keywords" .
51 People depend on knowing that all the readable files in a directory
55 Don't do as Berkeley did and change
56 .Dq Li "shell commands text"
58 .Dq Li "shell script" .
60 .Pa /usr/share/misc/magic
61 is built mechanically from a large number of small files in
64 in the source distribution of this program.
66 The file system tests are based on examining the return from a
69 The program checks to see if the file is empty,
70 or if it's some sort of special file.
71 Any known file types appropriate to the system you are running on
72 (sockets, symbolic links, or named pipes (FIFOs) on those systems that
74 are intuited if they are defined in
75 the system header file
78 The magic number tests are used to check for files with data in
79 particular fixed formats.
80 The canonical example of this is a binary executable (compiled program)
82 file, whose format is defined in
86 in the standard include directory.
89 stored in a particular place
90 near the beginning of the file that tells the
93 that the file is a binary executable, and which of several types thereof.
96 has been applied by extension to data files.
97 Any file with some invariant identifier at a small fixed
98 offset into the file can usually be described in this way.
99 The information identifying these files is read from the compiled
101 .Pa /usr/share/misc/magic.mgc ,
103 .Pa /usr/share/misc/magic
104 if the compile file does not exist.
106 If a file does not match any of the entries in the magic file,
107 it is examined to see if it seems to be a text file.
108 ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets
109 (such as those used on Macintosh and IBM PC systems),
110 UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC
111 character sets can be distinguished by the different
112 ranges and sequences of bytes that constitute printable text
114 If a file passes any of these tests, its character set is reported.
115 ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified
118 because they will be mostly readable on nearly any terminal;
119 UTF-16 and EBCDIC are only
120 .Dq Li "character data"
122 they contain text, it is text that will require translation
123 before it can be read.
126 will attempt to determine other characteristics of text-type files.
127 If the lines of a file are terminated by CR, CRLF, or NEL, instead
130 LF, this will be reported.
131 Files that contain embedded escape sequences or overstriking
132 will also be identified.
136 has determined the character set used in a text-type file,
138 attempt to determine in what language the file is written.
139 The language tests look for particular strings (cf
141 that can appear anywhere in the first few blocks of a file.
142 For example, the keyword
144 indicates that the file is most likely a
146 input file, just as the keyword
148 indicates a C program.
149 These tests are less reliable than the previous
150 two groups, so they are performed last.
151 The language test routines also test for some miscellany
156 Any file that cannot be identified as having been written
157 in any of the character sets listed above is simply said to be
160 .Bl -tag -width indent
162 Do not prepend filenames to output lines (brief mode).
164 Cause a checking printout of the parsed form of the magic file.
165 This is usually used in conjunction with
167 to debug a new magic file before installing it.
171 output file that contains a pre-parsed version of
174 Read the names of the files to be examined from
177 before the argument list.
180 or at least one filename argument must be present;
181 to test the standard input, use
183 as a filename argument.
185 Causes the file command to output mime type strings rather than the more
186 traditional human readable ones.
188 .Dq Li "text/plain; charset=us-ascii"
190 .Dq Li "ASCII text" .
191 In order for this option to work, file changes the way
192 it handles files recognised by the command itself (such as many of the
193 text file types, directories etc), and makes use of an alternative
200 Don't stop at the first match, keep going.
202 Specify an alternate list of files containing magic numbers.
203 This can be a single file, or a colon-separated list of files.
205 Force stdout to be flushed after checking each file.
206 This is only useful if checking a list of files.
207 It is intended to be used by programs that want
208 filetype output from a pipe.
210 Print the version of the program and exit.
212 Try to look inside compressed files.
214 option causes symlinks to be followed, as the like-named option in
216 (on systems that support symbolic links).
220 only attempts to read and determine the type of argument files which
222 reports are ordinary files.
223 This prevents problems, because reading special files may have peculiar
229 to also read argument files which are block or character special files.
230 This is useful for determining the file system types of the data in raw
231 disk partitions, which are block special files.
232 This option also causes
234 to disregard the file size as reported by
236 since on some systems it reports a zero size for raw disk partitions.
239 .Bl -tag -width ".Pa /usr/share/misc/magic.mime" -compact
240 .It Pa /usr/share/misc/magic.mgc
241 default compiled list of magic numbers
242 .It Pa /usr/share/misc/magic
243 default list of magic numbers
244 .It Pa /usr/share/misc/magic.mime
245 default list of magic numbers, used to output mime types when the
250 The environment variable
252 can be used to set the default magic number files.
258 .Sh STANDARDS CONFORMANCE
259 This program is believed to exceed the
261 of FILE(CMD), as near as one can determine from the vague language
263 Its behaviour is mostly compatible with the System V program of the same name.
264 This version knows more magic, however, so it will produce
265 different (albeit more accurate) output in many cases.
267 The one significant difference
268 between this version and System V
269 is that this version treats any white space
270 as a delimiter, so that spaces in pattern strings must be escaped.
273 .Dl ">10 string language impress\ (imPRESS data)"
275 in an existing magic file would have to be changed to
277 .Dl ">10 string language\e impress (imPRESS data)"
279 In addition, in this version, if a pattern string contains a backslash,
283 .Dl "0 string \ebegindata Andrew Toolkit document"
285 in an existing magic file would have to be changed to
287 .Dl "0 string \e\ebegindata Andrew Toolkit document"
289 SunOS releases 3.2 and later from Sun Microsystems include a
291 command derived from the System V one, but with some extensions.
292 My version differs from Sun's only in minor ways.
293 It includes the extension of the
298 .Dl ">16 long&0x7fffffff >0 not stripped"
300 The magic file entries have been collected from various sources,
301 mainly USENET, and contributed by various authors.
303 (address below) will collect additional
304 or corrected magic file entries.
305 A consolidation of magic file entries
306 will be distributed periodically.
308 The order of entries in the magic file is significant.
309 Depending on what system you are using, the order that
310 they are put together may be incorrect.
313 command uses a magic file,
314 keep the old magic file around for comparison purposes
316 .Pa /usr/share/misc/magic.orig ) .
319 $ file file.c file /dev/{wd0a,hda}
320 file.c: C program text
321 file: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV),
322 dynamically linked (uses shared libs), stripped
323 /dev/wd0a: block special (0/0)
324 /dev/hda: block special (3/0)
325 $ file -s /dev/wd0{b,d}
327 /dev/wd0d: x86 boot sector
328 $ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10}
329 /dev/hda: x86 boot sector
330 /dev/hda1: Linux/i386 ext2 filesystem
331 /dev/hda2: x86 boot sector
332 /dev/hda3: x86 boot sector, extended partition table
333 /dev/hda4: Linux/i386 ext2 filesystem
334 /dev/hda5: Linux/i386 swap file
335 /dev/hda6: Linux/i386 swap file
336 /dev/hda7: Linux/i386 swap file
337 /dev/hda8: Linux/i386 swap file
341 $ file -i file.c file /dev/{wd0a,hda}
343 file: application/x-executable, dynamically linked (uses shared libs),
345 /dev/hda: application/x-not-regular-file
346 /dev/wd0a: application/x-not-regular-file
353 since at least Research Version 4
354 (man page dated November, 1973).
355 The System V version introduced one significant major change:
356 the external list of magic number types.
357 This slowed the program down slightly but made it a lot more flexible.
359 This program, based on the System V version,
361 .An Ian Darwin Aq ian@darwinsys.com
362 without looking at anybody else's source code.
365 revised the code extensively, making it better than
368 found several inadequacies
369 and provided some magic file entries.
373 .An Rob McMahon Aq cudcv@warwick.ac.uk ,
376 .An Guy Harris Aq guy@netapp.com ,
377 made many changes from 1993 to the present.
379 Primary development and maintenance from 1990 to the present by
380 .An Christos Zoulas Aq christos@astron.com .
383 .An Chris Lowth Aq chris@lowth.com ,
387 option to output mime type strings and using an alternative
388 magic file and internal logic.
391 .An Eric Fischer Aq enf@pobox.com ,
393 to identify character codes and attempt to identify the languages
398 The list of contributors to the
400 directory (source for the
401 .Pa /usr/share/misc/magic
402 file) is too long to include here.
403 You know who you are; thank you.
405 Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999.
406 Covered by the standard Berkeley Software Distribution copyright; see the file
408 in the source distribution.
416 from his public-domain
418 program, and are not covered by the above license.
420 There must be a better way to automate the construction of the
422 file from all the glop in
425 Better yet, the magic file should be compiled into binary (say,
427 or, better yet, fixed-length
429 strings for use in heterogenous network environments) for faster startup.
430 Then the program would run as fast as the Version 7 program of the same name,
431 with the flexibility of the System V version.
435 utility uses several algorithms that favor speed over accuracy,
436 thus it can be misled about the contents of
442 files (primarily for programming languages)
443 is simplistic, inefficient and requires recompilation to update.
447 clause to follow a series of continuation lines.
449 The magic file and keywords should have regular expression support.
452 as a field delimiter is ugly and makes
453 it hard to edit the files, but is entrenched.
455 It might be advisable to allow upper-case letters in keywords
458 commands vs man page macros.
459 Regular expression support would make this easy.
461 The program doesn't grok
463 It should be able to figure
465 by seeing some keywords which
466 appear indented at the start of line.
467 Regular expression support would make this easy.
469 The list of keywords in
471 probably belongs in the
474 This could be done by using some keyword like
476 for the offset value.
478 Another optimisation would be to sort
479 the magic file so that we can just run down all the
480 tests for the first byte, first word, first long, etc, once we
482 Complain about conflicts in the magic file entries.
483 Make a rule that the magic entries sort based on file offset rather
484 than position within the magic file?
486 The program should provide a way to give an estimate
490 We end up removing guesses (e.g.\&
492 as first 5 chars of file) because
493 they are not as good as other guesses (e.g.\&
496 .Dq Li "Return-Path:" ) .
497 Still, if the others don't pan out, it should be
498 possible to use the first guess.
500 This program is slower than some vendors' file commands.
501 The new support for multiple character codes makes it even slower.
503 This manual page, and particularly this section, is too long.
505 You can obtain the original author's latest version by anonymous FTP
509 .Pa /pub/file/file-X.YY.tar.gz
projects / FreeBSD / FreeBSD.git / blob