HYLAFAX-CLIENT(1)

💖 HYLAFAX-CLIENT 💖

okay bestie, welcome to the HylaFAX-client page — it's your lil intro to all the HylaFAX client apps and how to actually use them 🫶 this is the manual for HYLAFAX-CLIENT(1), General Commands Manual, and no we are not skipping a single crumb.

---

✨ NAME ✨

HylaFAX-client — introduction to HylaFAX client applications and usage 💅

---

🌸 SYNOPSIS 🌸

sendfax [options] [files...]
sendpage [options] [message...]
faxstat [options]
faxrm [options]
faxalter [options] jobid...
fax2ps [options] [files...]

---

🦋 DESCRIPTION 🦋

So HylaFAX is a telecommunication system for UNIX® systems, and honestly it's giving legend behaviour. Among the features of HylaFAX are, and I'm listing every single one because you deserve the full tea:

• HylaFAX runs as a network service; this means a modem may be effectively shared by a large number of users. one modem, everybody eats 🍽️
• HylaFAX can be configured to work with a wide variety of modems on a wide variety of systems. it's flexible like that.
• Access to the system can be restricted by the administrator to selected hosts and/or users. gatekeeping, but make it a feature.
• Transmission requests may be processed immediately (that's the default, periodt) or queued for processing at a later time, in the manner of the at(1) command. your call, bestie.
• Remote facsimile machines may be polled to retrieve publicly available documents. yes, you can just go get the docs 👑
• POSTSCRIPT®, PDF, and TIFF Class F documents are passed directly to the fax server for transmission; the system attempts to convert other file formats to either POSTSCRIPT or TIFF through the use of an extensible file typing and conversion facility. In normal operation ASCII-text, troff(1) output, and Silicon Graphics images are automatically converted. Additional file formats can be added; see typerules(5F). it literally just knows 💫
• The faxcover(1) program can be automatically invoked to create a cover page for each facsimile, using information deduced by the sendfax command. Alternatively, users may supply their own cover pages using their preferred tools. main character cover page energy.
• Facsimile are normally imaged in a system-default page size (usually letter-size pages, 8.5" by 11", for sites in North America). Alternate page sizes can be specified with a -s option to all HylaFAX programs. Well known page sizes include: ISO A3, ISO A4, ISO A5, ISO A6, ISO B4, North American Letter, American Legal, American Ledger, American Executive, Japanese Letter, and Japanese Legal. Note that it may not be permissible to image into the full page area; the guaranteed reproducible area for a page is typically smaller. Also, note that while arbitrary page sizes can be specified, only a limited number of page dimensions are supported by the facsimile protocol. Thus if an odd-size facsimile is submitted for transmission it may not be possible to determine if it can be sent until the fax server establishes communication with the remote facsimile machine. so like. don't get cocky with the weird sizes, okay? 😭
• Facsimile can be sent at low resolution (98 lines/inch) or medium resolution (196 lines/inch) — often called fine mode. Documents with mixed resolution pages are handled correctly. no chaos, just vibes.
• Users are notified by electronic mail if a job can not be transmitted. It is also possible to receive notification by mail when a job has been completed successfully and each time that the job is requeued for retransmission. Any untransmitted documents are returned to the sender by electronic mail in a form suitable for re-submission. it will literally email you back, so attentive 💖
• Support is provided for broadcasting facsimile. The HylaFAX server software optimizes preparation of broadcast documents and the client applications support the notion of a job group which permits a group of jobs to be manipulated together. group chat, but for fax jobs.
• Support is provided for transmitting alpha-numeric messages to pager devices or GSM mobiles using the Simple Network Paging Protocol (SNPP) and the IXO or UCP protocol (for message delivery).

The HylaFAX software is divided into two packages: software used on client machines and software used on machines where one or more modems reside. Client software includes:

• sendfax, a program to submit outgoing facsimile;
• sendpage, a program to submit alpha-numeric messages to SNPP servers;
• faxstat, a program obtain status information about HylaFAX servers;
• faxrm, a program to remove jobs and documents;
• faxalter, a program to change parameters of queued jobs; and
• fax2ps, a program that converts facsimile documents to POSTSCRIPT so that they may be viewed with a POSTSCRIPT previewer or printed on a POSTSCRIPT printer (this program is actually part of the companion TIFF distribution that is used by HylaFAX).

Many systems also support submission of outgoing facsimile by electronic mail and/or graphical interfaces to the sendfax program. Such facilities are site-dependent; consult local documentation for more information. iykyk 🫶

---

🎀 GETTING STARTED 🎀

To use the HylaFAX client software on your machine you need to either load the appropriate software on your machine, or you need to locate a machine that already has the client software installed and setup symbolic links to the appropriate directories. If you choose the latter, then beware — this is the part where people trip 💀 — you need links to three directories:

• the directory where client applications reside, /usr/bin,
• the directory where the client application database files reside, /etc/hylafax, and
• the directory where document conversion programs reside, /usr/bin

(the last two directories may be the same on your system).

Once the software is setup on your machine you need to locate a host that has a facsimile server that you can use. The host, and possibly the modem on the host, should be defined in your environment in the FAXSERVER variable. For example, for csh users,

setenv FAXSERVER flake.asd

or for ksh or sh users,

FAXSERVER=flake.asd; export FAXSERVER

If there are multiple modems on your server then you may be assigned to use a specific modem. For example, if you are to use the modem attached to the ttym2 port on the server machine, then the FAXSERVER variable should be setup as

FAXSERVER=ttym2@flake.asd; export FAXSERVER

(Note: the SNPPSERVER environment variable is used instead of FAXSERVER by the sendpage program; consult sendpage(8C) for more information.) 👈 don't mix these up bestie

Note also, that before you can submit outgoing facsimile jobs the administrator for the facsimile server may need to register your identity in an access control list. You will encounter the message 530 User %s access denied.'' if access to your server is controlled and you are not properly registered or you may be prompted for a password and then denied service with 530 Login incorrect.''. the 530 jump scare is real 😭

---

🌈 DIAL STRINGS 🌈

A dial string specifies how to dial the telephone in order to reach a destination facsimile machine. HylaFAX permits arbitrary strings to be passed to the facsimile server so that users can specify credit card information, PBX routing information, etc. Alphabetic characters are automatically mapped to their numeric key equivalents (e.g. 1800GotMilk'' becomes 18004686455''). Other characters can be included for readability; anything that must be stripped will be removed by the server before the dialing string is passed to the fax modem. Private information such as credit card access codes are withheld from status messages and publicly accessible log files (with proper configuration). Facsimile servers also automatically insert any leading dialing prefixing strings that are required to place outgoing phone calls; e.g. dialing 9'' to get an outside line. Additionally, if a phone number is fully specified with the <purple>international direct dialing digits (IDDD)</purple>, then any prefixing long distance or international dialing codes that are required to place the call will be inserted in the dial string by the server. For example, +31.77.594.131'' is a phone number in the Netherlands; it would be converted to 0113177594131'' if the call is placed in the United States. The number +14159657824'' is a phone number in California; if this number is called from within the 415 area code in the United States, then the server would automatically convert this to ``9657824'' because in the San Francisco Bay Area, local phone calls must not include the area code and long distance prefixing code. it does the thinking so you don't have to 🧚

The general rule in crafting dial strings is to specify exactly what you would dial on your telephone; and, in addition, the actual phone number can be specified in a location-independent manner by using the IDD syntax of ``+country-code local-part''. iconic, honestly 💅

🎀 COVER PAGES 🎀

okay so bestie, sendfax can literally ✨auto-make✨ a cover page for every fax you send out. Those cover pages are actually built by the faxcover(1) program, using a mix of stuff sendfax figures out on its own plus stuff you hand it on the command line. and if you're feeling DIY? you can just tell sendfax to skip the auto cover page and drop your own cover page right into the data you're sending. main character move tbh. 💅

Auto-generated cover pages can include all of this:

• the sender's name, affiliation, geographic location, fax number, and voice telephone number 🫶
• the recipient's name, affiliation, geographic location, fax number, and voice telephone number 💖
• text explaining what this fax is "regarding" (the whole point, lowkey)
• text commentary 📝
• the local date and time that the job was submitted 🕐
• the number of pages to be transmitted 🔢

Some of this info is currently pulled from your personal facsimile database file, ~/.faxdb.

heads up bestie: this file is deprecated 😭 it's only described here because it's still supported for compatibility with older versions of the software. it's giving legacy, fr fr.

The .faxdb file is an ASCII file with entries shaped like this:

keyword : value

and keyword can be:

• Name — a name associated with destination fax machine
• Company — a company name
• Location — in-company locational information, e.g. a building#
• FAX-Number — phone number of fax machine
• Voice-Number — voice telephone number

Data is free format. Whitespace (blank, tab, newline) can be freely interspersed with tokens. If tokens include whitespace, they must be enclosed in quote marks ("). The # character introduces a comment—everything to the end of the line is discarded. 🗑️

Entries get collected into aggregate records by wrapping them in []. Records can be nested to create a hierarchy that that supports the inheritance of information—unspecified information is inherited from parent aggregate records. 🧬

For example, a sample file might be:

[   Company:   "Silicon Graphics, Inc."
    Location: "Mountain View, California"
    [ Name: "Sam Leffler"    FAX-Number: +1.415.965.7824 ]
]

which could be extended to include another person at Silicon Graphics with the following:

[   Company:   "Silicon Graphics, Inc."
    Location: "Mountain View, California"
    [ Name: "Sam Leffler"    FAX-Number: +1.415.965.7824 ]
    [ Name: "Paul Haeberli"  FAX-Number: +1.415.965.7824 ]
]

Experience indicates that the hierarchical nature of this database format makes it difficult to maintain with automated mechanisms. As a result it is being replaced by other, more straightforward databases that are managed by programs that front-end the sendfax program. rip to the nesting era, we hardly knew ye 🙈

---

⚙️ CONFIGURATION FILES ⚙️

HylaFAX client applications can be tailored on a per-user and per-site basis through configuration files, bestie. 🌈 Per-site controls live in /etc/hylafax/hyla.conf, while per-user controls go in ~/.hylarc. and on top of that, a few programs that have a whole bunch of parameters specific to their operation support an additional configuration file — those files are identified in their manual pages.

Configuration files have a simple format and are entirely ASCII. A configuration parameter is of the form:

tag: value

where a tag identifies a parameter and a value is either a string, number, or boolean value. Comments are introduced by the # character and extend to the end of the line. String values start at the first non-blank character after the : and continue to the first non-whitespace character or, if whitespace is to be included, may be enclosed in quote marks ("). String values enclosed in quote marks may also use the standard C programming conventions for specifying escape codes; e.g. \n for a newline character and \xxx for an octal value. Numeric values are specified according to the C programming conventions (leading 0x for hex, leading 0 for octal, otherwise decimal). Boolean values are case insensitive. For a true value, either Yes or On should be used. For a false value, use No or Off. 🎯

---

📥 RECEIVED FACSIMILE 📥

Incoming facsimile are received by facsimile servers and deposited in a receive queue directory on the server machine. Depending on the server's configuration, files in this directory may or may not be readable by normal users. 👀 The faxstat program can be used to view the contents of the receive queue directory:

hyla% faxstat -r
HylaFAX scheduler on hyla.chez.sgi.com: Running
Modem ttyf2 (+1 510 999-0123): Running and idle

Protect Page  Owner        Sender/TSI  Recvd@ Filename
-rw-r--    9  fax       1 510 5268781 05Jan96 fax00005.tif
-rw-r--    8  fax       1 510 5268781 07Jan96 fax00009.tif
-rw-r--    2  fax       1 510 5268781 07Jan96 fax00010.tif
-rw-r--    3  fax        +14159657824 08Jan96 fax00011.tif
-rw-r--    2  fax        +14159657824 08Jan96 fax00012.tif

Consult the faxstat manual page for a more detailed description of this information.

Received facsimile are stored as TIFF Class F files. These files are Bi-level images that are encoded using the CCITT T.4 or CCITT T.6 encoding algorithms. The fax2ps(1) program can be used to view and print these files. A file can be viewed by converting it to POSTSCRIPT and then viewing it with a suitable POSTSCRIPT previewing program, such as xpsview(1) (Adobe's Display POSTSCRIPT-based viewer), ghostview(1) (a public domain previewer), or image viewer programs such as viewfax(1) (public domain), faxview(1) (another public domain TIFF viewer program), xv(1) (shareware and/or public domain), or xtiff(1) (a program included in the public domain TIFF software distribution). Consult your local resources to figure out what tools are available for viewing and printing received facsimile. 🖨️✨

---

🔌 CLIENT-SERVER PROTOCOL 🔌

HylaFAX client applications communicate with servers using either a special-purpose communications protocol that is modeled after the Internet File Transfer Protocol (FTP) or, when submitting alpha-numeric pages, the Simple Network Paging Protocol (SNPP), specified in RFC 1861. All client programs support a -v option that can be used to observe the protocol message exchanges. 👀✨

In some situations it may be more effective to communicate directly with a HylaFAX server using the client-server protocol. This can be accomplished with an FTP or Telnet client application; though an FTP client is recommended because it implements the protocol needed to obtain server status information. For information on the server-side support provided with HylaFAX consult hfaxd(8C). For documentation on the client-server fax protocol consult RFC XXXX (to be filled in). (yes bestie, they left a placeholder in the manpage, iconic behavior 💀)

---

🌟 EXAMPLES 🌟

This section gives several examples of command line usage; consult the manual pages for the individual commands for information on the options and program operation.

The following command queues the file zall.ps for transmission to John Doe at the number (123)456-7890 using fine mode; the server will attempt to send it at 4:30 A.M.:

sendfax -a "0430" -m -d "John Doe@1.123.456.7890" zall.ps

(the leading 1. is supplied to dial area code 123 in the United States.)

The following command generates a one-page facsimile that is just a cover page:

faxcover -t "John Doe" -n "(123)456-7890"
    -c "Sorry John, I forgot the meeting..." |
    sendfax -n -d "(123)456-7890"

(note that the line was broken into several lines solely for presentation.)

The following command displays the status of the facsimile server and any jobs queued for transmission:

faxstat -s

The following command displays the status of the facsimile server and any documents waiting in the receive queue on the server machine:

faxstat -r

The following command shows how to use an FTP client program to communicate directly with a HylaFAX server:

hyla% ftp localhost hylafax
Connected to localhost.
220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
Name (localhost:sam):
230 User sam logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> dir sendq
200 PORT command successful.
150 Opening new data connection for "sendq".
208  126 S    sam 5268781       0:3   1:12   16:54 No local dialtone
226 Transfer complete.
ftp> quote jkill 208
200 Job 208 killed.
ftp> dir doneq
200 PORT command successful.
150 Opening new data connection for "doneq".
208  126 D    sam 5268781       0:3   1:12         No local dialtone
226 Transfer complete.
ftp> quote jdele 208
200 Job 208 deleted; current job: (default).
ftp> dir docq
200 PORT command successful.
150 Opening new data connection for "docq".
-rw----   1      sam    11093 Jan 21 16:48 doc9.ps
226 Transfer complete.
ftp> dele docq/doc9.ps
250 DELE command successful.
ftp> dir recvq
200 PORT command successful.
150 Opening new data connection for "recvq".
-rw-r--    4  fax       1 510 5268781 30Sep95 faxAAAa006uh
-rw-r--    9  fax        +14159657824 11Nov95 faxAAAa006nC
-rw----   25  fax        +14159657824 Fri08PM fax00016.tif
226 Transfer complete.
ftp> quit
221 Goodbye.

The following command shows how to use a Telnet client program to communicate directly with an SNPP server:

hyla% telnet melange.esd 444
Trying 192.111.25.40...
Connected to melange.esd.sgi.com.
Escape character is '^]'.
220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
login sam
230 User sam logged in.
help
214 The following commands are recognized (* =>'s unimplemented).
214 2WAY*   ALER*   DATA    HOLD    LOGI    MSTA*   PING    RTYP*   STAT
214 ABOR    CALL*   EXPT*   KTAG*   MCRE*   NOQU*   QUIT    SEND    SUBJ
214 ACKR*   COVE*   HELP    LEVE    MESS    PAGE    RESE    SITE
250 Direct comments to FaxMaster@melange.esd.sgi.com.
page 5551212
250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
send
250 Message processing completed.
quit
221 Goodbye.
Connection closed by foreign host.

✨ FILES ✨

okay so here's the whole squad of files this thing rolls with, no cap 💖

• /usr/bin/sendfax — this one's for sending facsimile, like, the whole point 🎀
• /usr/bin/sendpage — for sending alpha-numeric pages, yep it does that too
• /usr/bin/fax2ps — for converting facsimile to POSTSCRIPT, glow up incoming ✨
• /usr/bin/faxalter — for altering queued jobs, aka changing your mind after the fact 💅
• /usr/bin/faxcover — for generating cover sheets, the aesthetic part fr
• /usr/bin/faxmail — for converting email to POSTSCRIPT, iconic crossover
• /usr/bin/faxrm — for removing queued jobs, the "never mind" button 🫶
• /usr/bin/faxstat — for facsimile server status, your daily vibe check 👑
• /usr/bin/sgi2fax — SGI image file converter, niche but slay
• /usr/bin/textfmt — ASCII text converter, lowkey the workhorse
• /etc/hylafax/typerules — file type and conversion rules, the rulebook bestie
• /etc/hylafax/pagesizes — page size database, all the dimensions 🌸
• /etc/hylafax/faxcover.ps — prototype cover page, the template energy
• /etc/hylafax/dialrules — optional client dialstring rules, optional but cute
• /var/spool/hylafax/tmp/sndfaxXXXXXX — temporary files, they come and they go 🦋

---

🌈 SEE ALSO 🌈

go read these too, they're all in the friend group fr fr:

at(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1), faxstat(1), sgi2fax(1), faxq(8C), viewfax(1), hylafax-server(5F), dialrules(5F), pagesizes(5F), typerules(5F), services(4)

---

and that's the whole page bestie, you made it to the end 🥹💖

this little masterpiece is from HYLAFAX-CLIENT(1), dated May 8, 1996 — yeah she's vintage, she's timeless, she's giving main character energy from another era 👑✨ go forth and fax responsibly, mwah 💅🎀