SENDFAX(1)SENDFAX(1)NAMEsendfax - submit a facsimile job for transmission
SYNOPSISsendfax [ options ] [ files... ]
DESCRIPTIONsendfax submits one or more facsimile transmission requests to a
HylaFAX facsimile server. sendfax may prompt the user for a password
and admin password depending on the invocation and server configura‐
tion. Requests are normally processed immediately, although they may
also be queued for transmission at a later time using a syntax identi‐
cal 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, sendfax will read data from the standard
input unless polling is requested. Cover pages are distinguished for
the purpose of generating ``continuation cover pages'' on the server;
these are makeup cover pages that are automatically 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 automati‐
cally converts ASCII-text, troff(1) output, Portable Document Format
(PDF), 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 fax‐
cover(1) program using information deduced by sendfax and by informa‐
tion 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 documents. 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 docu‐
ments, the poll request will take place after the documents are trans‐
mitted. 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 readability—only alphanumerics, ``+'' (for denoting a
country code), and ``#'' (for denoting a subaddress) are significant in
placing a call. Alphabetic 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 dis‐
tance calling in the United States) need not be included if an unam‐
biguous 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 waiting), 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 dialstring rules configured for use on the server;
c.f. hylafax-config(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 Leffler@+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 handling. 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 MH compression. 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 compression, if
possible. By default HylaFAX will use the optimal compres‐
sion scheme supported by the transmitting modem and receiv‐
ing facsimile device.
-3 Transmit facsimile documents using 2-D MMR compression, if
possible. By default HylaFAX will use the optimal compres‐
sion scheme supported by the transmitting modem and receiv‐
ing facsimile device.
-a time Schedule transmission up to one year in advance at the
indicated time. Time is specified in the format: ``HH:MM
[AM|PM] | now [+ N period | month DD | dayofweek ] [ @
timeofday ]´´ where month can be Jan(uary), Feb(ruary),
Mar(ch), Apr(il), May, Jun(e), Jul(y), Aug(ust), Sep(tem‐
ber), Oct(ober), Nov(ember), or Dec(ember); period can be
minute(s), hour(s), day(s), week(s), or month(s); dayofweek
can be Mon(day), Tue(sday), Wed(nesday), Thu(rsday),
Fri(day), Sat(urday), Sun(day); e.g. ``now + 30 minutes´´
to schedule transmission 30 minutes in the future. Trail‐
ing information in the time field (such as YYYY) is
ignored. By default, sendfax schedules facsimile for imme‐
diate delivery. Time should be given in the user's local
time. Conversely, the timeofday field restricts the job
from sending at various times relative to the server. The
syntax for timeofday is identical to the TimeOfDay syntax
found in hylafax-config(5F).
-A Archive the job on the server according to the bin/archive
script when the job is done.
-b speed Transmit facsimile documents using a signalling 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 possi‐
ble speed both devices support. 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, 14400, 16800, 19200, 21600, 24000,
26400, 28800, 31200, and 33600. 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 sig‐
nalling rate. Possible speeds are: 2400, 4800, 7200, 9600,
12000, 14400, 16800, 19200, 21600, 24000, 26400, 28800,
31200, and 33600. 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 support.
By default HylaFAX will use the fastest possible rate sup‐
ported by the transmitting modem and receiving facsimile
device (unless restricted by other server configuration);
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. For
Class 1/1.0 devices, if the specified speed is not greater
than 14400 then V.34 will not be attempted, and if the
specified speed is 9600 or 7200 then V.29 will be assumed
in lieu of V.17.
-c comments Pass comments to the faxcover(1) program for inclusion in
the comments field of any generated cover page.
-C file Pass file to the faxcover(1) program for use as the cover
page template.
-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 documents to a fac‐
simile machine at the indicated destination. If the desti‐
nation is of the form ``user@phone-number#subaddress'' then
any cover page will show user as the intended recipient,
and the remote system will be supplied the subaddress value
(i.e. for routing) provided that the sending modem and the
receiving system support it.
-E Disable use of the Error Correction Mode (ECM) when trans‐
mitting page data. Setting ECM to false will limit the max‐
imum speed to 14400 bps. By default HylaFAX will attempt
to use ECM when both the transmitting 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 transmission failures.
-e name Use name as the name value in the outbound call identifica‐
tion.
-f from Use from as the identity of the facsimile sender. Other‐
wise 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 identity may
be a full-blown ``From:'' line, e.g. e.g. ``Joe Blow
<joe@foo.com>'' and ``joe@foo.com (Joe Blow)'' are accept‐
able. 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 imple‐
mentation of an electronic mail to fax gateway.
-F format Use the specified format when imaging tag lines on outgoing
pages. Consult the description of the TagLineFormat param‐
eter in hylafax-config(5F) for an explanation of how to
construct a format string.
Note that many locales require that proper identification
appear on all transmitted facsimile; when using this facil‐
ity one should always include proper identification (e.g. a
phone number) in the imaged taglines.
-G Enable usage of any extended resolutions supported by the
receiver. -G supersedes the usage of any -l or -m options.
Beware that increased resolution will increase transmission
time.
-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 supplied, 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 avail‐
able modem.
-i identifier
Use the identifier string in any notification messages
instead of the usual job identifier number. This option is
useful for applications that cross reference notification
messages against job submissions.
-I time If a job must be requeued because of a communication fail‐
ure 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.
The time is specified using notation identical to the -a
option. Note that the time is relative to the time of the
initial time-to-send. The default kill time is ``now + 3
hours'' (three hours from the time the job is first pro‐
cessed). To retry for an hour, ``now +1 hour'' could be
used.
-l Transmit the facsimile at a vertical resolution of 98
lines/inch; otherwise known as low resolution.
-m Transmit the facsimile at a vertical resolution of 196
lines/inch; otherwise known as medium resolution or fine
mode.
-M mst Transmit facsimile documents using the specified 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 fac‐
simile device (unless restricted by other server configura‐
tion). This option is mostly useful for debugging.
-n Suppress the automatic generation of a cover page for sub‐
sequent 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 fac‐
simile has been delivered or requeued.
-o login Specify the fax owner login name, replacing any FAXUSER
environment variable that may be set for the same purpose.
If neither is specified, the user's current login name is
used. The login password may also be provided by separat‐
ing it from the owner login name with a colon, like
``owner:pass''.
-O option:value
Submit option with the indicated value as a job parameter
in the client-server protocol for the job. Multiple
instances of this command-line option may be used. The
following options are currently supported:
Option Value Type Description
ignoremodembusy boolean whether or not to ignore modem busy status (requires server configuration to allow)
nocountcover integer don't include this number of initial pages in the page counting
serverdocover boolean whether or not the server should generate the cover-page, if configured
skippages integer assume this number of pages in the first document have already been sent
skippedpages integer assume this number of pages in unsubmitted documents were previously sent
-p Poll each destination for any available documents. If a
poll request is made together with document transmission,
the poll operation is done after the documents are trans‐
mitted. 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 initial scheduling
priority. If a job's priority is greater than bulk faxes
then the job's priority is raised (numerically lowered) for
each failed attempt to transmit so that retransmit attempts
are done ahead of newly submitted jobs. In the case of
bulk faxes (numerically higher than 190), then the job's
priority is lowered (numerically raised) for each failed
attempt to transmit so that the whole of the bulk-queued
jobs will be attempted before any are retried. The prior‐
ity may also be specified as one of the following symbolic
names: default or normal (127), bulk or junk (191), low
(190), or high (63).
-R Enable notification by electronic mail when the facsimile
has been delivered and when it is requeued for retransmis‐
sion. 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 generated 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 symbol‐
ically using either the name or abbreviation 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 Ameri‐
can Letter), us-leg (American Legal), us-led (American
Ledger), us-exe (American Executive), jp-let (Japanese Let‐
ter), and jp-leg (Japanese Legal). Comparisons are case-
insensitive and any match of a substring of the full page-
size name is sufficient; e.g. ``legal'' would match ``Amer‐
ican Legal''.
Note that it may not be permissible to image into the full
page area; the guaranteed reproducible 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 supported 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 facsimile machine.
-S tsi Pass tsi to the server as the suggested sender identifica‐
tion to be used, for example, in tagline imaging and fax
protocol.
-t tries Make no more than tries attempts to send the facsimile. (A
try is a call in which carrier is established and the fac‐
simile protocol is commenced; this is contrasted with a
call attempt that might have failed because the line was
busy.) Without specifying a "tries" value to the server
HylaFAX will, with some exceptions, make an unlimited num‐
ber of attempts to completely send the facsimile before the
kill time expires. (The exceptions are that HylaFAX will
terminate a job if 3 consecutive attempts to send a partic‐
ular page fail, or if it appears the receiver is not a fac‐
simile machine.) Use ``-1'' to indicate that no tries
value should be specified to the server.
-T maxdials Make no more than maxdials calls in attempting to send the
facsimile. By default, HylaFAX will redial 12 times before
killing a job. Use ``-1'' to indicate that no maxdials
value should be specified to the server.
-U voice-no Pass voice-no to the faxcover(1) program as the sender's
voice number.
-u number Use number as the number value in the outbound call identi‐
fication and in tagline generation.
-V voice-no Pass voice-no to the faxcover(1) program as the destination
person's voice number.
-w Wait for the job to complete before ending the sendfax ses‐
sion. If this option is used, the sendfax process will not
terminate until the job is completed.
-W fax-no Pass fax-no to the faxcover(1) program as the sender's fax
number.
-x company Pass company to the faxcover(1) program as the destination
company name.
-X company Pass company to the faxcover(1) program as the sender's
company name.
-y location Pass location to the faxcover(1) program as the destination
company's location.
-Y location Pass location to the faxcover(1) program as the sender's
company location.
-z filename Read destinations from filename which contains a list of
the destinations formatted identically as destinations for
the -d option, one per line. Usage of this option is simi‐
lar to the -d option and may be done in conjunction with
other -d and -z options.
-v Print information on the standard output about each conver‐
sion 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 PARAMETERSsendfax reads configuration information from the files
/usr/share/fax/hfaxd.conf, /usr/share/fax/hyla.conf,
/usr/share/fax/sendfax.conf, and ~/.hylarc; in that order, with later-
read settings superseding any that may have been previously read. Con‐
figuration files follow the conventions described in hylafax-client(1).
The following configuration parameters are recognized. Parameters
marked with ¹ are not available in /usr/share/fax/hfaxd.conf :
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 to-company name string
Cover-Location¹ string - cover page to-company location string
Cover-Regarding string - cover page regarding string
Cover-Template string - cover page template filename
Cover-Voice¹ string - cover page to-voice number string
Cover-From-Company¹ string -cover page from-company string
Cover-From-Location¹ string -cover page from-location string
Cover-From-Voice¹ string -cover page from-voice number string
Cover-From-Fax¹ string - cover page from-fax number string
DateFormat string - cover page date format string
DesiredEC integer 2 desired type of ECM
DesiredMST string - desired minimum scanline 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
PassiveMode boolean false whether or not to use passive mode
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 configura‐
tion parameters, notably those for setting strings on automatically
generated cover pages, are defined mainly for use by other HylaFAX pro‐
grams 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/bin/faxcover.
Cover-Comments The comments string to pass to the cover sheet program
when auto-generating cover pages.
Cover-Company The to-company name string to pass to the cover sheet
program when auto-generating cover pages.
Cover-Location The to-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 to-voice number string to pass to the cover sheet
program when auto-generating cover pages.
Cover-From-Company
The from-company name string to pass to the cover sheet
program when auto-generating cover pages.
Cover-From-Location
The from-location string to pass to the cover sheet
program when auto-generating cover pages.
Cover-From-Voice
The from-voice number string to pass to the cover sheet
program when auto-generating cover pages.
Cover-From-Fax The from-fax 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-generating cover pages.
DesiredEC Which type of the optional Error Correct Mode (ECM) to
use when transmitting facsimile. 0 to disable, 1 for
64-byte ECM, and 2 for 256-byte ECM (default).
DesiredMST The desired minimum scanline time to use when transmit‐
ting facsimile. (Equivalent to the -M option.)
DesiredSpeed The desired signalling rate to the use when transmit‐
ting facsimile. (Equivalent to the -B option.)
DialRules The name of the file containing the dialstring process‐
ing rules to when preparing an externally visible rep‐
resentation of the dialstring (e.g. to strip credit
card numbers). By default this is /usr/share/fax/dial‐
rules.
From The sender's identity. (Equivalent to the -f option.)
Host The host to contact for service. (Equivalent to the -h
option.)
HRes The horizontal resolution to use when transmitting fac‐
simile. (NB: this currently 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 mes‐
sages from the server. If this string is specified
without an ``@hostname'' part then the local hostname
will automatically be appended. (Equivalent 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 sending a job.
(Equivalent to the -t option.)
MinSpeed The minimum acceptable signalling rate to use when
transmitting facsimile. (Equivalent to the -b option.)
Modem The modem to use on the server. (Equivalent 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 preced‐
ing ``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 transmitting 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 ChopThreshold parameter.
PageLength Set the transmitted page length in millimeters.
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 millimeters.
PassiveMode Whether or not to use passive mode in communication
with the server.
Port The network port to contact for service. (Equivalent
to the -h option.)
Priority The scheduling priority to assign to each job. (Equiv‐
alent to the -P option.)
Protocol The name of the communication protocol to use when con‐
tacting a server. (Equivalent to the FAXSERVICE envi‐
ronment variable.)
RetryTime The time to delay between job retries due to a communi‐
cation 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 fac‐
simile. (Equivalent to the -F option.)
TypeRules The name of the file containing file type conversion
rules. By default this is /usr/share/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; transmission aborted. No data was supplied (typically
on the standard input). No facsimile will be sent.
Error converting data; command was %s." A data conversion 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 process 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/share/fax/hyla.conf system-wide configuration file
/usr/share/fax/sendfax.conf system-wide configuration file
/usr/share/fax/typerules file type and conversion rules
/usr/share/fax/pagesizes page size database
/usr/share/fax/dialrules optional client dialstring rules
/usr/bin/faxcover for generating cover sheets
/usr/sbin/textfmt for converting text to PostScript
/usr/sbin/sgi2fax for converting SGI RGB images
/var/spool/fax/tmp/sndfaxXXXXXXtemporary files
SEE ALSOat(1), hylafax-client(1), faxalter(1), faxcover(1), faxmail(1),
faxrm(1), faxstat(1), sgi2fax(1), textfmt(1), hfaxd(8C), hylafax-
server(5F), typerules(5F)
January 06, 2001 SENDFAX(1)
