1 .TH EFAX 1 "February 1999" "" ""
4 efax \- send/receive faxes with Class 1, 2 or 2.0 fax modem
7 (Please read the \fBfax\fP man page first.)
15 \fB-t\fP \fInum\fP [ \fIfile\fP... ]
19 Where \fIoptions\fP are:
23 use the command \fBATcmd\fP when answering the phone. The
28 set the local modem capabilities. See the section on
29 capabilities below for the format and meaning of \fIcaps\fP. For
30 Class 1 the default is 1,n,0,2,0,0,0,0 where n is the highest
31 speed supported by the modem. For Class 2 the default is
32 determined by the modem.
36 use the fax modem connected to device \fIdev\fP. The default is
41 use font file \fIfnt\fP for generating the header. The default
42 is a built-in 8x16 font. See the efix(1) -f option for the font
47 if a \fBCONNECT\fP (or \fBDATA\fP) response indicates a data
48 call, the shell \fB/bin/sh\fP is exec(2)'ed with \fIcmd\fP as its
49 command. \fIcmd\fP is a printf(3) format that may contain up to
50 6 %d escapes which are replaced by the baud rate following the
51 most recent \fBCONNECT\fP message. \fIcmd\fP typically exec's
56 put string `hdr' at the top of each page. The first %d in `hdr'
57 is replaced by the page number and the second, if any, is
58 replaced by the number of pages being sent.
66 send the command \fBAT\fP\fIstr\fP to the modem to initialize it.
67 -i commands are sent before the modem is put into fax mode, -j
68 commands after the modem is in fax mode, and -k commands just
69 before efax exits. The only default is a hang-up (ATH) command
70 that is sent before exiting only if no other -k options are
71 given. Multiple options may be used.
75 set the local identification string to \fIid\fP. \fIid\fP should
76 be the local telephone number in international format (for
77 example "+1 800 555 1212"). This is passed to the remote fax
78 machine. Some fax machines may not accept characters other than
79 numbers, space, and '+'.
83 use option \fIopt\fP to accommodate a non-standard fax modem
84 protocol. See the MODEM REQUIREMENTS section below for more
85 details. The \fIopt\fPions are:
90 Force use of Class 2.0 fax modem commands. The modem must
96 Force use of Class 2 fax modem commands. The modem must support
102 Force use of Class 1 fax modem commands. The modem must support
103 Class 1. By default efax queries the modem and uses the first of
104 the three above classes which is supported by the modem.
109 use software adaptive answer method. If the first attempt to
110 answer the call does not result in a data connection within 8
111 seconds the phone is hung up temporarily and answered again in
112 fax mode (see "Accepting both fax and data calls" below).
117 ignore errors in modem initialization commands.
122 use "virtual flow control". efax tries to estimate the number of
123 bytes in the modem's transmit buffer and pauses as necessary to
124 avoid filling it. The modem's buffer is assumed to hold at least
125 96 bytes. This feature does not work properly with Class 2
126 modems that add redundant padding to scan lines. Use this option
127 only if you have problems configuring flow control.
132 use hardware (RTS/CTS) in addition to software (XON/XOFF) flow
133 control. Many modems will stop responding if this option is
134 used. See the section `Resolving Problems' before using this
140 halve the time between testing lock files when waiting for other
141 programs to complete. By default this is 8 seconds. For example
142 -olll sets the interval to 1 second.
147 ignore requests for pages to be retransmitted. Use this option if
148 you don't care about the quality of the received fax or if the
149 receiving machine is too fussy. Otherwise each page may be
150 retransmitted up to 3 times.
155 do not reverse bit order during data reception for Class 2
156 modems. Only Multitech modems require this option. Not normally
157 required since efax detects these modems.
162 send XON (DC1) instead of DC2 to start data reception. Applies
163 to a very few Class 2 modems only.
168 delay an additional 100 milliseconds before each modem
169 initialization or reset command. The initial delay is 100
170 ms. For example, -ozzz produces a 400 ms delay. Use with modems
171 that get confused when commands arrive too quickly.
176 ask for retransmission of pages received with more than \fIn\fP
177 errors. Default is 10.
181 each received fax page is stored in a separate file. The file
182 name is created using \fIpat\fP as a strftime(3) format string.
183 A page number of the form .001, .002, ... is appended to the
184 file name. If \fIpat\fP is blank ("") or no -r option is given a
185 default string of "%m%d%H%M%S" is used.
187 .\" If a file already exists, efax terminates with an error.
191 remove lock file(s) after initializing the modem. This allows
192 outgoing calls to proceed when efax is waiting for an incoming
193 call. If efax detects modem activity it will attempt to re-lock
194 the device. If the modem has been locked by the other program
195 efax will exit and return 1 (``busy''). Normally a new efax
196 process is then started by init(8). The new efax process will
197 then check periodically until the lock file disappears and
198 then re-initialize the modem.
201 .B -t \fInum [file\fP...]
202 dial telephone number \fInum\fP and send the fax image files
203 \fIfile\fP.... If used, this must be the last argument on the
204 command line. The telephone number \fInum\fP is a string that
205 may contain any dial modifiers that the modem supports such as a
206 T prefix for tone dialing or commas for delays. If no file names
207 are given the remote fax machine will be polled. If no -t
208 argument is given efax will answer the phone and attempt to
213 select types of messages to be printed. Each \fIlower-case\fP
214 letter in \fIstrng\fP enables one type of message:
227 session progress information
231 capability negotiation information
235 modem (AT) commands and responses
239 HDLC frame data (Class 1 only)
251 reception error details
267 Up to two -v options may be used. The first is for messages
268 printed to the standard error and the second is for messages to
269 the standard output. The default is "ewin" to the standard error
275 wait for an OK or CONNECT prompt instead of issuing an answer
276 (\fBATA\fP) command to receive a fax. Use this option when the
277 modem is set to auto-answer (using S0=\fIn\fP) or if another
278 program has already answered the call.
282 use a UUCP-style lock file \fIlkf\fP to lock the modem device
283 before opening it. If the device is locked, efax checks every 15
284 seconds until it is free. Up to 16 -x options may be used if
285 there are several names for the same device. A `#' prefix on the
286 file name creates an binary rather than text (HDB-style) lock
287 file. This is the reverse of what was used by previous efax
292 efax can read the same types of files as \fBefix(1)\fP including
293 text, T.4 (Group 3), PBM, single- and multi-page TIFF (G3 and
294 uncompressed). efax automatically determines the type of file
295 from its contents. TIFF files are recommended as they contain
296 information about the image size and resolution.
298 Each page to be sent should be converted to a separate TIFF
299 format file with Group 3 (G3) compression. Received files are
300 also stored in this format. The EXAMPLES section below shows how
301 efix and other programs can be used to create, view and print
304 .SH OPERATING SYSTEM REQUIREMENTS
306 The operating system must provide short response times to avoid
307 protocol timeouts. For Class 2 and 2.0 modems the delay should
308 not exceed 1 or 2 seconds.
310 When using Class 1 modems the program must respond to certain
311 events within 55 milliseconds. Longer delays may cause the fax
312 protocol to fail in certain places (between DCS and TCF or
313 between RTC and MPS). Class 1 modems should therefore not be
314 used on systems that cannot guarantee that the program will
315 respond to incoming data in less than 55 milliseconds. In
316 particular, some intelligent serial cards and terminal servers
317 may introduce enough delay to cause problems with Class 1
320 The operating system must also provide sufficient low-level
321 buffering to allow uninterrupted transfer of data between the
322 modem and a disk file at the selected baud rate, typically 9600
323 bps. Since the fax protocol does not provide end-to-end flow
324 control the effectiveness of flow control while receiving is
325 limited by the size of the modem's buffer. This can be less than
326 100 bytes. Efax does not use flow control during reception.
328 .SH MODEM REQUIREMENTS
330 The "Group" is the protocol used to send faxes between fax
331 machines. Efax supports the Group 3 protocol used over the
332 public telephone network.
334 The "Class" is the protocol used by computers to control fax
335 modems. Efax supports Class 1, 2 and 2.0 fax modems.
337 Most fax modems use XON/XOFF flow control when in fax mode. This
338 type of flow control adds very little overhead for fax use. Many
339 modems have unreliable hardware (RTS/CTS) flow control in fax
340 mode. By default efax enables only XON/XOFF flow control and the
341 -oh option must be used to add hardware flow control.
343 While some modems have serial buffers of about 1k bytes, many
344 inexpensive modems have buffers of about one hundred bytes and
345 are thus more likely to suffer overruns when sending faxes.
347 A few older modems may need a delay between commands of more than
348 the default value used by efax (100 milliseconds). If the delay
349 is too short, commands may not echo properly, may time out, or
350 may give inconsistent responses. Use one or more \fB-oz\fP
351 options to increase the delay between modem initialization
352 commands and use the E0 modem initialization command to disable
353 echoing of modem commands.
355 By default efax sends DC2 to start the data flow from the modem
356 when receiving faxes from Class 2 modems. A few older modems
357 require XON instead. Use of DC2 would cause the modem to give an
358 error message and/or the program to time out. The \fB-ox\fP
359 option should be used in this case.
361 A few older Class 2 modems (e.g. some Intel models) don't send
362 DC2 or XON to start the data flow to the modem when sending
363 faxes. After waiting 2 seconds efax will print a warning and
364 start sending anyways.
366 A very few Class 2 modems do not reverse the bit order (MSB to
367 LSB) by default on receive. This might cause errors when trying
368 to display or print the received files. The \fB-or\fP option can
369 be used in this case.
371 Some inexpensive "9600 bps" fax modems only \fItransmit\fP at
372 9600 bps and reception is limited to 4800 bps.
374 The following Class 1 modems have been reported to work with efax:
376 .\" Andrea Gozzi <work@forum.sublink.org>, v0.6, SCO 3.2.0, (Class 1)
377 Cardinal Digital Fax Modem (14400),
378 .\" awk0%navajo@gte.com, v0.6, linux 1.0, downloading fax144c.car
380 .\" umlin000@CC.UManitoba.CA, v 0.6, Linux 1.1.12
381 Motorola Lifestyle 28.8,
382 .\" mortbay@ozemail.com.au
384 .\" danz@wv.mentorg.com, Linux 1.2.10
386 .\" umlin000@CC.UManitoba.CA, v 0.6, Linux 1.1.12
387 .\" gsmith@softsmiths.oz.au, v 0.7a, add "*F1" for Xon/Xoff
388 Smartlink 9614AV-Modem,
389 .\" gt@sky.gun.de, v0.6, Linux 1.1.15
390 Supra Faxmodem 144LC,
391 .\" john@johncon.johncon.com, v0.6, Consensys (ie., Unixware) 4.2
392 USR Courier V.32bis Terbo,
393 .\" meyer@geomatic.no, v0.6, SunOS 4.1.3
394 USR Sportster (V.32 and V.34),
395 .\" satyr!kayvan@apple.com (Kayvan Sylvan), v0.6, Linux (?)
397 .\" hausutzu@pse.panic.bln.sub.org (Utz-Uwe Haus), v0.6, Linux
399 .\" edc@ee.ubc.ca (me!), v0.6, Linux
401 The following Class 2 modems have been reported to work with efax:
402 14k4 Amigo Communion fax/modem,
403 .\" bekker@tn.utwente.nl, efax0.5
404 Adtech Micro Systems 14.4 Fax/modem,
405 .\" gmaughan@grape.fcit.monash.edu.au, Linux 1.2.10, efax 07a
406 askey modem type 1414VQE,
407 .\" thowi@chiba.escape.de, efax06?, Linux?
409 .\" ingber@alumni.caltech.edu (Class 2)
411 .\" john@johncon.johncon.com
412 AT&T Paradyne PCMCIA,
413 .\" jh@datanet.tele.fi (Juha Heinanen)
417 .\" v0.6a, SunOS 4.1.1, Linux 1.0.9
418 .\" hsw1@papa.attmail.com
419 Crosslink 9614FH faxmodem,
422 .\" a PCMCIA Class 3 faxmodem
423 .\" ron@draconia.hacktic.nl
425 .\" jchen@ee.mcgill.ca, 0.6a w/ stty fax patch, Linux kernel 1.1.59
426 Intel 14.4 fax modem,
427 .\" (matloff@cs.ucdavis.edu)
429 ,\" norman@bellcore.com
430 Microcom DeskPorte FAST ES 28.8,
431 .\" Skip Montanaro (skip@automatrix.com), 0.6a, Linux
432 Motorola UDS FasTalk II,
433 .\" Raj Mathur (root@darbari.ncst.ernet.in), 0.6a, Linux 1.1.48
436 Practical Peripherals PM14400FXMT,
437 .\" (DEC Alpha AXP 3000/500 running OSF/1 V1.3)
439 .\" john@johncon.johncon.com, v0.5b, SysV R4.2
440 .\" tbucks!timothy@csn.org
442 .\" Alec.Muffett@UK.Sun.COM (Alec Muffett), Linux 1.1.51,
443 .\" Supra FAXModem v.32bis
445 .\" blurfl!jhood@Dartmouth.EDU
446 .\" Telebit Worldblazer with ROM version LA7.02. (requires -or)
447 .\" (my configuration required hardware flow control)
448 .\" Dario_Ballabio@milano.europe.dg.com, v 0.6, Version LA7.05C.
450 .\" rainer.dorsch@student.uni-ulm.de
452 .\" (ROCKWELL, V.32AC, V1.270 TR14-Jxxx-001)
454 .\" Robert.Sprockeels@csc.be, v0.6a, Linux
455 Vobis Fax-Modem (BZT-approved),
456 .\" klein@pc-klein.zxa.basf-ag.de (Peter Klein), Linux, kernel 0.99.14
457 .\" beck@irs.inf.tu-dresden.de (Andre Beck), v 0.6, Ultrix 4.3, gcc V2.5.8:
458 .\" gcc -ansi -D_XOPEN_SOURCE -O2 efax.c -o efax -lcP
460 .\" edc@ee.ubc.ca (me!), v0.6, Linux
462 .\" plph@umcc.umich.edu, v0.3 & faxmodem ROM version 5.05M)
464 .\" Marc@Synergytics.Com, v0.5a & ZyXEL 1496E Plus, ROM Version 6.11a)
465 .\" -or -i '+FCLASS=2;+FCR=1' -c '+FDCC=1,5,2,2,0,0,0,0'
467 .\" schlatt@dial.eunet.ch, v0.7a, using -Xn (n<4)
469 .SH MODEM INITIALIZATION OPTIONS
471 The required modem initialization commands are generated by efax.
472 Additional commands may be supplied as command-line arguments.
473 The modem must be set up to issue verbose(text) result codes.
474 The following command does this and is sent by efax before trying
475 to initialize the modem.
479 respond to commands with verbose result codes
482 The following commands may be useful for special purposes:
486 don't wait for dial tone before dialing. This may be used to
487 send a fax when the call has already been dialed manually. In
488 this case use an empty string ("") as the first argument to the
489 \fB-t\fP command. Use \fBX4\fP (usual default) to enable all
494 leave the monitor speaker turned on for the duration of the call
495 (use \fBM0\fP to leave it off).
499 turn monitor speaker volume to minimum (use \fBL3\fP for maximum).
503 disable echoing of modem commands. See the Resolving Problems
508 returns the modem to command mode when DTR is dropped. The
509 program drops DTR at the start and end of the call if it can't
510 get a response to a modem command. You can use \fB&D3\fP to
511 reset the modem when DTR is dropped.
515 wait up to two minutes (120 seconds) for carrier. This may be
516 useful if the answering fax machine takes a long time to start
517 the handshaking operation (e.g. a combined fax/answering machine
518 with a long announcement).
522 The capabilities of the local hardware and software can be set
523 using a string of 8 digits separated by commas:
525 .BR \fIvr\fP,\fIbr\fP,\fIwd\fP,\fIln\fP,\fIdf\fP,\fIec\fP,\fIbf\fP,\fIst\fP
530 .I vr \fP (vertical resolution) =
531 0 for 98 lines per inch
536 .I br \fP (bit rate) =
551 0 for 8.5" (21.5 cm) page width
559 0 for 11" (A4: 29.7 cm) page length
561 1 for 14" (B4: 36.4 cm)
563 2 for unlimited page length
566 .I df \fP (data format) =
569 1 for 2-D coding (not supported)
572 .I ec \fP (error correction) =
573 0 for no error correction
575 .\" 1 for EC mode with 64 byte frames (not supported)
577 .\" 2 for EC mode with 256 byte frames (not supported)
580 .I bf \fP (binary file) =
581 0 for no binary file transfer
584 .I st \fP (minimum scan time) =
585 0 for zero delay per line
597 When \fIreceiving\fP a fax the \fIvr\fP, \fIwd\fP, and \fIln\fP
598 fields of the capability string should be set to the maximum
599 values that your display software supports. The default is 196
600 lpi, standard (8.5"/21.5cm) width and unlimited length.
602 When \fIsending\fP a fax efax will determine \fIvr\fP and
603 \fIln\fP from the image file and set \fIwd\fP to the default.
605 If the receiving fax machine does not support high resolution
606 (\fIvr\fP=1) mode, efax will reduce the resolution by combining
607 pairs of scan lines. If the receiving fax machine does not
608 support the image's width then efax will truncate or pad as
609 required. Most fax machines can receive \fIln\fP up to 2. Few
610 machines support values of \fIwd\fP other than 0.
615 efax adds blank scan lines at the top of each image when it is
616 sent. This allows room for the page header but increases the
617 length of the image (by default about 0.1" or 2.5mm of blank
620 The header placed in this area typically includes the date and
621 time, identifies the, and shows the page number and total pages.
622 Headers cannot be disabled but the header string can be set to a
625 The default font for generating the headers is the built-in 8x16
626 pixel font scaled to 12x24 pixels (about 9 point size).
628 Note that both efax and efix have -f options to specify the font.
629 efIx uses the font to generate text when doing text-to-fax
630 conversions (during "fax make") while efAx uses the font to
631 generate the header (during "fax send").
635 A session log is written to the standard error stream. This log
636 gives status and error messages from the program as selected by
637 the \fB-v\fP option. A time stamp showing the full time or just
638 minutes and seconds is printed before each message. Times
639 printed along with modem responses also show milliseconds.
643 The program returns an error code as follows:
647 The fax was successfully sent or received.
651 The dialed number was busy or the modem device was in use. Try
656 Something failed (e.g. file not found or disk full). Don't retry.
657 Check the session log for more details.
661 Modem protocol error. The program did not receive the expected
662 response from the modem. The modem may not have been properly
663 initialized, the correct \fB-o\fP options were not used, or a bug
664 report may be in order. Check the session log for more details.
668 The modem is not responding. Operator attention is required.
669 Check that the modem is turned on and connected to the correct
674 The program was terminated by a signal.
678 .B Creating fax (G3) files
680 The efix program can be used to convert text files to TIFF-G3
681 format. For example, the following command will convert the text
682 file \fBletter\fP to the files \fBletter.001\fP,
683 \fBletter.002\fP, etc,:
688 efix -nletter.%03d letter
693 Ghostscript's \fBtiffg3\fP driver can generate fax files in
694 TIFF-G3 format from postscript files. For example, the command:
698 \f(CW gs -q -sDEVICE=tiffg3 -dNOPAUSE \\
699 -sOutputFile=letter.%03d letter.ps </dev/null\fP
703 will convert the Postscript file
706 (\fIvr\fP=1) G3 fax image files \fBletter.001, letter.002,\fP ...
708 The images should have margins of at least 1/2 inch (1 cm) since
709 the fax standard only requires that fax machines print a central
710 portion of the image 196.6mm (7.7 inches) wide by 281.5mm (11.1
713 The efix program can also insert bitmaps in images to create
714 letterhead, signatures, etc.
716 .B Printing fax files
718 You can use the efix program to print faxes on Postscript or
719 HP-PCL (LaserJet) printers. For example, to print the received
720 fax file \fBreply.001\fP on a Postscript printer use the command:
725 efix -ops reply.001 | lpr
732 The following command will dial the number 222-2222 using tone
733 dialing and send a two-page fax from the TIFF-G3 files letter.001
734 and letter.002 using the fax modem connected to device /dev/cua1.
740 -t T222-2222 letter.001 letter.002
747 You can use efax to answer the phone immediately and start fax
748 reception. Use this mode if you need to answer calls manually to
749 see if they are fax or voice.
751 For example, the following command will make the fax modem on
752 device \fB/dev/ttyS1\fP answer the phone and attempt to receive a
753 fax. The received fax will be stored in the files
754 \fBreply.001\fP, \fBreply.002\fP, and so on. The modem will
755 identify itself as "555 1212" and receive faxes at high or low
756 resolution (\fIvr\fP=1), at up to 14.4 kbps (\fIbr\fP=5).
761 efax -d /dev/ttyS1 -l "555 1212" \\
769 The \fB-w\fP option makes efax wait for characters to become
770 available from the modem (indicating an incoming call) before
771 starting fax reception. Use the \fB-w\fP option and a
772 \fB-i\fPS0=\fIn\fP option to answer the phone after \fIn\fP
773 rings. The example below will make the modem answer incoming
774 calls in fax mode on the fourth ring and save the received faxes
775 using files names corresponding to the reception date and time.
780 efax -d /dev/ttyb -w -iS0=4 2>&1 >> fax.log
785 .B Sharing the modem with outgoing calls
787 The modem device can be shared by programs that use the UUCP
788 device locking protocol. This includes pppd, chat, minicom,
789 kermit, uucico, efax, cu, and many others others. However,
790 locking will only work if all programs use the same lock file.
792 efax will lock the modem device before opening it if one or more
793 UUCP lock file names are given with \fB-x\fP options. Most
794 programs place their lock files in the \fR/usr/spool/uucp\fP or
795 \fR/var/lock\fP directories and use the name \fRLCK..\fP\fIdev\fP
796 where \fIdev\fP is the name of the device file in the /dev
797 directory that is to be locked.
799 If the \fB-s\fP (share) option is used, the lock file is removed
800 while waiting for incoming calls so other programs can use the
803 If efax detects another program using the modem while it is
804 waiting to receive a fax, efax exits with a termination code of
805 1. A subsequent efax process using this device will wait until
806 the other program is finished before re-initializing the modem
807 and starting to wait for incoming calls again.
809 Programs that try to lock the modem device by using device
810 locking facilities other than UUCP lock files not be able to use
811 this arbitration mechanism because the device will still be open
812 to the efax process. In this case you will need to kill the efax
813 process (e.g. "fax stop") before starting the other program.
815 When efax is waiting for a fax it leaves the modem ready to
816 receive in fax mode but removes the lock file. When a slip or
817 PPP program takes over the modem port by setting up its own lock
818 file efax cannot send any more commands to the modem -- not even
819 to reset it. Therefore the other program has to set the modem
820 back to data mode when it starts up. To do this add a modem
821 reset command (send ATZ expect OK) to the beginning of your slip
824 .B Accepting both fax and data calls
826 Many modems have an adaptive data/fax answer mode that can be
827 enabled using the \fB-j+FAE=1\fP (for Class 1) or \fB-jFAA=1\fP
828 (for Class 2[.0]) initialization string. The type of call (data
829 or fax) can then be deduced from the modem's responses.
831 Some modems have limited adaptive answer features (e.g. only
832 working properly at certain baud rates or only in Class 2) or
833 none at all. In this case use the initialization string
834 \fB-i+FCLASS=0\fP to answer in data mode first and the \fB-oa\fP
835 option to then hang up and try again in fax mode if the first
836 answer attempt was not successful. This method only works if
837 your telephone system waits a few seconds after you hang up
838 before disconnecting incoming calls.
840 If the \fB-g\fP option is used then the option's argument will be
841 run as a shell command when an incoming data call is detected.
842 Typically this command will exec \fBgetty\fP(8). This program
843 should expect to find the modem already off-hook and a lock file
844 present so it should not try to hang up the line or create a lock
845 file. Note that the modem should be set up to report the DCE-DTE
846 (modem-computer, e.g. CONNECT 38400) speed, not the DCE-DCE
847 (modem-modem, e.g. CONNECT 14400) speed. For many modems the
848 initialization option -iW0 will set this.
850 The following command will make efax answer incoming calls on
851 \fB/dev/cua1\fP on the second ring. This device will be locked
852 using two different lock files but these lock files will be
853 removed while waiting for incoming calls (\fB-s\fP). If a data
854 call is detected, the \fBgetty\fP program will be run to
855 initialize the terminal driver and start a \fBlogin\fP(1)
856 process. Received fax files will be stored using names like
857 \fBDec02-12.32.33.001\fP, in the \fB/usr/spool/fax/incoming\fP
858 directory and the log file will be appended to
859 \fB/usr/spool/fax/faxlog.cua1\fP.
864 efax -d /dev/cua1 -j '+FAA=1' \\
865 -x /usr/spool/uucp/LCK..cua1 \\
866 -x /usr/spool/uucp/LCK..ttyS1 \\
867 -g "exec /sbin/getty -h /dev/cua1 %d" \\
869 -r "/usr/spool/fax/incoming/%b%d-%H.%I.%S" \\
870 >> /usr/spool/fax/faxlog.cua1 2>&1
875 Note that adaptive answer of either type will not work for all
876 callers. For some data calls the duration of the initial
877 data-mode answer may be too short for data handshaking to
878 complete. In other cases this duration may be so long that
879 incoming fax calls will time out before efax switches to fax
880 mode. In addition, some calling fax modems mistake data-mode
881 answering tones for fax signaling tones and initiate fax
882 negotiation too soon. If you use software adaptive answer you
883 can reduce the value of the initial data-mode answer (set by
884 TO_DATAF in efax.c) to get more reliable fax handshaking or
885 increase it for more reliable data handshaking. However, if you
886 need to provide reliable fax and data service to all callers you
887 should use separate phone numbers for the two types of calls.
889 When a call is answered the modem goes on-line with the
890 computer-to-modem baud rate fixed at the speed used for the most
891 recent AT command. When efax is waiting for a fax or data call
892 it sets the interface speed to 19200 bps since this is the speed
893 required for fax operation. This prevents full use of 28.8kbps
897 .SH USING INIT TO RUN EFAX
899 efax can answer all incoming calls if you place an entry for efax
900 in \fB/etc/inittab\fP (for SysV-like systems) or
901 \fB/etc/ttytab\fP (for BSD-like systems). The \fBinit\fP(8)
902 process will run a new copy of efax when the system boots up and
903 whenever the previous efax process terminates. The inittab or
904 ttytab entry should invoke efax by running the \fBfax\fP script
905 with an \fBanswer\fP argument.
907 For example, placing the following line in \fB/etc/inittab\fP
908 (and running "kill -1 1") will make init run the \fBfax\fP script
909 with the argument \fBanswer\fP every time previous process
910 terminates and \fBinit\fP is in runlevel 4 or 5.
915 s1:45:respawn:/bin/sh /usr/bin/fax answer
920 For BSD-like systems (e.g. SunOS), a line such as the following
921 in \fB/etc/ttytab\fP will have the same effect:
926 ttya "/usr/local/bin/fax answer" unknown on
931 You should protect the fax script and configuration files against
932 tampering since init will execute them as a privileged (root)
933 process. If you will be allowing data calls via getty and login
934 you should ensure that your system is reasonably secure
935 (e.g. that all user id's have secure passwords).
937 If efax exec()'s getty properly but you get a garbled login
938 prompt then there is probably a baud rate mismatch between the
939 modem and the computer. First, check the efax log file to make
940 sure the modem's CONNECT response reported the serial port speed
941 (e.g. 19200), \fBnot\fP the modem-modem speed (e.g. 14400).
942 Next, check the getty options and/or configuration files
943 (e.g. /etc/gettydefs) for that particular baud rate. Then run
944 getty manually with the same arguments and verify the port
945 settings using ``stty </dev/XXX''. Note that you'll probably
946 want to enable hardware flow control for data connections (-h for
947 agetty, CRTSCTS for getty_ps).
949 A few programs won't work properly when efax is set up to answer
950 calls because they don't create lock files. You can put the
951 shell script ``wrapper'' below around such programs to make them
952 work properly. Change BIN and LOCKF to suit.
959 LOCKF=/var/spool/uucp/LCK..cua1
962 echo lock file $LOCKF exists
965 printf "%10d\n" $$ >$LOCKF
974 .SH DELIVERING RECEIVED FAXES BY E-MAIL
976 The "fax answer" script described above can be configured to
977 e-mail the fax files received by the previous fax answer process
978 to a "fax manager" who can then forward the fax to the correct
979 recipient. The received fax files are send as MIME attachments,
980 one file per page, using the ``base64'' text encoding and the
981 ``image/tiff'' file format.
983 To view the fax images directly from your e-mail reader you will
984 have to configure it with an application that can display files
985 of type image/tiff. Typically this is specified in a ``mailcap''
986 file. For example, placing the following line in /etc/mailcap
987 will cause the fax file attachments to be displayed using the
988 ``fax view'' command.
991 image/tiff; fax view %s
994 .SH SENDING FAXES USING THE PRINT SPOOLER
996 You can configure a "fax" printer into the lpr print spooler that
997 will fax a document out using efax instead of printing it. This
998 allows a network server running efax to send faxes on behalf of
999 other machines, including non-Unix clients. In the following
1000 steps use the directories specified in the fax script if they are
1001 different than /usr/bin and /var/spool/fax (FAXDIR). To set up a
1002 fax printer do the following as root:
1004 (1) Create a link to the fax script called ``faxlpr'' so the fax
1005 script can determine when it is being invoked from the print
1009 ln /usr/bin/fax /usr/bin/faxlpr
1013 (2) Edit /etc/printcap and add an entry such as:
1018 fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr:
1023 to define a printer called "fax". Print files will be spooled to
1024 the /var/spool/fax (sd=) directory and then piped to the
1025 /usr/bin/faxlpr filter (if=).
1027 (3) Create and/or set the permissions to allow anyone to read and
1028 write in the fax spool directory. For example:
1033 mkdir /var/spool/fax
1034 chmod 777 /var/spool/fax
1039 (4) Create a printer daemon lock file that is readable by anyone:
1044 touch /var/spool/fax/lock
1045 chmod 644 /var/spool/fax/lock
1050 You should now be able to send a fax using the lpr interface by
1051 using a command such as:
1056 lpr -P fax -J "555 1212" file.ps
1061 where the -J option is used to specify the phone number or alias
1064 Note that if more than one file is given on the command line they
1065 will be concatenated before being passed to "fax send". TIFF-G3,
1066 Postscript or PBM files must therefore be sent one file at a time
1067 although TIFF and Postscript files may contain multiple pages.
1068 Only multiple \fItext\fP files can be sent in one command. Page
1069 breaks in text files can be marked with form-feed characters.
1070 Files will be converted and sent at the default (high)
1073 You can use lpq(1) to check the fax queue, lprm(1) to remove fax
1074 jobs and lpc(8) to control the spooler. In each case use the
1075 -Pfax option to specify the fax ``printer.'' A log file will be
1076 mailed to the user when the fax is sent.
1078 You should also be able to send a fax from any networked computer
1079 that has lpr-compatible remote printing software and that allows
1080 you to set the job name (-J option) to an arbitrary string. Such
1081 software is available for most computers.
1083 See the lpd(8) and printcap(5) man pages for information on the
1084 print spooler and for restricting access by host name
1085 (/etc/host.lpd) or by user group (the `rg' printcap entry).
1087 .SH RESOLVING PROBLEMS
1089 Double check the configuration setup in the first part of the fax
1090 script, particularly the modem device name and the lock file
1093 If efax hangs when trying to open the modem device (typically
1094 /dev/ttyX), the device is either already in use by another
1095 process (e.g. pppd) or it requires the carrier detect line to be
1096 true before it can be opened. Many systems define an alternate
1097 device name for the same physical device (typically cuaX) that
1098 can be opened even if carrier is not present or other programs
1099 are already using it.
1101 If responses to modem initialization commands are being lost or
1102 generated at random, another processes (e.g. getty or an efax
1103 auto-answer process) may be trying to use the modem at the same
1104 time. Try running efax while this other program is running. If
1105 efax does not report "/dev/ttyX locked or busy. waiting." then
1106 the lock files names are not specified correctly.
1108 Attempt to send a fax. Check that the modem starts making the
1109 calling signal (CNG, a 0.5 second beep every 3 seconds) as soon
1110 as it's finished dialing. This shows the modem is in fax mode.
1111 You may need to set the SPKR variable to -iM2L3 to monitor the
1112 phone line to do this.
1114 Listen for the answering fax machine and check that it sends the
1115 answer signal (CED, a 3 second beep) followed by "warbling"
1116 sounds (DIS frames) every 3 seconds. If you hear a continuous
1117 sound (tones or noise) instead, then you've connected to a data
1120 Your modem should send back its own warble (DCS frame) in
1121 response to DIS immediately followed by 1.5 seconds of noise (a
1122 channel check). If everything is OK, the receiving end will send
1123 another warble (CFR frame) and your modem will start to send
1124 data. If you have an external modem, check its LEDs. If flow
1125 control is working properly the modem's send data (SD) LED will
1126 turn off periodically while the fax data is sent.
1128 Check the message showing the line count and the average bit rate
1129 when the page transmission is done. Low line counts (under 1000
1130 for a letter size image) or the warning "fax output buffer
1131 overflow" while sending indicate that the image data format is
1132 incorrect. Check the file being sent using the "fax view"
1135 If you get the error message ``flow control did not work'' then
1136 flow control was not active. This usually results in a garbled
1137 transmission and the receiving machine may reject the page, abort
1138 the call, print a distorted or blank image and/or hang up.
1140 The warning "characters received while sending" or an <XOFF>
1141 character appearing after the transmission means that the
1142 operating system ignored the modem's XOFF flow control character.
1143 Ensure that you are not running other programs such as getty or
1144 pppd at the same time as efax since they will turn off xon/xoff
1147 If you cannot get flow control to work properly then enable
1148 ``virtual flow control'' with the \fB-of\fP option or hardware
1149 flow control with the \fB-oh\fP option.
1151 Check that the remote machine confirms reception with a +FPTS:1
1152 response (Class 2) or an MCF frame (Class 1).
1154 For Class 2 modems, the error message "abnormal call termination
1155 (code \fInn\fP)" indicates that the modem detected an error and
1158 Many companies advertise services that will fax back information
1159 on their products. These can be useful for testing fax
1162 The message "run length buffer overflow" when receiving indicates
1163 an error with the image data format. You may need to use the
1164 \fB-or\fP option with certain Class 2 modems.
1166 If efax displays the message "can't happen (<details>)" please
1167 send a bug report to the author.
1169 Finally, don't play "option bingo," if you can't resolve the
1170 problem send a verbose log of the failed session (the output from
1171 \fBfax -v ...\fP) to the address below.
1175 A Web Page with pointers to the latest version, known bugs and
1176 patches is available at:
1179 http://casas.ee.ubc.ca/efax/
1183 .SH RELATED SOFTWARE
1187 Independent packages provide more user-friendly interfaces to
1188 efax (xfax, tefax) and provide an e-mail-to-fax (Qfax) gateway
1189 using efax. All are available by anonymous FTP from
1190 metalab.unc.edu in /pub/Linux/apps/serialcomm/fax/.
1194 A port of an early version of efax for the Amiga is available as
1195 a component of a shareware voice mail package, AVM, distributed
1196 by Al Villarica (rvillari@cat.syr.edu).
1200 efax is relatively easy to port. All system-dependent code is in
1201 \fBefaxos.c\fP. An early version of efax was ported to VMS.
1202 Version 0.8a was ported to Win32 by Luigi Capriotti. Contact the
1203 author if you would like to integrate the Win32 code into the
1208 Efax was written by Ed Casas. Please send comments or bug
1209 reports to edc@cce.com.
1213 Bug reports should include the operating system, the type of the
1214 modem and a copy of a verbose session log that demonstrates the
1215 problem. It's usually impossible to help without a verbose log.
1216 Please do \fBnot\fP send fax image files.
1220 efax is copyright 1993 -- 1999 Ed Casas. It may be used, copied
1221 and modified under the terms of the GNU Public License.
1225 Although \fBefax\fP has been tested it may have errors that will
1226 prevent it from working correctly on your system. Some of these
1227 errors may cause serious problems including loss of data and
1228 interruptions to telephone service.
1232 CCITT Recommendation T.30, "Procedures for Document Facsimile
1233 Transmission in the General Switched Telephone Network". 1988
1235 CCITT Recommendation T.4, "Standardization of Group 3 Facsimile
1236 Apparatus for Document Transmission". 1988.
1238 For documentation on Class 1 and Class 2 fax commands as
1239 implemented by Connexant (formerly Rockwell) modems see
1240 http://www.conexant.com/techinfo.
1242 For the TIFF specification see
1243 http://partners.adobe.com/supportservice/devrelations/PDFS/TN/TIFF6.pdf
1244 or RFC 2301 (ftp://ftp.isi.edu/in-notes/rfc2301.txt).
1246 For information on Ghostscript see
1247 http://www.cs.wisc.edu/~ghost/.
1249 The pbm utilities can be obtained by ftp from wuarchive.wustl.edu
1250 in /graphics/graphics/packages/NetPBM/netpbm-1mar1994.tar.gz.
1252 PCX and many other file formats are described in: Gunter Born,
1253 The File Formats Handbook, International Thomson Computer Press,
1256 The "Fax Modem Source Book" by Andrew Margolis, published by John
1257 Wiley & Sons in 1994 (ISBN 0471950726), is a book on writing fax
1258 applications which includes source code.
1260 Dennis Bodson et. al., "FAX: Digital Facsimile Technology and
1261 Applications", Second Edition. Artech House, Boston. 1992.
1278 Can't read TIFF files with more than 1 strip
1280 Class 1 operation may fail if the program can't respond to
1281 certain data received from the modem within 55 milliseconds.
1283 May fail if multitasking delays cause the received data to
1284 overflow the computer's serial device buffer or if an under-run
1285 of transmit data exceeds 5 seconds.
1287 Polling does not work.
1289 Does not support 2-D coding, ECM, or BFT.