efax - send/receive faxes using Class 1 or 2 fax modems [ ] [ | ] Where _o_p_t_i_o_n_s are: use the fax modem connected to device _d_e_v. The default is /dev/fax. use option _o_p_t to accommodate a non-standard fax modem protocol. See the MODEM REQUIREMENTS section below for more details. The _o_p_tions are: 1 Use Class 1 fax modem commands. The modem must suport Class 1 commands. The default is to use Class 2 commands. a use software adaptive answer method. If the first attempt to answer the call does not result in a data connection within 20 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. If errors are already being ignored, pay attention to them again. r reverse bit order during data reception. Most modems re- quire this option. x send XON (DC1) instead of DC2 to start data reception. Ap- plies to Class 2 only. z delay an additional 100 milliseconds before each modem ini- tialization or reset command. The initial delay is 100 ms. For example, -ozzz produces a 400 ms delay. send the command AT_s_t_r to the modem to initialize it. Multiple -i may options be used. send the command AT_s_t_r to the modem to reset it when done. Mul- tiple -z may options be used. set the local capabilities to _c_a_p_s. See the section on capabili- ties below for the format and meaning of _c_a_p_s. The default is 1,3,0,2,0,0,0,0. For Class 2 operation this option must appear after the modem initialization (-i) option that enables fax mode. set the local identification string to _i_d. _i_d should be the lo- cal telephone number in international format (for example "+1 800 555 1212"). This option must appear after the modem initializa- tion (-i) option that enables fax mode. select types of messages to be printed. Each _l_o_w_e_r-_c_a_s_e letter in _s_t_r_n_g 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 The default is "ewin". use UUCP-style lock file _l_k_f 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 HDB-style (text) lock file. remove lock file(s) after initializing the modem. This allows outgoing calls to proceed. When efax detects modem activity it will attempt to re-lock the device. If the modem is now locked by another program efax will exit and return 1 (``busy''). If efax is run again (e.g. by init) it will then wait until the line becomes free. don't issue an answer (ATA) command before starting 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. if a CONNECT (or DATA) response indicates a data call, the shell /bin/sh is exec(2)'ed with _c_m_d as its command. _c_m_d 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 mes- sage. _c_m_d typically exec's getty(8). ask for page retransmission if more than _n errors detected, De- fault is 10. answer phone and receive a fax. Each fax page is stored in a separate file. The file name is created using _p_a_t as a strftime(3) format string. A page number of the form .001, .002, ... is appended to the file name. If _p_a_t is blank (""), a de- fault string of "%m%d%H%M%S" is used. If a file already exists, efax terminates with an error message. dial telephone number _n_u_m and send the fax image files _f_i_l_e.... The telephone number _n_u_m is a string that may contain any dial modifiers that the modem supports, for example, a T prefix for tone dialing or commas for delays. Each page is stored in a separate file. The images are coded ac- cording to the ITU-T (CCITT) Group 3 fax standard, T.4. The EX- AMPLES section below shows how Ghostscript and the PBMPlus utili- ties can be used to create and print these files. The operating system must provide short response times to avoid protocol timeouts. When using Class 1 modems the program must respond to certain events (DCS frame or end of data) within 55 milliseconds. For Class 2 modems the delay should not exceed 1 or 2 seconds. The operating system must also provide sufficient low-level buffering to allow uninterrupted transfer of data from the modem to 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. "Group" describes the protocol used to send faxes over the tele- phone network. Efax suports the universal Group 3 standard. The "Class" is the protocol used between a computer and a fax modem. Efax supports Class 1 and 2 (but not 2.0) fax modems. Most modems (including those based on Rockwell or Sierra chip- sets) reverse the bit order (MSB to LSB) on receive. This will cause errors when trying to display or print the received files. The -or option should be specified when receiving faxes using these modems. While all fax modems support XON/XOFF flow control, most have un- reliable hardware (RTS/CTS) flow control in fax mode. Since XON/XOFF flow control adds very little overhead in fax mode, efax does not support 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 receiving data. Some 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 in- crease the delay between modem initialization commands. Class 1 modems should not be used on systems that cannot guaran- tee that the program will respond to incoming data in less than 55 milliseconds. Longer delays may cause the fax protocol to fail in certain places (between DCS and TCF or between RTC and MPS). By default efax sends DC2 to start the data flow from the modem when receiving faxes from Class 2 modems. A few older modems re- quire 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 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. The following modems have been reported to work with efax: AT&T DataPort, ATT/Paradyne, Boca modem, Cardinal Digital Fax Modem (14400) (Class 1), Crosslink 9614FH faxmodem, FuryCard DNE 5005, Intel 14.4 fax modem, MultiTech 1432MU, Practical Peripherals PM14400FXMT, Supra V32bis, Supra Faxmodem 144LC (Class 1), Tele- bit Worldblazer, Twincom 144/DFi, Vobis Fax-Modem (BZT-approved), Zoom VFX14.4V (Class 1 and 2), ZyXEL U-1496E[+]. Modem initialization commands are supplied as command-line argu- ments. The modem must be set up to issue verbose(text) result codes. The following command does this: respond to commands with verbose result codes The following commands may be useful in some cases: 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. leave the monitor speaker turned on for the duration of the call (use M0 to leave it off). turn monitor speaker volume to minimum (use L3 for maximum). returns the modem to command mode when DTR is dropped. The pro- gram drops DTR at the start and end of the call if it can't get a response to a reset (ATZ) command. &D3 resets the modem when DTR is dropped. 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 following initialization command be used with Class 1 modems: enables Class 1 fax modem commands. The following initialization commands be used with Class 2 modems: enables Class 2 fax modem commands. enable Class 2 fax reception. The capabilities of the local hardware and software are set using a string of 8 digits separated by commas: where: 0 for 98 lines per inch 1 for 196 lpi 0 for 2400 bps 1 for 4800 2 for 7200 3 for 9600 4 for 12000 (V.17) 5 for 14400 (V.17) 0 for 8.5 1 for 10 2 for 12 0 for 11 1 for 14 2 for unlimited page length 0 for 1-D coding 1 for 2-D coding (not supported) 0 for no error correction 0 for no binary file transfer 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 It is important that the proper capability string be specified. When _r_e_c_e_i_v_i_n_g a fax the _v_r, _w_d, _l_n and _d_f fields of the capabil- ity string should be set to the maximum values that your display software supports. When _s_e_n_d_i_n_g a fax the _v_r, _w_d, _l_n and _d_f fields of the capability string should correspond to the format of the image files. If necessary, efax will convert a file in high resolution mode (_v_r=1) to low resolution (_v_r=0) by sending alternate scan lines. However, if the receiving machine does not support any of the other format values then the fax files must be created again in a compatible format and another call made. Most fax machines can receive _v_r=0 or 1 and _l_n up to 2. Few machines support values of _w_d or _d_f other than 0. 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 time (or just minutes and seconds) is printed after each message if more than 1 second has elapsed since the last time stamp. 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 re- try. 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 re- port 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. Ghostscript's and drivers can be used to generate fax files in Group 3 (T.4) format from postscript files if the 32-byte header is removed. For example, the command: gs -q -sDEVICE=dfaxhigh -dNOPAUSE \ -sOutputFile=letter.%03d letter.ps &_1 | _t_e_e _r_e_p_l_y._l_o_g 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 -or -i"+FCLASS=2;+FCR=1" \ -iS0=4 -w -r "" 2>&1 >> fax.in.log _T_h_e _m_o_d_e_m _d_e_v_i_c_e _c_a_n _b_e _s_h_a_r_e_d _b_y _p_r_o_g_r_a_m_s _t_h_a_t _u_s_e _t_h_e _U_U_C_P _d_e_v_- _i_c_e _l_o_c_k_i_n_g _p_r_o_t_o_c_o_l (_k_e_r_m_i_t, _u_u_c_i_c_o, _e_f_a_x, _c_u, _e_t_c.). _e_f_a_x _w_i_l_l _l_o_c_k _t_h_e _m_o_d_e_m _d_e_v_i_c_e _b_e_f_o_r_e _o_p_e_n_i_n_g _i_t _i_f _o_n_e _o_r _m_o_r_e _U_U_C_P _l_o_c_k _f_i_l_e _n_a_m_e_s _a_r_e _g_i_v_e_n _w_i_t_h -x _o_p_t_i_o_n_s. _T_h_e _l_o_c_k _f_i_l_e _n_a_m_e_s _a_r_e _t_y_p_i_c_a_l_l_y /usr/spool/uucp/LCK.._d_e_v _w_h_e_r_e _d_e_v _i_s _t_h_e _n_a_m_e _o_f _t_h_e _d_e_v_i_c_e _f_i_l_e _i_n _t_h_e /_d_e_v _d_i_r_e_c_t_o_r_y _t_h_a_t _i_s _t_o _b_e _l_o_c_k_e_d. _I_f _t_h_e -s (_s_h_a_r_e) _o_p_t_i_o_n _i_s _u_s_e_d, _t_h_e _l_o_c_k _f_i_l_e _i_s _r_e_m_o_v_e_d _w_h_i_l_e _w_a_i_t_i_n_g _f_o_r _i_n_c_o_m_i_n_g _c_a_l_l_s _s_o _o_t_h_e_r _p_r_o_g_r_a_m_s _c_a_n _u_s_e _t_h_e _s_a_m_e _d_e_v_i_c_e. _I_f _e_f_a_x _d_e_t_e_c_t_s _a_n_o_t_h_e_r _p_r_o_g_r_a_m _u_s_i_n_g _t_h_e _m_o_d_e_m _w_h_i_l_e _i_t _i_s _w_a_i_t_- _i_n_g _t_o _r_e_c_e_i_v_e _a _f_a_x, _e_f_a_x _e_x_i_t_s _w_i_t_h _a _t_e_r_m_i_n_a_t_i_o_n _c_o_d_e _o_f _1. _A _s_u_b_s_e_q_u_e_n_t _e_f_a_x _p_r_o_c_e_s_s _u_s_i_n_g _t_h_i_s _d_e_v_i_c_e _w_i_l_l _w_a_i_t _u_n_t_i_l _t_h_e _o_t_h_e_r _p_r_o_g_r_a_m _i_s _f_i_n_i_s_h_e_d _b_e_f_o_r_e _r_e-_i_n_i_t_i_a_l_i_z_i_n_g _t_h_e _m_o_d_e_m _a_n_d _s_t_a_r_t_i_n_g _t_o _w_a_i_t _f_o_r _i_n_c_o_m_i_n_g _c_a_l_l_s _a_g_a_i_n. _M_a_n_y _m_o_d_e_m_s _h_a_v_e _a_n _a_d_a_p_t_i_v_e _d_a_t_a/_f_a_x _a_n_s_w_e_r _m_o_d_e _t_h_a_t _c_a_n _b_e _e_n_- _a_b_l_e_d _u_s_i_n_g _t_h_e -i+FAE=1 (_f_o_r _C_l_a_s_s _1) _o_r -i+FAA=1 (_f_o_r _C_l_a_s_s _2) _i_n_i_t_i_a_l_i_z_a_t_i_o_n _s_t_r_i_n_g. _T_h_e _t_y_p_e _o_f _c_a_l_l (_d_a_t_a _o_r _f_a_x) _c_a_n _t_h_e_n _b_e _d_e_d_u_c_e_d _f_r_o_m _t_h_e _m_o_d_e_m'_s _r_e_s_p_o_n_s_e_s. _S_o_m_e _m_o_d_e_m_s _h_a_v_e _l_i_m_i_t_e_d _a_d_a_p_t_i_v_e _a_n_s_w_e_r _f_e_a_t_u_r_e_s (_e._g. _o_n_l_y _w_o_r_k_i_n_g _p_r_o_p_e_r_l_y _a_t _c_e_r_t_a_i_n _b_a_u_d _r_a_t_e_s _o_r _o_n_l_y _i_n _C_l_a_s_s _2) _o_r _n_o_n_e _a_t _a_l_l. _I_n _t_h_i_s _c_a_s_e _u_s_e _t_h_e _i_n_i_t_i_a_l_i_z_a_t_i_o_n _s_t_r_i_n_g -i+FCLASS=0 _t_o _a_n_s_w_e_r _i_n _d_a_t_a _m_o_d_e _f_i_r_s_t _a_n_d _t_h_e -oa _o_p_t_i_o_n _t_h_e_n _h_a_n_g _u_p _a_n_d _t_r_y _a_g_a_i_n _i_n _f_a_x _m_o_d_e _i_f _t_h_e _t_h_e _f_i_r_s_t _a_n_s_w_e_r _a_t_t_e_m_p_t _w_a_s _n_o_t _s_u_c_c_e_s_s_f_u_l. _T_h_i_s _m_e_t_h_o_d _o_n_l_y _w_o_r_k_s _i_f _y_o_u_r _t_e_l_e_p_h_o_n_e _s_y_s_t_e_m _w_a_i_t_s _a _f_e_w _s_e_c_o_n_d_s _a_f_t_e_r _y_o_u _h_a_n_g _u_p _b_e_f_o_r_e _d_i_s_c_o_n_n_e_c_t_i_n_g _i_n_c_o_m_i_n_g _c_a_l_l_s. _I_f _t_h_e -g _o_p_t_i_o_n _i_s _u_s_e_d, _t_h_e _o_p_t_i_o_n'_s _a_r_g_u_m_e_n_t _w_i_l_l _b_e _r_u_n _a_s _a _s_h_e_l_l _c_o_m_m_a_n_d _w_h_e_n _a_n _i_n_c_o_m_i_n_g _d_a_t_a _c_a_l_l _i_s _d_e_t_e_c_t_e_d. _T_y_p_i_c_a_l_l_y _t_h_i_s _c_o_m_m_a_n_d _w_i_l_l _e_x_e_c getty(_8). _T_h_i_s _p_r_o_g_r_a_m _s_h_o_u_l_d _e_x_p_e_c_t _t_o _f_i_n_d _t_h_e _m_o_d_e_m _a_l_r_e_a_d_y _o_f_f-_h_o_o_k _a_n_d _a _l_o_c_k _f_i_l_e _p_r_e_s_e_n_t _s_o _i_t _s_h_o_u_l_d _n_o_t _t_r_y _t_o _h_a_n_g _u_p _t_h_e _l_i_n_e _o_r _c_r_e_a_t_e _a _l_o_c_k _f_i_l_e. _T_h_e _f_o_l_l_o_w_i_n_g _c_o_m_m_a_n_d _w_i_l_l _m_a_k_e _e_f_a_x _a_n_s_w_e_r _i_n_c_o_m_i_n_g _c_a_l_l_s _o_n /dev/cua1 _o_n _t_h_e _s_e_c_o_n_d _r_i_n_g. _T_h_i_s _d_e_v_i_c_e _w_i_l_l _b_e _l_o_c_k_e_d _u_s_i_n_g _t_w_o _d_i_f_f_e_r_e_n_t _l_o_c_k _f_i_l_e_s _b_u_t _t_h_e_s_e _l_o_c_k _f_i_l_e_s _w_i_l_l _b_e _r_e_m_o_v_e_d _w_h_i_l_e _w_a_i_t_i_n_g _f_o_r _i_n_c_o_m_i_n_g _c_a_l_l_s (-s). _I_f _a _d_a_t_a _c_a_l_l _i_s _d_e_t_e_c_t_- _e_d, _t_h_e getty _p_r_o_g_r_a_m _w_i_l_l _b_e _r_u_n _t_o _i_n_i_t_i_a_l_i_z_e _t_h_e _t_e_r_m_i_n_a_l _d_r_i_v_e_r _a_n_d _s_t_a_r_t _a login(_1) _p_r_o_c_e_s_s. _R_e_c_e_i_v_e_d _f_a_x _f_i_l_e_s _w_i_l_l _b_e _s_t_o_r_e_d _u_s_i_n_g _n_a_m_e_s _l_i_k_e Dec02-12.32.33.001, _i_n _t_h_e /usr/spool/fax/incoming _d_i_r_e_c_t_o_r_y _a_n_d _t_h_e _l_o_g _f_i_l_e _w_i_l_l _b_e _a_p_- _p_e_n_d_e_d _t_o /usr/spool/fax/faxlog.cua1. _e_f_a_x -_d /_d_e_v/_c_u_a_1 -_o_r \ -_i '+_F_C_L_A_S_S=_2;+_F_C_R=_1;+_F_A_A=_1' \ -_x /_u_s_r/_s_p_o_o_l/_u_u_c_p/_L_C_K.._c_u_a_1 \ -_x /_u_s_r/_s_p_o_o_l/_u_u_c_p/_L_C_K.._t_t_y_S_1 \ -_g "_e_x_e_c /_s_b_i_n/_g_e_t_t_y -_h /_d_e_v/_c_u_a_1 %_d" \ -_i_S_0=_2 -_w -_s \ -_r "/_u_s_r/_s_p_o_o_l/_f_a_x/_i_n_c_o_m_i_n_g/%_b%_d-%_H.%_I.%_S" \ >> /_u_s_r/_s_p_o_o_l/_f_a_x/_f_a_x_l_o_g._c_u_a_1 _2>&_1 Note that adaptive answer of either type is unreliable. Some fax modems mistake the initial data-mode answering tones for a fax machine's answering (CED) tone. In some cases the duration of the initial data-mode answer (set by TO_DATAF in efax.c) may not be long enough for incoming data calls to be set up. In other cases it may be too long for incoming fax calls. If you need re- liable fax reception you should use a modem or other device that can detect incoming faxes using the fax calling (CNG) tones. 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 process ter- minates. The inittab or ttytab entry should invoke efax by run- ning the fax script with an answer argument. For example, placing the following line in /etc/inittab will make init run the fax script with argument answer every time previous process terminates (and init is in runlevel 4 or 5). s1:45:respawn:/bin/sh /usr/bin/fax answer In this case the fax script should be protected against tampering since init will execute it as a privileged (root) process. If you will also 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). Double check the configuration setup in the fax script. Run the "fax test" script and check that the modem is responding to commands. If efax hangs when trying to open the modem device (typically ttyX), the device is either already in use by another process (e.g. getty) 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 al- ready using it. If modem responses are being lost or generated at random, another processes (e.g. getty) may be trying to use the same device at the same time. Using lock files (-x options) can sometimes resolve this problem. Check the response to the "AT+FCLASS=?" command to make sure your modem supports the Class (1 or 2) that you have selected. Attempt to send a fax. Check that the modem starts making CNG tones (a 0.5 second tone every 3 seconds) as soon as it's fin- ished dialing. This shows the modem is in fax mode. You may need to enable the monitor speaker (add -iM2L3 to the INIT string) to monitor the phone line. Listen to the answering fax machine and check that it sends a 2 second beep (CED) followed by DIS HDLC frames (the "warbling" signal) every 3 seconds. If you hear a continuous signal instead (tones or noise), then you've connected to a data modem instead. Your modem should now send back a DCS frame followed by 1.5 seconds of training check data. If everything is OK, the receiv- ing end will send a CFR frame and your modem will start to send data. If you have a modem with a flow control (FC) LED, it should start to blink. When the transmission completes, check the message showing the line count and the average bit rate. Low line counts (under 1000 for letter size image) or the warning "fax output buffer overflow" indicate that the image format is probably incorrect. Possibly the bit order is reversed. If the average bit rate is much higher than the negotiated bit rate (e.g. 15000 bps for a 9600bps connection) then flow control was not active. This usually results in a garbled transmission. The receiving machine may reject the page, abort the call or hang up. An message appearing during the transmission means that the operating system was ignoring the modem's XON/XOFF charac- ters. This is sometimes caused by compiling efax with an out- of-date "termios.h" include file. Most modems enable XON/XOFF flow control when fax mode is en- abled. Check the output of the fax test command for the flow control settings in fax mode (typically &K4 or Q1). If they are incorrect you can use additional -i commands to enable flow con- trol after the +FCLASS= command. Check that the remote machine confirms reception with an +FTPS:1 response (Class 2) or an MCF frame (Class 1). The error message "abnormal call termination (code _n_n)" indicates that the modem detected an error (in Class 2 mode) and hung up. The modem's manual may give an explanation for the error number _n_n. Many companies advertise services that will fax back information on their products. These can be useful for testing fax recep- tion. Finally, don't play "option bingo," if you can't resolve the problem, save the output of the fax test command to a file (e.g. fax test >test.out) and send it along with the log of the failed session to the address below. If efax should display the message "can't happen (
)" please send a bug report to the author. Efax was written by Ed Casas. Please send comments or bug re- ports to edc@ee.ubc.ca. Please mention the operating system, the type of the modem used and include a copy of any relevant session logs. efax is copyright 1993, 1994 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. Class 1 operation may fail if the program can't respond within 55 milliseconds. May fail if multitasking delays cause the received data to over- flow the computer's serial device buffer or if an under-run of transmitted data exceeds 5 seconds. Does not handle 2-D coded images, documents with pages of mixed formats or procedure interrupts. Can't read TIFF-F files.