packages icon

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

      -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

                                    - 1 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

               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.

                                    - 2 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

          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

                                    - 3 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

               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.

                                    - 4 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

      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

                                    - 5 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

      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

      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.

                                    - 6 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

                                    - 7 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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)

                                    - 8 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

      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

                                    - 9 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

               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.

      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 </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 command:

                                   - 10 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

           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,

                                   - 11 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

           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

           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.

                                   - 12 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

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

                                   - 13 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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.


                                   - 14 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

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

                                   - 15 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

           the /var/spool/fax (sd=) directory and then piped to the
           /usr/bin/faxlpr filter (if=).

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

                                   - 16 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

                                   - 17 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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.

      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

      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

                                   - 18 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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

      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

                                   - 19 -           Formatted:  July 3, 2022

 EFAX(1)                                                             EFAX(1)
                                February 1999

      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), strftime(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.

                                   - 20 -           Formatted:  July 3, 2022