Import file-5.10.
[dragonfly.git] / contrib / file / doc / file.man
1 .\" $File: file.man,v 1.98 2011/12/08 12:12:46 rrt Exp $
2 .Dd October 17, 2011
3 .Dt FILE __CSECTION__
4 .Os
5 .Sh NAME
6 .Nm file
7 .Nd determine file type
8 .Sh SYNOPSIS
9 .Nm
10 .Bk -words
11 .Op Fl bchiklLNnprsvz0
12 .Op Fl Fl apple
13 .Op Fl Fl mime-encoding
14 .Op Fl Fl mime-type
15 .Op Fl e Ar testname
16 .Op Fl F Ar separator
17 .Op Fl f Ar namefile
18 .Op Fl m Ar magicfiles
19 .Ar
20 .Ek
21 .Nm
22 .Fl C
23 .Op Fl m Ar magicfiles
24 .Nm
25 .Op Fl Fl help
26 .Sh DESCRIPTION
27 This manual page documents version __VERSION__ of the
28 .Nm
29 command.
30 .Pp
31 .Nm
32 tests each argument in an attempt to classify it.
33 There are three sets of tests, performed in this order:
34 filesystem tests, magic tests, and language tests.
35 The
36 .Em first
37 test that succeeds causes the file type to be printed.
38 .Pp
39 The type printed will usually contain one of the words
40 .Em text
41 (the file contains only
42 printing characters and a few common control
43 characters and is probably safe to read on an
44 .Dv ASCII
45 terminal),
46 .Em executable
47 (the file contains the result of compiling a program
48 in a form understandable to some
49 .Tn UNIX
50 kernel or another),
51 or
52 .Em data
53 meaning anything else (data is usually
54 .Dq binary
55 or non-printable).
56 Exceptions are well-known file formats (core files, tar archives)
57 that are known to contain binary data.
58 When modifying magic files or the program itself, make sure to
59 .Em "preserve these keywords" .
60 Users depend on knowing that all the readable files in a directory
61 have the word
62 .Dq text
63 printed.
64 Don't do as Berkeley did and change
65 .Dq shell commands text
66 to
67 .Dq shell script .
68 .Pp
69 The filesystem tests are based on examining the return from a
70 .Xr stat 2
71 system call.
72 The program checks to see if the file is empty,
73 or if it's some sort of special file.
74 Any known file types appropriate to the system you are running on
75 (sockets, symbolic links, or named pipes (FIFOs) on those systems that
76 implement them)
77 are intuited if they are defined in the system header file
78 .In sys/stat.h .
79 .Pp
80 The magic tests are used to check for files with data in
81 particular fixed formats.
82 The canonical example of this is a binary executable (compiled program)
83 .Dv a.out
84 file, whose format is defined in
85 .In elf.h ,
86 .In a.out.h
87 and possibly
88 .In exec.h
89 in the standard include directory.
90 These files have a
91 .Dq "magic number"
92 stored in a particular place
93 near the beginning of the file that tells the
94 .Tn UNIX
95 operating system
96 that the file is a binary executable, and which of several types thereof.
97 The concept of a
98 .Dq "magic"
99 has been applied by extension to data files.
100 Any file with some invariant identifier at a small fixed
101 offset into the file can usually be described in this way.
102 The information identifying these files is read from the compiled
103 magic file
104 .Pa __MAGIC__.mgc ,
105 or the files in the directory
106 .Pa __MAGIC__
107 if the compiled file does not exist.
108 In addition, if
109 .Pa $HOME/.magic.mgc
110 or
111 .Pa $HOME/.magic
112 exists, it will be used in preference to the system magic files.
113 .Pp
114 If a file does not match any of the entries in the magic file,
115 it is examined to see if it seems to be a text file.
116 ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets
117 (such as those used on Macintosh and IBM PC systems),
118 UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC
119 character sets can be distinguished by the different
120 ranges and sequences of bytes that constitute printable text
121 in each set.
122 If a file passes any of these tests, its character set is reported.
123 ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified
124 as
125 .Dq text
126 because they will be mostly readable on nearly any terminal;
127 UTF-16 and EBCDIC are only
128 .Dq character data
129 because, while
130 they contain text, it is text that will require translation
131 before it can be read.
132 In addition,
133 .Nm
134 will attempt to determine other characteristics of text-type files.
135 If the lines of a file are terminated by CR, CRLF, or NEL, instead
136 of the Unix-standard LF, this will be reported.
137 Files that contain embedded escape sequences or overstriking
138 will also be identified.
139 .Pp
140 Once
141 .Nm
142 has determined the character set used in a text-type file,
143 it will
144 attempt to determine in what language the file is written.
145 The language tests look for particular strings (cf.
146 .In names.h )
147 that can appear anywhere in the first few blocks of a file.
148 For example, the keyword
149 .Em .br
150 indicates that the file is most likely a
151 .Xr troff 1
152 input file, just as the keyword
153 .Em struct
154 indicates a C program.
155 These tests are less reliable than the previous
156 two groups, so they are performed last.
157 The language test routines also test for some miscellany
158 (such as
159 .Xr tar 1
160 archives).
161 .Pp
162 Any file that cannot be identified as having been written
163 in any of the character sets listed above is simply said to be
164 .Dq data .
165 .Sh OPTIONS
166 .Bl -tag -width indent
167 .It Fl b , Fl Fl brief
168 Do not prepend filenames to output lines (brief mode).
169 .It Fl C , Fl Fl compile
170 Write a
171 .Pa magic.mgc
172 output file that contains a pre-parsed version of the magic file or directory.
173 .It Fl c , Fl Fl checking-printout
174 Cause a checking printout of the parsed form of the magic file.
175 This is usually used in conjunction with the
176 .Fl m
177 flag to debug a new magic file before installing it.
178 .It Fl e , Fl Fl exclude Ar testname
179 Exclude the test named in
180 .Ar testname
181 from the list of tests made to determine the file type.
182 Valid test names are:
183 .Bl -tag -width compress
184 .It apptype
185 .Dv EMX
186 application type (only on EMX).
187 .It ascii
188 Various types of text files (this test will try to guess the text
189 encoding, irrespective of the setting of the
190 .Sq encoding
191 option).
192 .It encoding
193 Different text encodings for soft magic tests.
194 .It tokens
195 Ignored for backwards compatibility.
196 .It cdf
197 Prints details of Compound Document Files.
198 .It compress
199 Checks for, and looks inside, compressed files.
200 .It elf
201 Prints ELF file details.
202 .It soft
203 Consults magic files.
204 .It tar
205 Examines tar files.
206 .El
207 .It Fl F , Fl Fl separator Ar separator
208 Use the specified string as the separator between the filename and the
209 file result returned.
210 Defaults to
211 .Sq \&: .
212 .It Fl f , Fl Fl files-from Ar namefile
213 Read the names of the files to be examined from
214 .Ar namefile
215 (one per line)
216 before the argument list.
217 Either
218 .Ar namefile
219 or at least one filename argument must be present;
220 to test the standard input, use
221 .Sq -
222 as a filename argument.
223 Please note that 
224 .Ar namefile 
225 is unwrapped and the enclosed filenames are processed when this option is
226 encountered and before any further options processing is done.
227 This allows one to process multiple lists of files with different command line
228 arguments on the same
229 .Nm
230 invocation.
231 Thus if you want to set the delimiter, you need to do it before you specify
232 the list of files, like:
233 .Dq Fl F Ar @ Fl f Ar namefile ,
234 instead of:
235 .Dq Fl f Ar namefile Fl F Ar @ .
236 .It Fl h , Fl Fl no-dereference
237 option causes symlinks not to be followed
238 (on systems that support symbolic links).
239 This is the default if the environment variable
240 .Dv POSIXLY_CORRECT
241 is not defined.
242 .It Fl i , Fl Fl mime
243 Causes the file command to output mime type strings rather than the more
244 traditional human readable ones.
245 Thus it may say
246 .Sq text/plain; charset=us-ascii
247 rather than
248 .Dq ASCII text .
249 .It Fl Fl mime-type , Fl Fl mime-encoding
250 Like
251 .Fl i ,
252 but print only the specified element(s).
253 .It Fl k , Fl Fl keep-going
254 Don't stop at the first match, keep going.
255 Subsequent matches will be
256 have the string
257 .Sq "\[rs]012\- "
258 prepended.
259 (If you want a newline, see the
260 .Fl r
261 option.)
262 .It Fl l , Fl Fl list
263 Print information about the strength of each magic pattern.
264 .It Fl L , Fl Fl dereference
265 option causes symlinks to be followed, as the like-named option in
266 .Xr ls 1
267 (on systems that support symbolic links).
268 This is the default if the environment variable
269 .Ev POSIXLY_CORRECT
270 is defined.
271 .It Fl l
272 Shows sorted patterns list in the order which is used for the matching.
273 .It Fl m , Fl Fl magic-file Ar magicfiles
274 Specify an alternate list of files and directories containing magic.
275 This can be a single item, or a colon-separated list.
276 If a compiled magic file is found alongside a file or directory,
277 it will be used instead.
278 .It Fl N , Fl Fl no-pad
279 Don't pad filenames so that they align in the output.
280 .It Fl n , Fl Fl no-buffer
281 Force stdout to be flushed after checking each file.
282 This is only useful if checking a list of files.
283 It is intended to be used by programs that want filetype output from a pipe.
284 .It Fl p , Fl Fl preserve-date
285 On systems that support
286 .Xr utime 3
287 or
288 .Xr utimes 2 ,
289 attempt to preserve the access time of files analyzed, to pretend that
290 .Nm
291 never read them.
292 .It Fl r , Fl Fl raw
293 Don't translate unprintable characters to \eooo.
294 Normally
295 .Nm
296 translates unprintable characters to their octal representation.
297 .It Fl s , Fl Fl special-files
298 Normally,
299 .Nm
300 only attempts to read and determine the type of argument files which
301 .Xr stat 2
302 reports are ordinary files.
303 This prevents problems, because reading special files may have peculiar
304 consequences.
305 Specifying the
306 .Fl s
307 option causes
308 .Nm
309 to also read argument files which are block or character special files.
310 This is useful for determining the filesystem types of the data in raw
311 disk partitions, which are block special files.
312 This option also causes
313 .Nm
314 to disregard the file size as reported by
315 .Xr stat 2
316 since on some systems it reports a zero size for raw disk partitions.
317 .It Fl v , Fl Fl version
318 Print the version of the program and exit.
319 .It Fl z , Fl Fl uncompress
320 Try to look inside compressed files.
321 .It Fl 0 , Fl Fl print0
322 Output a null character
323 .Sq \e0
324 after the end of the filename.
325 Nice to
326 .Xr cut 1
327 the output.
328 This does not affect the separator which is still printed.
329 .It Fl -help
330 Print a help message and exit.
331 .El
332 .Sh FILES
333 .Bl -tag -width __MAGIC__.mgc -compact
334 .It Pa __MAGIC__.mgc
335 Default compiled list of magic.
336 .It Pa __MAGIC__
337 Directory containing default magic files.
338 .El
339 .Sh ENVIRONMENT
340 The environment variable
341 .Ev MAGIC
342 can be used to set the default magic file name.
343 If that variable is set, then
344 .Nm
345 will not attempt to open
346 .Pa $HOME/.magic .
347 .Nm
348 adds
349 .Dq Pa .mgc
350 to the value of this variable as appropriate.
351 However,
352 .Pa file
353 has to exist in order for
354 .Pa file.mime
355 to be considered.
356 The environment variable
357 .Ev POSIXLY_CORRECT
358 controls (on systems that support symbolic links), whether
359 .Nm
360 will attempt to follow symlinks or not.
361 If set, then
362 .Nm
363 follows symlink, otherwise it does not.
364 This is also controlled by the
365 .Fl L
366 and
367 .Fl h
368 options.
369 .Sh SEE ALSO
370 .Xr magic __FSECTION__ ,
371 .Xr hexdump 1 ,
372 .Xr od 1 ,
373 .Xr strings 1 ,
374 .Sh STANDARDS CONFORMANCE
375 This program is believed to exceed the System V Interface Definition
376 of FILE(CMD), as near as one can determine from the vague language
377 contained therein.
378 Its behavior is mostly compatible with the System V program of the same name.
379 This version knows more magic, however, so it will produce
380 different (albeit more accurate) output in many cases.
381 .\" URL: http://www.opengroup.org/onlinepubs/009695399/utilities/file.html
382 .Pp
383 The one significant difference
384 between this version and System V
385 is that this version treats any white space
386 as a delimiter, so that spaces in pattern strings must be escaped.
387 For example,
388 .Bd -literal -offset indent
389 \*[Gt]10        string  language impress\       (imPRESS data)
390 .Ed
391 .Pp
392 in an existing magic file would have to be changed to
393 .Bd -literal -offset indent
394 \*[Gt]10        string  language\e impress      (imPRESS data)
395 .Ed
396 .Pp
397 In addition, in this version, if a pattern string contains a backslash,
398 it must be escaped.
399 For example
400 .Bd -literal -offset indent
401 0       string          \ebegindata     Andrew Toolkit document
402 .Ed
403 .Pp
404 in an existing magic file would have to be changed to
405 .Bd -literal -offset indent
406 0       string          \e\ebegindata   Andrew Toolkit document
407 .Ed
408 .Pp
409 SunOS releases 3.2 and later from Sun Microsystems include a
410 .Nm
411 command derived from the System V one, but with some extensions.
412 This version differs from Sun's only in minor ways.
413 It includes the extension of the
414 .Sq \*[Am]
415 operator, used as,
416 for example,
417 .Bd -literal -offset indent
418 \*[Gt]16        long\*[Am]0x7fffffff    \*[Gt]0         not stripped
419 .Ed
420 .Sh MAGIC DIRECTORY
421 The magic file entries have been collected from various sources,
422 mainly USENET, and contributed by various authors.
423 Christos Zoulas (address below) will collect additional
424 or corrected magic file entries.
425 A consolidation of magic file entries
426 will be distributed periodically.
427 .Pp
428 The order of entries in the magic file is significant.
429 Depending on what system you are using, the order that
430 they are put together may be incorrect.
431 If your old
432 .Nm
433 command uses a magic file,
434 keep the old magic file around for comparison purposes
435 (rename it to
436 .Pa __MAGIC__.orig ) .
437 .Sh EXAMPLES
438 .Bd -literal -offset indent
439 $ file file.c file /dev/{wd0a,hda}
440 file.c:   C program text
441 file:     ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV),
442           dynamically linked (uses shared libs), stripped
443 /dev/wd0a: block special (0/0)
444 /dev/hda: block special (3/0)
445
446 $ file -s /dev/wd0{b,d}
447 /dev/wd0b: data
448 /dev/wd0d: x86 boot sector
449
450 $ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10}
451 /dev/hda:   x86 boot sector
452 /dev/hda1:  Linux/i386 ext2 filesystem
453 /dev/hda2:  x86 boot sector
454 /dev/hda3:  x86 boot sector, extended partition table
455 /dev/hda4:  Linux/i386 ext2 filesystem
456 /dev/hda5:  Linux/i386 swap file
457 /dev/hda6:  Linux/i386 swap file
458 /dev/hda7:  Linux/i386 swap file
459 /dev/hda8:  Linux/i386 swap file
460 /dev/hda9:  empty
461 /dev/hda10: empty
462
463 $ file -i file.c file /dev/{wd0a,hda}
464 file.c:      text/x-c
465 file:        application/x-executable
466 /dev/hda:    application/x-not-regular-file
467 /dev/wd0a:   application/x-not-regular-file
468
469 .Ed
470 .Sh HISTORY
471 There has been a
472 .Nm
473 command in every
474 .Dv UNIX since at least Research Version 4
475 (man page dated November, 1973).
476 The System V version introduced one significant major change:
477 the external list of magic types.
478 This slowed the program down slightly but made it a lot more flexible.
479 .Pp
480 This program, based on the System V version,
481 was written by Ian Darwin
482 .Aq ian@darwinsys.com
483 without looking at anybody else's source code.
484 .Pp
485 John Gilmore revised the code extensively, making it better than
486 the first version.
487 Geoff Collyer found several inadequacies
488 and provided some magic file entries.
489 Contributions by the
490 .Sq \*[Am]
491 operator by Rob McMahon, 
492 .Aq cudcv@warwick.ac.uk ,
493 1989.
494 .Pp
495 Guy Harris, 
496 .Aq guy@netapp.com ,
497 made many changes from 1993 to the present.
498 1989.
499 .Pp
500 Primary development and maintenance from 1990 to the present by
501 Christos Zoulas
502 .Aq christos@astron.com .
503 .Pp
504 Altered by Chris Lowth
505 .Aq chris@lowth.com ,
506 2000: handle the
507 .Fl i
508 option to output mime type strings, using an alternative
509 magic file and internal logic.
510 .Pp
511 Altered by Eric Fischer
512 .Aq enf@pobox.com ,
513 July, 2000,
514 to identify character codes and attempt to identify the languages
515 of non-ASCII files.
516 .Pp
517 Altered by Reuben Thomas
518 .Aq rrt@sc3d.org ,
519 2007-2011, to improve MIME support, merge MIME and non-MIME magic,
520 support directories as well as files of magic, apply many bug fixes,
521 update and fix a lot of magic, improve the build system, improve the
522 documentation, and rewrite the Python bindings in pure Python.
523 .Pp
524 The list of contributors to the
525 .Sq magic
526 directory (magic files)
527 is too long to include here.
528 You know who you are; thank you.
529 Many contributors are listed in the source files.
530 .Sh LEGAL NOTICE
531 Copyright (c) Ian F. Darwin, Toronto, Canada, 1986-1999.
532 Covered by the standard Berkeley Software Distribution copyright; see the file
533 COPYING in the source distribution.
534 .Pp
535 The files
536 .Pa tar.h
537 and
538 .Pa is_tar.c
539 were written by John Gilmore from his public-domain
540 .Xr tar 1
541 program, and are not covered by the above license.
542 .Sh RETURN CODE
543 .Nm
544 returns 0 on success, and non-zero on error.
545 .Sh BUGS
546 .Pp
547 Please report bugs and send patches to the bug tracker at
548 .Pa http://bugs.gw.com/
549 or the mailing list at
550 .Aq file@mx.gw.com .
551 .Sh TODO
552 .Pp
553 Fix output so that tests for MIME and APPLE flags are not needed all
554 over the place, and actual output is only done in one place. This
555 needs a design. Suggestion: push possible outputs on to a list, then
556 pick the last-pushed (most specific, one hopes) value at the end, or
557 use a default if the list is empty. This should not slow down evaluation.
558 .Pp
559 Continue to squash all magic bugs. See Debian BTS for a good source.
560 .Pp
561 Store arbitrarily long strings, for example for %s patterns, so that
562 they can be printed out. Fixes Debian bug #271672. Would require more
563 complex store/load code in apprentice.
564 .Pp
565 Add syntax for relative offsets after current level (Debian bug #466037).
566 .Pp
567 Make file -ki work, i.e. give multiple MIME types.
568 .Pp
569 Add a zip library so we can peek inside Office2007 documents to
570 figure out what they are.
571 .Pp
572 Add an option to print URLs for the sources of the file descriptions.
573 .Sh AVAILABILITY
574 You can obtain the original author's latest version by anonymous FTP
575 on
576 .Pa ftp.astron.com
577 in the directory
578 .Pa /pub/file/file-X.YZ.tar.gz .