+..TH FILE 1 "Copyright but distributable"
+..SH NAME
+..I file
+\- determine file type
+..SH SYNOPSIS
+..B file
+[
+..B -c
+]
+[
+..B -f
+namefile ]
+[
+..B -m
+magicfile ]
+file ...
+..SH DESCRIPTION
+..I File
+tests each argument in an attempt to classify it.
+There are three sets of tests, performed in this order:
+filesystem tests, magic number tests, and language tests.
+The
+..I first
+test that succeeds causes the file type to be printed.
+..PP
+The type printed will usually contain one of the words
+..B text
+(the file contains only ASCII characters and is
+probably safe to read on an ASCII terminal),
+..B executable
+(the file contains the result of compiling a program
+in a form understandable to some \s-1UNIX\s0 kernel or another),
+or
+..B data
+meaning anything else (data is usually `binary' or non-printable).
+Exceptions are well-known file formats (core files, tar archives)
+that are known to contain binary data.
+When modifying the file
+..I /etc/magic
+or the program itself,
+..B "preserve these keywords" .
+People depend on knowing that all the readable files in a directory
+have the word ``text'' printed.
+Don't do as one computer vendor did \- change ``shell commands text''
+to ``shell script''.
+..PP
+The filesystem tests are based on examining the return from a
+..I stat (2)
+system call.
+The program checks to see if the file is empty,
+or if it's some sort of special file.
+Any known file types appropriate to the system you are running on
+(sockets and symbolic links on 4.2BSD, named pipes (FIFOs) on System V)
+are intuited if they are defined in
+the system header file
+..I sys/stat.h .
+..PP
+The magic number tests are used to check for files with data in
+particular fixed formats.
+The canonical example of this is a binary executable (compiled program)
+..I a.out
+file, whose format is defined in
+..I a.out.h
+and possibly
+..I exec.h
+in the standard include directory.
+These files have a `magic number' stored in a particular place
+near the beginning of the file that tells the \s-1UNIX\s0 operating system
+that the file is a binary executable, and which of several types thereof.
+The concept of `magic number' has been applied by extension to data files.
+Any file with some invariant identifier at a small fixed
+offset into the file can usually be described in this way.
+The information in these files is read from the magic file
+..I /etc/magic .
+..PP
+If an argument appears to be an
+..SM ASCII
+file,
+..I file
+attempts to guess its language.
+The language tests look for particular strings (cf \fInames.h\fP)
+that can appear anywhere in the first few blocks of a file.
+For example, the keyword
+..I .br
+indicates that the file is most likely a troff input file,
+just as the keyword
+..I struct
+indicates a C program.
+These tests are less reliable than the previous
+two groups, so they are performed last.
+The language test routines also test for some miscellany
+(such as
+..I tar
+archives) and determine whether an unknown file should be
+labelled as `ascii text' or `data'.
+..PP
+Use
+..B -m
+..I file
+to specify an alternate file of magic numbers.
+..PP
+The
+..B -c
+option causes a checking printout of the parsed form of the magic file.
+This is usually used in conjunction with
+..B -m
+to debug a new magic file before installing it.
+..PP
+The
+..B -f
+..I namefile
+option specifies that the names of the files to be examined
+are to be read (one per line) from
+..I namefile
+before the argument list.
+Either
+..I namefile
+or at least one filename argument must be present;
+to test the standard input, use ``-'' as a filename argument.
+..SH FILES
+..I /etc/magic
+\- default list of magic numbers
+..SH SEE ALSO
+..IR Magic (FILES)
+\- description of magic file format.
+..br
+..IR Strings (1), " od" (1)
+\- tools for examining non-textfiles.
+..SH STANDARDS CONFORMANCE
+This program is believed to exceed the System V Interface Definition
+of FILE(CMD), as near as one can determine from the vague language
+contained therein.
+Its behaviour is mostly compatible with the System V program of the same name.
+This version knows more magic, however, so it will produce
+different (albeit more accurate) output in many cases.
+..PP
+The one significant difference
+between this version and System V
+is that this version treats any white space
+as a delimiter, so that spaces in pattern strings must be escaped.
+For example,
+..br
+>10 string language impress\ (imPRESS data)
+..br
+in an existing magic file would have to be changed to
+..br
+>10 string language\e impress (imPRESS data)
+..PP
+The Sun Microsystems implementation of System V compatibility
+includes a file(1) command that has some extentions.
+My version differs from Sun's only in minor ways.
+The significant one is the `&' operator, which Sun's program expects as,
+for example,
+..br
+>16 long&0x7fffffff >0 not stripped
+..br
+would be entered in my version as
+..br
+>16 long &0x7fffffff not stripped
+..br
+which is a little less general; it simply tests (location 16)&0x7ffffff
+and returns its truth value as a C expression.
+..SH MAGIC DIRECTORY
+The magic file entries have been collected from various sources,
+mainly USENET, and contributed by various authors.
+Ian Darwin (address below) will collect additional
+or corrected magic file entries.
+A consolidation of magic file entries
+will be distributed periodically.
+..PP
+The order of entries in the magic file is significant.
+Depending on what system you are using, the order that
+they are put together may be incorrect.
+If your old
+..I file
+command uses a magic file,
+keep the old magic file around for comparison purposes
+(rename it to
+..IR /etc/magic.orig ).
+..SH HISTORY
+There has been a
+..I file
+command in every UNIX since at least Research Version 6
+(man page dated January, 1975).
+The System V version introduced one significant major change:
+the external list of magic number types.
+This slowed the program down slightly but made it a lot more flexible.
+..PP
+This program, based on the System V version,
+was written by Ian Darwin without looking at anybody else's source code.
+..PP
+John Gilmore revised the code extensively, making it better than
+the first version.
+Geoff Collyer found several inadequacies
+and provided some magic file entries.
+The program has undergone continued evolution since.
+..SH NOTICE
+Copyright (c) Ian F. Darwin, 1986 and 1987.
+Written by Ian F. Darwin, UUCP address {utzoo | ihnp4}!darwin!ian,
+Internet address ian@sq.com,
+postal address: P.O. Box 603, Station F, Toronto, Ontario, CANADA M4Y 2L8.
+..PP
+..I Strtok.c
+and
+..I getopt.c
+written by and copyright by Henry Spencer, utzoo!henry.
+..PP
+This software is not subject to any license of the American Telephone
+and Telegraph Company or of the Regents of the University of California.
+..PP
+Permission is granted to anyone to use this software for any purpose on
+any computer system, and to alter it and redistribute it freely, subject
+to the following restrictions:
+..PP
+1. The author is not responsible for the consequences of use of this
+software, no matter how awful, even if they arise from flaws in it.
+..PP
+2. The origin of this software must not be misrepresented, either by
+explicit claim or by omission. Since few users ever read sources,
+credits must appear in the documentation.
+..PP
+3. Altered versions must be plainly marked as such, and must not be
+misrepresented as being the original software. Since few users
+ever read sources, credits must appear in the documentation.
+..PP
+4. This notice may not be removed or altered.
+..PP
+A few support files (\fIgetopt\fP, \fIstrtok\fP)
+distributed with this package
+are by Henry Spencer and are subject to the same terms as above.
+..PP
+A few simple support files (\fIstrtol\fP, \fIstrchr\fP)
+distributed with this package
+are in the public domain; they are so marked.
+..PP
+The files
+..I tar.h
+and
+..I is_tar.c
+were written by John Gilmore from his public-domain
+..I tar
+program, and are not covered by the above restrictions.
+..SH BUGS
+There must be a way to automate the construction of the Magic
+file from all the glop in magdir. What is it?
+..PP
+..I File
+uses several algorithms that favor speed over accuracy,
+thus it can be misled about the contents of ASCII files.
+..PP
+The support for ASCII files (primarily for programming languages)
+is simplistic, inefficient and requires recompilation to update.
+..PP
+Should there be an ``else'' clause to follow a series of continuation lines?
+..PP
+Is it worthwhile to implement recursive file inspection,
+so that compressed files, uuencoded, etc., can say ``compressed
+ascii text'' or ``compressed executable'' or ``compressed tar archive"
+or whatever?
+..PP
+The magic file and keywords should have regular expression support.
+..PP
+It might be advisable to allow upper-case letters in keywords
+for e.g., troff commands vs man page macros.
+Regular expression support would make this easy.
+..PP
+The program doesn't grok \s-2FORTRAN\s0.
+It should be able to figure \s-2FORTRAN\s0 by seeing some keywords which
+appear indented at the start of line.
+Regular expression support would make this easy.
+..PP
+The list of keywords in
+..I ascmagic
+probably belongs in the Magic file.
+This could be done by using some keyword like `*' for the offset value.
+..PP
+The program should malloc the magic file structures,
+rather than using a fixed-size array as at present.
+..PP
+The magic file should be compiled into binary
+(or better yet, fixed-length ASCII strings
+for use in heterogenous network environments) for faster startup.
+Then the program would run as fast as the Version 7 program of the same name,
+with the flexibility of the System V version.
+But then there would have to be yet another magic number for the
+..I magic.out
+file.
+..PP
+Another optimisation would be to sort
+the magic file so that we can just run down all the
+tests for the first byte, first word, first long, etc, once we
+have fetched it. Complain about conflicts in the magic file entries.
+Make a rule that the magic entries sort based on file offset rather
+than position within the magic file?
+..PP
+The program should provide a way to give an estimate
+of ``how good'' a guess is.
+We end up removing guesses (e.g. ``From '' as first 5 chars of file) because
+they are not as good as other guesses (e.g. ``Newsgroups:'' versus
+"Return-Path:"). Still, if the others don't pan out, it should be
+possible to use the first guess.
+..PP
+Perhaps the program should automatically try all tests with
+byte-swapping done, to avoid having to figure out the byte-swapped values
+when constructing the magic file.
+Of course this will run more slowly, so it should probably be
+an option (-a?).
+..PP
+This manual page, and particularly this section, is too long.
projects / unix-history / commitdiff