1TYPERULES(5F)                                                    TYPERULES(5F)


6       typerules - HylaFAX file type identification and conversion rules


9       Only three types of files are accepted by the HylaFAX server for trans‐
10       mission as facsimile: POSTSCRIPT® files, PDF files, and  TIFF  Class  F
11       (bilevel Group 3-encoded) files.  All other types of files must be con‐
12       verted to one of these three formats.  The facsimile submission program
13       applies a set of rules against the contents of each input file to iden‐
14       tify the file's type and to figure out how to convert  the  file  to  a
15       format  that  is  suitable for transmission.  These rules are stored in
16       the file /etc/hylafax/typerules, an ASCII file that is patterned  after
17       the  /etc/magic  file  used  by the System V file(1) program.  However,
18       there are significant differences, noted below.
20       Type rules work by matching data patterns in a file; typically patterns
21       that  appear  in the first few bytes of the file (i.e.  magic numbers).
22       There are two types of rules, primary rules and secondary rules.   Sec‐
23       ondary rules specify additional rules to apply after a primary rule has
24       been matched.  When secondary rules are used, rule  scanning  continues
25       up to the next primary type rule in the file.
27       Each rule consists of a set of whitespace-separated fields:
28            offset    datatype    match    result   command
29       If  an  line is terminated wth a backslash character, the entry is con‐
30       tinued on the next line with any  leading  whitespace  characters  com‐
31       pressed  to a single space.  Comments are marked with the ``#'' charac‐
32       ter; everything from to the end of the line  is  discarded.   Secondary
33       rules  have  a ``>'' character in the first column of the line; primary
34       rules do not.
36       The fields in each rule entry are:
38       offset    The byte offset in the file at which data should be extracted
39                 and compared to a matching string or value.
41       datatype  The type of data value to extract at the specified offset for
42                 comparison purposes; one of: ``byte'' (8  bit  unsigned  num‐
43                 ber),  ``short''  (16  bit unsigned number), ``long'' (32 bit
44                 unsigned  number),  ``filename''  (the  name  of  the  file),
45                 ``string''  (an array of bytes), ``istring'' (a case-insensi‐
46                 tive array of bytes), or ``ascii'' (an  array  of  ASCII-only
47                 bytes).
49       match     The value and operation to use in matching; the value used is
50                 based on the datatype field.  If value is ``x'', then  it  is
51                 interpreted  to  mean match anything; otherwise the following
52                 operators are supported (where data is  the  value  extracted
53                 from  the  file  and  value  is specified in the match field)
54                 except for types ``filename'', ``string'',  ``istring'',  and
55                 ``ascii'':
56                 =     data == value              !=    data != value
57                 >     data > value               <     data < value
58                 <=    data <= value              >=    data >= value
59                 &     (data & value) == value    !     (data & value) != value
60                 ^     (data ^ value) != 0
62       If no operation is specified then ``='' is used.
64       For ``string'', ``istring'', and ``ascii'' no operator is allowed; the implicit
65       operation is always ``=''.  In these cases, the field is terminated by
66       a tab or end of line, not by ``#'' or `` ''.  Characters in the field have
67       their literal value; there are no C-style character escapes.  For ``filename'' no
68       operator is allowed; the operation expects that the value is a regular expression
69       to positively match the supplied data.
71       result    One  of  ``ps'',  ``tiff'',  or ``error'' (case insensitive).
72                 The first two results specify whether the  rule  generates  a
73                 POSTSCRIPT  file  or  a  TIFF/F file (Group 3-encoded bilevel
74                 data), respectively.  The ``error'' result indicates  that  a
75                 file  is  unsuitable  for  transmission  and, if supplied for
76                 transmission, should cause the job to  be  aborted  with  the
77                 command field used in an error message.
79       command   A  command  description  that  is  expanded and passed to the
80                 shell to convert the input file to the result  format  (suit‐
81                 able  for sending as facsimile).  Before the string is passed
82                 to the shell, it is scanned and the  following  ``%''  escape
83                 codes are substituted for:
84                 %i      input file name
85                 %o      output file name
86                 %r      output horizontal resolution in pixels/mm
87                 %R      output horizontal resolution in pixels/inch
88                 %v      output vertical resolution in lines/mm
89                 %V      output vertical resolution in lines/inch
90                 %f      data format, ``1'' for 1-d encoding or ``2'' for 2-d encoding
91                 %w      page width in pixels
92                 %W      page width in mm
93                 %l      page length in pixels
94                 %L      page length in mm
95                 %s      page size by name
96                 %F      the directory where HylaFAX filter programs reside
97                 %<x>    the <x> character (e.g. ``%%'' results in ``%''
98       See below for example uses of these codes.


101       The  following  rules  are  used  to match the formats that are handled
102       directly by the server:
103       #offset   datatype    match          result    command
104       0         string      %!             ps                       # POSTSCRIPT
105       0         string      %PDF           ps                       # POSTSCRIPT by Ghostscript
106       0         short       0x4d4d         tiff                     # big-endian TIFF
107       0         short       0x4949         tiff                     # little-endian TIFF
109       These rules are used to process the  ASCII  version  of  IRIS  Inventor
110       database  files  while  blocking  the transmission of the binary format
111       variant:
112       #offset   datatype    match          result    command
113       0         string      #Inventor V    error     IRIS Inventor file
114       >15       string      binary         error     binary IRIS Inventor file
115       >15       string      ascii          ps        %F/textfmt -fCourier-Bold -p11bp\
116                                                          -U -q >%o <%i
118       This rule is typically the last entry in the file and is used  to  con‐
119       vert all unmatched ASCII data files to POSTSCRIPT:
120       #offset   datatype    match          result    command
121       0         ascii       x              ps        %F/textfmt -fCourier-Bold -p11bp -U -q >%o <%i


124       It  is  much  better to convert data that is to be transmitted to POST‐
125       SCRIPT because this data format permits the facsimile server to do  the
126       final imaging according to the optimal transfer parameters (resolution,
127       binary encoding, etc.).
129       It might be better to allow secondary rules to augment a  primary  rule
130       rather  than just replace them.  This would allow, for example, command
131       line options to be selected based on file type.


134       sendfax(1), hylafax-client(1)
138                                 May 12, 1993                    TYPERULES(5F)