Formatting and update.

Author: IanDarwin

doc/file.man

@@ -1,5 +1,5 @@
 .TH FILE 1 "Copyright but distributable"
-.\# $Id: file.man,v 1.21 1993/01/05 14:55:13 ian Exp $
+.\# $Id: file.man,v 1.22 1993/04/05 10:38:26 ian Exp $
 .SH NAME
 .I file
 \- determine file type
@@ -48,28 +48,29 @@ 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''
+Don't do as Berkeley did \- change ``shell commands text''
 to ``shell script''.
 .PP
 The filesystem tests are based on examining the return from a
-.I stat (2)
+.IR 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)
+(sockets, symbolic links, or named pipes (FIFOs) on those systems that
+implement them)
 are intuited if they are defined in
 the system header file
-.I sys/stat.h .
+.BR 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
+.B a.out
 file, whose format is defined in 
-.I a.out.h
+.B a.out.h
 and possibly
-.I exec.h
+.B 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
@@ -88,10 +89,10 @@ 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
+.B .br
 indicates that the file is most likely a troff input file,
 just as the keyword 
-.I struct
+.B struct
 indicates a C program.
 These tests are less reliable than the previous
 two groups, so they are performed last.
@@ -131,7 +132,8 @@ to test the standard input, use ``-'' as a filename argument.
 .PP
 The 
 .B \-L
-option causes symlinks to be followed, as the like-named option in ls(1).
+option causes symlinks to be followed, as the like-named option in
+.IR ls (1).
 .SH FILES
 .I __MAGIC__
 \- default list of magic numbers
@@ -160,9 +162,20 @@ For example,
 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
-The Sun Microsystems implementation of System V compatibility
-includes a file(1) command that has some extentions.
+SunOS releases 3.2 and later from Sun Microsystems include a
+.IR 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,
@@ -210,6 +223,25 @@ postal address: P.O. Box 603, Station F, Toronto, Ontario, CANADA M4Y 2L8.
 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@auspex.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
+.I 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
+.IR file .
+.RE
+.PP
 Changes by Ian Darwin and various authors including
 Christos Zoulas (christos@ee.cornell.edu), 1990-1992.
 .SH LEGAL NOTICE
@@ -260,8 +292,9 @@ 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, ndbm(3) or,
-better yet, fixed-length ASCII strings 
+Better yet, the magic file should be compiled into binary (say,
+.IR ndbm (3)
+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.
@@ -307,15 +340,12 @@ 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 program is slower than some vendors' file commands.
 .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 ftp.cs.toronto.edu in the directory /pub/darwin/file.
+on
+.B ftp.cs.toronto.edu
+in the directory
+.BR /pub/darwin/file .