3.3 Basic sendfax usage

Sendfax is very primitive—no spool management, no format conversion, etc. It is designed to be able to send exactly one fax (consisting of multiple pages) to exactly one fax machine, but it is usable from within shell scripts. Its input are pages in “g3” format, either created with ghostscript or with pbm2g3.

It is called like this:

sendfax [-v] [-n] <phone-number> <fax page(s)>

e.g.

sendfax 0893243328 /tmp/to_gert_1.g3 /var/spool/fax/outgoing/picture.g3

It will then attempt to open the fax device and send all the pages to the remote fax machine, in the given order.

It will print little or nothing to stdout or stderr, except if it cannot find or open one of the named files, or if some transmission errors occur.

(There are a few stubs in the code to put headers on the pages at run-time, but since most class 2 faxmodems do not implement the command set properly, putting a header on a page does not work with them - because of that, I had to disable the corresponding code. faxspool works around this problem by using g3cat (see Fax-Tools) to “paste” a header line on top of each page)

If you specify ‘-v’, sendfax will output more verbose progress messages.

If you specify ‘-n’, it will try to send the fax data in normal resolution, default is fine resolution. (No conversion is done, so make sure that your input data is already in the proper format.)

Detailed reports can be found in the log file (usually /var/log/sendfax.log) — but they may be of little more than technical interest since virtually all conversation with the fax modem is logged. (Nevertheless, if you send me any bug report, please include all log files)

Warning: Watch sendfax closely when sending the first few faxes. I had it abort a transfer a couple of times, not being able to recover and not hanging up the modem (the modem was completely locked up, with the phone line off-hook)! In my case, it was a problem of the modem that went away when I upgraded the firmware. Very old ZyXEL releases sometimes stopped the DTE and forgot to re-start it again.

The return codes of the sendfax program were chosen to make it easy for external programs (i.e. faxrunq) to decide whether to try again or not:

 0: all pages transmitted successful
 1: error on command line
 2: cannot open fax device (typically happens if fax device is
    locked, but could also be a permission problem)
 3: error initializing the modem
 4: dial failed, "BUSY"
 5: dial failed, "NO DIALTONE"
10: dial failed, "ERROR" or "NO CARRIER"
11: waiting for XON failed (should never be seen)
12: transmitting page(s) failed (or polling failed)
15: some catastrophe hit (termination signal or blocked modem)

If the error code is less than 10, the attempt didn’t cost anything, so an external program should try again to send the files. If it is 10 or higher, the failed attempt probably cost something, and the program should decide whether to try again (thus expending more money) or mail the operator and tell him something went wrong. My faxrunq program will suspend the job after five unsuccessful tries with error codes >= 10.