summaryrefslogtreecommitdiffstats
path: root/contrib/file/file.man
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/file/file.man')
-rw-r--r--contrib/file/file.man476
1 files changed, 476 insertions, 0 deletions
diff --git a/contrib/file/file.man b/contrib/file/file.man
new file mode 100644
index 0000000..198a14c
--- /dev/null
+++ b/contrib/file/file.man
@@ -0,0 +1,476 @@
+.TH FILE __CSECTION__ "Copyright but distributable"
+.\" $Id: file.man,v 1.36 2000/08/05 17:36:48 christos Exp $
+.SH NAME
+file
+\- determine file type
+.SH SYNOPSIS
+.B file
+[
+.B \-bciknsvzL
+]
+[
+.B \-f
+namefile ]
+[
+.B \-m
+magicfiles ]
+file ...
+.SH DESCRIPTION
+This manual page documents version __VERSION__ of the
+.B file
+command.
+.PP
+.B 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
+printing characters and a few common control
+characters and is probably safe to read on an
+.SM 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 __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 Berkeley did and change ``shell commands text''
+to ``shell script''.
+.PP
+The filesystem tests are based on examining the return from a
+.BR 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, symbolic links, or named pipes (FIFOs) on those systems that
+implement them)
+are intuited if they are defined in
+the system header file
+.IR <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 identifying these files is read from the magic file
+.I __MAGIC__.
+.PP
+If a file does not match any of the entries in the magic file,
+it is examined to see if it seems to be a text file.
+ASCII, ISO-8859-x, non-ISO 8-bit extended-ASCII character sets
+(such as those used on Macintosh and IBM PC systems),
+UTF-8-encoded Unicode, UTF-16-encoded Unicode, and EBCDIC
+character sets can be distinguished by the different
+ranges and sequences of bytes that constitute printable text
+in each set.
+If a file passes any of these tests, its character set is reported.
+ASCII, ISO-8859-x, UTF-8, and extended-ASCII files are identified
+as ``text'' because they will be mostly readable on nearly any terminal;
+UTF-16 and EBCDIC are only ``character data'' because, while
+they contain text, it is text that will require translation
+before it can be read.
+In addition,
+.B file
+will attempt to determine other characteristics of text-type files.
+If the lines of a file are terminated by CR, CRLF, or NEL, instead
+of the Unix-standard LF, this will be reported.
+Files that contain embedded escape sequences or overstriking
+will also be identified.
+.PP
+Once
+.B file
+has determined the character set used in a text-type file,
+it will
+attempt to determine in what language the file is written.
+The language tests look for particular strings (cf
+.IR names.h )
+that can appear anywhere in the first few blocks of a file.
+For example, the keyword
+.B .br
+indicates that the file is most likely a
+.BR troff (1)
+input file, just as the keyword
+.B 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
+.BR tar (1)
+archives).
+.PP
+Any file that cannot be identified as having been written
+in any of the character sets listed above is simply said to be ``data''.
+.SH OPTIONS
+.TP 8
+.B \-b
+Do not prepend filenames to output lines (brief mode).
+.TP 8
+.B \-c
+Cause 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.
+.TP 8
+.B \-f namefile
+Read the names of the files to be examined from
+.I namefile
+(one per line)
+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.
+.TP 8
+.B \-i
+Causes the file command to output mime type strings rather than the more
+traditional human readable ones. Thus it may say
+``text/plain; charset=us-ascii''
+rather
+than ``ASCII text''. In order for this option to work, file changes the way
+it handles files recognised by the command it's self (such as many of the
+text file types, directories etc), and makes use of an alternative
+``magic'' file.
+(See ``FILES'' section, below).
+.TP 8
+.B \-k
+Don't stop at the first match, keep going.
+.TP 8
+.B \-m list
+Specify an alternate list of files containing magic numbers.
+This can be a single file, or a colon-separated list of files.
+.TP 8
+.B \-n
+Force stdout to be flushed after check a file. This is only useful if
+checking a list of files. It is intended to be used by programs want
+filetype output from a pipe.
+.TP 8
+.B \-v
+Print the version of the program and exit.
+.TP 8
+.B \-z
+Try to look inside compressed files.
+.TP 8
+.B \-L
+option causes symlinks to be followed, as the like-named option in
+.BR ls (1).
+(on systems that support symbolic links).
+.TP 8
+.B \-s
+Normally,
+.B file
+only attempts to read and determine the type of argument files which
+.BR stat (2)
+reports are ordinary files.
+This prevents problems, because reading special files may have peculiar
+consequences.
+Specifying the
+.BR \-s
+option causes
+.B file
+to also read argument files which are block or character special files.
+This is useful for determining the filesystem types of the data in raw
+disk partitions, which are block special files.
+This option also causes
+.B file
+to disregard the file size as reported by
+.BR stat (2)
+since on some systems it reports a zero size for raw disk partitions.
+.SH FILES
+.I __MAGIC__
+\- default list of magic numbers
+.PP
+.I __MAGIC__.mime
+\- default list of magic numbers, used to output mime types when the -i option
+is specified.
+
+.SH ENVIRONMENT
+The environment variable
+.B MAGIC
+can be used to set the default magic number files.
+.SH SEE ALSO
+.BR magic (__FSECTION__)
+\- description of magic file format.
+.br
+.BR strings (1), " od" (1), " hexdump(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)
+.br
+In addition, in this version, if a pattern string contains a backslash,
+it must be escaped. For example
+.br
+0 string \ebegindata Andrew Toolkit document
+.br
+in an existing magic file would have to be changed to
+.br
+0 string \e\ebegindata Andrew Toolkit document
+.br
+.PP
+SunOS releases 3.2 and later from Sun Microsystems include a
+.BR file (1)
+command derived from the System V one, but with some extensions.
+My version differs from Sun's only in minor ways.
+It includes the extension of the `&' operator, used as,
+for example,
+.br
+>16 long&0x7fffffff >0 not stripped
+.SH MAGIC DIRECTORY
+The magic file entries have been collected from various sources,
+mainly USENET, and contributed by various authors.
+Christos Zoulas (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
+.B file
+command uses a magic file,
+keep the old magic file around for comparison purposes
+(rename it to
+.IR __MAGIC__.orig ).
+.SH EXAMPLES
+.nf
+$ file file.c file /dev/hda
+file.c: C program text
+file: ELF 32-bit LSB executable, Intel 80386, version 1,
+ dynamically linked, not stripped
+/dev/hda: block special
+
+$ file -s /dev/hda{,1,2,3,4,5,6,7,8,9,10}
+/dev/hda: x86 boot sector
+/dev/hda1: Linux/i386 ext2 filesystem
+/dev/hda2: x86 boot sector
+/dev/hda3: x86 boot sector, extended partition table
+/dev/hda4: Linux/i386 ext2 filesystem
+/dev/hda5: Linux/i386 swap file
+/dev/hda6: Linux/i386 swap file
+/dev/hda7: Linux/i386 swap file
+/dev/hda8: Linux/i386 swap file
+/dev/hda9: empty
+/dev/hda10: empty
+
+$ file -i file.c file /dev/hda
+file.c: text/x-c
+file: application/x-executable, dynamically linked (uses shared libs), not stripped
+/dev/hda: application/x-not-regular-file
+
+.fi
+.SH HISTORY
+There has been a
+.B file
+command in every \s-1UNIX\s0 since at least Research Version 6
+(man page dated January 16, 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 AUTHOR
+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
+Altered by Rob McMahon, cudcv@warwick.ac.uk, 1989, to extend the `&' operator
+from simple `x&y != 0' to `x&y op z'.
+.PP
+Altered by Guy Harris, guy@netapp.com, 1993, to:
+.RS
+.PP
+put the ``old-style'' `&'
+operator back the way it was, because 1) Rob McMahon's change broke the
+previous style of usage, 2) the SunOS ``new-style'' `&' operator,
+which this version of
+.B file
+supports, also handles `x&y op z', and 3) Rob's change wasn't documented
+in any case;
+.PP
+put in multiple levels of `>';
+.PP
+put in ``beshort'', ``leshort'', etc. keywords to look at numbers in the
+file in a specific byte order, rather than in the native byte order of
+the process running
+.BR file .
+.RE
+.PP
+Changes by Ian Darwin and various authors including
+Christos Zoulas (christos@astron.com), 1990-1999.
+.PP
+Altered by Chris Lowth, chris@lowth.com, 2000:
+Handle the ``-i'' option to output mime type strings and using an alternative
+magic file and internal logic.
+.PP
+Altered by Eric Fischer (enf@pobox.com), July, 2000,
+to identify character codes and attempt to identify the languages
+of non-ASCII files.
+.SH LEGAL NOTICE
+Copyright (c) Ian F. Darwin, Toronto, Canada,
+1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993.
+.PP
+This software is not subject to and may not be made subject to any
+license of the American Telephone and Telegraph Company, Sun
+Microsystems Inc., Digital Equipment Inc., Lotus Development Inc., the
+Regents of the University of California, The X Consortium or MIT, or
+The Free Software Foundation.
+.PP
+This software is not subject to any export provision of the United States
+Department of Commerce, and may be exported to any country or planet.
+.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.
+.\"
+.\" enf: commented out because these support files don't seem to be included
+.PP
+The files
+.I tar.h
+and
+.I is_tar.c
+were written by John Gilmore from his public-domain
+.B tar
+program, and are not covered by the above restrictions.
+.SH BUGS
+There must be a better way to automate the construction of the Magic
+file from all the glop in Magdir. What is it?
+Better yet, the magic file should be compiled into binary (say,
+.BR ndbm (3)
+or, better yet, fixed-length
+.SM 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.
+.PP
+.B File
+uses several algorithms that favor speed over accuracy,
+thus it can be misled about the contents of
+text
+files.
+.PP
+The support for
+text
+files (primarily for programming languages)
+is simplistic, inefficient and requires recompilation to update.
+.PP
+There should be an ``else'' clause to follow a series of continuation lines.
+.PP
+The magic file and keywords should have regular expression support.
+Their use of
+.SM "ASCII TAB"
+as a field delimiter is ugly and makes
+it hard to edit the files, but is entrenched.
+.PP
+It might be advisable to allow upper-case letters in keywords
+for e.g.,
+.BR troff (1)
+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
+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
+This program is slower than some vendors' file commands.
+The new support for multiple character codes makes it even slower.
+.PP
+This manual page, and particularly this section, is too long.
+.SH AVAILABILITY
+You can obtain the original author's latest version by anonymous FTP
+on
+.B ftp.astron.com
+in the directory
+.I /pub/file/file-X.YY.tar.gz
OpenPOWER on IntegriCloud