Annotation of src/usr.bin/file/file.1, Revision 1.1.1.1
1.1 deraadt 1: .TH FILE 1 "Copyright but distributable"
2: .\" $Id: file.1,v 1.7 1995/03/25 22:35:42 christos Exp $
3: .SH NAME
4: file
5: \- determine file type
6: .SH SYNOPSIS
7: .B file
8: [
9: .B \-vczL
10: ]
11: [
12: .B \-f
13: namefile ]
14: [
15: .B \-m
16: magicfile ]
17: file ...
18: .SH DESCRIPTION
19: .I File
20: tests each argument in an attempt to classify it.
21: There are three sets of tests, performed in this order:
22: filesystem tests, magic number tests, and language tests.
23: The
24: .I first
25: test that succeeds causes the file type to be printed.
26: .PP
27: The type printed will usually contain one of the words
28: .B text
29: (the file contains only ASCII characters and is
30: probably safe to read on an ASCII terminal),
31: .B executable
32: (the file contains the result of compiling a program
33: in a form understandable to some \s-1UNIX\s0 kernel or another),
34: or
35: .B data
36: meaning anything else (data is usually `binary' or non-printable).
37: Exceptions are well-known file formats (core files, tar archives)
38: that are known to contain binary data.
39: When modifying the file
40: .I /etc/magic
41: or the program itself,
42: .B "preserve these keywords" .
43: People depend on knowing that all the readable files in a directory
44: have the word ``text'' printed.
45: Don't do as Berkeley did \- change ``shell commands text''
46: to ``shell script''.
47: .PP
48: The filesystem tests are based on examining the return from a
49: .IR stat (2)
50: system call.
51: The program checks to see if the file is empty,
52: or if it's some sort of special file.
53: Any known file types appropriate to the system you are running on
54: (sockets, symbolic links, or named pipes (FIFOs) on those systems that
55: implement them)
56: are intuited if they are defined in
57: the system header file
58: .BR sys/stat.h .
59: .PP
60: The magic number tests are used to check for files with data in
61: particular fixed formats.
62: The canonical example of this is a binary executable (compiled program)
63: .B a.out
64: file, whose format is defined in
65: .B a.out.h
66: and possibly
67: .B exec.h
68: in the standard include directory.
69: These files have a `magic number' stored in a particular place
70: near the beginning of the file that tells the \s-1UNIX\s0 operating system
71: that the file is a binary executable, and which of several types thereof.
72: The concept of `magic number' has been applied by extension to data files.
73: Any file with some invariant identifier at a small fixed
74: offset into the file can usually be described in this way.
75: The information in these files is read from the magic file
76: .I /etc/magic.
77: .PP
78: If an argument appears to be an
79: .SM ASCII
80: file,
81: .I file
82: attempts to guess its language.
83: The language tests look for particular strings (cf \fInames.h\fP)
84: that can appear anywhere in the first few blocks of a file.
85: For example, the keyword
86: .B .br
87: indicates that the file is most likely a troff input file,
88: just as the keyword
89: .B struct
90: indicates a C program.
91: These tests are less reliable than the previous
92: two groups, so they are performed last.
93: The language test routines also test for some miscellany
94: (such as
95: .I tar
96: archives) and determine whether an unknown file should be
97: labelled as `ascii text' or `data'.
98: .SH OPTIONS
99: .TP 8
100: .B \-v
101: Print the version of the program and exit.
102: .TP 8
103: .B \-m file
104: Specify an alternate file of magic numbers.
105: .TP 8
106: .B \-z
107: Try to look inside compressed files.
108: .TP 8
109: .B \-c
110: Cause a checking printout of the parsed form of the magic file.
111: This is usually used in conjunction with
112: .B \-m
113: to debug a new magic file before installing it.
114: .TP 8
115: .B \-f namefile
116: Read the names of the files to be examined from
117: .I namefile
118: (one per line)
119: before the argument list.
120: Either
121: .I namefile
122: or at least one filename argument must be present;
123: to test the standard input, use ``-'' as a filename argument.
124: .TP 8
125: .B \-L
126: option causes symlinks to be followed, as the like-named option in
127: .IR ls (1).
128: (on systems that support symbolic links).
129: .SH FILES
130: .I /etc/magic
131: \- default list of magic numbers
132: .SH SEE ALSO
133: .IR magic (5)
134: \- description of magic file format.
135: .br
136: .IR Strings (1), " od" (1)
137: \- tools for examining non-textfiles.
138: .SH STANDARDS CONFORMANCE
139: This program is believed to exceed the System V Interface Definition
140: of FILE(CMD), as near as one can determine from the vague language
141: contained therein.
142: Its behaviour is mostly compatible with the System V program of the same name.
143: This version knows more magic, however, so it will produce
144: different (albeit more accurate) output in many cases.
145: .PP
146: The one significant difference
147: between this version and System V
148: is that this version treats any white space
149: as a delimiter, so that spaces in pattern strings must be escaped.
150: For example,
151: .br
152: >10 string language impress\ (imPRESS data)
153: .br
154: in an existing magic file would have to be changed to
155: .br
156: >10 string language\e impress (imPRESS data)
157: .br
158: In addition, in this version, if a pattern string contains a backslash,
159: it must be escaped. For example
160: .br
161: 0 string \ebegindata Andrew Toolkit document
162: .br
163: in an existing magic file would have to be changed to
164: .br
165: 0 string \e\ebegindata Andrew Toolkit document
166: .br
167: .PP
168: SunOS releases 3.2 and later from Sun Microsystems include a
169: .IR file (1)
170: command derived from the System V one, but with some extensions.
171: My version differs from Sun's only in minor ways.
172: It includes the extension of the `&' operator, used as,
173: for example,
174: .br
175: >16 long&0x7fffffff >0 not stripped
176: .SH MAGIC DIRECTORY
177: The magic file entries have been collected from various sources,
178: mainly USENET, and contributed by various authors.
179: Christos Zoulas (address below) will collect additional
180: or corrected magic file entries.
181: A consolidation of magic file entries
182: will be distributed periodically.
183: .PP
184: The order of entries in the magic file is significant.
185: Depending on what system you are using, the order that
186: they are put together may be incorrect.
187: If your old
188: .I file
189: command uses a magic file,
190: keep the old magic file around for comparison purposes
191: (rename it to
192: .IR /etc/magic.orig ).
193: .SH HISTORY
194: There has been a
195: .I file
196: command in every UNIX since at least Research Version 6
197: (man page dated January, 1975).
198: The System V version introduced one significant major change:
199: the external list of magic number types.
200: This slowed the program down slightly but made it a lot more flexible.
201: .PP
202: This program, based on the System V version,
203: was written by Ian Darwin without looking at anybody else's source code.
204: .PP
205: John Gilmore revised the code extensively, making it better than
206: the first version.
207: Geoff Collyer found several inadequacies
208: and provided some magic file entries.
209: The program has undergone continued evolution since.
210: .SH AUTHOR
211: Written by Ian F. Darwin, UUCP address {utzoo | ihnp4}!darwin!ian,
212: Internet address ian@sq.com,
213: postal address: P.O. Box 603, Station F, Toronto, Ontario, CANADA M4Y 2L8.
214: .PP
215: Altered by Rob McMahon, cudcv@warwick.ac.uk, 1989, to extend the `&' operator
216: from simple `x&y != 0' to `x&y op z'.
217: .PP
218: Altered by Guy Harris, guy@auspex.com, 1993, to:
219: .RS
220: .PP
221: put the ``old-style'' `&'
222: operator back the way it was, because 1) Rob McMahon's change broke the
223: previous style of usage, 2) the SunOS ``new-style'' `&' operator,
224: which this version of
225: .I file
226: supports, also handles `x&y op z', and 3) Rob's change wasn't documented
227: in any case;
228: .PP
229: put in multiple levels of `>';
230: .PP
231: put in ``beshort'', ``leshort'', etc. keywords to look at numbers in the
232: file in a specific byte order, rather than in the native byte order of
233: the process running
234: .IR file .
235: .RE
236: .PP
237: Changes by Ian Darwin and various authors including
238: Christos Zoulas (christos@ee.cornell.edu), 1990-1992.
239: .SH LEGAL NOTICE
240: Copyright (c) Ian F. Darwin, Toronto, Canada,
241: 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993.
242: .PP
243: This software is not subject to and may not be made subject to any
244: license of the American Telephone and Telegraph Company, Sun
245: Microsystems Inc., Digital Equipment Inc., Lotus Development Inc., the
246: Regents of the University of California, The X Consortium or MIT, or
247: The Free Software Foundation.
248: .PP
249: This software is not subject to any export provision of the United States
250: Department of Commerce, and may be exported to any country or planet.
251: .PP
252: Permission is granted to anyone to use this software for any purpose on
253: any computer system, and to alter it and redistribute it freely, subject
254: to the following restrictions:
255: .PP
256: 1. The author is not responsible for the consequences of use of this
257: software, no matter how awful, even if they arise from flaws in it.
258: .PP
259: 2. The origin of this software must not be misrepresented, either by
260: explicit claim or by omission. Since few users ever read sources,
261: credits must appear in the documentation.
262: .PP
263: 3. Altered versions must be plainly marked as such, and must not be
264: misrepresented as being the original software. Since few users
265: ever read sources, credits must appear in the documentation.
266: .PP
267: 4. This notice may not be removed or altered.
268: .PP
269: A few support files (\fIgetopt\fP, \fIstrtok\fP)
270: distributed with this package
271: are by Henry Spencer and are subject to the same terms as above.
272: .PP
273: A few simple support files (\fIstrtol\fP, \fIstrchr\fP)
274: distributed with this package
275: are in the public domain; they are so marked.
276: .PP
277: The files
278: .I tar.h
279: and
280: .I is_tar.c
281: were written by John Gilmore from his public-domain
282: .I tar
283: program, and are not covered by the above restrictions.
284: .SH BUGS
285: There must be a better way to automate the construction of the Magic
286: file from all the glop in Magdir. What is it?
287: Better yet, the magic file should be compiled into binary (say,
288: .IR ndbm (3)
289: or, better yet, fixed-length ASCII strings
290: for use in heterogenous network environments) for faster startup.
291: Then the program would run as fast as the Version 7 program of the same name,
292: with the flexibility of the System V version.
293: .PP
294: .I File
295: uses several algorithms that favor speed over accuracy,
296: thus it can be misled about the contents of ASCII files.
297: .PP
298: The support for ASCII files (primarily for programming languages)
299: is simplistic, inefficient and requires recompilation to update.
300: .PP
301: There should be an ``else'' clause to follow a series of continuation lines.
302: .PP
303: The magic file and keywords should have regular expression support.
304: Their use of ASCII TAB as a field delimiter is ugly and makes
305: it hard to edit the files, but is entrenched.
306: .PP
307: It might be advisable to allow upper-case letters in keywords
308: for e.g., troff commands vs man page macros.
309: Regular expression support would make this easy.
310: .PP
311: The program doesn't grok \s-2FORTRAN\s0.
312: It should be able to figure \s-2FORTRAN\s0 by seeing some keywords which
313: appear indented at the start of line.
314: Regular expression support would make this easy.
315: .PP
316: The list of keywords in
317: .I ascmagic
318: probably belongs in the Magic file.
319: This could be done by using some keyword like `*' for the offset value.
320: .PP
321: Another optimisation would be to sort
322: the magic file so that we can just run down all the
323: tests for the first byte, first word, first long, etc, once we
324: have fetched it. Complain about conflicts in the magic file entries.
325: Make a rule that the magic entries sort based on file offset rather
326: than position within the magic file?
327: .PP
328: The program should provide a way to give an estimate
329: of ``how good'' a guess is.
330: We end up removing guesses (e.g. ``From '' as first 5 chars of file) because
331: they are not as good as other guesses (e.g. ``Newsgroups:'' versus
332: "Return-Path:"). Still, if the others don't pan out, it should be
333: possible to use the first guess.
334: .PP
335: This program is slower than some vendors' file commands.
336: .PP
337: This manual page, and particularly this section, is too long.
338: .SH AVAILABILITY
339: You can obtain the original author's latest version by anonymous FTP
340: on
341: .B tesla.ee.cornell.edu
342: in the directory
343: .BR /pub/file-X.YY.tar.gz
![[BACK]](/icons/back.gif){kind=icon}
Return to file.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / file