EFAX(1)
NAME
efax - send/receive faxes using Class 1 or 2 fax modems
SYNOPSIS
efax [ options ] [ -t num [ file... ] ]
OPTIONS
Where options are:
-a cmd use the command ATcmd when answering the phone.
The default is "A".
-c caps set the local modem capabilities. See the sec-
tion on capabilities below for the format and
meaning of caps. The default is 1,3,0,2,0,0,0,0.
-d dev use the fax modem connected to device dev. The
default is /dev/fax.
-f fnt use font file fnt for generating the header. The
default is a built-in 8x16 font. See efix(1) for
the font file format.
-g cmd if a CONNECT (or DATA) response indicates a data
call, the shell /bin/sh is exec(2)'ed with cmd as
its command. cmd is a printf(3) format that may
contain up to 6 %d escapes which are replaced by
the baud rate following the most recent CONNECT
message. cmd typically exec's getty(8).
-h hdr put string `hdr' at the top of each page. The
first %d in `hdr' is replaced by the page number
and the second, if any, is replaced by the number
of files being sent.
-i str
-j str
-k str send the command ATstr to the modem to initialize
it. -i commands are sent before the modem is put
into fax mode, -j commands after the modem is in
fax mode, and -k commands just before efax exits.
The only default is a hang-up (ATH) command that
is sent before exiting only if no other -k
options are given. Multiple options may be used.
-l id set the local identification string to id. id
should be the local telephone number in interna-
tional format (for example "+1 800 555 1212").
This is passed to the remote fax machine. Some
fax machines may not accept characters other than
numbers, space, and '+'. This is also used as
the ID when polling.
-o opt use option opt to accommodate a non-standard fax
modem protocol. See the MODEM REQUIREMENTS sec-
tion below for more details. The options are:
1 Use Class 1 fax modem commands. The modem must
support Class 1 commands. The default is to use
Class 2 commands.
0 Use Class 2.0 fax modem commands.
a use software adaptive answer method. If the
first attempt to answer the call does not result
in a data connection within 15 seconds the phone
is 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 esti-
mate the number of bytes in the modem's transmit
buffer and pauses as necessary to avoid filling
it. The modem's buffer is assumed to hold at
least 96 bytes. This feature does not work prop-
erly with Class 2 modems that add redundant
padding to scan lines. Use this option only if
you have problems configuring flow control.
l halve the time between testing lock files when
waiting for other programs to complete. By
default this is 8 seconds. For example -olll sets
the interval to 1 second.
n ignore requests for pages to be retransmitted.
Use this option if you don't care about the qual-
ity of the received fax or if the receiving
machine is too fussy. Otherwise each page may be
retransmitted up to 3 times.
r do not reverse bit order during data reception
for Class 2 modems. The meaning of this option
has been reversed from previous versions. Very
few Class 2 modems will require this option.
x send XON (DC1) instead of DC2 to start data
reception. Applies to Class 2 only.
z delay an additional 100 milliseconds before each
modem initialization or reset command. The ini-
tial delay is 100 ms. For example, -ozzz produces
a 400 ms delay. Use with modems that get con-
fused when commands arrive too quickly.
-q n ask for retransmission pages received with more
than n errors per page. Default is 10.
-r pat each received fax page is stored in a separate
file. The file name is created using pat as a
strftime(3) format string. A page number of the
form .001, .002, ... is appended to the file
name. If pat is blank ("") or no -r option is
given a default string of "%m%d%H%M%S" is used.
-s remove lock file(s) after initializing the modem.
This allows outgoing calls when efax is waiting
for an incoming call. If efax detects modem
activity it will attempt to re-lock the device.
If the modem is now locked by another program
efax will exit and return 1 (``busy''). Normally
a new efax process is then started by init(8).
The new efax process will typically check period-
ically until the lock file disappears and then
re-initializes the modem.
-t num [file...]
dial telephone number num and send the fax image
files file.... If used, this must be the last
argument on the command line. The telephone num-
ber num is a string that may contain any dial
modifiers that the modem supports such as a T
prefix for tone dialing or commas for delays. If
no file names are given the remote fax machine
will be polled. If no -t argument is given efax
will answer the phone and attempt to receive a
fax.
-v strng select types of messages to be printed. Each
lower-case letter in strng enables 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
Up to two -v options may be used. The first is
for messages printed to the standard error and
the second is for messages to the standard out-
put. The default is "ewin" to the standard error
only.
-w wait for an OK or CONNECT prompt instead of issu-
ing an answer (ATA) command to receive a fax.
Use this option when the modem is set to auto-
answer (using S0=n) or if another program has
already answered the call.
-x lkf use 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 is
free. Up to 16 -x options may be used if there
are several names for the same device. A `#'
prefix on the file name creates an HDB-style
(text) lock file.
FAX FILE FORMATS
Each page to be sent should be converted to a separate
TIFF format file with Group 3 (G3) compression. Received
files are also stored in this format. The EXAMPLES sec-
tion below shows how efix and other programs can be used
to create, view and print these files.
efax can read the same types of files as efix(1) including
text, T.4 (Group 3), PBM, and TIFF (G3 and uncompressed).
efax automatically determines the type of file from its
contents. TIFF files are recommended as they contain
information about the image resolution. The page counts
in the headers could be wrong when sending text or muti-
page TIFF since the page count is taken to be the number
of file name arguments.
OPERATING SYSTEM REQUIREMENTS
The operating system must provide short response times to
avoid protocol timeouts. For Class 2 modems the delay
should not exceed 1 or 2 seconds.
When using Class 1 modems the program must respond to cer-
tain events within 55 milliseconds. Longer delays may
cause the fax protocol to fail in certain places (between
DCS and TCF or between RTC and MPS). Class 1 modems
should therefore not be used on systems that cannot guar-
antee that the program will respond to incoming data in
less than 55 milliseconds. In particular, some intelli-
gent serial cards and terminal servers may introduce
enough delay to cause problems with Class 1 operation.
The operating system must also provide sufficient low-
level buffering to allow uninterrupted transfer of data
from the modem to a disk file at the selected baud rate,
typically 9600 bps. Since the fax protocol does not pro-
vide end-to-end flow control the effectiveness of flow
control while receiving is limited by the size of the
modem's buffer. This can be less than 100 bytes. Efax
does not use flow control during reception.
MODEM GROUP AND CLASS REQUIREMENTS
The "Group" is the protocol used to send faxes between fax
machines or fax modems. Efax supports the standard Group
3 protocol. The "Class" is the protocol used by a com-
puter to control a fax modem. Efax supports Class 1 and 2
fax modems. Class 2.0 support is untested.
Most fax modems use XON/XOFF flow control when in fax
mode. This type of flow control adds very little overhead
for fax use. Many modems have unreliable hardware
(RTS/CTS) flow control in fax mode. efax enables both
XON/XOFF and hardware flow control.
While some modems have serial buffers of about 1k bytes,
many inexpensive modems have buffers of about one hundred
bytes and are thus more likely to suffer overruns when
sending faxes.
Some modems may need a delay between commands of more than
the default value used by efax (100 milliseconds). If the
delay is too short, commands may not echo properly, may
time out, or may give inconsistent responses. Use one or
more -oz options to increase the delay between modem
initialization commands and use the E0 modem initializa-
tion 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 require XON instead. Use of DC2 would cause
the modem to give an error message and/or the program to
time out. The -ox option should be used in this case.
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. After waiting 2 seconds efax will print a
warning and start sending anyways.
A very few Class 2 modems do not reverse the bit order
(MSB to LSB) by default on receive. This might cause
errors when trying to display or print the received files.
The -or option can be used in this case.
Some inexpensive "9600 bps" fax modems only transmit at
9600 bps and reception is limited to 4800 bps.
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.
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
Mandatory modem initialization commands are generated by
efax. Additional commands may be supplied as command-line
arguments. The modem must be set up to issue ver-
bose(text) result codes. The following command does this
and is sent by efax before trying to initialize the modem.
Q0V1 respond to commands with verbose result codes
The following commands may be useful:
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 dura-
tion 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 opera-
tion (e.g. a combined fax/answering machine with
a long announcement).
CAPABILITIES
The capabilities of the local hardware and software are
set using a string of 8 digits separated by commas:
vr,br,wd,ln,df,ec,bf,st
where:
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
It is important that the proper capability string be spec-
ified.
When receiving a fax the vr, wd, ln and fields of the
capability string should be set to the maximum values that
your display software supports.
When sending a fax efax will determine vr from the image
file header and the wd and ln and fields should show the
format of the image files.
If the receiving fax machine does not support high resolu-
tion (vr=1) mode, efax will reduce the resolution by com-
bining pairs of scan lines. If the receiving fax machine
does not support the image's width then 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.
HEADERS
efax adds blank scan lines at the top of each image when
it is sent. This allows room for the page header but
increases the length of the image (by default about 0.1"
or 2.5mm of blank space is added).
A header is printed in the first scan lines at the top of
the page. It typically includes the date and time the
sender and recipient ID and the page number and count.
Headers cannot be disabled but the header string can be
set to blanks.
The default font for generating the headers is the built-
in 8x16 pixel font scaled to 12x24 pixesl (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").
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.
RETURN VALUES
The program returns an error code as follows:
0 The fax was successfully sent or received.
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 be used to convert text-only files to
TIFF-G3 format. For example, the following command will
convert the text file letter to the files letter.001, let-
ter.002, etc,:
efix -nletter.%03d <letter
The efix program can also insert bitmaps in images to cre-
ate letterhead, signatures, etc.
Ghostscript's tiffg3 driver can generate fax files in
TIFF-G3 format from postscript files. For example, the
command:
gs -q -sDEVICE=tiffg3 -dNOPAUSE \
-sOutputFile=letter.%03d letter.ps <</dev/null
will convert the Postscript file letter.ps into high-reso-
lution (vr=1) G3 fax image files letter.001, letter.002,
...
The images should have margins of at least 1/2 inch (1 cm)
since 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.
Printing fax files
For printing on HP-PCL printers or Postscript devices you
can use the efix program. For example, to print the
received fax on a Postscript printer at 300 dpi use the
command:
efix -ops -r300 -s1.5 <reply.001 | lpr
The Portable Bit Map (pbm) suite can also be used to con-
vert between to many other image formats. For example, a
received image file, reply.001, may be printed on an HP
Laserjet (at approximately 2/3 size) by using the command:
efix -opbm reply.001 | pbmtolj -resolution 300 | lpr
Sending fax files
The following 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 Class 1 fax
modem connected to device /dev/cua1.
efax -d /dev/cua1 -o1 \
-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 are fax or voice.
For example, the following command will make the Class 2
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 -or -l "555 1212" \
-c 1,5 -r reply
Automatic answer
The -w option makes efax wait for characters to become
available from the modem (indicating an incoming call)
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 files names corresponding to the reception date and
time.
efax -d /dev/ttyb -or -w -iS0=4 2>&1 >> fax.in.log
Sharing the modem with outgoing calls
The modem device can be shared by programs that use the
UUCP device locking protocol (kermit, uucico, efax, cu,
etc.).
efax will lock the modem device before opening it if one
or more UUCP lock file names are given with -x options.
The lock file names are typically /usr/spool/uucp/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.
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 reset 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.
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 initializa-
tion 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 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) pro-
cess. Received fax files will be stored using names like
Dec02-12.32.33.001, in the /usr/spool/fax/incoming direc-
tory 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
Note that adaptive answer of either type will not work for
all callers. For some data calls the duration of the ini-
tial data-mode answer may be too short for the initial
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 pro-
vide reliable fax and data service to all callers you
should use separate phone numbers for the two types of
calls.
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.
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 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 argument answer every time previous process
terminates (and init is in runlevel 4 or 5).
s1:45:respawn:/bin/sh /usr/bin/fax answer
For BSD-like systems, a line such as the following in
/etc/ttytab will have the same effect:
ttya "/usr/local/bin/fax answer" unknown off
You should protect the fax script and configuration files
against tampering since init will execute them as a privi-
leged (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).
If efax exec()'s getty properly but you get a garbled
login prompt then there is probably a mismatch between the
two ends of the serial link between the modem and the com-
puter. 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
SENDING FAXES USING THE PRINT SPOOLER
You can add a "fax" printer to the lpr print spooler that
will fax out a document using efax instead of printing it.
This allows a network server running efax to send faxes on
behalf of other machines, including non-Unix clients. In
the following steps use the directories specified in the
fax script if they are different than /usr/bin and
/var/spool/fax (FAXDIR). To set up a fax printer:
(1) Create a link to the fax script called ``faxlpr'' so
the fax script can determine when it is being invoked from
the print spooler:
ln -s /usr/bin/fax /usr/bin/faxlpr
(2) Edit /etc/printcap and add an entry such as:
fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr
to define a printer called "fax". Print files will be
spooled to the /var/spool/fax (sd=) directory and then
piped to the /usr/bin/faxlpr filter (if=).
(3) Create and/or set the permissions on the fax spool
directory. For example:
mkdir /var/spool/fax
chmod ugo=rwx /var/spool/fax
You should now be able to send a fax using the lpr inter-
face by using a command such as:
lpr -P fax -J "555 1212" file.ps
where the -J option is used to specify the phone number or
alias to be dialed.
Note that if more than one file is given on the command
line they will be concatenated before being passed to "fax
send". TIFF-G3, Postscript or PBM files must therefore be
sent one file at a time although the TIFF and Postscript
file 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 will be con-
verted and sent at the default (high) resolution.
You can use lpq(1) to check the fax queue, lprm(1) to
remove fax jobs and lpc(8) to control the spooler. In
each case use the -Pfax option to specify the fax
``printer.'' A log file will be 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 allows you to set the job name (-J option) to an
arbitrary string. Such software is available for most
computers.
See the lpd(8) and printcap(5) man pages for information
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.
Run the "fax test" script to check the modem's responses
to various commands. The results will be displayed at the
end of the test. Some ERROR responses from the modem
should be expected since most modems don't implement all
the possible commands.
If efax hangs when trying to open the modem device (typi-
cally ttyX), the device is either already in use by
another process (e.g. getty) or it requires the carrier
detect line to be true before it can be opened. Many sys-
tems define an alternate device name for the same physical
device (typically cuaX) that can be opened even if carrier
is not present or other programs are already using it.
If modem responses are being lost or generated at random,
another processes (e.g. getty or an efax auto-answer pro-
cess) may be trying to use the same device at the same
time. Using lock files (-x options) can often resolve
this problem.
Check the response to the "AT+FCLASS=?" command to make
sure your modem supports the Class (1, 2 or 2.0) that you
have selected. If you have a Class 1 modem, check the
response to the "AT+FRM=?" command to verify the speeds
supported (e.g. a response of "24,48" would mean only 2400
and 4800 bps are supported). For Class 2 modems check the
response to the "AT+FDCC=?" command to make sure the modem
supports the capabilities you have selected (see CAPABILI-
TIES above).
Attempt to send a fax. Check that the modem starts making
the calling signal (CNG, a 0.5 second beep every 3 sec-
onds) as soon as it's finished dialing. This shows the
modem is in fax mode. You may need to use the option
-iM2L3 to monitor the phone line (see the SPKR string in
the fax script).
Listen to the answering fax machine and check that it
sends the answering signal (CED, a 3 second beep) when it
answers followed by "warbling" sounds (DIS frames) every 3
seconds. If you hear a continuous signal instead (tones
or noise), then you've connected to a data modem instead.
Your modem should now send back another warble (DCS frame)
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.
When the transmission completes, check the message showing
the line count and the average bit rate.
Low line counts (under 1000 for a letter size image) or
the warning "fax output buffer overflow" when 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.
Most modems enable XON/XOFF flow control when fax mode is
enabled. Check the output of the fax test command for the
flow control settings in fax mode (typically &K4 or \Q1).
If they are incorrect you can use -j commands to enable
flow control.
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.
Check that the remote machine confirms reception with a
+FTPS:1 response (Class 2) or an MCF frame (Class 1).
For Class 2 modems, the error message "abnormal call ter-
mination (code nn)" indicates that the modem detected an
error and hung up. The modem's manual may give an expla-
nation for the error number nn.
Many companies advertise services that will fax back
information on their products. These can be useful for
testing fax reception.
The message "run length buffer overflow" when receiving
indicates an error with the image data format -- make sure
you are using the -or option with Class 2 modems.
If efax should display 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 save the output of the fax test command to a
file (e.g. fax test >>test.out) and send it along with a
verbose log of the failed session to the address below.
If you don't get a response in a reasonable time try the
mailing list described below.
MAILING LIST
A mailing list has been set up to support users of efax
and related software. To subscribe, send e-mail to efax-
request@renaissoft.com with the word "subscribe" in the
subject field. After subscribing you can post to the
mailing list by sending your post to efax@renaissoft.com.
FTP SITE
Wimsey Information Services provides an anonymous FTP site
for efax at ftp://ftp.wimsey.com/pub/efax/. Bug reports
and patches will be posted here.
RELATED SOFTWARE
For Linux Systems
An independent package, Qfax, uses efax to provide fax
services for multiuser Linux systems through a mail-to-fax
gateway. It is available by anonymous ftp from sun-
site.unc.edu as /pub/Linux/apps/comm/fax/qfax1.0.tar.gz.
Another program, g3vga, can be used to provide fax preview
with VGA displays. Also available from sunsite.unc.edu.
For Amiga Systems
A port of an early version of efax for the Amiga is avail-
able as a component of a shareware voice mail package,
AVM, distributed by Al Villarica rvillari@cat.syr.edu.
AUTHOR
Efax was written by Ed Casas. Please send comments or bug
reports to edc@cce.com.
BUG REPORTS
Please mention the operating system, the type of the modem
used and include a copy of a verbose session log that
demonstrates the problem. Without the verbose log it's
usually impossible to diagnose problems. Please do not
send fax image files.
ACKNOWLEDGEMENTS
Many people have helped with the development of efax by
providing encouragement, suggestions, bug reports and
fixes, by doing pre-release testing and by developing
related software.
A very incomplete list includes: Michele Bergonzoni, John
Conover, Mitchum DSouza, Bradley Dale, Dirk Eddelbuettel,
Debbe Gervin, Juha Heinanen, Jim Hitzel, Jamie Honan,
Michael Huehne, Lester Ingber, Sarantos Kapidakis, Al
Knudson, Ken Land, Ulrich Lauther, Robert J. LeBlanc,
Derek Lee, Charles H. Lindsey, Norm Matloff, Mark Mon-
tague, Michele Bergonzoni, Jose' M. Piquer, Munagala V. S.
Ramanath, Markus Regnet, Adam J. Richter, Stewart C. Rus-
sel, Lal Sanjay, Bogdan Urma, Al Villarica, and Brian
White.
Yggdrasil and SuSE have provided complementary copies of
their Linux CD-ROMs. Their support is gratefully acknowl-
edged.
COPYRIGHT
efax is copyright 1993 -- 1996 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
Dennis Bodson et. al., "FAX: Digital Facsimile Technology
and Applications", Second Edition. Artech House, Boston.
1992.
CCITT Recommendation T.4, "Standardization of Group 3 Fac-
simile Apparatus for Document Transmission". 1988.
CCITT Recommendation T.30, "Procedures for Document Fac-
simile Transmission in the General Switched Telephone Net-
work". 1988
The above CCITT (now ITU-T) standards could be downloaded
from gopher://info.itu.ch although this service seems to
have been discontinued and it is now necessary to order
printed copies.
Documentation on Class 1 and Class 2 fax commands as
implemented by Rockwell are available from
http://www.tokyo.rockwell.com/ref/reference.html.
The pbm utilities can be obtained by ftp from
wuarchive.wustl.edu in /graphics/graphics/pack-
ages/NetPBM/netpbm-1mar1994.tar.gz.
Ghostscript can be obtained from any GNU archive site.
SEE ALSO
fax(1) efix(1) pbm(5) g3topbm(1) gs(1) init(8) init-
tab(5) ttytab(5) printcap(5) lpd(8) printf(3) strf-
time(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 millisec-
onds.
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 and Class 2.0 are not well tested.
Does not support 2-D coding, ECM, or BFT.