1EFAX(1)                                                                EFAX(1)
2
3
4

NAME

6       efax - send/receive faxes with Class 1, 2 or 2.0 fax modem
7
8                        (Please read the fax man page first.)
9

SYNOPSIS

11       efax [ options ] [ -t num [ file... ] ]
12
13

OPTIONS

15       Where options are:
16
17
18       -a cmd   use  the  command ATcmd when answering the phone.  The default
19                is "A".
20
21
22       -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
28
29       -d dev   use the fax modem connected to device  dev.   The  default  is
30                /dev/modem.
31
32
33       -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
37
38       -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
44
45       -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
49
50       -i str
51
52       -j str
53
54       -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
61
62       -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
68
69       -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
73
74           0    Force use of Class 2.0 fax modem  commands.   The  modem  must
75                support Class 2.0.
76
77
78           2    Force  use of Class 2 fax modem commands.  The modem must sup‐
79                port Class 2.
80
81
82           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
87
88           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
93
94           e    ignore errors in modem initialization commands.
95
96
97           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
105
106           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
111
112           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
116
117           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
122
123           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
127
128           x    send XON  (DC1)  instead  of  DC2  to  start  data  reception.
129                Applies to a very few Class 2 modems only.
130
131
132           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
137
138
139       -q n     ask for retransmission of pages  received  with  more  than  n
140                errors.  Default is 10.
141
142
143       -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
149
150
151       -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
160
161       -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
171
172       -v strng select  types of messages to be printed.  Each lower-case let‐
173                ter in strng enables one type of message:
174
175                   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
188                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
193
194       -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
199
200       -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
208

FAX FILE FORMATS

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
216       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
221

OPERATING SYSTEM REQUIREMENTS

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
227       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
236       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
244

MODEM REQUIREMENTS

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
250       The "Class" is the protocol used by computers to  control  fax  modems.
251       Efax supports Class 1, 2 and 2.0 fax modems.
252
253       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
259       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
263       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
270       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
276       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
280       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
284       Some inexpensive "9600 bps" fax modems only transmit at  9600  bps  and
285       reception is limited to 4800 bps.
286
287       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
293       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
303

MODEM INITIALIZATION OPTIONS

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
311
312       Q0V1     respond to commands with verbose result codes
313
314
315       The following commands may be useful for special purposes:
316
317
318       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
324
325       M2       leave  the  monitor  speaker turned on for the duration of the
326                call (use M0 to leave it off).
327
328
329       L0       turn monitor speaker volume to minimum (use L3 for maximum).
330
331
332       E0       disable echoing of modem commands.  See the Resolving Problems
333                section below.
334
335
336       &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
341
342       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
347

CAPABILITIES

349       The  capabilities of the local hardware and software can be set using a
350       string of 8 digits separated by commas:
351
352       vr,br,wd,ln,df,ec,bf,st
353
354       where:
355
356
357       vr  (vertical resolution) =
358                0 for 98 lines per inch
359                1 for 196 lpi
360
361
362       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
370
371       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
376
377       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
382
383       df  (data format) =
384                0 for 1-D coding
385                1 for 2-D coding (not supported)
386
387
388       ec  (error correction) =
389                0 for no error correction
390
391
392       bf  (binary file) =
393                0 for no binary file transfer
394
395
396       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
403
404       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
409       When  sending  a  fax efax will determine vr and ln from the image file
410       and set wd to the default.
411
412       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
418
419

HEADERS

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
425       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
429       The default font for generating the headers is the built-in 8x16  pixel
430       font scaled to 12x24 pixels (about 9 point size).
431
432       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
437

SESSION LOG

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
445

RETURN VALUES

447       The program returns an error code as follows:
448
449
450       0        The fax was successfully sent or received.
451
452
453       1        The dialed number was busy or the modem  device  was  in  use.
454                Try again later.
455
456
457       2        Something  failed  (e.g.  file  not found or disk full). Don't
458                retry.  Check the session log for more details.
459
460
461       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
467
468       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
472
473       5        The program was terminated by a signal.
474
475

EXAMPLES

477       Creating fax (G3) files
478
479       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
483
484              efix -nletter.%03d letter
485
486       Ghostscript's tiffg3 driver can generate fax files  in  TIFF-G3  format
487       from postscript files.  For example, the command:
488
489
490               gs -q -sDEVICE=tiffg3 -dNOPAUSE \
491                   -sOutputFile=letter.%03d letter.ps </dev/null
492
493       will  convert the Postscript file letter.ps into high-resolution (vr=1)
494       G3 fax image files letter.001, letter.002, ...
495
496       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
500       The efix program can also insert bitmaps in images  to  create  letter‐
501       head, signatures, etc.
502
503       Printing fax files
504
505       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
509
510              efix -ops reply.001 | lpr
511
512       Sending fax files
513
514       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
518
519              efax -d /dev/cua1 \
520                   -t T222-2222 letter.001 letter.002
521
522       Manual answer
523
524       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
528       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
534
535              efax -d /dev/ttyS1 -l "555 1212" \
536                 -c 1,5 -r reply
537
538       Automatic answer
539
540       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
547
548              efax -d /dev/ttyb -w -iS0=4 2>&1 >> fax.log
549
550       Sharing the modem with outgoing calls
551
552       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
557       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
563       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
566       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
572       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
578       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
586       Accepting both fax and data calls
587
588       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
593       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
601       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
610       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
619
620              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
628       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
641       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
647
648

USING INIT TO RUN EFAX

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
657       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
661
662              s1:45:respawn:/bin/sh /usr/bin/fax answer
663
664       For  BSD-like  systems  (e.g.  SunOS),  a line such as the following in
665       /etc/ttytab will have the same effect:
666
667
668              ttya "/usr/local/bin/fax answer" unknown on
669
670       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
676       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
687       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
692
693              #!/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

DELIVERING RECEIVED FAXES BY E-MAIL

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
713       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
719       image/tiff; fax view %s
720
721

SENDING FAXES USING THE PRINT SPOOLER

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
731       (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
734       ln /usr/bin/fax /usr/bin/faxlpr
735
736
737       (2) Edit /etc/printcap and add an entry such as:
738
739
740              fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr:
741
742       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=).
745
746       (3) Create and/or set the permissions to allow anyone to read and write
747       in the fax spool directory.  For example:
748
749
750              mkdir /var/spool/fax
751              chmod 777 /var/spool/fax
752
753       (4) Create a printer daemon lock file that is readable by anyone:
754
755
756              touch /var/spool/fax/lock
757              chmod 644 /var/spool/fax/lock
758
759       You should now be able to send a fax using the lpr interface by using a
760       command such as:
761
762
763              lpr -P fax -J "555 1212" file.ps
764
765       where  the -J option is used to specify the phone number or alias to be
766       dialed.
767
768       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
776       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
781       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
786       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
790

RESOLVING PROBLEMS

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
795       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
802       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
809       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
814       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
819       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
827       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
833       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
838       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
844       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
848       Check that  the  remote  machine  confirms  reception  with  a  +FPTS:1
849       response (Class 2) or an MCF frame (Class 1).
850
851       For  Class 2 modems, the error message "abnormal call termination (code
852       nn)" indicates that the modem detected an error and hung up.
853
854       Many companies advertise services that will  fax  back  information  on
855       their products.  These can be useful for testing fax reception.
856
857       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
861       If  efax  displays the message "can't happen (<details>)" please send a
862       bug report to the author.
863
864       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
868

WEB PAGE

870       A Web Page with pointers to the latest version, known bugs and  patches
871       is available at:
872
873              http://casas.ee.ubc.ca/efax/
874
876       For Linux Systems
877
878       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
883       For Amiga Systems
884
885       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
889       Other Ports
890
891       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
896

AUTHOR

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

BUG REPORTS

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
908
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
913

DISCLAIMER

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
920

REFERENCES

922       CCITT Recommendation T.30, "Procedures for Document Facsimile Transmis‐
923       sion in the General Switched Telephone Network". 1988
924
925       CCITT Recommendation T.4, "Standardization of Group 3 Facsimile Appara‐
926       tus for Document Transmission". 1988.
927
928       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
932       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
936       For information on Ghostscript see http://www.cs.wisc.edu/~ghost/.
937
938       The  pbm  utilities  can be obtained by ftp from wuarchive.wustl.edu in
939       /graphics/graphics/packages/NetPBM/netpbm-1mar1994.tar.gz.
940
941       PCX and many other file formats are described in: Gunter Born, The File
942       Formats Handbook, International Thomson Computer Press, 1995.
943
944       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
948       Dennis  Bodson et. al., "FAX: Digital Facsimile Technology and Applica‐
949       tions", Second Edition. Artech House, Boston. 1992.
950
951

SEE ALSO

953       fax(1), efix(1), gs(1), init(8),  inittab(5),  ttytab(5),  printcap(5),
954       lpd(8), printf(3), strftime(3).
955
956

BUGS

958       Can't read TIFF files with more than 1 strip
959
960       Class 1 operation may fail if the program can't respond to certain data
961       received from the modem within 55 milliseconds.
962
963       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
967       Polling does not work.
968
969       Does not support 2-D coding, ECM, or BFT.
970
971
972
9733rd Berkeley Distribution        February 1999                         EFAX(1)
Impressum