TYPERULES(5F)

🌸 NAME 🌸

typerules — the HylaFAX file type identification and conversion rules 💅 (yes bestie, this is a whole (5F) manpage, we're in the file-formats section, stay with me)

---

✨ DESCRIPTION ✨

okay so, plot twist: the HylaFAX server is picky. It only accepts three types of files for transmission as facsimile:

• POSTSCRIPT® files
• PDF files
• TIFF Class F (bilevel Group 3-encoded) files

That's it. That's the list. Everything else has to be converted into one of those three, no exceptions. 😤

So the facsimile submission program does a little vibe check on every input file — it applies a set of rules against the file's contents to identify what type it is and to figure out how to convert it into something actually transmittable. Those rules live in the file /etc/hylafax/typerules, which is an ASCII file patterned after the /etc/magic file used by the System V file(1) program. But — and this is important — there are significant differences, which we will absolutely get into below. 👀

Type rules work by matching data patterns in a file; typically the patterns that show up in the first few bytes of the file (i.e. magic numbers ✨). There are two flavors of rule:

• primary rules
• secondary rules

Secondary rules specify additional rules to apply after a primary rule has been matched. When secondary rules are used, rule scanning continues up to the next primary type rule in the file.

🧾 the shape of a rule

Each rule is a set of whitespace-separated fields, in this exact order:

offset    datatype    match    result   command

If a line is terminated with a backslash character \, the entry continues on the next line with any leading whitespace characters compressed to a single space. Comments are marked with the # character; everything from there 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, one by one

• offset — the byte offset in the file where data should be extracted and compared to a matching string or value.
• datatype — the type of data value to extract at the specified offset for comparison purposes. It's one of: byte (8 bit unsigned number), short (16 bit unsigned number), long (32 bit unsigned number), filename (the name of the file), string (an array of bytes), istring (a case-insensitive array of bytes), or ascii (an array of ASCII-only bytes).
• match — the value and the 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) — except for types filename, string, istring, and ascii:

=     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.

For string, istring, and ascii no operator is allowed; the implicit operation is always =. In these cases, the field is terminated by a tab or end of line — not by # or . Characters in the field have their literal value; there are no C-style character escapes. For filename no operator is allowed either; the operation expects that the value is a regular expression to positively match the supplied data.

• 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 facsimile). 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 pixels
  • %W — page width in mm
  • %l — page length in pixels
  • %L — page length in mm
  • %s — page size by name
  • %F — the directory where HylaFAX filter programs reside
  • %<x> — the <x> character (e.g. %% results in %)

See below for example uses of these codes. 🫶

---

🌈 EXAMPLES 🌈

These rules are the ones used to match the formats that are handled directly by the server (no conversion needed, they just are that girl):

#offset   datatype    match          result    command
0         string      %!             ps                       # POSTSCRIPT
0         string      %PDF           ps                       # POSTSCRIPT by Ghostscript
0         short       0x4d4d         tiff                     # big-endian TIFF
0         short       0x4949         tiff                     # little-endian TIFF

These rules process the ASCII version of IRIS Inventor database files while blocking the transmission of the binary format variant (not me catching the binary one and shutting it down 🙈):

#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

And this rule is typically the last entry in the file — it's the catch-all that converts 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 transmitted 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.). tl;dr: POSTSCRIPT lets the server cook with the best settings 🔥

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. (Just a thought, bestie. A little wishlist moment. ✨)

---

🦋 SEE ALSO 🦋

• sendfax(1)
• hylafax-client(1)

---

and that's the whole page, periodt 💖 this one shipped way back on May 12, 1993, from the TYPERULES(5F) manual — shoutout to the HylaFAX era for giving us magic numbers before magic numbers were cool 🎀✨ go forth and let the right file types through, ily 🫶