Provided by: efax_0.9a-19_amd64 bug


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

                                 (Please read the fax man page first.)


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


       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.

       -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

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

       -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

           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.

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


       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.


       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.


       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.


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


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



       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

       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.


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


       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.


       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

       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.


       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,

              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 </dev/null

       will convert the Postscript file 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

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

       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

       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-,  in  the
       /usr/spool/fax/incoming   directory   and   the   log   file   will   be    appended    to

              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.


       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.

              if [ -f $LOCKF ]
                      echo lock file $LOCKF exists
                      exit 1
                      printf "%10d0 $$ >$LOCKF
                      $BIN $*
                      rm $LOCKF


       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


       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:


       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"

       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)

       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


       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

       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

       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.


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



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

       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.


       Efax was written by Ed Casas.  Please send comments or bug reports to


       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.


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


       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.


       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

       For                the                TIFF                specification                see    or   RFC   2301

       For information on Ghostscript see

       The   pbm   utilities   can   be   obtained   by   ftp   from    in

       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.


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


       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.