.TH EFAX 1 "May 1996" ""  ""
.UC 1
.SH NAME
efax \- send/receive faxes using Class 1 or 2 fax modems
.SH SYNOPSIS

.B efax
[
\fIoptions\fP
]
[
\fB-t\fP \fInum\fP [ \fIfile\fP... ]
]

.SH OPTIONS

Where \fIoptions\fP are:

.TP 9
.B -a \fIcmd\fP
use the command \fBATcmd\fP when answering the phone.  The
default is "A".

.TP 9
.B -c \fIcaps\fP
set the local modem capabilities.  See the section on
capabilities below for the format and meaning of \fIcaps\fP.  The
default is 1,3,0,2,0,0,0,0.

.TP 9 
.B -d \fIdev\fP 
use the fax modem connected to device \fIdev\fP.  The default is
\fB/dev/fax\fP.  

.TP 9
.B -f \fIfnt\fP
use font file \fIfnt\fP for generating the header.  The default
is a built-in 8x16 font.  See efix(1) for the font file format.

.TP 9
.B -g \fIcmd\fP
if a \fBCONNECT\fP (or \fBDATA\fP) response indicates a data
call, the shell \fB/bin/sh\fP is exec(2)'ed with \fIcmd\fP as its
command.  \fIcmd\fP is a printf(3) format that may contain up to
6 %d escapes which are replaced by the baud rate following the
most recent \fBCONNECT\fP message. \fIcmd\fP typically exec's
getty(8).

.TP 9
.B -h \fIhdr\fP
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.

.TP 9
.B -i \fIstr\fP
.TP 9
.B -j \fIstr\fP
.TP 9
.B -k \fIstr\fP
send the command \fBAT\fP\fIstr\fP 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.

.TP 9
.B -l \fIid\fP
set the local identification string to \fIid\fP.  \fIid\fP should
be the local telephone number in international 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.

.TP 9 
.B -o \fIopt\fP 
use option \fIopt\fP to accommodate a non-standard fax modem
protocol.  See the MODEM REQUIREMENTS section below for more
details.  The \fIopt\fPions are:

.TP 9
.B 
    1
Use Class 1 fax modem commands.  The modem must support Class 1
commands.  The default is to use Class 2 commands.

.TP 9
.B 
    0
Use Class 2.0 fax modem commands.

.TP 9
.B 
    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).

.TP 9
.B 
    e 
ignore errors in modem initialization commands.

.TP 9
.B 
    f
use "virtual flow control".  efax tries to estimate 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 properly with Class 2
modems that add redundant padding to scan lines.  Use this option
only if you have problems configuring flow control.

.TP 9
.B 
    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.

.TP 9
.B 
    n
ignore requests for pages to be retransmitted. Use this option if
you don't care about the quality of the received fax or if the
receiving machine is too fussy.  Otherwise each page may be
retransmitted up to 3 times.

.TP 9
.B 
    r
do not reverse bit order during data reception for Class 2
modems.  \fIThe meaning of this option has been reversed from
previous versions\fP. Very few Class 2 modems will require this
option.


.TP 9
.B 
    x
send XON (DC1) instead of DC2 to start data reception.  Applies
to Class 2 only.

.TP 9
.B 
    z
delay an additional 100 milliseconds before each modem
initialization or reset command.  The initial delay is 100
ms. For example, -ozzz produces a 400 ms delay.  Use with modems
that get confused when commands arrive too quickly.


.TP 9
.B -q \fIn\fP
ask for retransmission pages received with more than \fIn\fP
errors per page.  Default is 10.

.TP 9
.B -r \fIpat\fP
each received fax page is stored in a separate file.  The file
name is created using \fIpat\fP as a strftime(3) format string.
A page number of the form .001, .002, ...  is appended to the
file name.  If \fIpat\fP is blank ("") or no -r option is given a
default string of "%m%d%H%M%S" is used.

.\" If a file already exists, efax terminates with an error.

.TP 9
.B -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 periodically until the lock file disappears and then
re-initializes the modem.

.TP 9 
.B -t \fInum [file\fP...]  
dial telephone number \fInum\fP and send the fax image files
\fIfile\fP....  If used, this must be the last argument on the
command line.  The telephone number \fInum\fP 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.

.TP 9
.B -v \fIstrng\fP
select types of messages to be printed.  Each \fIlower-case\fP
letter in \fIstrng\fP enables one type of message:

.RS 12
.B
e - 
errors
.br
.B
w - 
warnings
.br
.B
i - 
session progress information
.br
.B
n - 
capability negotiation information
.br
.B
c - 
modem (AT) commands and responses
.br
.B
h - 
HDLC frame data (Class 1 only)
.br
.B
m - 
modem output
.br
.B
a - 
program arguments
.br
.B
r -
reception error details
.br
.B
t -
transmission details
.br
.B
f -
image file details 
.br
.B
x -
lock file processing

.RE
.RS 9
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 output. The default is "ewin" to the standard error
only.
.RE

.TP 9
.B -w
wait for an OK or CONNECT prompt instead of issuing an answer
(\fBATA\fP) command to receive a fax.  Use this option when the
modem is set to auto-answer (using S0=\fIn\fP) or if another
program has already answered the call.

.TP 9
.B -x \fIlkf\fP
use UUCP-style lock file \fIlkf\fP 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.

.SH 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 section 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 \fBefix(1)\fP 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.

.SH 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 certain
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 guarantee that the program will
respond to incoming data in less than 55 milliseconds.  In
particular, some intelligent 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 provide 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.

.SH 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 computer 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 \fB-oz\fP 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
require XON instead.  Use of DC2 would cause the modem to give an
error message and/or the program to time out.  The \fB-ox\fP
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 \fB-or\fP option can
be used in this case.

Some inexpensive "9600 bps" fax modems only \fItransmit\fP 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,
.\" Andrea Gozzi <work@forum.sublink.org>, v0.6, SCO 3.2.0, (Class 1)
Cardinal Digital Fax Modem (14400),
.\" awk0%navajo@gte.com, v0.6, linux 1.0, downloading fax144c.car
Digicom Scout+,
.\" umlin000@CC.UManitoba.CA, v 0.6, Linux 1.1.12
Motorola Lifestyle 28.8,
.\" mortbay@ozemail.com.au
Motorola Power 28.8,
.\" danz@wv.mentorg.com, Linux 1.2.10
QuickComm Spirit II,
.\" umlin000@CC.UManitoba.CA, v 0.6, Linux 1.1.12
.\" gsmith@softsmiths.oz.au, v 0.7a, add "*F1" for Xon/Xoff
Smartlink 9614AV-Modem,
.\" gt@sky.gun.de, v0.6, Linux 1.1.15
Supra Faxmodem 144LC,
.\" john@johncon.johncon.com, v0.6, Consensys (ie., Unixware) 4.2
USR Courier V.32bis Terbo,
.\" meyer@geomatic.no, v0.6, SunOS 4.1.3
USR Sportster (V.32 and V.34),
.\" satyr!kayvan@apple.com (Kayvan Sylvan), v0.6, Linux (?)
Zoom AFC 2.400,
.\" hausutzu@pse.panic.bln.sub.org (Utz-Uwe Haus), v0.6, Linux
Zoom VFX14.4V.
.\" edc@ee.ubc.ca (me!), v0.6, Linux

The following Class 2 modems have been reported to work with efax:
14k4 Amigo Communion fax/modem,
.\" bekker@tn.utwente.nl, efax0.5
Adtech Micro Systems 14.4 Fax/modem,
.\" gmaughan@grape.fcit.monash.edu.au, Linux 1.2.10, efax 07a
askey modem type 1414VQE,
.\" thowi@chiba.escape.de, efax06?, Linux?
AT&T DataPort,
.\" ingber@alumni.caltech.edu (Class 2)
ATT/Paradyne,
.\" john@johncon.johncon.com
AT&T Paradyne PCMCIA,
.\" jh@datanet.tele.fi (Juha Heinanen)
Boca modem,
.\" ?
BOCA M1440E, 
.\" v0.6a, SunOS 4.1.1, Linux 1.0.9
.\" hsw1@papa.attmail.com
Crosslink 9614FH faxmodem,
.\" ?
FuryCard DNE 5005,
.\" a PCMCIA Class 3 faxmodem
.\" ron@draconia.hacktic.nl
GVC 14.4k internal,
.\" jchen@ee.mcgill.ca, 0.6a w/ stty fax patch, Linux kernel 1.1.59
Intel 14.4 fax modem,
.\" (matloff@cs.ucdavis.edu)
Megahertz 14.4,
,\" norman@bellcore.com
Microcom DeskPorte FAST ES 28.8,
.\" Skip Montanaro (skip@automatrix.com), 0.6a, Linux
Motorola UDS FasTalk II,
.\" Raj Mathur (root@darbari.ncst.ernet.in), 0.6a, Linux 1.1.48
MultiTech 1432MU,
.\"reb@pdsf.ssc.gov
Practical Peripherals PM14400FXMT,
.\" (DEC Alpha AXP 3000/500 running OSF/1 V1.3)
Supra V32bis,
.\" john@johncon.johncon.com, v0.5b, SysV R4.2
.\" tbucks!timothy@csn.org
.\" (ROCKWELL)
.\" Alec.Muffett@UK.Sun.COM (Alec Muffett), Linux 1.1.51, 
.\"  Supra FAXModem v.32bis
Telebit Worldblazer,
.\" blurfl!jhood@Dartmouth.EDU
.\" Telebit Worldblazer with ROM version LA7.02. (requires -or)
.\" (my configuration required hardware flow control)
.\" Dario_Ballabio@milano.europe.dg.com, v 0.6, Version LA7.05C.  
TKR DM-24VF+,
.\" rainer.dorsch@student.uni-ulm.de
Twincom 144/DFi,
.\" (ROCKWELL, V.32AC, V1.270 TR14-Jxxx-001)
ViVa 14.4/Fax modem,
.\" Robert.Sprockeels@csc.be, v0.6a, Linux
Vobis Fax-Modem (BZT-approved),
.\" klein@pc-klein.zxa.basf-ag.de (Peter Klein), Linux, kernel 0.99.14
.\" beck@irs.inf.tu-dresden.de (Andre Beck), v 0.6, Ultrix 4.3, gcc V2.5.8:
.\" gcc -ansi -D_XOPEN_SOURCE -O2 efax.c -o efax -lcP
Zoom VFX14.4V,
.\" edc@ee.ubc.ca (me!), v0.6, Linux
ZyXEL U-1496E[+], 
.\" plph@umcc.umich.edu, v0.3 & faxmodem ROM version 5.05M)
.\" requires -or
.\" Marc@Synergytics.Com, v0.5a & ZyXEL 1496E Plus, ROM Version 6.11a)
.\" -or -i '+FCLASS=2;+FCR=1' -c '+FDCC=1,5,2,2,0,0,0,0'
ZyXEL Elite 2864I.
.\" schlatt@dial.eunet.ch, v0.7a, using -Xn (n<4)

.SH 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 verbose(text) result codes.
The following command does this and is sent by efax before trying
to initialize the modem.

.TP 9
.BR Q0V1
respond to commands with verbose result codes

.PP
The following commands may be useful:

.TP 9 
.BR 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
\fB-t\fP command.  Use \fBX4\fP (usual default) to enable all
result codes.

.TP 9 
.BR M2
leave the monitor speaker turned on for the duration of the call
(use \fBM0\fP to leave it off).

.TP 9 
.BR L0
turn monitor speaker volume to minimum (use \fBL3\fP for maximum).

.TP 9 
.BR E0 
disable echoing of modem commands.  See the Resolving Problems
section below.

.TP 9 
.BR &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 \fB&D3\fP to
reset the modem when DTR is dropped.

.TP 9
.BR 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).

.SH CAPABILITIES

The capabilities of the local hardware and software are set using
a string of 8 digits separated by commas:

.BR  \fIvr\fP,\fIbr\fP,\fIwd\fP,\fIln\fP,\fIdf\fP,\fIec\fP,\fIbf\fP,\fIst\fP

where:

.TP 9
.I vr \fP (vertical resolution) =
0 for 98 lines per inch
.br
1 for 196 lpi

.TP 9
.I br \fP (bit rate) =
0 for 2400 bps
.br
1 for 4800
.br
2 for 7200
.br
3 for 9600
.br
4 for 12000 (V.17)
.br
5 for 14400 (V.17)

.TP 9
.I wd \fP (width) =
0 for 8.5" (21.5 cm) page width
.br
1 for 10" (25.5 cm)
.br
2 for 12" (30.3 cm)

.TP 9
.I ln  \fP (length) =
0 for 11" (A4: 29.7 cm) page length
.br
1 for 14" (B4: 36.4 cm)
.br
2 for unlimited page length

.TP 9
.I df \fP (data format) =
0 for 1-D coding
.br
1 for 2-D coding (not supported)

.TP 9
.I ec  \fP (error correction) =
0 for no error correction
.\" .br
.\" 1 for EC mode with 64 byte frames (not supported)
.\" .br
.\" 2 for EC mode with 256 byte frames (not supported)

.TP 9
.I bf \fP (binary file) =
0 for no binary file transfer

.TP 9
.I st  \fP (minimum scan time) =
0 for zero delay per line
.br
1 for 5 ms per line
.br
3 for 10 ms per line
.br
5 for 20 ms per line
.br
7 for 40 ms per line

.PP
It is important that the proper capability string be specified.

When \fIreceiving\fP a fax the \fIvr\fP, \fIwd\fP, \fIln\fP and
fields of the capability string should be set to the maximum
values that your display software supports.

When \fIsending\fP a fax efax will determine \fIvr\fP from the
image file header and the \fIwd\fP and \fIln\fP and fields should
show the format of the image files.

If the receiving fax machine does not support high resolution
(\fIvr\fP=1) mode, efax will reduce the resolution by combining
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 \fIln\fP up to 2.  Few
machines support values of \fIwd\fP other than 0.


.SH 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").

.SH 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 \fB-v\fP 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.

.SH RETURN VALUES

The program returns an error code as follows:

.TP 9
0
The fax was successfully sent or received.

.TP 9
1
The dialed number was busy or the modem device was in use.  Try
again later.

.TP 9
2
Something failed (e.g. file not found or disk full). Don't retry.
Check the session log for more details.

.TP 9
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 \fB-o\fP options were not used, or a bug
report may be in order.  Check the session log for more details.

.TP 9
4
The modem is not responding.  Operator attention is required.
Check that the modem is turned on and connected to the correct
port.

.TP 9
5
The program was terminated by a signal.

.SH EXAMPLES

.B 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 \fBletter\fP to the files \fBletter.001\fP,
\fBletter.002\fP, etc,:

.RS
.nf
.ft CW
efix -nletter.%03d <letter
.ft P
.fi
.RE

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

Ghostscript's \fBtiffg3\fP driver can generate fax files in
TIFF-G3 format from postscript files.  For example, the command:

.RS
.nf
.ft CW
gs -q -sDEVICE=tiffg3 -dNOPAUSE \\
	-sOutputFile=letter.%03d letter.ps </dev/null
.ft P
.fi
.RE

will convert the Postscript file
.BR letter.ps
into high-resolution
(\fIvr\fP=1) G3 fax image files \fBletter.001, letter.002,\fP ...

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.

.B 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:

.RS
.nf
.ft CW
efix -ops -r300 -s1.5 <reply.001 | lpr
.ft P
.fi
.RE

The Portable Bit Map (pbm) suite can also be used to convert
between to many other image formats.  For example, a received
image file, \fBreply.001\fP, may be printed on an HP Laserjet (at
approximately 2/3 size) by using the command:

.RS
.nf
.ft CW
efix -opbm reply.001 | pbmtolj -resolution 300 | lpr
.ft P
.fi
.RE

.B 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/ttyS1.

.RS
.nf
.ft CW
efax -d /dev/ttyS1 -o1 \\
     -t T222-2222 letter.001 letter.002
.ft P
.fi
.RE

.B 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 \fB/dev/ttyS1\fP answer the phone and attempt to
receive a fax.  The received fax will be stored in the files
\fBreply.001\fP, \fBreply.002\fP, and so on.  The modem will
identify itself as "555 1212" and receive faxes at high or
low resolution (\fIvr\fP=1), at up to 14.4 kbps (\fIbr\fP=5).

.RS
.nf
.ft CW
efax -d /dev/ttyS1 -or -l "555 1212" \\
   -c 1,5 -r reply
.ft P
.fi
.RE

.B Automatic answer

The \fB-w\fP option makes efax wait for characters to become
available from the modem (indicating an incoming call) before
starting fax reception.  Use the \fB-w\fP option and a
\fB-i\fPS0=\fIn\fP option to answer the phone after \fIn\fP
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.

.RS
.nf
.ft CW
efax -d /dev/ttyb -or -w -iS0=4 2>&1 >> fax.in.log
.ft P
.fi
.RE

.B 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 \fB-x\fP options.  The lock
file names are typically \fR/usr/spool/uucp/LCK..\fP\fIdev\fP
where \fIdev\fP is the name of the device file in the /dev
directory that is to be locked.

If the \fB-s\fP (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.

.B Accepting both fax and data calls

Many modems have an adaptive data/fax answer mode that can be
enabled using the \fB-j+FAE=1\fP (for Class 1) or \fB-jFAA=1\fP
(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 initialization string
\fB-i+FCLASS=0\fP to answer in data mode first and the \fB-oa\fP
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 \fB-g\fP 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 \fBgetty\fP(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
\fB/dev/ttyS1\fP 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 (\fB-s\fP).  If a data
call is detected, the \fBgetty\fP program will be run to
initialize the terminal driver and start a \fBlogin\fP(1)
process.  Received fax files will be stored using names like
\fBDec02-12.32.33.001\fP, in the \fB/usr/spool/fax/incoming\fP
directory and the log file will be appended to
\fB/usr/spool/fax/faxlog.ttyS1\fP.

.RS
.nf
.ft CW
efax -d /dev/ttyS1  -j '+FAA=1' \\
   -x /usr/spool/uucp/LCK..cua1 \\
   -x /usr/spool/uucp/LCK..ttyS1 \\
   -g "exec /sbin/getty -h /dev/ttyS1 %d" \\
   -iS0=2 -w -s \\
   -r "/usr/spool/fax/incoming/%b%d-%H.%I.%S" \\
   >> /usr/spool/fax/faxlog.ttyS1 2>&1
.ft P
.fi
.RE

Note that 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 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 provide 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.


.SH USING INIT TO RUN EFAX

efax can answer all incoming calls if you place an entry for efax
in \fB/etc/inittab\fP (for SysV-like systems) or
\fB/etc/ttytab\fP (for BSD-like systems). The \fBinit\fP(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 \fBfax\fP script with an
\fBanswer\fP argument.

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

.RS
.nf
.ft CW
s1:45:respawn:/bin/sh /usr/bin/fax answer
.ft P
.fi
.RE

For BSD-like systems, a line such as the following in
\fB/etc/ttytab\fP will have the same effect:

.RS
.nf
.ft CW
ttya "/usr/local/bin/fax answer" unknown off
.ft P
.fi
.RE

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

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 computer.  First, check
the efax log file to make sure the modem's CONNECT response
reported the serial port speed (e.g. 19200), \fBnot\fP 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.

.RS
.nf
.ft CW
#!/bin/sh
BIN=/bin/badprogram
LOCKF=/var/spool/uucp/LCK..ttyS1
if [ -f $LOCKF ]
then
        echo lock file $LOCKF exists
        exit 1
else
        printf "%10d\n" $$ >$LOCKF
        $BIN $*
        rm $LOCKF
fi
.ft P
.fi
.RE


.SH 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:

.ft CW
ln -s /usr/bin/fax /usr/bin/faxlpr
.ft P


(2) Edit /etc/printcap and add an entry such as:

.RS
.nf
.ft CW
fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr
.ft P
.fi
.RE

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:

.RS
.nf
.ft CW
mkdir /var/spool/fax
chmod ugo=rwx /var/spool/fax
.ft P
.fi
.RE

You should now be able to send a fax using the lpr interface by
using a command such as:

.RS
.nf
.ft CW
lpr -P fax -J "555 1212" file.ps
.ft P
.fi
.RE

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 \fItext\fP files can be sent in one command.  Page
breaks in text files can be marked with form-feed characters.
Files will be converted 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).

.SH 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 (typically
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 systems define an alternate device
name for the same physical device (typically ttySX) 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 process) 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 CAPABILITIES above).

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 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 \fB-of\fP 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 termination
(code \fInn\fP)" indicates that the modem detected an error and
hung up.  The modem's manual may give an explanation for the
error number \fInn\fP.

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 \fB-or\fP 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 \fBfax test\fP command to a file
(e.g. \fBfax test >test.out\fP) 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.

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

.SH FTP SITE

Wimsey Information Services provides an anonymous FTP site for
efax at \fBftp://ftp.wimsey.com/pub/efax/\fP.  Bug reports and
patches will be posted here.

.SH 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 sunsite.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 available as
a component of a shareware voice mail package, AVM, distributed
by Al Villarica (rvillari@cat.syr.edu).

.SH AUTHOR

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

.SH 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 \fBnot\fP send fax image files.

.SH 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 Montague, 
Michele Bergonzoni,
Jose' M. Piquer, 
Munagala V. S. Ramanath,
Markus Regnet, 
Adam J. Richter, 
Stewart C. Russel,
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 acknowledged.

.SH COPYRIGHT

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

.SH DISCLAIMER

Although \fBefax\fP 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.

.SH 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 Facsimile
Apparatus for Document Transmission". 1988.

CCITT Recommendation T.30, "Procedures for Document Facsimile
Transmission in the General Switched Telephone Network". 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/packages/NetPBM/netpbm-1mar1994.tar.gz.

Ghostscript can be obtained from any GNU archive site.

.SH SEE ALSO

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

.SH  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 and Class 2.0 are not well tested.

Does not support 2-D coding, ECM, or BFT.