Imported Upstream version 93u+upstream

1 files changed, 493 insertions, 0 deletions

diff --git a/src/lib/libast/man/magic.3 b/src/lib/libast/man/magic.3
new file mode 100644
index 0000000..e8bf0e3
--- /dev/null
+++ b/src/lib/libast/man/magic.3
@@ -0,0 +1,493 @@
+.fp 5 CW
+.de Af
+.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
+.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
+..
+.de aF
+.ie \\$3 .ft \\$1
+.el \{\
+.ds ;G \&
+.nr ;G \\n(.f
+.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
+\\*(;G
+.ft \\n(;G \}
+..
+.de L
+.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de LR
+.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de RL
+.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
+..
+.de EX		\" start example
+.ta 1i 2i 3i 4i 5i 6i
+.PP
+.RS 
+.PD 0
+.ft 5
+.nf
+..
+.de EE		\" end example
+.fi
+.ft
+.PD
+.RE
+.PP
+..
+.TH MAGIC 3
+.SH NAME
+magic \- magic file interface
+.SH SYNOPSIS
+.EX
+#include <magic.h>
+
+Magic_t
+{
+	unsigned long	flags;
+};
+
+Magic_t*  magicopen(unsigned long \fIflags\fP);
+void      magicclose(Magic_t* \fImagic\fP);
+
+int       magicload(Magic_t* \fImagic\fP, const char* \fIpath\fP, unsigned long \fIflags\fP);
+int       magiclist(Magic_t* \fImagic\fP, Sfio_t* \fIsp\fP);
+
+char*     magictype(Magic_t* \fImagic\fP, const char* \fIpath\fP, struct stat* \fIst\fP);
+.EE
+.SH DESCRIPTION
+These routines provide an interface to the
+.IR file (1)
+command magic file.
+.L magicopen
+returns a magic session handle that is passed to all of the other routines.
+.I flags 
+may be
+.TP
+.L MAGIC_MIME
+Return the MIME type string rather than the magic file description.
+.TP
+.L MAGIC_PHYSICAL
+Don't follow symbolic links.
+.TP
+.L MAGIC_STAT
+The stat structure
+.I st
+passed to
+.I magictype
+will contain valid
+.I stat (2)
+information.
+See
+.L magictype
+below.
+.TP
+.L MAGIC_VERBOSE
+Enable verbose error messages.
+.PP
+.L magicclose
+closes the magic session.
+.PP
+.L magicload
+loads the magic file named by
+.I path
+into the magic session.
+.I flags
+are the same as with 
+.LR magicopen .
+More than one magic file can be loaded into a session;
+the files are searched in load order.
+If
+.I path
+is 
+.L 0
+then the default magic file is loaded.
+.PP
+.L magiclist
+lists the magic file contents on the
+.IR sfio (3)
+stream
+.IR sp .
+This is used for debugging magic entries.
+.PP
+.L magictype
+returns the type string for
+.I path
+with optional
+.IR stat (2)
+information
+.IR st .
+If
+.I "st == 0"
+then
+.L magictype
+calls
+.L stat
+on a private stat buffer,
+else if
+.L magicopen
+was called with the
+.L MAGIC_STAT
+flag then
+.I st
+is assumed to contain valid stat information, otherwise
+.L magictype
+calls 
+.L stat
+on
+.IR st .
+.L magictype
+always returns a non-null string.
+If errors are encounterd on
+.I path
+then the return value will contain information on those errors, e.g.,
+.LR "cannot stat" .
+.SH FORMAT
+The magic file format is a backwards compatible extension of an
+ancient System V file implementation.
+However, with the extended format it is possible to write a single
+magic file that works on all platforms.
+Most of the net magic files floating around work with
+.LR magic ,
+but they usually double up on 
+.I le
+and
+.I be
+entries that are automatically handled by
+.LR magic .
+.PP
+A magic file entry describes a procedure for determining a single file type
+based on the file pathname,
+.I stat (2)
+information, and the file data.
+An entry is a sequence of lines, each line being a record of
+.I space
+separated fields.
+The general record format is:
+.EX
+[op]offset type [mask]expression description [mimetype]
+.EE
+.L #
+in the first column introduces a comment.
+The first record in an entry contains no
+.LR op ;
+the remaining records for an entry contain an
+.LR op .
+Integer constants are as in C:
+.L 0x*
+or
+.L 0X*
+for hexadecimal,
+.L 0*
+for octal and decimal otherwise.
+.PP
+The
+.L op
+field may be one of:
+.TP
+.L +
+The previous records must match but the current record is optional.
+.L >
+is an old-style synonym for
+.LR + .
+.TP
+.L &
+The previous and current records must match.
+.TP
+.L {
+Starts a nesting block that is terminated by
+.LR } .
+A nesting block pushes a new context for the
+.L +
+and
+.L &
+ops.
+The
+.L {
+and
+.L }
+records have no other fields.
+.TP
+\fIid\f5{\fR
+A function declaration and call for the single character identifier
+.IR id .
+The function return is a nesting block end record
+.LR } .
+Function may be redefined.
+Functions have no arguments or return value.
+.TP
+\fIid\f5()\fR
+A call to the function
+.IR id .
+.PP
+The
+.L offset
+field is either the offset into the data upon which the current entry operates
+or a file metadata identifier.
+Offsets are either integer constants or offset expressions.
+An offset expression is contained in (...) and is a combination of
+integral arithmetic operators and the 
+.L @
+indirection operator.
+Indirections take the form
+.LI @ integer
+where integer is the data offset for the indirection value.
+The size of the indirection value is taken either from one of the suffixes
+.LR B (byte, 1 char),
+.LR H (short, 2 chars),
+.LR L (long, 4 chars),
+pr
+.LR Q (quead, 8 chars),
+or from the
+.L type 
+field.
+Valid file metadata identifiers are:
+.TP
+.L atime
+The string representation of
+.LR stat.st_atime .
+.TP
+.L blocks
+.LR stat.st_blocks .
+.TP
+.L ctime
+The string representation of
+.LR stat.st_ctime .
+.TP
+.L fstype
+The string representation of
+.LR stat.st_fstype .
+.TP
+.L gid
+The string representation of
+.LR stat.st_gid .
+.TP
+The
+.L stat.st_mode
+file mode bits in
+.IR modecanon (3)
+canonical representation (i.e., the good old octal values).
+.TP
+.L mtime
+The string representation of
+.LR stat.st_mtime .
+.TP
+.L nlink
+.LR stat.st_nlink .
+.TP
+.L size
+.LR stat.st_size .
+.TP
+.L name
+The file path name sans directory.
+.TP
+.L uid
+The string representation of
+.LR stat.st_uid .
+.PP
+The
+.L type
+field specifies the type of the data at
+.LR offset .
+Integral types may be prefixed by
+.L le
+or
+.L be
+for specifying exact little-endian or big-endian representation,
+but the internal algorithm automatically loops through the
+standard representations to find integral matches,
+so representation prefixes are rarely used.
+However, this looping may cause some magic entry conflicts; use the
+.L le
+or
+.L be
+prefix in these cases.
+Only one representation is used for all the records in an entry.
+Valid types are:
+.TP
+.L byte
+A 1 byte integer.
+.TP
+.L short
+A 2 byte integer.
+.TP
+.L long
+A 4 byte integer.
+.TP
+.L quad
+An 8 byte integer.
+Tests on this type may fail is the local compiler does not support
+an 8 byte integral type and the corresponding value overflows 4 bytes.
+.TP
+.L date
+The data at
+.L offset
+is interpreted as a 4 byte seconds-since-the-epoch date and
+converted to a string.
+.TP
+.L edit
+The
+.L expression
+field is an
+.IR ed (1)
+style substitution expression
+\fIdel old del new del \fP [ \fI flags \fP ]
+where the substituted value is made available to the
+.L description
+field
+.L %s
+format.
+In addition to the
+.I flags
+supported by
+.IR ed (3)
+are
+.L l
+that converts the substituted value to lower case and
+.L u
+that converts the substituted value to upper case.
+If
+.I old
+does not match the string data at
+.L offset
+then the entry record fails.
+.TP
+.L match
+.L expression
+field is a
+.IR strmatch (3)
+pattern that is matched against the string data at
+.LR offset .
+.TP
+.L string
+The
+.L expression
+field is a string that is compared with the string data at
+.LR offset .
+.PP
+The optional
+.L mask
+field takes the form
+.LI & number
+where
+.I number
+is 
+.I anded
+with the integral value at
+.L offset
+before the
+.L expression
+is applied.
+.PP
+The contents of the expression field depends on the
+.LR type .
+String type expression are described in the
+.L type
+field entries above.
+.L *
+means any value and applies to all types.
+Integral
+.L type
+expression take the form [\fIoperator\fP] \fIoperand\P where 
+.I operand
+is compared with the data value at
+.L offset
+using
+.IR operator .
+.I operator 
+may be one of
+.LR < .
+.LR <= ,
+.LR == ,
+.LR >=
+or
+.LR > .
+.I operator
+defaults to
+.L ==
+if omitted.
+.I operand 
+may be an integral constant or one of the following builtin function calls:
+.TP
+.L magic()
+A recursive call to the magic algorithm starting with the data at
+.LR offset .
+.TP
+\f5loop(\fIfunction\fP,\fIoffset\fP,\fIincrement\fP)\fR
+Call 
+.I function
+starting at
+.I offset
+and increment
+.I offset
+by
+.I increment
+after each iteration.
+Iteration continues until the description text does not change.
+.PP
+The
+.L description
+field is the most important because it is this field that is presented
+to the outside world.
+When constructing description
+fields one must be very careful to follow the style layed out in the
+magic file, lest yet another layer of inconsistency creep into the system.
+The description for each matching record in an entry are concatenated
+to form the complete magic type.
+If the previous matching description in the current entry does not end with
+.I space
+and the current description is not empty and does not start with
+.I comma ,
+.I dot
+or
+.I backspace
+then a
+.I space
+is placed between the descriptions
+(most optional descriptions start with
+.IR comma .)
+The data value at 
+.L offset
+can be referenced in the description using
+.L %s
+for the string types and
+.L %ld
+or
+.L %lu
+for the integral types.
+.PP
+The
+.L mimetype
+field specifies the MIME type, usually in the form
+.IR a / b .
+.SH FILES
+.L ../lib/file/magic
+located on
+.L $PATH
+.SH EXAMPLES
+.EX
+0	long		0x020c0108	hp s200 executable, pure
+o{
++36	long		>0		, not stripped
++4	short		>0		, version %ld
+}
+
+0	long		0x020c0107	hp s200 executable
+o()
+
+0	long		0x020c010b	hp s200 executable, demand-load
+o()
+.EE
+The function
+.LR o() ,
+shared by 3 entries,
+determines if the executable is stripped and also extracts the version number.
+.EX
+0	long		0407		bsd 386 executable
+&mode	long		&0111!=0
++16	long		>0		, not stripped
+.EE
+This entry requires that the file also has execute permission.
+.SH "SEE ALSO"
+file(1), mime(4), tw(1), modecanon(3)