Provided by: efax-gtk_3.2.8-2.2_amd64 bug

NAME

       efax - send/receive faxes with Class 1, 2 or 2.0 fax modem

                                 (Please read the fax man page first.)

SYNOPSIS

       efax [ options ] [ -t num [ file... ] ]

OPTIONS

       Where options are:

       -a cmd   use the command ATcmd when answering the phone.  The default is "A".

       -c caps  set  the local modem capabilities.  See the section on capabilities below for the
                format and meaning of caps.  For Class 1 the default is 1,n,0,2,0,0,0,0  where  n
                is  the  highest  speed  supported  by  the  modem.   For  Class 2 the default is
                determined by the modem.

       -d dev   use the fax modem connected to device dev.  The default is /dev/modem.

       -e cmd   if a CONNECT response indicates a voice call, the  shell  /bin/sh  is  exec(2)'ed
                with cmd as its command.

       -f fnt   use  font  file  fnt  for  generating the header.  The default is a built-in 8x16
                font.  See the efix(1) -f option for the font file format.

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

       -h hdr   put  string  `hdr' at the top of each page.  The first %d in `hdr' is replaced by
                the page number and the second, if any, is replaced by the number of pages  being
                sent.

       -i str

       -j str

       -k str   send  the  command  ATstr  to  the  modem to initialize it.  -i commands are sent
                before the modem is put into fax mode, -j commands after  the  modem  is  in  fax
                mode,  and  -k  commands  just  before efax exits.  The only default is a hang-up
                (ATH) command that is sent before exiting only if no other -k options are  given.
                Multiple options may be used.

       -l id    set  the  local  identification  string  to id.  id should be the local telephone
                number in international format (for example "+1 800 555 1212").  This  is  passed
                to  the  remote  fax  machine.  Some fax machines may not accept characters other
                than numbers, space, and '+'.

       -n       force line buffering of  stdout  instead  of  block  buffering.   This  might  be
                necessary  if  outputting UTF-8 to a terminal with translated text via NLS, since
                otherwise the terminal may be confronted (when the buffer is flushed  when  full)
                with  only  a partially formed UTF-8 character.  Don't use this option unless you
                have to.

       -o opt   use option opt to accommodate a non-standard fax modem protocol.  See  the  MODEM
                REQUIREMENTS section below for more details.  The options are:

           0    Force use of Class 2.0 fax modem commands.  The modem must support Class 2.0.

           2    Force use of Class 2 fax modem commands.  The modem must support Class 2.

           1    Force  use  of  Class  1  fax modem commands. The modem must support Class 1.  By
                default efax queries the modem and uses the first  of  the  three  above  classes
                which is supported by the modem.

           a    use  software  adaptive  answer  method.  If the first attempt to answer the call
                does not result in a data connection within  8  seconds  the  phone  is  hung  up
                temporarily  and  answered  again  in  fax mode (see "Accepting both fax and data
                calls" below).

           e    ignore errors in modem initialization commands.

           f    use "virtual flow control".  efax tries to estimate the number of  bytes  in  the
                modem's transmit buffer and pauses as necessary to avoid filling it.  The modem's
                buffer is assumed to hold at least 96 bytes.  This feature does not work properly
                with  Class  2  modems that add redundant padding to scan lines.  Use this option
                only if you have problems configuring flow control.

           h    use hardware (RTS/CTS) in addition to software  (XON/XOFF)  flow  control.   Many
                modems  will  stop responding if this option is used.  See the section `Resolving
                Problems' before using this option.

           l    halve the time between testing lock files when  waiting  for  other  programs  to
                complete.  By default this is 8 seconds. For example -olll sets the interval to 1
                second.

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

           r    do not reverse bit  order  during  data  reception  for  Class  2  modems.   Only
                Multitech  modems  require  this option. Not normally required since efax detects
                these modems.

           x    send XON (DC1) instead of DC2 to start data reception.  Applies  to  a  very  few
                Class 2 modems only.

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

       -q n     ask for retransmission of pages received with more than n errors.  Default is 10.

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

       -s       remove lock file(s) after initializing the modem.  This allows outgoing calls  to
                proceed  when  efax  is  waiting  for  an  incoming  call.  If efax detects modem
                activity it will attempt to re-lock the device.  If the modem has been locked  by
                the  other  program  efax will exit and return 1 (``busy'').  Normally a new efax
                process is then started  by  init(8).  The  new  efax  process  will  then  check
                periodically until the lock file disappears and then re-initialize the modem.

       -t num [file...]
                dial  telephone  number  num and send the fax image files file....  If used, this
                must be the last argument on the command line.  The telephone  number  num  is  a
                string  that  may  contain any dial modifiers that the modem supports such as a T
                prefix for tone dialing or commas for delays.  If no file  names  are  given  the
                remote  fax  machine  will be polled. If no -t argument is given efax will answer
                the phone and attempt to receive a fax.

       -u       use UTF-8 and not locale codeset (if different) for messages to stderr and stdout
                (see  also the -n option) - this is useful if efax is used with a front-end which
                expects UTF-8 encoding of internationalized strings.

       -v strng select types of messages to be printed.  Each lower-case letter in strng  enables
                one type of message:

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

                Up  to  two  -v  options  may  be used.  The first is for messages printed to the
                standard error and the second is for messages to the standard output. The default
                is "ewin" to the standard error only.

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

       -x lkf   use  a  UUCP-style  lock file lkf to lock the modem device before opening it.  If
                the device is locked, efax checks every 15 seconds until it is free.  Up to 16 -x
                options may be used if there are several names for the same device.  A `#' prefix
                on the file name creates an binary rather than text (HDB-style) lock file.   This
                is the reverse of what was used by previous efax versions.

FAX FILE FORMATS

       efax  can  read  the  same  types  of files as efix(1) including text, T.4 (Group 3), PBM,
       single- and multi-page TIFF (G3 and uncompressed).  efax automatically determines the type
       of  file  from its contents.  TIFF files are recommended as they contain information about
       the image size and resolution.

       Each page to be sent should be converted to a separate TIFF format file with Group 3  (G3)
       compression.   Received  files are also stored in this format.  The EXAMPLES section below
       shows how efix and other programs can be used to create, view and print these files.

OPERATING SYSTEM REQUIREMENTS

       The operating system must provide short response times to avoid  protocol  timeouts.   For
       Class 2 and 2.0 modems the delay should not exceed 1 or 2 seconds.

       When  using  Class  1  modems  the  program  must  respond  to  certain  events  within 55
       milliseconds.  Longer delays may cause the fax protocol to fail in certain places (between
       DCS  and  TCF  or  between  RTC  and MPS).  Class 1 modems should therefore not be used on
       systems that cannot guarantee that the program will respond to incoming data in less  than
       55  milliseconds.   In  particular, some intelligent serial cards and terminal servers may
       introduce enough delay to cause problems with Class 1 operation.

       The  operating  system  must  also  provide  sufficient  low-level  buffering   to   allow
       uninterrupted  transfer  of  data  between  the modem and a disk file at the selected baud
       rate, typically 9600 bps.  Since the fax protocol does not provide end-to-end flow control
       the  effectiveness  of  flow control while receiving is limited by the size of the modem's
       buffer. This can be less than 100 bytes.  Efax does not use flow control during reception.

MODEM REQUIREMENTS

       The "Group" is the protocol used to send faxes between fax machines.   Efax  supports  the
       Group 3 protocol used over the public telephone network.

       The  "Class" is the protocol used by computers to control fax modems.  Efax supports Class
       1, 2 and 2.0 fax modems.

       Most fax modems use XON/XOFF flow control when in fax mode.  This  type  of  flow  control
       adds very little overhead for fax use. Many modems have unreliable hardware (RTS/CTS) flow
       control in fax mode.  By default efax enables only  XON/XOFF  flow  control  and  the  -oh
       option must be used to add hardware flow control.

       While  some  modems  have  serial  buffers of about 1k bytes, many inexpensive modems have
       buffers of about one hundred bytes and are  thus  more  likely  to  suffer  overruns  when
       sending faxes.

       A  few  older modems may need a delay between commands of more than the default value used
       by efax (100 milliseconds).  If the delay is too short, commands may  not  echo  properly,
       may time out, or may give inconsistent responses.  Use one or more -oz options to increase
       the delay between modem initialization  commands  and  use  the  E0  modem  initialization
       command to disable echoing of modem commands.

       By  default efax sends DC2 to start the data flow from the modem when receiving faxes from
       Class 2 modems.  A few older modems require XON instead.  Use of DC2 would cause the modem
       to give an error message and/or the program to time out.  The -ox option should be used in
       this case.

       A few older Class 2 modems (e.g. some Intel models) don't send DC2 or  XON  to  start  the
       data  flow  to  the  modem  when sending faxes.  After waiting 2 seconds efax will print a
       warning and start sending anyways.

       A very few Class 2 modems do not reverse the bit order (MSB to LSB) by default on receive.
       This  might  cause  errors  when  trying  to display or print the received files.  The -or
       option can be used in this case.

       Some inexpensive "9600 bps" fax modems only transmit at 9600 bps and reception is  limited
       to 4800 bps.

       The following Class 1 modems have been reported to work with efax: AT&T DataPort, Cardinal
       Digital Fax Modem (14400), Digicom Scout+, Motorola Lifestyle 28.8, Motorola  Power  28.8,
       QuickComm  Spirit  II,  Smartlink  9614AV-Modem, Supra Faxmodem 144LC, USR Courier V.32bis
       Terbo, USR Sportster (V.32 and V.34), Zoom AFC 2.400, Zoom VFX14.4V.

       The following Class 2 modems have been reported to work with efax:  14k4  Amigo  Communion
       fax/modem,  Adtech  Micro Systems 14.4 Fax/modem, askey modem type 1414VQE, AT&T DataPort,
       ATT/Paradyne, AT&T Paradyne PCMCIA, Boca modem, BOCA M1440E,  Crosslink  9614FH  faxmodem,
       FuryCard  DNE  5005,  GVC 14.4k internal, Intel 14.4 fax modem, Megahertz 14.4, , Microcom
       DeskPorte FAST ES 28.8, Motorola UDS FasTalk II, MultiTech 1432MU,  Practical  Peripherals
       PM14400FXMT,  Supra  V32bis,  Telebit  Worldblazer,  TKR  DM-24VF+,  Twincom 144/DFi, ViVa
       14.4/Fax modem, Vobis Fax-Modem (BZT-approved), Zoom  VFX14.4V,  ZyXEL  U-1496E[+],  ZyXEL
       Elite 2864I.

MODEM INITIALIZATION OPTIONS

       The required modem initialization commands are generated by efax.  Additional commands may
       be supplied as command-line arguments.  The modem must be set up  to  issue  verbose(text)
       result  codes.   The  following  command  does  this  and is sent by efax before trying to
       initialize the modem.

       Q0V1     respond to commands with verbose result codes

       The following commands may be useful for special purposes:

       X3       don't wait for dial tone before dialing.  This may be used to send a fax when the
                call  has already been dialed manually.  In this case use an empty string ("") as
                the first argument to the -t command.  Use  X4  (usual  default)  to  enable  all
                result codes.

       M2       leave the monitor speaker turned on for the duration of the call (use M0 to leave
                it off).

       L0       turn monitor speaker volume to minimum (use L3 for maximum).

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

       &D2      returns the modem to command mode when DTR is dropped.  The program drops DTR  at
                the start and end of the call if it can't get a response to a modem command.  You
                can use &D3 to reset the modem when DTR is dropped.

       S7=120   wait up to two minutes (120 seconds) for carrier.  This  may  be  useful  if  the
                answering  fax machine takes a long time to start the handshaking operation (e.g.
                a combined fax/answering machine with a long announcement).

CAPABILITIES

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

       vr,br,wd,ln,df,ec,bf,st

       where:

       vr  (vertical resolution) =
                0 for 98 lines per inch
                1 for 196 lpi

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

       wd  (width) =
                0 for 8.5" (21.5 cm) page width
                1 for 10" (25.5 cm)
                2 for 12" (30.3 cm)

       ln  (length) =
                0 for 11" (A4: 29.7 cm) page length
                1 for 14" (B4: 36.4 cm)
                2 for unlimited page length

       df  (data format) =
                0 for 1-D coding
                1 for 2-D coding (not supported)

       ec  (error correction) =
                0 for no error correction

       bf  (binary file) =
                0 for no binary file transfer

       st  (minimum scan time) =
                0 for zero delay per line
                1 for 5 ms per line
                3 for 10 ms per line
                5 for 20 ms per line
                7 for 40 ms per line

       When  receiving  a fax the vr, wd, and ln fields of the capability string should be set to
       the maximum values that your display software supports.  The default is 196 lpi,  standard
       (8.5"/21.5cm) width and unlimited length.

       When  sending  a  fax  efax will determine vr and ln from the image file and set wd to the
       default.

       If the receiving fax machine does not support  high  resolution  (vr=1)  mode,  efax  will
       reduce the resolution by combining pairs of scan lines.  If the receiving fax machine does
       not support the image's width then efax  will  truncate  or  pad  as  required.  Most  fax
       machines can receive ln up to 2.  Few machines support values of wd other than 0.

HEADERS

       efax adds blank scan lines at the top of each image when it is sent.  This allows room for
       the page header but increases the length of the image (by default about 0.1" or  2.5mm  of
       blank space is added).

       The  header  placed in this area typically includes the date and time, identifies the, and
       shows the page number and total pages.  Headers cannot be disabled but the  header  string
       can be set to a blank line.

       The  default  font  for  generating  the headers is the built-in 8x16 pixel font scaled to
       12x24 pixels (about 9 point size).

       Note that both efax and efix have -f options to specify the font.  efIx uses the  font  to
       generate  text  when doing text-to-fax conversions (during "fax make") while efAx uses the
       font to generate the header (during "fax send").

SESSION LOG

       A session log is written to the standard error stream.  This log gives  status  and  error
       messages from the program as selected by the -v option. A time stamp showing the full time
       or just minutes and seconds is printed before each  message.   Times  printed  along  with
       modem responses also show milliseconds.

RETURN VALUES

       The program returns an error code as follows:

       0        The fax was successfully sent or received.

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

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

       3        Modem protocol error.  The program did not receive the expected response from the
                modem.   The modem may not have been properly initialized, the correct -o options
                were not used, or a bug report may be in order.  Check the session log  for  more
                details.

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

       5        The program was terminated by a signal.

EXAMPLES

       Creating fax (G3) files

       The efix program can be used to convert text files to TIFF-G3 format.   For  example,  the
       following  command  will convert the text file letter to the files letter.001, letter.002,
       etc,:

              efix -nletter.%03d letter

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

               gs -q -sDEVICE=tiffg3 -dNOPAUSE \
                   -sOutputFile=letter.%03d letter.ps </dev/null

       will  convert the Postscript file letter.ps into high-resolution (vr=1) G3 fax image files
       letter.001, letter.002, ...

       The images should have margins of at least 1/2 inch (1 cm) since  the  fax  standard  only
       requires  that fax machines print a central portion of the image 196.6mm (7.7 inches) wide
       by 281.5mm (11.1 inches) high.

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

       Printing fax files

       You can use the efix program to print faxes on Postscript or HP-PCL  (LaserJet)  printers.
       For  example,  to  print  the  received fax file reply.001 on a Postscript printer use the
       command:

              efix -ops reply.001 | lpr

       Sending fax files

       The following command will dial the number 222-2222 using tone dialing and send a two-page
       fax  from  the  TIFF-G3  files  letter.001 and letter.002 using the fax modem connected to
       device /dev/cua1.

              efax -d /dev/cua1 \
                   -t T222-2222 letter.001 letter.002

       Manual answer

       You can use efax to answer the phone immediately and start fax reception.  Use  this  mode
       if you need to answer calls manually to see if they are fax or voice.

       For example, the following command will make the fax modem on device /dev/ttyS1 answer the
       phone and attempt to receive a fax.   The  received  fax  will  be  stored  in  the  files
       reply.001, reply.002, and so on.  The modem will identify itself as "555 1212" and receive
       faxes at high or low resolution (vr=1), at up to 14.4 kbps (br=5).

              efax -d /dev/ttyS1 -l "555 1212" \
                 -c 1,5 -r reply

       Automatic answer

       The -w option  makes  efax  wait  for  characters  to  become  available  from  the  modem
       (indicating  an  incoming  call)  before  starting fax reception.  Use the -w option and a
       -iS0=n option to answer the phone after n rings.  The example below will  make  the  modem
       answer  incoming  calls  in  fax mode on the fourth ring and save the received faxes using
       files names corresponding to the reception date and time.

              efax -d /dev/ttyb -w -iS0=4 2>&1 >> fax.log

       Sharing the modem with outgoing calls

       The modem device can be shared by programs that use  the  UUCP  device  locking  protocol.
       This  includes  pppd,  chat,  minicom,  kermit,  uucico, efax, cu, and many others others.
       However, locking will only work if all programs use the same lock file.

       efax will lock the modem device before opening it if one or more UUCP lock file names  are
       given  with  -x  options.   Most programs place their lock files in the /usr/spool/uucp or
       /var/lock directories and use the name LCK..dev where dev is the name of the  device  file
       in the /dev directory that is to be locked.

       If  the  -s  (share)  option  is used, the lock file is removed while waiting for incoming
       calls so other programs can use the same device.

       If efax detects another program using the modem while it is waiting to receive a fax, efax
       exits with a termination code of 1.  A subsequent efax process using this device will wait
       until the other program is finished before re-initializing the modem and starting to  wait
       for incoming calls again.

       Programs  that  try to lock the modem device by using device locking facilities other than
       UUCP lock files not be able to use this arbitration  mechanism  because  the  device  will
       still  be  open  to the efax process.  In this case you will need to kill the efax process
       (e.g. "fax stop") before starting the other program.

       When efax is waiting for a fax it leaves the modem  ready  to  receive  in  fax  mode  but
       removes the lock file.  When a slip or PPP program takes over the modem port by setting up
       its own lock file efax cannot send any more commands to the modem -- not even to reset it.
       Therefore  the other program has to set the modem back to data mode when it starts up.  To
       do this add a modem reset command (send ATZ expect OK) to the beginning of  your  slip  or
       PPP chat script.

       Accepting both fax and data calls

       Many  modems  have an adaptive data/fax answer mode that can be enabled using the -j+FAE=1
       (for Class 1) or -jFAA=1 (for Class 2[.0]) initialization string.  The type of call  (data
       or fax) can then be deduced from the modem's responses.

       Some  modems  have limited adaptive answer features (e.g. only working properly at certain
       baud rates or only in Class 2) or none at all.  In this case use the initialization string
       -i+FCLASS=0  to answer in data mode first and the -oa option to then hang up and try again
       in fax mode if the first answer attempt was not successful.  This  method  only  works  if
       your  telephone system waits a few seconds after you hang up before disconnecting incoming
       calls.

       If the -g option is used then the option's argument will be run as a shell command when an
       incoming  data call is detected.  Typically this command will exec getty(8).  This program
       should expect to find the modem already off-hook and a lock file present so it should  not
       try  to  hang  up the line or create a lock file.  Note that the modem should be set up to
       report the DCE-DTE (modem-computer, e.g. CONNECT 38400) speed,  not  the  DCE-DCE  (modem-
       modem, e.g. CONNECT 14400) speed.  For many modems the initialization option -iW0 will set
       this.

       The following command will make efax answer incoming calls  on  /dev/cua1  on  the  second
       ring.  This device will be locked using two different lock files but these lock files will
       be removed while waiting for incoming calls (-s).  If a data call is detected,  the  getty
       program  will  be  run  to  initialize  the  terminal driver and start a login(1) process.
       Received  fax  files  will  be  stored  using  names  like  Dec02-12.32.33.001,   in   the
       /usr/spool/fax/incoming    directory    and   the   log   file   will   be   appended   to
       /usr/spool/fax/faxlog.cua1.

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

       Note that adaptive answer of either type will not work for all  callers.   For  some  data
       calls  the  duration of the initial data-mode answer may be too short for data handshaking
       to complete.  In other cases this duration may be so long that  incoming  fax  calls  will
       time  out  before efax switches to fax mode.  In addition, some calling fax modems mistake
       data-mode answering tones for fax signaling tones and initiate fax negotiation  too  soon.
       If  you  use  software  adaptive  answer you can reduce the value of the initial data-mode
       answer (set by TO_DATAF in efax.c) to get more reliable fax handshaking or increase it for
       more  reliable  data  handshaking.   However, if you need to provide reliable fax and data
       service to all callers you should use separate phone numbers for the two types of calls.

       When a call is answered the modem goes on-line with the computer-to-modem baud rate  fixed
       at  the speed used for the most recent AT command.  When efax is waiting for a fax or data
       call it sets the interface speed to 19200 bps since this is the  speed  required  for  fax
       operation.  This prevents full use of 28.8kbps modem capabilities.

USING INIT TO RUN EFAX

       efax  can  answer  all  incoming calls if you place an entry for efax in /etc/inittab (for
       SysV-like systems) or /etc/ttytab (for BSD-like systems). The init(8) process will  run  a
       new  copy  of  efax  when  the  system  boots  up  and  whenever the previous efax process
       terminates.  The inittab or ttytab entry should invoke efax by running the fax script with
       an answer argument.

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

              s1:45:respawn:/bin/sh /usr/bin/fax answer

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

              ttya "/usr/local/bin/fax answer" unknown on

       You should protect the fax script and configuration files  against  tampering  since  init
       will  execute them as a privileged (root) process.  If you will be allowing data calls via
       getty and login you should ensure that your system is reasonably  secure  (e.g.  that  all
       user id's have secure passwords).

       If  efax exec()'s getty properly but you get a garbled login prompt then there is probably
       a baud rate mismatch between the modem and the computer.  First, check the efax  log  file
       to make sure the modem's CONNECT response reported the serial port speed (e.g. 19200), not
       the modem-modem speed (e.g. 14400).  Next, check the getty  options  and/or  configuration
       files  (e.g.  /etc/gettydefs) for that particular baud rate.  Then run getty manually with
       the same arguments and verify the port  settings  using  ``stty  </dev/XXX''.   Note  that
       you'll  probably want to enable hardware flow control for data connections (-h for agetty,
       CRTSCTS for getty_ps).

       A few programs won't work properly when efax is set up to answer calls because they  don't
       create lock files.  You can put the shell script ``wrapper'' below around such programs to
       make them work properly.  Change BIN and LOCKF to suit.

              #!/bin/sh
              BIN=/bin/badprogram
              LOCKF=/var/spool/uucp/LCK..cua1
              if [ -f $LOCKF ]
              then
                      echo lock file $LOCKF exists
                      exit 1
              else
                      printf "%10d0 $$ >$LOCKF
                      $BIN $*
                      rm $LOCKF
              fi

DELIVERING RECEIVED FAXES BY E-MAIL

       The "fax answer" script described above can be configured to e-mail the fax files received
       by  the previous fax answer process to a "fax manager" who can then forward the fax to the
       correct recipient.  The received fax files are send as  MIME  attachments,  one  file  per
       page, using the ``base64'' text encoding and the ``image/tiff'' file format.

       To view the fax images directly from your e-mail reader you will have to configure it with
       an application that can display files of type image/tiff.  Typically this is specified  in
       a  ``mailcap''  file.   For example, placing the following line in /etc/mailcap will cause
       the fax file attachments to be displayed using the ``fax view'' command.

       image/tiff; fax view %s

SENDING FAXES USING THE PRINT SPOOLER

       You can configure a "fax" printer into the lpr print spooler that will fax a document  out
       using  efax  instead  of  printing  it.  This allows a network server running efax to send
       faxes on behalf of other machines, including non-Unix clients.  In the following steps use
       the  directories  specified  in  the  fax  script  if they are different than /usr/bin and
       /var/spool/fax (FAXDIR).  To set up a fax printer do the following as root:

       (1) Create a link to the fax script called ``faxlpr'' so the fax script can determine when
       it is being invoked from the print spooler:

       ln -s /usr/bin/fax /usr/bin/faxlpr

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

              fax:lp=/dev/null:sd=/var/spool/fax:if=/usr/bin/faxlpr:

       to define a printer called "fax".  Print files will be spooled to the /var/spool/fax (sd=)
       directory and then piped to the /usr/bin/faxlpr filter (if=).  Error messages will  appear
       on /dev/console.

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

              mkdir /var/spool/fax
              chmod 777 /var/spool/fax

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

              touch /var/spool/fax/lock
              chmod 644 /var/spool/fax/lock

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

              lpr -P fax -J "555 1212" file.ps

       where the -J option is used to specify the phone number or alias to be dialed.

       Note that if more than one file is given on the command line  they  will  be  concatenated
       before  being  passed  to  "fax send".  TIFF-G3, Postscript or PBM files must therefore be
       sent one file at a time although TIFF and Postscript files  may  contain  multiple  pages.
       Only  multiple  text  files  can be sent in one command.  Page breaks in text files can be
       marked with form-feed characters.  Files will be converted and sent at the default  (high)
       resolution.

       You  can  use  lpq(1)  to  check  the  fax queue, lprm(1) to remove fax jobs and lpc(8) to
       control the spooler.  In each case use the -Pfax option to specify the fax ``printer.''  A
       log file will be mailed to the user when the fax is sent.

       You  should also be able to send a fax from any networked computer that has lpr-compatible
       remote printing software and that allows you to  set  the  job  name  (-J  option)  to  an
       arbitrary string.  Such software is available for most computers.

       See  the  lpd(8)  and  printcap(5)  man pages for information on the print spooler and for
       restricting access by host name (/etc/host.lpd)  or  by  user  group  (the  `rg'  printcap
       entry).

RESOLVING PROBLEMS

       Double check the configuration setup in the first part of the fax script, particularly the
       modem device name and the lock file names.

       If efax hangs when trying to open the modem device (typically /dev/ttyX),  the  device  is
       either  already  in  use  by another process (e.g. pppd) or it requires the carrier detect
       line to be true before it can be opened.  Many systems define an alternate device name for
       the  same  physical  device  (typically  cuaX)  that  can be opened even if carrier is not
       present or other programs are already using it.

       If responses to modem initialization commands are  being  lost  or  generated  at  random,
       another  processes  (e.g.  getty  or an efax auto-answer process) may be trying to use the
       modem at the same time.  Try running efax while this other program is  running.   If  efax
       does  not  report  "/dev/ttyX locked or busy. waiting."  then the lock files names are not
       specified correctly.

       Attempt to send a fax. Check that the modem starts making the calling signal (CNG,  a  0.5
       second beep every 3 seconds) as soon as it's finished dialing.  This shows the modem is in
       fax mode.  You may need to set the SPKR variable to -iM2L3 to monitor the phone line to do
       this.

       Listen  for  the answering fax machine and check that it sends the answer signal (CED, a 3
       second beep) followed by "warbling" sounds (DIS frames) every 3 seconds.  If  you  hear  a
       continuous sound (tones or noise) instead, then you've connected to a data modem instead.

       Your  modem  should  send  back  its own warble (DCS frame) in response to DIS immediately
       followed by 1.5 seconds of noise (a channel check).  If everything is  OK,  the  receiving
       end  will  send another warble (CFR frame) and your modem will start to send data.  If you
       have an external modem, check its LEDs.  If flow control is working properly  the  modem's
       send data (SD) LED will turn off periodically while the fax data is sent.

       Check  the  message  showing  the  line  count  and  the  average  bit  rate when the page
       transmission is done.  Low line counts (under 1000 for a letter size image) or the warning
       "fax  output  buffer  overflow"  while  sending  indicate  that  the  image data format is
       incorrect. Check the file being sent using the "fax view" command.

       If you get the error message ``flow control did not  work''  then  flow  control  was  not
       active.   This  usually  results  in  a garbled transmission and the receiving machine may
       reject the page, abort the call, print a distorted or blank image and/or hang up.

       The warning "characters received while sending" or an <XOFF> character appearing after the
       transmission  means  that  the  operating  system  ignored  the  modem's XOFF flow control
       character.  Ensure that you are not running other programs such as getty or  pppd  at  the
       same time as efax since they will turn off xon/xoff flow control.

       If  you cannot get flow control to work properly then enable ``virtual flow control'' with
       the -of option or hardware flow control with the -oh option.

       Check that the remote machine confirms reception with a +FPTS:1 response (Class 2)  or  an
       MCF frame (Class 1).

       For Class 2 modems, the error message "abnormal call termination (code nn)" indicates that
       the modem detected an error and hung up.

       Many companies advertise services that will fax back information on their products.  These
       can be useful for testing fax reception.

       The  message "run length buffer overflow" when receiving indicates an error with the image
       data format.  You may need to use the -or option with certain Class 2 modems.

       If efax displays the message "can't happen (<details>)" please send a bug  report  to  the
       author.

       Finally, don't play "option bingo," if you can't resolve the problem send a verbose log of
       the failed session (the output from fax -v ...) to the address below.

WEB PAGE

       A Web Page with pointers to the latest version, known bugs and patches is available at:

              http://casas.ee.ubc.ca/efax/

RELATED SOFTWARE

       For Linux Systems

       Independent packages provide more user-friendly  interfaces  to  efax  (xfax,  tefax)  and
       provide  an  e-mail-to-fax  (Qfax)  gateway using efax. All are available by anonymous FTP
       from metalab.unc.edu in /pub/Linux/apps/serialcomm/fax/.

       For Amiga Systems

       A port of an early version of efax for  the  Amiga  is  available  as  a  component  of  a
       shareware voice mail package, AVM, distributed by Al Villarica (rvillari@cat.syr.edu).

       Other Ports

       efax  is  relatively  easy  to  port.  All system-dependent code is in efaxos.c.  An early
       version of efax was ported to VMS.  Version 0.8a was ported to Win32 by  Luigi  Capriotti.
       Contact the author if you would like to integrate the Win32 code into the current version.

AUTHOR

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

BUG REPORTS

       Bug  reports  should  include  the operating system, the type of the modem and a copy of a
       verbose session log that demonstrates  the  problem.   It's  usually  impossible  to  help
       without a verbose log.  Please do not send fax image files.

COPYRIGHT

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

DISCLAIMER

       Although efax has been tested it may  have  errors  that  will  prevent  it  from  working
       correctly  on your system.  Some of these errors may cause serious problems including loss
       of data and interruptions to telephone service.

REFERENCES

       CCITT Recommendation T.30, "Procedures for Document Facsimile Transmission in the  General
       Switched Telephone Network". 1988

       CCITT  Recommendation  T.4,  "Standardization  of Group 3 Facsimile Apparatus for Document
       Transmission". 1988.

       For documentation on Class 1  and  Class  2  fax  commands  as  implemented  by  Connexant
       (formerly Rockwell) modems see http://www.conexant.com/techinfo.

       For                the                TIFF                specification                see
       http://partners.adobe.com/supportservice/devrelations/PDFS/TN/TIFF6.pdf   or   RFC    2301
       (ftp://ftp.isi.edu/in-notes/rfc2301.txt).

       For information on Ghostscript see http://www.cs.wisc.edu/~ghost/.

       The    pbm    utilities   can   be   obtained   by   ftp   from   wuarchive.wustl.edu   in
       /graphics/graphics/packages/NetPBM/netpbm-1mar1994.tar.gz.

       PCX and many other file formats are described in: Gunter Born, The File Formats  Handbook,
       International Thomson Computer Press, 1995.

       The  "Fax  Modem  Source  Book" by Andrew Margolis, published by John Wiley & Sons in 1994
       (ISBN 0471950726), is a book on writing fax applications which includes source code.

       Dennis Bodson et. al.,  "FAX:  Digital  Facsimile  Technology  and  Applications",  Second
       Edition. Artech House, Boston. 1992.

SEE ALSO

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

BUGS

       Can't read TIFF files with more than 1 strip

       Class 1 operation may fail if the program can't respond to certain data received from  the
       modem within 55 milliseconds.

       May  fail if multitasking delays cause the received data to overflow the computer's serial
       device buffer or if an under-run of transmit data exceeds 5 seconds.

       Polling does not work.

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