SENDFAX(1)
NAME
sendfax - submit a facsimile job for transmission
SYNOPSIS
sendfax [ options ] [ files... ]
DESCRIPTION
sendfax submits one or more facsimile transmission
requests to a HylaFAX facsimile server. Requests are nor-
mally processed immediately, although they may also be
queued for transmission at a later time using a syntax
identical to the at(1) command. For each job that is
queued, sendfax prints a job identifier and a job group
identifier on the standard output. A job identifier is
the token by which jobs are identified within HylaFAX; job
group identifiers are used to reference a set of jobs that
have been submitted at the same time. Job and job group
identifiers can be supplied to the faxrm(1) command to
remove the jobs or to the faxalter(1) command to alter job
parameters.
Facsimile are made from the concatenation of a cover page
(see below) and one or more files specified on the command
line. If no files are supplied on the command line, send-
fax will read data from the standard input unless polling
is requested. Cover pages are distinguished for the pur-
pose of generating ``continuation cover pages'' on the
server; these are makeup cover pages that are automati-
cally generated if a job fails after sending the original
user-specified cover page.
sendfax passes POSTSCRIPT and TIFF documents directly
through to the fax server for transmission, and attempts
to convert other file formats to either POSTSCRIPT or
TIFF. In normal operation sendfax automatically converts
ASCII-text, troff(1) output, and Silicon Graphics format
images for transmission. Support for other file formats
can be easily added through an extensible file typing and
conversion facility; see typerules(5F). Note that since
TIFF Class F documents are processed directly it is simple
to forward a received facsimile.
By default sendfax will generate a cover page for each
facsimile that is to be transmitted. This cover page is
created by the ancillary faxcover(1) program using infor-
mation deduced by sendfax and by information supplied on
the command line. Automatic cover page generation may be
suppressed with the -n option.
In addition to sending documents, sendfax can be used to
poll a remote facsimile machine to retrieve waiting docu-
ments. If the -p option is specified, a polling request
will be submitted to each destination. If a poll request
is made in conjunction with the transmission of documents,
the poll request will take place after the documents are
transmitted. Documents retrieved by polling are returned
to the requestor by electronic mail and may be viewed with
a suitable viewer program.
One or more destinations must be specified on the command
line using the -d option. A destination is the dialing
string to use to contact the remote fax machine. Phone
numbers may include non-alphanumeric characters for read-
ability--only alphanumerics and ``+'' (for denoting a
country code) are significant in placing a call. Alpha-
betic characters are automatically mapped to their numeric
key equivalents: ``abcABC'' to ``2'', ``defDEF'' to ``3'',
etc. Dialing prefixes, such as ``1'' and ``011'' (for
long distance calling in the United States) need not be
included if an unambigous number is specified. Examples
of unambiguous phone numbers are:
+31.77.594.131 to call the Netherlands
+14159657824 to call California
9657824 to make a local call
1-215-356-1666 to call Pennsylvania from within the US
Non-numeric strings, such as ``*70'' (to defeat call wait-
ing), may be included in the destination phone number.
Whether or not they are stripped from the string used to
dial the destination fax machine is dependent on the dial-
string rules configured for use on the server; c.f. con-
fig(5F) and dialrules(5F).
A destination may also be specified as user@fax-number.
In this case the user string will be passed to faxcover as
the identity of the recipient. Note that multi-word names
must be enclosed in quote marks; for example, ``Sam Lef-
fler@+1.415.555.1212''.
The order of options on the command line is significant.
Each fax to be transmitted is assigned the current value
of parameters specified on the command line; e.g. whether
or not to generate a cover page. This means that options
that specify parameters for a particular destination must
precede the dialstring specified with the -d option. For
example,
sendfax -n -d 5551212 /etc/passwd
submits a fax to 5551212 that has no cover page while
sendfax -d 5551212 -n /etc/passwd
submits the same fax but with the default cover page han-
dling. Note also that parameter values persist across -d
options so the following
sendfax -n -d 5551212 -d 5551313 /etc/network
submits two facsimile, both of which have no cover page.
OPTIONS
-1 Transmit facsimile documents using 1-D MR com-
pression. By default HylaFAX will use the
optimal compression scheme supported by the
transmitting modem and receiving facsimile
device.
-2 Transmit facsimile documents using 2-D MR com-
pression, if possible. By default HylaFAX
will use the optimal compression scheme sup-
ported by the transmitting modem and receiving
facsimile device.
-a time Schedule transmission at the indicated time.
Times are specified using the syntax of the
at(1) command; e.g. ``now + 30 minutes'' to
schedule transmission 30 minutes in the
future. By default, sendfax schedules facsim-
ile for ``now''.
-b speed Transmit facsimile documents using a sig-
nalling rate that is constrained to be at
least speed bits/second. If the specified
speed is greater than the transmitting modem
or receiver is capable of, it is reduced to
the highest possible speed both devices sup-
port. If a negotiated signalling rate greater
than or equal to speed cannot be negotiated
then the job is aborted. Possible speeds are:
2400, 4800, 7200, 9600, 12000, and 14400. By
default HylaFAX will use the fastest possible
rate supported by the transmitting modem and
receiving facsimile device.
-B speed Try to transmit facsimile documents using the
desired signalling rate. Possible speeds are:
2400, 4800, 7200, 9600, 12000, and 14400. If
the specified speed is greater than the trans-
mitting modem or receiver is capable of, it is
reduced to the highest possible speed both
devices support. By default HylaFAX will use
the fastest possible rate supported by the
transmitting modem and receiving facsimile
device (unless restricted by other server con-
figuration); this option can be used to reduce
the speed. Note that international calls are
frequently more reliable when transmissions
are restricted to 9600 bits/second.
-c comments Pass comments to the faxcover(1) program for
inclusion in the comments field of any gener-
ated cover page.
-D Enable notification by electronic mail when
the facsimile has been delivered. By default
HylaFAX will notify the submitter only if
there is a problem with a job.
-d destination
Create a job to transmit the supplied docu-
ments to a facsimile machine at the indicated
destination. If the destination is of the
form ``user@phone-number'' then any cover page
will show user as the intended receipient.
-E Disable use of the Error Correction Mode (ECM)
when transmitting page data. By default
HylaFAX will attempt to use ECM when both the
trasmitting modem and receiving device support
it. Note that international calls are some-
times faster when ECM is disabled. Beware
also that some modems and/or facsimile devices
do not properly implement ECM causing trans-
mission failures.
-f from Use from as the identity of the facsimile
sender. Otherwise the sender is the user that
invoked sendfax. The sender is an account
name to which the HylaFAX software should
direct notification messages. The from iden-
tity may be a fullblown ``From:'' line, e.g.
e.g. ``Joe Blow lt;joe@foo.com'' and
``joe@foo.com (Joe Blow)'' are acceptable. If
no host-part is specified in the from string
the local hostname is used. This option is
useful when sendfax is invoked on behalf of
another user, such as in the implementation of
an electronic mail to fax gateway.
-F format Use the specified format when imaging tag
lines on outgoing pages. Consult the descrip-
tion of the TagLineFormat parameter in con-
fig(5F) for an explanation of how to construct
a format string.
Note that many locales require that proper
identification appear on all transmitted fac-
simile; when using this facility one should
always include proper identification (e.g. a
phone number) in the imaged taglines.
-h [modem@]host[:port]
Force the jobs to be processed on a specific
host and, optionally, using a particular
modem. The host may be either a symbolic name
or a network address. If no -h option is sup-
plied, sendfax uses the FAXSERVER environment
variable to identify the HylaFAX server to
which the jobs should be directed. If no
server is specified then sendfax attempts to
contact a server on the local host. If no
modem is specified, the job will be submitted
to any available modem.
-i identifier
Use the identifier string in any notification
messages instead of the usual job identifier
number. This option is useful for applica-
tions that cross reference notification mes-
sages against job submissions.
-I time If a job must be requeued because of a commu-
nication failure schedule the retry according
to the specified time. Times are given in
seconds. Minutes, hours, and days can be
specified with ``min'', ``hour'', and ``day''
suffixes, respectively. By default HylaFAX
reschedules jobs using retry times that depend
on the manner in which the job failed; this
interface permits a user to override this
algorithm and specify a single fixed retry
time for all communication failures.
-k time Kill the job if it does not complete in the
indicated time. As for the -a option, the
time is specifed using notation compatible
with at(1). Note that the time is relative to
the time of the initial transmission attempt.
The default kill time is ``now +1 day'' (one
day from the time the job is first processed).
To retry for an hour, ``now +1 hour'' could be
used.
-l Transmit the facsimile at a vertical resolu-
tion of 98 lines/inch; otherwise known as low
resolution.
-m Transmit the facsimile at a vertical resolu-
tion of 196 lines/inch; otherwise known as
medium resolution or fine mode.
-M mst Transmit facsimile documents using the speci-
fied minimum scanline time. Possible times
are: 0ms, 5ms, 10ms2, 10ms, 20ms2, 20ms,
40ms2, and 40ms. If the specified time is
less than the transmitting modem or receiver
is capable of, it is increased to the lowest
possible time both devices support. By
default HylaFAX will use the lowest possible
time supported by the transmitting modem and
receiving facsimile device (unless restricted
by other server configuration). This option
is mostly useful for debugging.
-n Suppress the automatic generation of a cover
page for subsequent facsimile. Note that
polling requests do not receive a cover page
unless they are combined with the transmission
of one or more files.
-N Do not notify the sender by electronic mail
when the facsimile has been delivered or
requeued.
-p Poll each destination for any available docu-
ments. If a poll request is made together
with document transmission, the poll operation
is done after the documents are transmitted.
Documents received by polling are returned to
the sender by electronic mail.
-P priority Assign the specified scheduling priority to
subsequent jobs. A priority is an integer
value in the range [0-255]. Lower values
result in higher priority processing. By
default, each job is assigned 127 for an ini-
tial scheduling priority. A job's priority is
raised (numerically lowered) for each failed
attempt to transmit so that retransmit
attempts are done ahead of newly submitted
jobs. The priority may also be specified as
one of the following symbolic names: default
or normal (127), bulk or junk (207), high
(63).
-R Enable notification by electronic mail when
the facsimile has been delivered and when it
is requeued for retransmission. By default
HylaFAX will notify the submitter only if
there is a problem with a job.
-r regarding
Pass regarding to the faxcover(1) program as
the value of the ``Re:'' field of any gener-
ated cover page.
-s size Set the page size to use for the transmitted
facsimile. Facsimile are normally imaged with
a system-default page size (usually letter-
size pages, 8.5" by 11", for sites in North
America). Alternate page sizes are specified
symbolically using either the name or abbrevi-
ation of an entry in the pagesizes(5F)
database; e.g. a3 (ISO A3), a4 (ISO A4), a5
(ISO A5), a6 (ISO A6), b4 (ISO B4), na-let
(North American Letter), us-leg (American
Legal), us-led (American Ledger), us-exe
(American Executive), jp-let (Japanese Let-
ter), and jp-leg (Japanese Legal). Compar-
isons are case-insensitive and any match of a
substring of the full page-size name is suffi-
cient; e.g. ``legal'' would match ``American
Legal''.
Note that it may not be permissible to image
into the full page area; the guaranteed repro-
ducible area for a page is typically inset.
Also, note that while arbitrary page sizes can
be specified through the page size database,
only a limited set of page dimensions are sup-
ported by the Group 3 facsimile protocol.
Thus if an odd-size facsimile is submitted for
transmission it may not be possible to deter-
mine if it can be sent until the fax server
establishes communication with the remote fac-
simile machine.
-t tries Make no more than tries attempts to send the
facsimile. By default, HylaFAX will terminate
a job if: 3 consecutive attempts to send a
particular page fail, or it appears the
receiver is not a facsimile machine. Other-
wise HylaFAX places no limit on the number of
attempts to send a facsimile, instead termi-
nating a job if it is not completed within a
kill time timeout interval. Note that a try
is a call in which carrier is established and
the facsimile protocol is commenced; this is
contrasted with a call attempt that might have
failed because the line was busy.
-x company Pass company to the faxcover(1) program as the
destination company name.
-y location Pass location to the faxcover(1) program as
the destination company's location.
-v Print information on the standard output about
each conversion and cover sheet generation
operation it does. If -v is specified twice,
the protocol between sendfax and the hfaxd
server process that does the submission work
on the remote machine is also displayed.
CONFIGURATION PARAMETERS
sendfax reads configuration information from the files
/usr/local/lib/fax/hyla.conf, /usr/local/lib/fax/send-
fax.conf, and ~/.hylarc; in that order. Configuration
files follow the conventions described in hylafax(1). The
following configuration parameters are recognized:
Tag Type Default Description
AutoCoverPage boolean Yes automatically generate cover page
ChopThreshold float 3.0 page chopping threshold
CoverCmd string see below pathname of cover sheet program
Cover-Comments string - cover page comments string
Cover-Company string - cover page company name string
Cover-Location string - cover page company location string
Cover-Regarding string - cover page regarding string
Cover-Template string - cover page template filename
Cover-Voice string - cover page voice number string
DateFormat string - cover page date format string
DesiredEC boolean - desired use of ECM
DesiredMST string - desired minimum scanling time to use
DesiredSpeed integer - desired signalling rate to use
DialRules string see below file containing dialstring rules
From string - sender's identity
HRes float 204. horizontal resolution
Host string localhost host to contact for service
KillTime string - time to expire job
MailAddr string - mail address for notification messages
MaxDials integer 12 times to retry dialing
MaxTries integer 3 times to retry transmission
MinSpeed integer - minimum acceptable signalling rate
Modem string - modem to use on server
Notify string none control email notification
PageChop string default control page chop handling
PageLength float - page length in millimeters
PageSize string default page size by name
PageWidth float - page width in millimeters
Port integer 4559 port to use in contacting server
Priority string default job scheduling priority
Protocol string tcp protocol to use in contacting server
RetryTime string - delay between failed attempts to send
SendTime string - time to send job
TagLine string - tagline format string
TypeRules string see below file containing file typing rules
VRes float 98. vertical resolution
Verbose boolean No whether or not to enable protocol tracing
The configuration parameters are explained below. Certain
configuration parameters, notably those for setting
strings on automatically generated cover pages, are
defined mainly for use by other HylaFAX programs that
share common code used by sendfax.
AutoCoverPage Control whether or not a cover page is
automatically generated for each job.
(Equivalent to the -n option.)
ChopThreshold The amount of white space, in inches, that
must be present at the bottom of a page
before HylaFAX will attempt to truncate
the page transmission.
CoverCmd The absolute pathname of the program to
use to generate cover pages. The default
cover sheet program is /usr/local/bin/fax-
cover.
Cover-Comments The comments string to pass to the cover
sheet program when auto-generating cover
pages.
Cover-Company The company name string to pass to the
cover sheet program when auto-generating
cover pages.
Cover-Location The company location string to pass to the
cover sheet program when auto-generating
cover pages.
Cover-Regarding The regarding string to pass to the cover
sheet program when auto-generating cover
pages.
Cover-Template The absolute pathname of a cover sheet
template file to use in auto-generating
cover pages.
Cover-Voice The voice number string to pass to the
cover sheet program when auto-generating
cover pages.
DateFormat The strftime(3) format string to pass to
the cover page command when auto-generat-
ing cover pages.
DesiredEC Whether or not to request the use of the
optional Error Correct Mode (ECM) when
transmitting facsimile. (Equivalent to
the -E option.)
DesiredMST The desired minimum scanline time to use
when transmitting facsimile. (Equivalent
to the -M option.)
DesiredSpeed The desired signalling rate to the use
when transmitting facsimile. (Equivalent
to the -B option.)
DialRules The name of the file containing the dial-
string processing rules to when preparing
an externally visible representation of
the dialstring (e.g. to strip credit card
numbers). By default this is
/usr/local/lib/fax/dialrules.
From The sender's identity. (Equivalent to the
-f option.)
Host The host to contact for service. (Equiva-
lent to the -h option.)
HRes The horizontal resolution to use when
transmitting facsimile. (NB: this cur-
rently has no effect.)
KillTime The expiration time to assign to each job.
(Equivalent to the -k option.)
MailAddr The electronic mail address to direct
notification messages from the server. If
this string is specified without an
``@hostname'' part then the local hostname
will automatically be appended. (Equiva-
lent to the -f option.)
MaxDials The maximum number of times to dial the
phone for each job. (Equivalent to the -T
option.)
MaxTries The maximum number of times to retry send-
ing a job. (Equivalent to the -t option.)
MinSpeed The minimum acceptable signalling rate to
use when transmitting facsimile. (Equiva-
lent to the -b option.)
Modem The modem to use on the server. (Equiva-
lent to the -h option.)
Notify Control the email notification messages
from the server. This string may be one
of ``done'', ``none'', ``requeued'' or
``default'' with an optionally preceding
``when '' (e.g. ``when done''). Note that
``when requeued'' implies ``when done''.
(Equivalent to the -D, -R, and -N
options.)
PageChop Control page chop handling when transmit-
ting facsimile. This string may be one of
``none'', ``all'', or ``last' to have no
pages chopped, all pages chopped, or only
the last page chopped; respectively. Page
chopping is controlled by the ChopThresh-
old parameter.
PageLength Set the transmitted page length in mil-
limeters.
PageSize Set the page dimensions according to an
entry in the pagesizes(5F) database.
(Equivalent to the -s option.)
PageWidth Set the transmitted page width in millime-
ters.
Port The network port to contact for service.
(Eqvuialent to the -h option.)
Priority The scheduling priority to assign to each
job. (Equivalent to the -P option.)
Protocol The name of the communication protocol to
use when contacting a server. (Equivalent
to the FAXSERVICE environment variable.)
RetryTime The time to delay between job retries due
to a communication failure. (Equivalent
to the -I option.)
SendTime The time to send jobs. (Equivalent to the
-a option.)
TagLine The tagline format string to use when
transmitting facsimile. (Equivalent to
the -F option.)
TypeRules The name of the file containing file type
conversion rules. By default this is
/usr/local/lib/fax/typerules.
Verbose Control protocol tracing. (Equivalent to
the -vv option.)
VRes Set the vertical resolution in lines/inch
to use when transmitting facsimile.
(Equivalent to the -m and -l options.)
DIAGNOSTICS
The following messages are generated because of problems
encountered on the local machine.
Could not call server. The facsimile server on the remote
machine did not respond.
No input data; tranmission aborted. No data was supplied
(typically on the standard input). No facsimile will be
sent.
Error converting data; command was %s." A data conver-
sion operation failed; the shell command that was used is
printed.
Can not convert %s. Data needed to be converted for
transmission, but the required conversion rule was not
located. This may indicate that the HylaFAX software was
incorrectly installed; or perhaps that an NFS-mounted
directory is temporarily unavailable.
%s: Can not determine file type. sendfax was unable to
deduce the type of the file.
%s: Not a regular file. The file is something other than
a regular file; for example, a directory.
The following messages may be printed by sendfax. These
messages describe problems encountered by the server pro-
cess on the remote machine. This list is incomplete;
other messages may be generated by the server under
unusual circumstances.
FILES
~/.hylarc per-user configuration file
/usr/local/lib/fax/hyla.conf system-wide configuration file
/usr/local/lib/fax/sendfax.conf system-wide configuration file
/usr/local/lib/fax/typerules file type and conversion rules
/usr/local/lib/fax/pagesizes page size database
/usr/local/lib/fax/dialrules optional client dialstring rules
/usr/local/bin/faxcover for generating cover sheets
/usr/local/sbin/textfmt for converting text to PostScript
/usr/local/sbin/sgi2fax for converting SGI RGB images
/usr/tmp/sndfaxXXXXXX temporary files
SEE ALSO
at(1) hylafax(1) faxalter(1) faxcover(1) faxmail(1)
faxrm(1) faxstat(1) sgi2fax(1) textfmt(1) hfaxd(8C)
hylafax(5F) typerules(5F)