TYPERULES(5F)
NAME
typerules - HylaFAX file type identification and conver-
sion rules
DESCRIPTION
Only two types of files are accepted by the HylaFAX server
for transmission as facsimile: POSTSCRIPT files and TIFF
Class F (bilevel Group 3-encoded) files. All other types
of files must be converted to one of these two formats.
The facsimile submission program applies a set of rules
against the contents of each input file to identify the
file's type and to figure out how to convert the file to a
format that is suitable for transmission. These rules are
stored in the file /usr/local/lib/fax/typerules, an ASCII
file that is patterned after the /etc/magic file used by
the System V file(1) program.
Type rules work by matching data patterns in a file; typi-
cally patterns that appear in the first few bytes of the
file (i.e. magic numbers). There are two types of rules,
primary rules and secondary rules. Secondary rules spec-
ify additional rules to apply after a primary rule has
been matched. When secondary rules are used, rule scan-
ning continues up to the next primary type rule in the
file.
Each rule consists of a set of whitespace-separated
fields:
offset datatype match result command
If an line is terminated wth a backslash character, the
entry is continued on the next line with any leading
whitespace characters compressed to a single space. Com-
ments are marked with the ``#'' character; everything from
to the end of the line is discarded. Secondary rules have
a ``>'' character in the first column of the line; primary
rules do not.
The fields in each rule entry are:
offset The byte offset in the file at which data should
be extracted and compared to a matching string
or value.
datatype The type of data value to extract at the speci-
fied offset for comparison purposes; one of:
``byte'' (8 bit unsigned number), ``short'' (16
bit unsigned number), ``long'' (32 bit unsigned
number), ``string'' (an array of bytes), or
``ascii'' (an array of ASCII-only bytes).
match The value and operation to use in matching; the
value used is based on the datatype field. If
value is ``x'', then it is interpreted to mean
match anything; otherwise the following
operators are supported (where data is the value
extracted from the file and value is specified
in the match field):
= data == value != data != value
> data > value < data < value
<= data <= value >= data >= value
& (data & value) == value ! (data & value) != value
^ (data ^ value) != 0
If no operation is specified then ``='' is used.
result One of ``ps'', ``tiff'', or ``error'' (case
insensitive). The first two results specify
whether the rule generates a POSTSCRIPT file or
a TIFF/F file (Group 3-encoded bilevel data),
respectively. The ``error'' result indicates
that a file is unsuitable for transmission and,
if supplied for transmission, should cause the
job to be aborted with the command field used in
an error message.
command A command description that is expanded and
passed to the shell to convert the input file to
the result format (suitable for sending as fac-
simile). Before the string is passed to the
shell, it is scanned and the following ``%''
escape codes are substituted for:
%i input file name
%o output file name
%r output horizontal resolution in pixels/mm
%R output horizontal resolution in pixels/inch
%v output vertical resolution in lines/mm
%V output vertical resolution in lines/inch
%f data format, ``1'' for 1-d encoding or ``2'' for 2-d encoding
%w page width in mm
%W page width in pixels
%l page length in mm
%L page length in pixels
%s page size by name
%F the directry where HylaFAX filter programs reside
%<x> the <x> character (e.g. ``%%'' results in ``%''
See below for example uses of these codes.
EXAMPLES
The following rules are used to match the formats that are
handled directly by the server:
#offset datatype match result command
0 string %! ps # POSTSCRIPT
0 short 0x4d4d tiff # big-endian TIFF
0 short 0x4949 tiff # little-endian TIFF
These rules are used to process the ASCII version of IRIS
Inventor database files while blocking the transmission of
the binary format variant:
#offset datatype match result command
0 string #Inventor V error IRIS Inventor file
>15 string binary error binary IRIS Inventor file
>15 string ascii ps %F/textfmt -fCourier-Bold -p11bp\
-U -q >%o <%i
This rule is typically the last entry in the file and is
used to convert all unmatched ASCII data files to
POSTSCRIPT:
#offset datatype match result command
0 ascii x ps %F/textfmt -fCourier-Bold -p11bp -U -q >%o <%i
NOTES
It is much better to convert data that is to be transmit-
ted to POSTSCRIPT because this data format permits the
facsimile server to do the final imaging according to the
optimal transfer parameters (resolution, binary encoding,
etc.).
It might be better to allow secondary rules to augment a
primary rule rather than just replace them. This would
allow, for example, command line options to be selected
based on file type.
SEE ALSO
sendfax(1) hylafax(1)