1EFAX(1) EFAX(1)
2
6 efax - send/receive faxes with Class 1, 2 or 2.0 fax modem
7 (Please read the fax man page first.)
9
11 efax [ options ] [ -t num [ file... ] ]
12
15 Where options are:
16 -a cmd use the command ATcmd when answering the phone. The default
19 is "A".
20 -c caps set the local modem capabilities. See the section on capabil‐
23 ities below for the format and meaning of caps. For Class 1
24 the default is 1,n,0,2,0,0,0,0 where n is the highest speed
25 supported by the modem. For Class 2 the default is determined
26 by the modem.
27 -d dev use the fax modem connected to device dev. The default is
30 /dev/modem.
31 -f fnt use font file fnt for generating the header. The default is a
34 built-in 8x16 font. See the efix(1) -f option for the font
35 file format.
36 -g cmd if a CONNECT (or DATA) response indicates a data call, the
39 shell /bin/sh is exec(2)'ed with cmd as its command. cmd is a
40 printf(3) format that may contain up to 6 %d escapes which are
41 replaced by the baud rate following the most recent CONNECT
42 message. cmd typically exec's getty(8).
43 -h hdr put string `hdr' at the top of each page. The first %d in
46 `hdr' is replaced by the page number and the second, if any,
47 is replaced by the number of pages being sent.
48 -i str
51 -j str
53 -k str send the command ATstr to the modem to initialize it. -i com‐
55 mands are sent before the modem is put into fax mode, -j com‐
56 mands after the modem is in fax mode, and -k commands just
57 before efax exits. The only default is a hang-up (ATH) com‐
58 mand that is sent before exiting only if no other -k options
59 are given. Multiple options may be used.
60 -l id set the local identification string to id. id should be the
63 local telephone number in international format (for example
64 "+1 800 555 1212"). This is passed to the remote fax machine.
65 Some fax machines may not accept characters other than num‐
66 bers, space, and '+'.
67 -o opt use option opt to accommodate a non-standard fax modem proto‐
70 col. See the MODEM REQUIREMENTS section below for more
71 details. The options are:
72 0 Force use of Class 2.0 fax modem commands. The modem must
75 support Class 2.0.
76 2 Force use of Class 2 fax modem commands. The modem must sup‐
79 port Class 2.
80 1 Force use of Class 1 fax modem commands. The modem must sup‐
83 port Class 1. By default efax queries the modem and uses the
84 first of the three above classes which is supported by the
85 modem.
86 a use software adaptive answer method. If the first attempt to
89 answer the call does not result in a data connection within 8
90 seconds the phone is hung up temporarily and answered again in
91 fax mode (see "Accepting both fax and data calls" below).
92 e ignore errors in modem initialization commands.
95 f use "virtual flow control". efax tries to estimate the number
98 of bytes in the modem's transmit buffer and pauses as neces‐
99 sary to avoid filling it. The modem's buffer is assumed to
100 hold at least 96 bytes. This feature does not work properly
101 with Class 2 modems that add redundant padding to scan lines.
102 Use this option only if you have problems configuring flow
103 control.
104 h use hardware (RTS/CTS) in addition to software (XON/XOFF) flow
107 control. Many modems will stop responding if this option is
108 used. See the section `Resolving Problems' before using this
109 option.
110 l halve the time between testing lock files when waiting for
113 other programs to complete. By default this is 8 seconds. For
114 example -olll sets the interval to 1 second.
115 n ignore requests for pages to be retransmitted. Use this option
118 if you don't care about the quality of the received fax or if
119 the receiving machine is too fussy. Otherwise each page may
120 be retransmitted up to 3 times.
121 r do not reverse bit order during data reception for Class 2
124 modems. Only Multitech modems require this option. Not nor‐
125 mally required since efax detects these modems.
126 x send XON (DC1) instead of DC2 to start data reception.
129 Applies to a very few Class 2 modems only.
130 z delay an additional 100 milliseconds before each modem ini‐
133 tialization or reset command. The initial delay is 100 ms.
134 For example, -ozzz produces a 400 ms delay. Use with modems
135 that get confused when commands arrive too quickly.
136 -q n ask for retransmission of pages received with more than n
140 errors. Default is 10.
141 -r pat each received fax page is stored in a separate file. The file
144 name is created using pat as a strftime(3) format string. A
145 page number of the form .001, .002, ... is appended to the
146 file name. If pat is blank ("") or no -r option is given a
147 default string of "%m%d%H%M%S" is used.
148 -s remove lock file(s) after initializing the modem. This allows
152 outgoing calls to proceed when efax is waiting for an incoming
153 call. If efax detects modem activity it will attempt to re-
154 lock the device. If the modem has been locked by the other
155 program efax will exit and return 1 (``busy''). Normally a
156 new efax process is then started by init(8). The new efax
157 process will then check periodically until the lock file dis‐
158 appears and then re-initialize the modem.
159 -t num [file...]
162 dial telephone number num and send the fax image files
163 file.... If used, this must be the last argument on the com‐
164 mand line. The telephone number num is a string that may con‐
165 tain any dial modifiers that the modem supports such as a T
166 prefix for tone dialing or commas for delays. If no file
167 names are given the remote fax machine will be polled. If no
168 -t argument is given efax will answer the phone and attempt to
169 receive a fax.
170 -v strng select types of messages to be printed. Each lower-case let‐
173 ter in strng enables one type of message:
174 e - errors
176 w - warnings
177 i - session progress information
178 n - capability negotiation information
179 c - modem (AT) commands and responses
180 h - HDLC frame data (Class 1 only)
181 m - modem output
182 a - program arguments
183 r - reception error details
184 t - transmission details
185 f - image file details
186 x - lock file processing
187 Up to two -v options may be used. The first is for messages
189 printed to the standard error and the second is for messages
190 to the standard output. The default is "ewin" to the standard
191 error only.
192 -w wait for an OK or CONNECT prompt instead of issuing an answer
195 (ATA) command to receive a fax. Use this option when the
196 modem is set to auto-answer (using S0=n) or if another program
197 has already answered the call.
198 -x lkf use a UUCP-style lock file lkf to lock the modem device before
201 opening it. If the device is locked, efax checks every 15
202 seconds until it is free. Up to 16 -x options may be used if
203 there are several names for the same device. A `#' prefix on
204 the file name creates an binary rather than text (HDB-style)
205 lock file. This is the reverse of what was used by previous
206 efax versions.
207
210 efax can read the same types of files as efix(1) including text, T.4
211 (Group 3), PBM, single- and multi-page TIFF (G3 and uncompressed).
212 efax automatically determines the type of file from its contents. TIFF
213 files are recommended as they contain information about the image size
214 and resolution.
215 Each page to be sent should be converted to a separate TIFF format file
217 with Group 3 (G3) compression. Received files are also stored in this
218 format. The EXAMPLES section below shows how efix and other programs
219 can be used to create, view and print these files.
220
223 The operating system must provide short response times to avoid proto‐
224 col timeouts. For Class 2 and 2.0 modems the delay should not exceed 1
225 or 2 seconds.
226 When using Class 1 modems the program must respond to certain events
228 within 55 milliseconds. Longer delays may cause the fax protocol to
229 fail in certain places (between DCS and TCF or between RTC and MPS).
230 Class 1 modems should therefore not be used on systems that cannot
231 guarantee that the program will respond to incoming data in less than
232 55 milliseconds. In particular, some intelligent serial cards and ter‐
233 minal servers may introduce enough delay to cause problems with Class 1
234 operation.
235 The operating system must also provide sufficient low-level buffering
237 to allow uninterrupted transfer of data between the modem and a disk
238 file at the selected baud rate, typically 9600 bps. Since the fax pro‐
239 tocol does not provide end-to-end flow control the effectiveness of
240 flow control while receiving is limited by the size of the modem's buf‐
241 fer. This can be less than 100 bytes. Efax does not use flow control
242 during reception.
243
246 The "Group" is the protocol used to send faxes between fax machines.
247 Efax supports the Group 3 protocol used over the public telephone net‐
248 work.
249 The "Class" is the protocol used by computers to control fax modems.
251 Efax supports Class 1, 2 and 2.0 fax modems.
252 Most fax modems use XON/XOFF flow control when in fax mode. This type
254 of flow control adds very little overhead for fax use. Many modems have
255 unreliable hardware (RTS/CTS) flow control in fax mode. By default
256 efax enables only XON/XOFF flow control and the -oh option must be used
257 to add hardware flow control.
258 While some modems have serial buffers of about 1k bytes, many inexpen‐
260 sive modems have buffers of about one hundred bytes and are thus more
261 likely to suffer overruns when sending faxes.
262 A few older modems may need a delay between commands of more than the
264 default value used by efax (100 milliseconds). If the delay is too
265 short, commands may not echo properly, may time out, or may give incon‐
266 sistent responses. Use one or more -oz options to increase the delay
267 between modem initialization commands and use the E0 modem initializa‐
268 tion command to disable echoing of modem commands.
269 By default efax sends DC2 to start the data flow from the modem when
271 receiving faxes from Class 2 modems. A few older modems require XON
272 instead. Use of DC2 would cause the modem to give an error message
273 and/or the program to time out. The -ox option should be used in this
274 case.
275 A few older Class 2 modems (e.g. some Intel models) don't send DC2 or
277 XON to start the data flow to the modem when sending faxes. After
278 waiting 2 seconds efax will print a warning and start sending anyways.
279 A very few Class 2 modems do not reverse the bit order (MSB to LSB) by
281 default on receive. This might cause errors when trying to display or
282 print the received files. The -or option can be used in this case.
283 Some inexpensive "9600 bps" fax modems only transmit at 9600 bps and
285 reception is limited to 4800 bps.
286 The following Class 1 modems have been reported to work with efax: AT&T
288 DataPort, Cardinal Digital Fax Modem (14400), Digicom Scout+, Motorola
289 Lifestyle 28.8, Motorola Power 28.8, QuickComm Spirit II, Smartlink
290 9614AV-Modem, Supra Faxmodem 144LC, USR Courier V.32bis Terbo, USR
291 Sportster (V.32 and V.34), Zoom AFC 2.400, Zoom VFX14.4V.
292 The following Class 2 modems have been reported to work with efax: 14k4
294 Amigo Communion fax/modem, Adtech Micro Systems 14.4 Fax/modem, askey
295 modem type 1414VQE, AT&T DataPort, ATT/Paradyne, AT&T Paradyne PCMCIA,
296 Boca modem, BOCA M1440E, Crosslink 9614FH faxmodem, FuryCard DNE 5005,
297 GVC 14.4k internal, Intel 14.4 fax modem, Megahertz 14.4, , Microcom
298 DeskPorte FAST ES 28.8, Motorola UDS FasTalk II, MultiTech 1432MU,
299 Practical Peripherals PM14400FXMT, Supra V32bis, Telebit Worldblazer,
300 TKR DM-24VF+, Twincom 144/DFi, ViVa 14.4/Fax modem, Vobis Fax-Modem
301 (BZT-approved), Zoom VFX14.4V, ZyXEL U-1496E[+], ZyXEL Elite 2864I.
302
305 The required modem initialization commands are generated by efax.
306 Additional commands may be supplied as command-line arguments. The
307 modem must be set up to issue verbose(text) result codes. The follow‐
308 ing command does this and is sent by efax before trying to initialize
309 the modem.
310 Q0V1 respond to commands with verbose result codes
313 The following commands may be useful for special purposes:
316 X3 don't wait for dial tone before dialing. This may be used to
319 send a fax when the call has already been dialed manually. In
320 this case use an empty string ("") as the first argument to
321 the -t command. Use X4 (usual default) to enable all result
322 codes.
323 M2 leave the monitor speaker turned on for the duration of the
326 call (use M0 to leave it off).
327 L0 turn monitor speaker volume to minimum (use L3 for maximum).
330 E0 disable echoing of modem commands. See the Resolving Problems
333 section below.
334 &D2 returns the modem to command mode when DTR is dropped. The
337 program drops DTR at the start and end of the call if it can't
338 get a response to a modem command. You can use &D3 to reset
339 the modem when DTR is dropped.
340 S7=120 wait up to two minutes (120 seconds) for carrier. This may be
343 useful if the answering fax machine takes a long time to start
344 the handshaking operation (e.g. a combined fax/answering
345 machine with a long announcement).
346
349 The capabilities of the local hardware and software can be set using a
350 string of 8 digits separated by commas:
351 vr,br,wd,ln,df,ec,bf,st
353 where:
355 vr (vertical resolution) =
358 0 for 98 lines per inch
359 1 for 196 lpi
360 br (bit rate) =
363 0 for 2400 bps
364 1 for 4800
365 2 for 7200
366 3 for 9600
367 4 for 12000 (V.17)
368 5 for 14400 (V.17)
369 wd (width) =
372 0 for 8.5" (21.5 cm) page width
373 1 for 10" (25.5 cm)
374 2 for 12" (30.3 cm)
375 ln (length) =
378 0 for 11" (A4: 29.7 cm) page length
379 1 for 14" (B4: 36.4 cm)
380 2 for unlimited page length
381 df (data format) =
384 0 for 1-D coding
385 1 for 2-D coding (not supported)
386 ec (error correction) =
389 0 for no error correction
390 bf (binary file) =
393 0 for no binary file transfer
394 st (minimum scan time) =
397 0 for zero delay per line
398 1 for 5 ms per line
399 3 for 10 ms per line
400 5 for 20 ms per line
401 7 for 40 ms per line
402 When receiving a fax the vr, wd, and ln fields of the capability string
405 should be set to the maximum values that your display software sup‐
406 ports. The default is 196 lpi, standard (8.5"/21.5cm) width and unlim‐
407 ited length.
408 When sending a fax efax will determine vr and ln from the image file
410 and set wd to the default.
411 If the receiving fax machine does not support high resolution (vr=1)
413 mode, efax will reduce the resolution by combining pairs of scan lines.
414 If the receiving fax machine does not support the image's width then
415 efax will truncate or pad as required. Most fax machines can receive ln
416 up to 2. Few machines support values of wd other than 0.
417
421 efax adds blank scan lines at the top of each image when it is sent.
422 This allows room for the page header but increases the length of the
423 image (by default about 0.1" or 2.5mm of blank space is added).
424 The header placed in this area typically includes the date and time,
426 identifies the, and shows the page number and total pages. Headers
427 cannot be disabled but the header string can be set to a blank line.
428 The default font for generating the headers is the built-in 8x16 pixel
430 font scaled to 12x24 pixels (about 9 point size).
431 Note that both efax and efix have -f options to specify the font. efIx
433 uses the font to generate text when doing text-to-fax conversions (dur‐
434 ing "fax make") while efAx uses the font to generate the header (during
435 "fax send").
436
439 A session log is written to the standard error stream. This log gives
440 status and error messages from the program as selected by the -v
441 option. A time stamp showing the full time or just minutes and seconds
442 is printed before each message. Times printed along with modem
443 responses also show milliseconds.
444
447 The program returns an error code as follows:
448 0 The fax was successfully sent or received.
451 1 The dialed number was busy or the modem device was in use.
454 Try again later.
455 2 Something failed (e.g. file not found or disk full). Don't
458 retry. Check the session log for more details.
459 3 Modem protocol error. The program did not receive the
462 expected response from the modem. The modem may not have been
463 properly initialized, the correct -o options were not used, or
464 a bug report may be in order. Check the session log for more
465 details.
466 4 The modem is not responding. Operator attention is required.
469 Check that the modem is turned on and connected to the correct
470 port.
471 5 The program was terminated by a signal.
474
477 Creating fax (G3) files
478 The efix program can be used to convert text files to TIFF-G3 format.
480 For example, the following command will convert the text file letter to
481 the files letter.001, letter.002, etc,:
482 efix -nletter.%03d letter
485 Ghostscript's tiffg3 driver can generate fax files in TIFF-G3 format
487 from postscript files. For example, the command:
488 gs -q -sDEVICE=tiffg3 -dNOPAUSE \
491 -sOutputFile=letter.%03d letter.ps </dev/null
492 will convert the Postscript file letter.ps into high-resolution (vr=1)
494 G3 fax image files letter.001, letter.002, ...
495 The images should have margins of at least 1/2 inch (1 cm) since the
497 fax standard only requires that fax machines print a central portion of
498 the image 196.6mm (7.7 inches) wide by 281.5mm (11.1 inches) high.
499 The efix program can also insert bitmaps in images to create letter‐
501 head, signatures, etc.
502 Printing fax files
504 You can use the efix program to print faxes on Postscript or HP-PCL
506 (LaserJet) printers. For example, to print the received fax file
507 reply.001 on a Postscript printer use the command:
508 efix -ops reply.001 | lpr
511 Sending fax files
513 The following command will dial the number 222-2222 using tone dialing
515 and send a two-page fax from the TIFF-G3 files letter.001 and let‐
516 ter.002 using the fax modem connected to device /dev/cua1.
517 efax -d /dev/cua1 \
520 -t T222-2222 letter.001 letter.002
521 Manual answer
523 You can use efax to answer the phone immediately and start fax recep‐
525 tion. Use this mode if you need to answer calls manually to see if
526 they are fax or voice.
527 For example, the following command will make the fax modem on device
529 /dev/ttyS1 answer the phone and attempt to receive a fax. The received
530 fax will be stored in the files reply.001, reply.002, and so on. The
531 modem will identify itself as "555 1212" and receive faxes at high or
532 low resolution (vr=1), at up to 14.4 kbps (br=5).
533 efax -d /dev/ttyS1 -l "555 1212" \
536 -c 1,5 -r reply
537 Automatic answer
539 The -w option makes efax wait for characters to become available from
541 the modem (indicating an incoming call) before starting fax reception.
542 Use the -w option and a -iS0=n option to answer the phone after n
543 rings. The example below will make the modem answer incoming calls in
544 fax mode on the fourth ring and save the received faxes using files
545 names corresponding to the reception date and time.
546 efax -d /dev/ttyb -w -iS0=4 2>&1 >> fax.log
549 Sharing the modem with outgoing calls
551 The modem device can be shared by programs that use the UUCP device
553 locking protocol. This includes pppd, chat, minicom, kermit, uucico,
554 efax, cu, and many others others. However, locking will only work if
555 all programs use the same lock file.
556 efax will lock the modem device before opening it if one or more UUCP
558 lock file names are given with -x options. Most programs place their
559 lock files in the /usr/spool/uucp or /var/lock directories and use the
560 name LCK..dev where dev is the name of the device file in the /dev
561 directory that is to be locked.
562 If the -s (share) option is used, the lock file is removed while wait‐
564 ing for incoming calls so other programs can use the same device.
565 If efax detects another program using the modem while it is waiting to
567 receive a fax, efax exits with a termination code of 1. A subsequent
568 efax process using this device will wait until the other program is
569 finished before re-initializing the modem and starting to wait for
570 incoming calls again.
571 Programs that try to lock the modem device by using device locking
573 facilities other than UUCP lock files not be able to use this arbitra‐
574 tion mechanism because the device will still be open to the efax
575 process. In this case you will need to kill the efax process (e.g.
576 "fax stop") before starting the other program.
577 When efax is waiting for a fax it leaves the modem ready to receive in
579 fax mode but removes the lock file. When a slip or PPP program takes
580 over the modem port by setting up its own lock file efax cannot send
581 any more commands to the modem -- not even to reset it. Therefore the
582 other program has to set the modem back to data mode when it starts up.
583 To do this add a modem reset command (send ATZ expect OK) to the begin‐
584 ning of your slip or PPP chat script.
585 Accepting both fax and data calls
587 Many modems have an adaptive data/fax answer mode that can be enabled
589 using the -j+FAE=1 (for Class 1) or -jFAA=1 (for Class 2[.0]) initial‐
590 ization string. The type of call (data or fax) can then be deduced
591 from the modem's responses.
592 Some modems have limited adaptive answer features (e.g. only working
594 properly at certain baud rates or only in Class 2) or none at all. In
595 this case use the initialization string -i+FCLASS=0 to answer in data
596 mode first and the -oa option to then hang up and try again in fax mode
597 if the first answer attempt was not successful. This method only works
598 if your telephone system waits a few seconds after you hang up before
599 disconnecting incoming calls.
600 If the -g option is used then the option's argument will be run as a
602 shell command when an incoming data call is detected. Typically this
603 command will exec getty(8). This program should expect to find the
604 modem already off-hook and a lock file present so it should not try to
605 hang up the line or create a lock file. Note that the modem should be
606 set up to report the DCE-DTE (modem-computer, e.g. CONNECT 38400)
607 speed, not the DCE-DCE (modem-modem, e.g. CONNECT 14400) speed. For
608 many modems the initialization option -iW0 will set this.
609 The following command will make efax answer incoming calls on /dev/cua1
611 on the second ring. This device will be locked using two different
612 lock files but these lock files will be removed while waiting for
613 incoming calls (-s). If a data call is detected, the getty program
614 will be run to initialize the terminal driver and start a login(1)
615 process. Received fax files will be stored using names like
616 Dec02-12.32.33.001, in the /usr/spool/fax/incoming directory and the
617 log file will be appended to /usr/spool/fax/faxlog.cua1.
618 efax -d /dev/cua1 -j '+FAA=1' \
621 -x /usr/spool/uucp/LCK..cua1 \
622 -x /usr/spool/uucp/LCK..ttyS1 \
623 -g "exec /sbin/getty -h /dev/cua1 %d" \
624 -iS0=2 -w -s \
625 -r "/usr/spool/fax/incoming/%b%d-%H.%I.%S" \
626 >> /usr/spool/fax/faxlog.cua1 2>&1
627 Note that adaptive answer of either type will not work for all callers.
629 For some data calls the duration of the initial data-mode answer may be
630 too short for data handshaking to complete. In other cases this dura‐
631 tion may be so long that incoming fax calls will time out before efax
632 switches to fax mode. In addition, some calling fax modems mistake
633 data-mode answering tones for fax signaling tones and initiate fax
634 negotiation too soon. If you use software adaptive answer you can
635 reduce the value of the initial data-mode answer (set by TO_DATAF in
636 efax.c) to get more reliable fax handshaking or increase it for more
637 reliable data handshaking. However, if you need to provide reliable
638 fax and data service to all callers you should use separate phone num‐
639 bers for the two types of calls.
640 When a call is answered the modem goes on-line with the computer-to-
642 modem baud rate fixed at the speed used for the most recent AT command.
643 When efax is waiting for a fax or data call it sets the interface speed
644 to 19200 bps since this is the speed required for fax operation. This
645 prevents full use of 28.8kbps modem capabilities.
646
650 efax can answer all incoming calls if you place an entry for efax in
651 /etc/inittab (for SysV-like systems) or /etc/ttytab (for BSD-like sys‐
652 tems). The init(8) process will run a new copy of efax when the system
653 boots up and whenever the previous efax process terminates. The init‐
654 tab or ttytab entry should invoke efax by running the fax script with
655 an answer argument.
656 For example, placing the following line in /etc/inittab (and running
658 "kill -1 1") will make init run the fax script with the argument answer
659 every time previous process terminates and init is in runlevel 4 or 5.
660 s1:45:respawn:/bin/sh /usr/bin/fax answer
663 For BSD-like systems (e.g. SunOS), a line such as the following in
665 /etc/ttytab will have the same effect:
666 ttya "/usr/local/bin/fax answer" unknown on
669 You should protect the fax script and configuration files against tam‐
671 pering since init will execute them as a privileged (root) process. If
672 you will be allowing data calls via getty and login you should ensure
673 that your system is reasonably secure (e.g. that all user id's have
674 secure passwords).
675 If efax exec()'s getty properly but you get a garbled login prompt then
677 there is probably a baud rate mismatch between the modem and the com‐
678 puter. First, check the efax log file to make sure the modem's CONNECT
679 response reported the serial port speed (e.g. 19200), not the modem-
680 modem speed (e.g. 14400). Next, check the getty options and/or config‐
681 uration files (e.g. /etc/gettydefs) for that particular baud rate.
682 Then run getty manually with the same arguments and verify the port
683 settings using ``stty </dev/XXX''. Note that you'll probably want to
684 enable hardware flow control for data connections (-h for agetty,
685 CRTSCTS for getty_ps).
686 A few programs won't work properly when efax is set up to answer calls
688 because they don't create lock files. You can put the shell script
689 ``wrapper'' below around such programs to make them work properly.
690 Change BIN and LOCKF to suit.
691 #!/bin/sh
694 BIN=/bin/badprogram
695 LOCKF=/var/spool/uucp/LCK..cua1
696 if [ -f $LOCKF ]
697 then
698 echo lock file $LOCKF exists
699 exit 1
700 else
701 printf "%10d0 $$ >$LOCKF
702 $BIN $*
703 rm $LOCKF
704 fi
705
707 The "fax answer" script described above can be configured to e-mail the
708 fax files received by the previous fax answer process to a "fax man‐
709 ager" who can then forward the fax to the correct recipient. The
710 received fax files are send as MIME attachments, one file per page,
711 using the ``base64'' text encoding and the ``image/tiff'' file format.
712 To view the fax images directly from your e-mail reader you will have
714 to configure it with an application that can display files of type
715 image/tiff. Typically this is specified in a ``mailcap'' file. For
716 example, placing the following line in /etc/mailcap will cause the fax
717 file attachments to be displayed using the ``fax view'' command.
718 image/tiff; fax view %s
720
723 You can configure a "fax" printer into the lpr print spooler that will
724 fax a document out using efax instead of printing it. This allows a
725 network server running efax to send faxes on behalf of other machines,
726 including non-Unix clients. In the following steps use the directories
727 specified in the fax script if they are different than /usr/bin and
728 /var/spool/fax (FAXDIR). To set up a fax printer do the following as
729 root:
730 (1) Create a link to the fax script called ``faxlpr'' so the fax script
732 can determine when it is being invoked from the print spooler:
733 ln -s /usr/bin/fax /usr/bin/faxlpr
735 (2) Edit /etc/printcap and add an entry such as:
738 fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr:
741 to define a printer called "fax". Print files will be spooled to the
743 /var/spool/fax (sd=) directory and then piped to the /usr/bin/faxlpr
744 filter (if=). Error messages will appear on /dev/console.
745 (3) Create and/or set the permissions to allow anyone to read and write
747 in the fax spool directory. For example:
748 mkdir /var/spool/fax
751 chmod 777 /var/spool/fax
752 (4) Create a printer daemon lock file that is readable by anyone:
754 touch /var/spool/fax/lock
757 chmod 644 /var/spool/fax/lock
758 You should now be able to send a fax using the lpr interface by using a
760 command such as:
761 lpr -P fax -J "555 1212" file.ps
764 where the -J option is used to specify the phone number or alias to be
766 dialed.
767 Note that if more than one file is given on the command line they will
769 be concatenated before being passed to "fax send". TIFF-G3, Postscript
770 or PBM files must therefore be sent one file at a time although TIFF
771 and Postscript files may contain multiple pages. Only multiple text
772 files can be sent in one command. Page breaks in text files can be
773 marked with form-feed characters. Files will be converted and sent at
774 the default (high) resolution.
775 You can use lpq(1) to check the fax queue, lprm(1) to remove fax jobs
777 and lpc(8) to control the spooler. In each case use the -Pfax option
778 to specify the fax ``printer.'' A log file will be mailed to the user
779 when the fax is sent.
780 You should also be able to send a fax from any networked computer that
782 has lpr-compatible remote printing software and that allows you to set
783 the job name (-J option) to an arbitrary string. Such software is
784 available for most computers.
785 See the lpd(8) and printcap(5) man pages for information on the print
787 spooler and for restricting access by host name (/etc/host.lpd) or by
788 user group (the `rg' printcap entry).
789
792 Double check the configuration setup in the first part of the fax
793 script, particularly the modem device name and the lock file names.
794 If efax hangs when trying to open the modem device (typically
796 /dev/ttyX), the device is either already in use by another process
797 (e.g. pppd) or it requires the carrier detect line to be true before it
798 can be opened. Many systems define an alternate device name for the
799 same physical device (typically cuaX) that can be opened even if car‐
800 rier is not present or other programs are already using it.
801 If responses to modem initialization commands are being lost or gener‐
803 ated at random, another processes (e.g. getty or an efax auto-answer
804 process) may be trying to use the modem at the same time. Try running
805 efax while this other program is running. If efax does not report
806 "/dev/ttyX locked or busy. waiting." then the lock files names are not
807 specified correctly.
808 Attempt to send a fax. Check that the modem starts making the calling
810 signal (CNG, a 0.5 second beep every 3 seconds) as soon as it's fin‐
811 ished dialing. This shows the modem is in fax mode. You may need to
812 set the SPKR variable to -iM2L3 to monitor the phone line to do this.
813 Listen for the answering fax machine and check that it sends the answer
815 signal (CED, a 3 second beep) followed by "warbling" sounds (DIS
816 frames) every 3 seconds. If you hear a continuous sound (tones or
817 noise) instead, then you've connected to a data modem instead.
818 Your modem should send back its own warble (DCS frame) in response to
820 DIS immediately followed by 1.5 seconds of noise (a channel check). If
821 everything is OK, the receiving end will send another warble (CFR
822 frame) and your modem will start to send data. If you have an external
823 modem, check its LEDs. If flow control is working properly the modem's
824 send data (SD) LED will turn off periodically while the fax data is
825 sent.
826 Check the message showing the line count and the average bit rate when
828 the page transmission is done. Low line counts (under 1000 for a let‐
829 ter size image) or the warning "fax output buffer overflow" while send‐
830 ing indicate that the image data format is incorrect. Check the file
831 being sent using the "fax view" command.
832 If you get the error message ``flow control did not work'' then flow
834 control was not active. This usually results in a garbled transmission
835 and the receiving machine may reject the page, abort the call, print a
836 distorted or blank image and/or hang up.
837 The warning "characters received while sending" or an <XOFF> character
839 appearing after the transmission means that the operating system
840 ignored the modem's XOFF flow control character. Ensure that you are
841 not running other programs such as getty or pppd at the same time as
842 efax since they will turn off xon/xoff flow control.
843 If you cannot get flow control to work properly then enable ``virtual
845 flow control'' with the -of option or hardware flow control with the
846 -oh option.
847 Check that the remote machine confirms reception with a +FPTS:1
849 response (Class 2) or an MCF frame (Class 1).
850 For Class 2 modems, the error message "abnormal call termination (code
852 nn)" indicates that the modem detected an error and hung up.
853 Many companies advertise services that will fax back information on
855 their products. These can be useful for testing fax reception.
856 The message "run length buffer overflow" when receiving indicates an
858 error with the image data format. You may need to use the -or option
859 with certain Class 2 modems.
860 If efax displays the message "can't happen (<details>)" please send a
862 bug report to the author.
863 Finally, don't play "option bingo," if you can't resolve the problem
865 send a verbose log of the failed session (the output from fax -v ...)
866 to the address below.
867
870 A Web Page with pointers to the latest version, known bugs and patches
871 is available at:
872 http://casas.ee.ubc.ca/efax/
874
876 For Linux Systems
877 Independent packages provide more user-friendly interfaces to efax
879 (xfax, tefax) and provide an e-mail-to-fax (Qfax) gateway using efax.
880 All are available by anonymous FTP from metalab.unc.edu in
881 /pub/Linux/apps/serialcomm/fax/.
882 For Amiga Systems
884 A port of an early version of efax for the Amiga is available as a com‐
886 ponent of a shareware voice mail package, AVM, distributed by Al Vil‐
887 larica (rvillari@cat.syr.edu).
888 Other Ports
890 efax is relatively easy to port. All system-dependent code is in
892 efaxos.c. An early version of efax was ported to VMS. Version 0.8a
893 was ported to Win32 by Luigi Capriotti. Contact the author if you
894 would like to integrate the Win32 code into the current version.
895
898 Efax was written by Ed Casas. Please send comments or bug reports to
899 edc@cce.com.
900
903 Bug reports should include the operating system, the type of the modem
904 and a copy of a verbose session log that demonstrates the problem.
905 It's usually impossible to help without a verbose log. Please do not
906 send fax image files.
907
910 efax is copyright 1993 -- 1999 Ed Casas. It may be used, copied and
911 modified under the terms of the GNU Public License.
912
915 Although efax has been tested it may have errors that will prevent it
916 from working correctly on your system. Some of these errors may cause
917 serious problems including loss of data and interruptions to telephone
918 service.
919
922 CCITT Recommendation T.30, "Procedures for Document Facsimile Transmis‐
923 sion in the General Switched Telephone Network". 1988
924 CCITT Recommendation T.4, "Standardization of Group 3 Facsimile Appara‐
926 tus for Document Transmission". 1988.
927 For documentation on Class 1 and Class 2 fax commands as implemented by
929 Connexant (formerly Rockwell) modems see http://www.conexant.com/tech‐
930 info.
931 For the TIFF specification see http://partners.adobe.com/supportser‐
933 vice/devrelations/PDFS/TN/TIFF6.pdf or RFC 2301 (ftp://ftp.isi.edu/in-
934 notes/rfc2301.txt).
935 For information on Ghostscript see http://www.cs.wisc.edu/~ghost/.
937 The pbm utilities can be obtained by ftp from wuarchive.wustl.edu in
939 /graphics/graphics/packages/NetPBM/netpbm-1mar1994.tar.gz.
940 PCX and many other file formats are described in: Gunter Born, The File
942 Formats Handbook, International Thomson Computer Press, 1995.
943 The "Fax Modem Source Book" by Andrew Margolis, published by John Wiley
945 & Sons in 1994 (ISBN 0471950726), is a book on writing fax applications
946 which includes source code.
947 Dennis Bodson et. al., "FAX: Digital Facsimile Technology and Applica‐
949 tions", Second Edition. Artech House, Boston. 1992.
950
953 fax(1), efix(1), gs(1), init(8), inittab(5), ttytab(5), printcap(5),
954 lpd(8), printf(3), strftime(3).
955
958 Can't read TIFF files with more than 1 strip
959 Class 1 operation may fail if the program can't respond to certain data
961 received from the modem within 55 milliseconds.
962 May fail if multitasking delays cause the received data to overflow the
964 computer's serial device buffer or if an under-run of transmit data
965 exceeds 5 seconds.
966 Polling does not work.
968 Does not support 2-D coding, ECM, or BFT.
9703rd Berkeley Distribution February 1999 EFAX(1)