efax.1

efax传真软件源代码

.ft CW
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
.ft P
.fi
.LP

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

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 efax 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 the argument \fBanswer\fP every time previous process
terminates and \fBinit\fP is in runlevel 4 or 5.

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

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

.IP
.nf
.ft CW
ttya "/usr/local/bin/fax answer" unknown on
.ft P
.fi
.LP

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

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


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

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.

.ft CW
image/tiff; fax view %s
.ft P

.SH SENDING FAXES USING THE PRINT SPOOLER

You can configure a "fax" printer into the lpr print spooler that
will fax a document out 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 do the following as root:

(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:

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

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=).  Error messages will appear on
/dev/console.

(3) Create and/or set the permissions to allow anyone to read and
write in the fax spool directory.  For example:

.IP
.nf
.ft CW
mkdir /var/spool/fax
chmod 777 /var/spool/fax
.ft P
.fi
.LP

(4) Create a printer daemon lock file that is readable by anyone:

.IP
.nf
.ft CW
touch /var/spool/fax/lock
chmod 644 /var/spool/fax/lock
.ft P
.fi
.LP

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

.IP
.nf
.ft CW
lpr -P fax -J "555 1212" file.ps
.ft P
.fi
.LP

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 TIFF and Postscript files 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, particularly the modem device name and the lock file
names.

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 is not present or other programs
are already using it.

If responses to modem initialization commands are being lost or
generated at random, another processes (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 files 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.

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 \fB-of\fP option or hardware
flow control with the \fB-oh\fP 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 \fInn\fP)" 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.

The message "run length buffer overflow" when receiving indicates
an error with the image data format.  You may need to use the
\fB-or\fP 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
\fBfax -v ...\fP) to the address below.

.SH WEB PAGE

A Web Page with pointers to the latest version, known bugs and
patches is available at:
.IP
.ft CW
http://casas.ee.ubc.ca/efax/
.ft P
.LP

.SH RELATED SOFTWARE

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 ([e-mail]).

Other Ports

efax is relatively easy to port.  All system-dependent code is in
\fBefaxos.c\fP.  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.

.SH AUTHOR

Efax was written by Ed Casas.  Please send comments or bug
reports to [e-mail].

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

.SH COPYRIGHT

efax is copyright 1993 -- 1999 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

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.

.SH SEE ALSO

.BR fax(1),
.BR efix(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 does not work.

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