EFAX(1)

📦
version 0.9a · 2 versions
  • 0.9a · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 0.9a · fedora 43, fedora 44
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 EFAX 💖

okay bestie, welcome to efax — the tool that sends and receives faxes with a Class 1, 2 or 2.0 fax modem. yes, faxes. yes, in this economy. she's iconic, she's vintage, she ATE. 🎀

bestie pls read the fax man page first. like actually, do that. it's giving "prerequisite". 💅

✨ SYNOPSIS ✨

efax [ options ] [ -t num [ file... ] ]

🌸 OPTIONS 🌸

so here's where all the options live. buckle up, there's a lot, and they're all real:

  • -a cmd — when she picks up the phone, send the command ATcmd. the default is literally just "A". short and sweet. 💖
  • -c caps — sets the local modem capabilities. the format and meaning of caps lives in the capabilities section down below, so peek there. for Class 1 the default is 1,n,0,2,0,0,0,0 where n is the highest speed your modem can do. for Class 2, the modem itself decides the default. not you. the modem. 😌
  • -d dev — use the fax modem chilling on device dev. default is /dev/modem.
  • -f fnt — use font file fnt for generating the header. default is a built-in 8x16 font. the font file format is described in the efix(1) -f option, iykyk. ✨
  • -g cmd — if a CONNECT (or DATA) response means it's a data call, then /bin/sh gets exec(2)'ed with cmd as its command. cmd is a printf(3) format and can hold up to 6 %d escapes — those get replaced by the baud rate from the most recent CONNECT message. typically cmd just exec's getty(8). 🫶
  • -h hdr — put the string hdr at the top of every page. the first %d in hdr becomes the page number, and the second one (if you put one) becomes the number of pages being sent. cute, right? 🎀
  • -i str
  • -j str
  • -k str — send the command ATstr to the modem to initialize it. so: -i commands go out before the modem is put into fax mode, -j commands go out after the modem is in fax mode, and -k commands go out right before efax exits. the only default is a hang-up (ATH) command, and it only gets sent before exiting if you gave no other -k options. you can stack multiple of these. 💅
  • -l id — set the local identification string to id. id should be your local telephone number in international format, like "+1 800 555 1212". this gets passed to the remote fax machine. heads up: some fax machines will straight up refuse characters that aren't numbers, spaces, or '+'. 🙈
  • -o opt — use option opt to accommodate a non-standard fax modem protocol. more deets live in the MODEM REQUIREMENTS section. the options are:
    • 0 — force use of Class 2.0 fax modem commands. the modem must support Class 2.0.
    • 2 — force use of Class 2 fax modem commands. the modem must support Class 2.
    • 1 — force use of Class 1 fax modem commands. the modem must support Class 1. by default efax queries the modem and uses the first of the three classes above that the modem actually supports.
    • a — use the software adaptive answer method. if the first attempt to answer the call doesn't give you a data connection within 8 seconds, the phone gets hung up temporarily and answered again in fax mode (see "Accepting both fax and data calls" below).
    • e — ignore errors in modem initialization commands.
    • f — use "virtual flow control". efax tries to estimate how many bytes are sitting in the modem's transmit buffer and pauses as needed so it doesn't overflow. the modem's buffer is assumed to hold at least 96 bytes. ⚠️ this does not work properly with Class 2 modems that add redundant padding to scan lines. only use this if you're having trouble configuring flow control.
    • h — use hardware (RTS/CTS) in addition to software (XON/XOFF) flow control. many modems will just stop responding if you do this. check the Resolving Problems section before you try it, fr fr. 💀
    • l — halve the time between testing lock files while waiting for other programs to finish. by default that's 8 seconds. so like, -olll sets the interval to 1 second. math! 🧚
    • n — ignore requests for pages to be retransmitted. use this if you don't care about the quality of the received fax, or if the receiving machine is being too fussy. otherwise each page can be retransmitted up to 3 times.
    • r — don't reverse bit order during data reception for Class 2 modems. only Multitech modems need this. not normally required because efax detects those modems itself. 👑
    • x — send XON (DC1) instead of DC2 to start data reception. this only applies to a very few Class 2 modems.
    • z — delay an extra 100 milliseconds before each modem initialization or reset command. the initial delay is 100 ms. so -ozzz gives you a 400 ms delay. use this with modems that get confused when commands show up too fast. 😭
  • -q n — ask for retransmission of pages that were received with more than n errors. default is 10.
  • -r pat — each received fax page gets stored in its own file. the file name is built using pat as a strftime(3) format string. a page number like .001, .002, ... gets appended to the file name. if pat is blank ("") or you didn't give a -r option at all, the default string is "%m%d%H%M%S". 🗂️
  • -s — remove lock file(s) after initializing the modem. this lets outgoing calls go through while efax is waiting for an incoming call. if efax detects modem activity it'll try to re-lock the device. but if the modem has been locked by the other program, efax will exit and return 1 (busy). normally a new efax process gets started by init(8) at that point, and that new process checks periodically until the lock file disappears, then re-initializes the modem. ✨
  • -t num [file...] — dial telephone number num and send the fax image files file.... if you use it, this must be the last argument on the command line. periodt. num is a string that can contain any dial modifiers your modem supports — like a T prefix for tone dialing, or commas for delays. if you give no file names, the remote fax machine gets polled. and if you give no -t argument at all, efax will answer the phone and try to receive a fax instead. 📞
  • -v strng — select which types of messages get printed. each lower-case letter in strng switches on one type of message:
    • e — errors
    • w — warnings
    • i — session progress information
    • n — capability negotiation information
    • c — modem (AT) commands and responses
    • h — HDLC frame data (Class 1 only)
    • m — modem output
    • a — program arguments
    • r — reception error details
    • t — transmission details
    • f — image file details
    • x — lock file processing

you can use up to two -v options. the first one controls messages printed to standard error, the second controls messages to standard output. the default is "ewin" to standard error only. 💖

  • -w — wait for an OK or CONNECT prompt instead of issuing an answer (ATA) command to receive a fax. use this when the modem is set to auto-answer (with S0=n) or if another program already answered the call. 👑
  • -x lkf — use a UUCP-style lock file lkf to lock the modem device before opening it. if the device is locked, efax checks every 15 seconds until it's free. you can use up to 16 -x options if the same device has several names. a '#' prefix on the file name creates a binary rather than text (HDB-style) lock file. this is the reverse of what previous efax versions used, so don't get it twisted. 💅

🌈 FAX FILE FORMATS 🌈

efax can read the same types of files as efix(1) — that means text, T.4 (Group 3), PBM, and single- and multi-page TIFF (G3 and uncompressed). she figures out the type of file from its contents automatically, main character energy. TIFF files are the recommended ones because they carry info about the image size and resolution. 🎀

each page you want to send should be converted into a separate TIFF format file with Group 3 (G3) compression. received files get stored in this format too. the EXAMPLES section further down shows how efix and other programs can create, view and print these files. 🦋

💜 OPERATING SYSTEM REQUIREMENTS 💜

the operating system has to provide short response times or you'll hit protocol timeouts. for Class 2 and 2.0 modems, the delay should not exceed 1 or 2 seconds.

when you're using Class 1 modems, the program must respond to certain events within 55 milliseconds. longer delays can make the fax protocol fail in certain places (between DCS and TCF, or between RTC and MPS). so Class 1 modems should not be used on systems that can't guarantee the program responds to incoming data in under 55 milliseconds. in particular, some intelligent serial cards and terminal servers add enough delay to cause problems with Class 1 operation. 😭

the operating system also has to provide enough low-level buffering to allow uninterrupted data transfer between the modem and a disk file at the selected baud rate — typically 9600 bps. since the fax protocol does not provide end-to-end flow control, how effective flow control is while receiving is limited by the size of the modem's buffer. and that can be less than 100 bytes. also: efax does not use flow control during reception. 💀

💖 MODEM REQUIREMENTS 💖

okay so first, the vocab, because these two words sound similar and they are NOT the same thing bestie:

  • The "Group" — this is the protocol fax machines use to talk to each other. efax supports Group 3, the one that runs over the public telephone network. 🫶
  • The "Class" — this is the protocol computers use to boss fax modems around. efax supports Class 1, 2 and 2.0 fax modems. slay.

Now, flow control. Most fax modems use XON/XOFF flow control when they're in fax mode, and honestly? For fax that's barely any overhead. But a lot of modems have straight-up unreliable hardware (RTS/CTS) flow control in fax mode. So by default efax only turns on XON/XOFF, and you have to use the -oh option if you want to add hardware flow control. noted. 💅

Buffers, babes: some modems have serial buffers around 1k bytes, but a whole lot of the inexpensive ones have buffers of about one hundred bytes, which means they're way more likely to suffer overruns when you're sending faxes. 😭

A few older modems need a delay between commands longer than the default efax uses (100 milliseconds). If that delay is too short, commands may not echo properly, may time out, or may give inconsistent responses — it's giving chaos. The fix: use one or more -oz options to increase the delay between modem initialization commands, and use the E0 modem initialization command to disable echoing of modem commands. ✨

By default efax sends DC2 to start the data flow from the modem when receiving faxes from Class 2 modems. A few older modems want XON instead. If you send DC2 anyway, the modem would give an error message and/or the program would time out. So in that case, use the -ox option. 🎀

A few older Class 2 modems (e.g. some Intel models) don't send DC2 or XON to start the data flow to the modem when sending faxes. efax waits 2 seconds, prints a warning, and starts sending anyways. iconic behaviour honestly.

A very few Class 2 modems don't reverse the bit order (MSB to LSB) by default on receive. That might cause errors when you try to display or print the received files. Use the -or option in this case. 🦋

Also: some inexpensive "9600 bps" fax modems only transmit at 9600 bps, and reception is limited to 4800 bps. read the fine print, bestie.

Here's the certified good-list. The following Class 1 modems have been reported to work with efax:

  • AT&T DataPort
  • Cardinal Digital Fax Modem (14400)
  • Digicom Scout+
  • Motorola Lifestyle 28.8
  • Motorola Power 28.8
  • QuickComm Spirit II
  • Smartlink 9614AV-Modem
  • Supra Faxmodem 144LC
  • USR Courier V.32bis Terbo
  • USR Sportster (V.32 and V.34)
  • Zoom AFC 2.400
  • Zoom VFX14.4V

And the following Class 2 modems have been reported to work with efax:

  • 14k4 Amigo Communion fax/modem
  • Adtech Micro Systems 14.4 Fax/modem
  • askey modem type 1414VQE
  • AT&T DataPort
  • ATT/Paradyne
  • AT&T Paradyne PCMCIA
  • Boca modem
  • BOCA M1440E
  • Crosslink 9614FH faxmodem
  • FuryCard DNE 5005
  • GVC 14.4k internal
  • Intel 14.4 fax modem
  • Megahertz 14.4, , Microcom DeskPorte FAST ES 28.8
  • Motorola UDS FasTalk II
  • MultiTech 1432MU
  • Practical Peripherals PM14400FXMT
  • Supra V32bis
  • Telebit Worldblazer
  • TKR DM-24VF+
  • Twincom 144/DFi
  • ViVa 14.4/Fax modem
  • Vobis Fax-Modem (BZT-approved)
  • Zoom VFX14.4V
  • ZyXEL U-1496E[+]
  • ZyXEL Elite 2864I

✨ MODEM INITIALIZATION OPTIONS ✨

The required modem initialization commands are generated by efax, no worries. But you can pass extra commands as command-line arguments if you're feeling extra. 💅

The modem has to be set up to issue verbose(text) result codes. This command does that, and efax sends it before trying to initialize the modem:

Q0V1     respond to commands with verbose result codes

The following commands may be useful for special purposes:

  • X3 — don't wait for dial tone before dialing. This may be used to send a fax when the call has already been dialed manually. In this case use an empty string ("") as the first argument to the -t command. Use X4 (usual default) to enable all result codes.
  • M2 — leave the monitor speaker turned on for the duration of the call (use M0 to leave it off).
  • L0 — turn monitor speaker volume to minimum (use L3 for maximum).
  • E0 — disable echoing of modem commands. See the Resolving Problems section below. 👀
  • &D2 — returns the modem to command mode when DTR is dropped. The program drops DTR at the start and end of the call if it can't get a response to a modem command. You can use &D3 to reset the modem when DTR is dropped.
  • S7=120 — wait up to two minutes (120 seconds) for carrier. This may be useful if the answering fax machine takes a long time to start the handshaking operation (e.g. a combined fax/answering machine with a long announcement). 😮‍💨

🌈 CAPABILITIES 🌈

You can set the capabilities of your local hardware and software with a string of 8 digits separated by commas:

vr,br,wd,ln,df,ec,bf,st

where, bestie:

  • vr (vertical resolution) =
    • 0 for 98 lines per inch
    • 1 for 196 lpi
  • br (bit rate) =
    • 0 for 2400 bps
    • 1 for 4800
    • 2 for 7200
    • 3 for 9600
    • 4 for 12000 (V.17)
    • 5 for 14400 (V.17)
  • wd (width) =
    • 0 for 8.5" (21.5 cm) page width
    • 1 for 10" (25.5 cm)
    • 2 for 12" (30.3 cm)
  • ln (length) =
    • 0 for 11" (A4: 29.7 cm) page length
    • 1 for 14" (B4: 36.4 cm)
    • 2 for unlimited page length
  • df (data format) =
    • 0 for 1-D coding
    • 1 for 2-D coding (not supported)
  • ec (error correction) =
    • 0 for no error correction
  • bf (binary file) =
    • 0 for no binary file transfer
  • st (minimum scan time) =
    • 0 for zero delay per line
    • 1 for 5 ms per line
    • 3 for 10 ms per line
    • 5 for 20 ms per line
    • 7 for 40 ms per line

When you're receiving a fax, the vr, wd, and ln fields of the capability string should be set to the maximum values that your display software supports. The default is 196 lpi, standard (8.5"/21.5cm) width and unlimited length. 🎀

When you're sending a fax, efax will determine vr and ln from the image file and set wd to the default. it just knows.

If the receiving fax machine does not support high resolution (vr=1) mode, efax will reduce the resolution by combining pairs of scan lines. And if the receiving fax machine does not support the image's width, efax will truncate or pad as required. Most fax machines can receive ln up to 2. Few machines support values of wd other than 0. shrug. 💀

🎀 HEADERS 🎀

efax adds blank scan lines at the top of each image when it is sent. This allows room for the page header, but it also increases the length of the image (by default about 0.1" or 2.5mm of blank space is added).

The header placed in this area typically includes the date and time, identifies the, and shows the page number and total pages. Headers cannot be disabled, but the header string can be set to a blank line. (yes, really, that's the loophole 🫶)

The default font for generating the headers is the built-in 8x16 pixel font scaled to 12x24 pixels (about 9 point size).

Note that both efax and efix have -f options to specify the font. efIx uses the font to generate text when doing text-to-fax conversions (during "fax make") while efAx uses the font to generate the header (during "fax send"). iykyk. ✨

💜 SESSION LOG 💜

A session log is written to the standard error stream. This log gives status and error messages from the program, as selected by the -v option. A time stamp showing the full time or just minutes and seconds is printed before each message. Times printed along with modem responses also show milliseconds. very precise of it.

⭐ RETURN VALUES ⭐

The program returns an error code as follows:

  • 0 — The fax was successfully sent or received. 🎉 ate.
  • 1 — The dialed number was busy or the modem device was in use. Try again later.
  • 2 — Something failed (e.g. file not found or disk full). Don't retry. Check the session log for more details.
  • 3 — Modem protocol error. The program did not receive the expected response from the modem. The modem may not have been properly initialized, the correct -o options were not used, or a bug report may be in order. Check the session log for more details. 🐛
  • 4 — The modem is not responding. Operator attention is required. Check that the modem is turned on and connected to the correct port. 😭
  • 5 — The program was terminated by a signal.

✨ EXAMPLES ✨

🎀 Creating fax (G3) files

The efix program can turn your boring text files into TIFF-G3 fax files. Like, actual fax-ready images. Bestie, it's giving magic.

For example, this command converts the text file letter into the files letter.001, letter.002, etc:

efix -nletter.%03d letter

Ghostscript's tiffg3 driver can also generate fax files in TIFF-G3 format from postscript files. For example, this command:

gs -q -sDEVICE=tiffg3 -dNOPAUSE \
    -sOutputFile=letter.%03d letter.ps </dev/null

will convert the Postscript file letter.ps into high-resolution (vr=1) G3 fax image files letter.001, letter.002, ...

💅 Real talk: your images should have margins of at least 1/2 inch (1 cm), because the fax standard only requires that fax machines print a central portion of the image 196.6mm (7.7 inches) wide by 281.5mm (11.1 inches) high. Everything outside that is living dangerously, no cap.

The efix program can also insert bitmaps in images to create letterhead, signatures, etc. Cute, right? 🎀

🌸 Printing fax files

You can use efix to print faxes on Postscript or HP-PCL (LaserJet) printers. For example, to print the received fax file reply.001 on a Postscript printer, use this command:

efix -ops reply.001 | lpr

💖 Sending fax files

This command will dial the number 222-2222 using tone dialing and send a two-page fax from the TIFF-G3 files letter.001 and letter.002 using the fax modem connected to device /dev/cua1.

efax -d /dev/cua1 \
     -t T222-2222 letter.001 letter.002

🦋 Manual answer

You can use efax to answer the phone immediately and start fax reception. Use this mode if you need to answer calls manually to see if they're fax or voice — like a little receptionist moment, but for modems.

For example, this command will make the fax modem on device /dev/ttyS1 answer the phone and attempt to receive a fax. The received fax will be stored in the files reply.001, reply.002, and so on. The modem will identify itself as "555 1212" and receive faxes at high or low resolution (vr=1), at up to 14.4 kbps (br=5).

efax -d /dev/ttyS1 -l "555 1212" \
   -c 1,5 -r reply

🌈 Automatic answer

The -w option makes efax wait for characters to become available from the modem (which indicates an incoming call, iykyk) before starting fax reception. Use the -w option and a -iS0=n option to answer the phone after n rings.

The example below will make the modem answer incoming calls in fax mode on the fourth ring and save the received faxes using file names corresponding to the reception date and time.

efax -d /dev/ttyb -w -iS0=4 2>&1 >> fax.log

💜 Sharing the modem with outgoing calls

The modem device can be shared by programs that use the UUCP device locking protocol. This includes pppd, chat, minicom, kermit, uucico, efax, cu, and many others others. (Yes, we said it twice. It's a vibe. 💀) However, locking will only work if all programs use the same lock file.

efax will lock the modem device before opening it if one or more UUCP lock file names are given with -x options. Most programs place their lock files in the /usr/spool/uucp or /var/lock directories and use the name LCK..dev where dev is the name of the device file in the /dev directory that is to be locked.

If the -s (share) option is used, the lock file is removed while waiting for incoming calls so other programs can use the same device. Sharing is caring, periodt. 🫶

If efax detects another program using the modem while it is waiting to receive a fax, efax exits with a termination code of 1. A subsequent efax process using this device will wait until the other program is finished before re-initializing the modem and starting to wait for incoming calls again.

Programs that try to lock the modem device by using device locking facilities other than UUCP lock files not be able to use this arbitration mechanism because the device will still be open to the efax process. In this case you will need to kill the efax process (e.g. "fax stop") before starting the other program.

When efax is waiting for a fax it leaves the modem ready to receive in fax mode but removes the lock file. When a slip or PPP program takes over the modem port by setting up its own lock file, efax cannot send any more commands to the modem — not even to reset it. 😭 Therefore the other program has to set the modem back to data mode when it starts up. To do this, add a modem reset command (send ATZ expect OK) to the beginning of your slip or PPP chat script.

⭐ Accepting both fax and data calls

Many modems have an adaptive data/fax answer mode that can be enabled using the -j+FAE=1 (for Class 1) or -jFAA=1 (for Class 2[.0]) initialization string. The type of call (data or fax) can then be deduced from the modem's responses. Detective energy. 🔍

Some modems have limited adaptive answer features (e.g. only working properly at certain baud rates or only in Class 2) or none at all. In this case use the initialization string -i+FCLASS=0 to answer in data mode first and the -oa option to then hang up and try again in fax mode if the first answer attempt was not successful. This method only works if your telephone system waits a few seconds after you hang up before disconnecting incoming calls.

If the -g option is used then the option's argument will be run as a shell command when an incoming data call is detected. Typically this command will exec getty(8). This program should expect to find the modem already off-hook and a lock file present, so it should not try to hang up the line or create a lock file. Note that the modem should be set up to report the DCE-DTE (modem-computer, e.g. CONNECT 38400) speed, not the DCE-DCE (modem-modem, e.g. CONNECT 14400) speed. For many modems the initialization option -iW0 will set this.

The following command will make efax answer incoming calls on /dev/cua1 on the second ring. This device will be locked using two different lock files but these lock files will be removed while waiting for incoming calls (-s). If a data call is detected, the getty program will be run to initialize the terminal driver and start a login(1) process. Received fax files will be stored using names like Dec02-12.32.33.001, in the /usr/spool/fax/incoming directory, and the log file will be appended to /usr/spool/fax/faxlog.cua1.

efax -d /dev/cua1  -j '+FAA=1' \
   -x /usr/spool/uucp/LCK..cua1 \
   -x /usr/spool/uucp/LCK..ttyS1 \
   -g "exec /sbin/getty -h /dev/cua1 %d" \
   -iS0=2 -w -s \
   -r "/usr/spool/fax/incoming/%b%d-%H.%I.%S" \
   >> /usr/spool/fax/faxlog.cua1 2>&1
⚠️ Heads up bestie: adaptive answer of either type will not work for all callers. For some data calls the duration of the initial data-mode answer may be too short for data handshaking to complete. In other cases this duration may be so long that incoming fax calls will time out before efax switches to fax mode. In addition, some calling fax modems mistake data-mode answering tones for fax signaling tones and initiate fax negotiation too soon. If you use software adaptive answer you can reduce the value of the initial data-mode answer (set by TO_DATAF in efax.c) to get more reliable fax handshaking, or increase it for more reliable data handshaking. However, if you need to provide reliable fax and data service to all callers you should use separate phone numbers for the two types of calls. Two numbers, two moods. 💅

When a call is answered the modem goes on-line with the computer-to-modem baud rate fixed at the speed used for the most recent AT command. When efax is waiting for a fax or data call it sets the interface speed to 19200 bps since this is the speed required for fax operation. This prevents full use of 28.8kbps modem capabilities. 😔 Sorry girl.

🌟 USING INIT TO RUN EFAX 🌟

efax can answer all incoming calls if you place an entry for efax in /etc/inittab (for SysV-like systems) or /etc/ttytab (for BSD-like systems). The init(8) process will run a new copy of efax when the system boots up and whenever the previous efax process terminates. The inittab or ttytab entry should invoke efax by running the fax script with an answer argument.

For example, placing the following line in /etc/inittab (and running "kill -1 1") will make init run the fax script with the argument answer every time the previous process terminates and init is in runlevel 4 or 5.

s1:45:respawn:/bin/sh /usr/bin/fax answer

For BSD-like systems (e.g. SunOS), a line such as the following in /etc/ttytab will have the same effect:

ttya "/usr/local/bin/fax answer" unknown on
👑 You should protect the fax script and configuration files against tampering, since init will execute them as a privileged (root) process. If you will be allowing data calls via getty and login you should ensure that your system is reasonably secure (e.g. that all user id's have secure passwords). Lock it down, bestie, main character energy means main character security. 🔥

If efax exec()'s getty properly but you get a garbled login prompt then there is probably a baud rate mismatch between the modem and the computer. First, check the efax log file to make sure the modem's CONNECT response reported the serial port speed (e.g. 19200), not the modem-modem speed (e.g. 14400). Next, check the getty options and/or configuration files (e.g. /etc/gettydefs) for that particular baud rate. Then run getty manually with the same arguments and verify the port settings using stty </dev/XXX. Note that you'll probably want to enable hardware flow control for data connections (-h for agetty, CRTSCTS for getty_ps).

A few programs won't work properly when efax is set up to answer calls because they don't create lock files. You can put the shell script wrapper below around such programs to make them work properly. Change BIN and LOCKF to suit.

#!/bin/sh
BIN=/bin/badprogram
LOCKF=/var/spool/uucp/LCK..cua1
if [ -f $LOCKF ]
then
        echo lock file $LOCKF exists
        exit 1
else
        printf "%10d0 $$ >$LOCKF
        $BIN $*
        rm $LOCKF
fi

💌 DELIVERING RECEIVED FAXES BY E-MAIL 💌

The "fax answer" script described above can be configured to e-mail the fax files received by the previous fax answer process to a "fax manager" who can then forward the fax to the correct recipient. The received fax files are send as MIME attachments, one file per page, using the base64 text encoding and the image/tiff file format. Slay. 📬

To view the fax images directly from your e-mail reader you will have to configure it with an application that can display files of type image/tiff. Typically this is specified in a mailcap file. For example, placing the following line in /etc/mailcap will cause the fax file attachments to be displayed using the fax view command.

image/tiff; fax view %s

🖨️ SENDING FAXES USING THE PRINT SPOOLER 🖨️

Okay bestie, this one is so fun. You can wire a "fax" printer straight into the lpr print spooler so that instead of printing a doc, it faxes it out using efax. Which means a network server running efax can send faxes on behalf of other machines, even the non-Unix girlies. Slay.

In the steps below, if the directories in the fax script aren't /usr/bin and /var/spool/fax (FAXDIR), use whatever the script actually says. To set up a fax printer, do all this as root:

  1. Make a link to the fax script called faxlpr so the fax script can clock when it's being invoked from the print spooler:
ln -s /usr/bin/fax /usr/bin/faxlpr
  1. Edit /etc/printcap and add an entry like:
fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr:

which defines a printer called "fax". Print files get spooled into the /var/spool/fax (sd=) directory and then piped to the /usr/bin/faxlpr filter (if=). Error messages will show up on /dev/console. 💅

  1. Create the fax spool directory and/or set its permissions so anyone can read and write in it. For example:
mkdir /var/spool/fax
chmod 777 /var/spool/fax
  1. Create a printer daemon lock file that's readable by anyone:
touch /var/spool/fax/lock
chmod 644 /var/spool/fax/lock

You should now be able to send a fax through the lpr interface with a command like:

lpr -P fax -J "555 1212" file.ps

where the -J option is what you use to specify the phone number or alias to be dialed. ✨

Heads up bestie: if more than one file is given on the command line they get concatenated before being passed to "fax send". So TIFF-G3, Postscript or PBM files have to be sent one file at a time, even though TIFF and Postscript files may contain multiple pages. Only multiple text files can be sent in one command. Page breaks in text files can be marked with form-feed characters. Files get converted and sent at the default (high) resolution. No cap.

You can use lpq(1) to check the fax queue, lprm(1) to remove fax jobs and lpc(8) to control the spooler. In every case use the -Pfax option to specify the fax "printer." A log file gets mailed to the user when the fax is sent. 🫶

You should also be able to send a fax from any networked computer that has lpr-compatible remote printing software and that lets you set the job name (-J option) to an arbitrary string. That kind of software exists for basically most computers, iconic.

See the lpd(8) and printcap(5) man pages for info on the print spooler and for restricting access by host name (/etc/host.lpd) or by user group (the rg printcap entry).

🚑 RESOLVING PROBLEMS 🚑

Double check the configuration setup in the first part of the fax script, especially the modem device name and the lock file names. Fr fr, it's always this.

If efax hangs when trying to open the modem device (typically /dev/ttyX), the device is either already in use by another process (e.g. pppd) or it requires the carrier detect line to be true before it can be opened. Many systems define an alternate device name for the same physical device (typically cuaX) that can be opened even if carrier isn't present or other programs are already using it. 💡

If responses to modem initialization commands are being lost or generated at random, another process (e.g. getty or an efax auto-answer process) may be trying to use the modem at the same time. Try running efax while this other program is running. If efax does not report "/dev/ttyX locked or busy. waiting." then the lock file names are not specified correctly. 😭

Attempt to send a fax. Check that the modem starts making the calling signal (CNG, a 0.5 second beep every 3 seconds) as soon as it's finished dialing. This shows the modem is in fax mode. You may need to set the SPKR variable to -iM2L3 to monitor the phone line to do this. 🔥

Listen for the answering fax machine and check that it sends the answer signal (CED, a 3 second beep) followed by "warbling" sounds (DIS frames) every 3 seconds. If you hear a continuous sound (tones or noise) instead, then you've connected to a data modem instead. Awkward.

Your modem should send back its own warble (DCS frame) in response to DIS, immediately followed by 1.5 seconds of noise (a channel check). If everything is OK, the receiving end will send another warble (CFR frame) and your modem will start to send data. If you have an external modem, check its LEDs. If flow control is working properly the modem's send data (SD) LED will turn off periodically while the fax data is sent. ⭐

Check the message showing the line count and the average bit rate when the page transmission is done. Low line counts (under 1000 for a letter size image) or the warning "fax output buffer overflow" while sending indicate that the image data format is incorrect. Check the file being sent using the "fax view" command. 👀

If you get the error message "flow control did not work" then flow control was not active. This usually results in a garbled transmission and the receiving machine may reject the page, abort the call, print a distorted or blank image and/or hang up. 💀

The warning "characters received while sending" or an <XOFF> character appearing after the transmission means that the operating system ignored the modem's XOFF flow control character. Ensure that you are not running other programs such as getty or pppd at the same time as efax since they will turn off xon/xoff flow control. 🙈

If you cannot get flow control to work properly then enable "virtual flow control" with the -of option or hardware flow control with the -oh option.

Check that the remote machine confirms reception with a +FPTS:1 response (Class 2) or an MCF frame (Class 1).

For Class 2 modems, the error message "abnormal call termination (code nn)" indicates that the modem detected an error and hung up.

Many companies advertise services that will fax back information on their products. These can be useful for testing fax reception. (Honestly? Kind of a vibe.)

The message "run length buffer overflow" when receiving indicates an error with the image data format. You may need to use the -or option with certain Class 2 modems.

If efax displays the message "can't happen (<details>)" please send a bug report to the author. 😳

Finally, don't play "option bingo," if you can't resolve the problem send a verbose log of the failed session (the output from fax -v ...) to the address below.

🌐 WEB PAGE 🌐

A Web Page with pointers to the latest version, known bugs and patches is available at:

http://www.cce.com/efax/

For Linux Systems

Independent packages provide more user-friendly interfaces to efax (xfax, tefax) and provide an e-mail-to-fax (Qfax) gateway using efax. All are available by anonymous FTP from metalab.unc.edu in /pub/Linux/apps/serialcomm/fax/. 💖

For Amiga Systems

A port of an early version of efax for the Amiga is available as a component of a shareware voice mail package, AVM, distributed by Al Villarica (rvillari@cat.syr.edu).

Other Ports

efax is relatively easy to port. All system-dependent code is in efaxos.c. An early version of efax was ported to VMS. Version 0.8a was ported to Win32 by Luigi Capriotti. Contact the author if you would like to integrate the Win32 code into the current version.

👑 AUTHOR 👑

Efax was written by Ed Casas. Please send comments or bug reports to edc@cce.com.

🐛 BUG REPORTS 🐛

Bug reports should include the operating system, the type of the modem and a copy of a verbose session log that demonstrates the problem. It's usually impossible to help without a verbose log. Please do not send fax image files. (Not the fax pics bestie, we beg. 😭)

efax is copyright 1993 -- 1999 Ed Casas. It may be used, copied and modified under the terms of the GNU Public License.

🙏 DISCLAIMER 🙏

Although efax has been tested it may have errors that will prevent it from working correctly on your system. Some of these errors may cause serious problems including loss of data and interruptions to telephone service. 😬

📚 REFERENCES 📚

  • CCITT Recommendation T.30, "Procedures for Document Facsimile Transmission in the General Switched Telephone Network". 1988
  • CCITT Recommendation T.4, "Standardization of Group 3 Facsimile Apparatus for Document Transmission". 1988.
  • For documentation on Class 1 and Class 2 fax commands as implemented by Connexant (formerly Rockwell) modems see http://www.conexant.com/techinfo.
  • For the TIFF specification see http://partners.adobe.com/supportservice/devrelations/PDFS/TN/TIFF6.pdf or RFC 2301 (ftp://ftp.isi.edu/in-notes/rfc2301.txt).
  • For information on Ghostscript see http://www.cs.wisc.edu/~ghost/.
  • The pbm utilities can be obtained by ftp from wuarchive.wustl.edu in /graphics/graphics/packages/NetPBM/netpbm-1mar1994.tar.gz.
  • PCX and many other file formats are described in: Gunter Born, The File Formats Handbook, International Thomson Computer Press, 1995.
  • The "Fax Modem Source Book" by Andrew Margolis, published by John Wiley & Sons in 1994 (ISBN 0471950726), is a book on writing fax applications which includes source code.
  • Dennis Bodson et. al., "FAX: Digital Facsimile Technology and Applications", Second Edition. Artech House, Boston. 1992.

🌈 SEE ALSO 🌈

fax(1), efix(1), gs(1), init(8), inittab(5), ttytab(5), printcap(5), lpd(8), printf(3), strftime(3).

💀 BUGS 💀

  • Can't read TIFF files with more than 1 strip
  • Class 1 operation may fail if the program can't respond to certain data received from the modem within 55 milliseconds.
  • May fail if multitasking delays cause the received data to overflow the computer's serial device buffer or if an under-run of transmit data exceeds 5 seconds.
  • Polling does not work.
  • Does not support 2-D coding, ECM, or BFT.

and that's the whole page, bestie!! 🎀 This one came from the 3rd Berkeley Distribution, dated February 1999, and it's the manual page for EFAX(1) — go forth and fax responsibly, mwah 💅✨🦋

📦 where this page comes from