Merge branch 'vendor/MDOCML'
[dragonfly.git] / contrib / file / README
CommitLineData
ab0b56cc 1** README for file(1) Command **
ff91a668 2@(#) $File: README,v 1.44 2011/03/24 13:03:39 rrt Exp $
ab0b56cc 3
79343712 4Mailing List: file@mx.gw.com
e4d4ce0c
PA
5Bug tracker: http://bugs.gw.com/
6E-mail: christos@astron.com
79343712
PA
7
8Phone: Do not even think of telephoning me about this program. Send cash first!
9
10This is Release 5.x of Ian Darwin's (copyright but distributable)
e4d4ce0c
PA
11file(1) command, an implementation of the Unix File(1) command.
12It knows the 'magic number' of several thousands of file types.
13This version is the standard "file" command for Linux,
ab0b56cc
JS
14*BSD, and other systems. (See "patchlevel.h" for the exact release number).
15
e4d4ce0c
PA
16You can download the latest version of file from:
17
18 ftp://ftp.astron.com/pub/file/
19
ff91a668
PA
20A public read-only git repository is available at:
21
22 https://github.com/glensc/file
23
79343712
PA
24The major changes for 5.x are CDF file parsing, indirect magic, and
25overhaul in mime and ascii encoding handling.
26
ab0b56cc
JS
27The major feature of 4.x is the refactoring of the code into a library,
28and the re-write of the file command in terms of that library. The library
29itself, libmagic can be used by 3rd party programs that wish to identify
30file types without having to fork() and exec() file. The prime contributor
31for 4.0 was M\xe5ns Rullg\xe5rd.
32
33UNIX is a trademark of UNIX System Laboratories.
34
35The prime contributor to Release 3.8 was Guy Harris, who put in megachanges
36including byte-order independence.
37
38The prime contributor to Release 3.0 was Christos Zoulas, who put
39in hundreds of lines of source code changes, including his own
40ANSIfication of the code (I liked my own ANSIfication better, but
41his (__P()) is the "Berkeley standard" way of doing it, and I wanted UCB
42to include the code...), his HP-like "indirection" (a feature of
43the HP file command, I think), and his mods that finally got the
44uncompress (-z) mode finished and working.
45
46This release has compiled in numerous environments; see PORTING
47for a list and problems.
48
49This fine freeware file(1) follows the USG (System V) model of the file
50command, rather than the Research (V7) version or the V7-derived 4.[23]
51Berkeley one. That is, the file /etc/magic contains much of the ritual
52information that is the source of this program's power. My version
53knows a little more magic (including tar archives) than System V; the
54/etc/magic parsing seems to be compatible with the (poorly documented)
55System V /etc/magic format (with one exception; see the man page).
56
57In addition, the /etc/magic file is built from a subdirectory
58for easier(?) maintenance. I will act as a clearinghouse for
59magic numbers assigned to all sorts of data files that
60are in reasonable circulation. Send your magic numbers,
61in magic(5) format please, to the maintainer, Christos Zoulas.
62
79343712 63COPYING - read this first.
ab0b56cc 64README - read this second (you are currently reading this file).
79343712
PA
65INSTALL - read on how to install
66
67src/apprentice.c - parses /etc/magic to learn magic
68src/apptype.c - used for OS/2 specific application type magic
69src/asprintf.c - replacement for OS's that don't have it.
70src/ascmagic.c - third & last set of tests, based on hardwired assumptions.
71src/cdf.c - parser for Microsoft Compound Document Files
72src/cdf_time.c - time converter for CDF.
73src/compress.c - handles decompressing files to look inside.
74src/encoding.c - handles unicode encodings
75src/file.c - the main program
76src/file.h - header file
77src/fsmagic.c - first set of tests the program runs, based on filesystem info
78src/funcs.c - utilility functions
79src/getopt_long.c - used for OS/2 specific application type magic
80src/is_tar.c, tar.h - knows about tarchives (courtesy John Gilmore).
81src/names.h - header file for ascmagic.c
82src/magic.c - the libmagic api
83src/print.c - print results, errors, warnings.
84src/readcdf.c - CDF wrapper.
85src/readelf.[ch] - Stand-alone elf parsing code.
86src/softmagic.c - 2nd set of tests, based on /etc/magic
87src/strlcat.c - used for OS/2 specific application type magic
88src/strlcpy.c - used for OS/2 specific application type magic
89src/vasprintf.c - used for OS/2 specific application type magic
90doc/file.1 - man page for the command
91doc/magic.4 - man page for the magic file, courtesy Guy Harris.
ab0b56cc 92 Install as magic.4 on USG and magic.5 on V7 or Berkeley; cf Makefile.
79343712
PA
93Magdir - directory of /etc/magic pieces
94
95------------------------------------------------------------------------------
96
97If you submit a new magic entry please make sure you read the following
98guidelines:
99
100- Initial match is preferably at least 32 bits long, and is a _unique_ match
101- If this is not feasible, use additional check
102- Match of <= 16 bits are not accepted
103- Delay printing string as much as possible, don't print output too early
104- Avoid printf arbitrary byte as string, which can be a source of
105 crash and buffer overflow
106
107- Provide complete information with entry:
108 * One line short summary
109 * Optional long description
110 * File extension, if applicable
111 * Full name and contact method (for discussion when entry has problem)
112 * Further reference, such as documentation of format
113
114------------------------------------------------------------------------------
115
ab0b56cc
JS
116Parts of this software were developed at SoftQuad Inc., developers
117of SGML/HTML/XML publishing software, in Toronto, Canada.
e4d4ce0c 118SoftQuad was swallowed up by Corel in 2002 and does not exist any longer.