Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HYLAFAX-CLIENT(1)	    General Commands Manual	     HYLAFAX-CLIENT(1)

       HylaFAX-client -	introduction to	HylaFAX	client applications and	usage

       sendfax [options] [files...]
       sendpage	[options] [message...]
       faxstat [options]
       faxrm [options]
       faxalter	[options] jobid...
       fax2ps [options]	[files...]

       HylaFAX	is  a telecommunication	system for UNIX(R) systems.  Among the
       features	of HylaFAX are:

       o  HylaFAX runs as a network service; this means	a modem	may be	effec-
	  tively shared	by a large number of users.

       o  HylaFAX can be configured to work with a wide	variety	of modems on a
	  wide variety of systems.

       o  Access to the	system can be restricted by the	administrator  to  se-
	  lected hosts and/or users.

       o  Transmission	requests  may  be  processed  immediately (default) or
	  queued for processing	at a later time, in the	manner	of  the	 at(1)

       o  Remote  facsimile machines may be polled to retrieve publicly	avail-
	  able documents.

       o  POSTSCRIPT(R), PDF, and TIFF Class F documents are  passed  directly
	  to  the  fax server for transmission;	the system attempts to convert
	  other	file formats to	either POSTSCRIPT or TIFF through the  use  of
	  an extensible	file typing and	conversion facility.  In normal	opera-
	  tion ASCII-text, troff(1) output, and	Silicon	 Graphics  images  are
	  automatically	 converted.  Additional	file formats can be added; see

       o  The faxcover(1) program can be automatically	invoked	 to  create  a
	  cover	 page  for  each  facsimile,  using information	deduced	by the
	  sendfax command.  Alternatively, users may supply  their  own	 cover
	  pages	using their preferred tools.

       o  Facsimile are	normally imaged	in a system-default page size (usually
	  letter-size pages, 8.5" by 11", for sites in North America).	Alter-
	  nate	page  sizes  can  be specified with a -s option	to all HylaFAX
	  programs.  Well known	page sizes include: ISO	A3, ISO	 A4,  ISO  A5,
	  ISO  A6,  ISO	 B4,  North  American Letter, American Legal, American
	  Ledger, American Executive, Japanese	Letter,	 and  Japanese	Legal.
	  Note	that  it  may  not  be permissible to image into the full page
	  area;	the guaranteed reproducible  area  for	a  page	 is  typically
	  smaller.   Also,  note that while arbitrary page sizes can be	speci-
	  fied,	only a limited number of page dimensions are supported by  the
	  facsimile  protocol.	Thus if	an odd-size facsimile is submitted for
	  transmission it may not be possible to determine if it can  be  sent
	  until	 the fax server	establishes communication with the remote fac-
	  simile machine.

       o  Facsimile can	be sent	at low resolution (98  lines/inch)  or	medium
	  resolution (196 lines/inch)--often called fine mode.	Documents with
	  mixed	resolution pages are handled correctly.

       o  Users	are notified by	electronic mail	if a job can not be  transmit-
	  ted.	It is also possible to receive notification by mail when a job
	  has been completed successfully and each time	that the  job  is  re-
	  queued for retransmission.  Any untransmitted	documents are returned
	  to the sender	by electronic mail in a	form  suitable	for  resubmis-

       o  Support  is provided for broadcasting	facsimile.  The	HylaFAX	server
	  software optimizes preparation of broadcast documents	and the	client
	  applications support the notion of a job group which permits a group
	  of jobs to be	manipulated together.

       o  Support is provided for transmitting alpha-numeric messages to pager
	  devices  or  GSM  mobiles  using  the	Simple Network Paging Protocol
	  (SNPP) and the IXO or	UCP protocol (for message delivery).

       The HylaFAX software is divided into two	 packages:  software  used  on
       client  machines	and software used on machines where one	or more	modems
       reside.	Client software	includes:

       o  sendfax, a program to	submit outgoing	facsimile;

       o  sendpage,  a	program	 to  submit  alpha-numeric  messages  to  SNPP

       o  faxstat, a program obtain status information about HylaFAX servers;

       o  faxrm, a program to remove jobs and documents;

       o  faxalter, a program to change	parameters of queued jobs; and

       o  fax2ps, a program that converts facsimile documents to POSTSCRIPT so
	  that they may	be viewed with a POSTSCRIPT previewer or printed on  a
	  POSTSCRIPT  printer  (this program is	actually part of the companion
	  TIFF distribution that is used by HylaFAX).

       Many systems also support submission of	outgoing  facsimile  by	 elec-
       tronic  mail  and/or graphical interfaces to the	sendfax	program.  Such
       facilities are site-dependent; consult local documentation for more in-

       To  use	the HylaFAX client software on your machine you	need to	either
       load the	appropriate software on	your machine, or you need to locate  a
       machine	that  already has the client software installed	and setup sym-
       bolic links to the appropriate directories.  If you choose the  latter,
       then  beware  that  you	need links to three directories: the directory
       where client applications reside, /usr/local/bin, the  directory	 where
       the  client  application	database files reside, /usr/local/lib/fax, and
       the directory  where  document  conversion  programs  reside,  /usr/lo-
       cal/sbin	(the last two directories may be the same on your system).

       Once  the  software  is setup on	your machine you need to locate	a host
       that has	a facsimile server that	you can	use.  The host,	 and  possibly
       the  modem  on  the  host, should be defined in your environment	in the
       FAXSERVER variable.  For	example, for csh users,

	      setenv FAXSERVER flake.asd

       or for ksh or sh	users,

	      FAXSERVER=flake.asd; export FAXSERVER

       If there	are multiple modems on your server then	you may	be assigned to
       use  a  specific	 modem.	  For example, if you are to use the modem at-
       tached to the ttym2 port	on the	server	machine,  then	the  FAXSERVER
       variable	should be setup	as

	      FAXSERVER=ttym2@flake.asd; export	FAXSERVER

       (Note: the SNPPSERVER environment variable is used instead of FAXSERVER
       by the sendpage program;	 consult sendpage(8C) for more information.)

       Note also, that before you can submit outgoing facsimile	jobs  the  ad-
       ministrator for the facsimile server may	need to	register your identity
       in an access control list.  You will encounter the message  ``530  User
       %s access denied.''  if access to your server is	controlled and you are
       not properly registered or you may be prompted for a password and  then
       denied service with ``530 Login incorrect.''.

       A  dial	string specifies how to	dial the telephone in order to reach a
       destination facsimile machine.  HylaFAX permits arbitrary strings to be
       passed  to  the	facsimile server so that users can specify credit card
       information, PBX	routing	information, etc.  Alphabetic  characters  are
       automatically  mapped to	their numeric key equivalents (e.g. ``1800Got-
       Milk'' becomes ``18004686455'').	 Other characters can be included  for
       readability;  anything  that  must  be  stripped	will be	removed	by the
       server before the dialing string	is passed to the fax  modem.   Private
       information  such  as credit card access	codes are withheld from	status
       messages	and publicly accessible	log files (with	proper configuration).
       Facsimile servers also automatically insert any leading dialing prefix-
       ing strings that	are required to	place outgoing phone calls; e.g. dial-
       ing  ``9''  to get an outside line.  Additionally, if a phone number is
       fully specified with the	international direct  dialing  digits  (IDDD),
       then  any  prefixing  long distance or international dialing codes that
       are required to place the call will be inserted in the dial  string  by
       the  server.   For example, ``+31.77.594.131'' is a phone number	in the
       Netherlands; it would be	converted to ``0113177594131'' if the call  is
       placed  in  the	United States.	The number ``+14159657824'' is a phone
       number in California; if	this number is called from within the 415 area
       code  in	the United States, then	the server would automatically convert
       this to ``9657824'' because in the San Francisco	Bay Area, local	 phone
       calls must not include the area code and	long distance prefixing	code.

       The  general  rule  in crafting dial strings is to specify exactly what
       you would dial on your telephone; and, in addition,  the	 actual	 phone
       number  can  be specified in a location-independent manner by using the
       IDD syntax of ``+country-code local-part''.

       The sendfax program can automatically generate a	cover  page  for  each
       outgoing	 facsimile.  Such cover	pages are actually created by the fax-
       cover(1)	program	by using information that is deduced  by  sendfax  and
       information that	is supplied on the command line	invocation of sendfax.
       Users may also request that sendfax not supply a	cover  page  and  then
       provide	their  own cover page as part of the data that is to be	trans-

       Automatically-generated cover pages may include the following  informa-

       o  the sender's name, affiliation, geographic location, fax number, and
	  voice	telephone number;

       o  the recipient's name,	affiliation, geographic	location, fax  number,
	  and voice telephone number;

       o  text explaining what this fax	is ``regarding'';

       o  text commentary;

       o  the local date and time that the job was submitted;

       o  the number of	pages to be transmitted.

       Certain	of  this  information is currently obtained from a user's per-
       sonal facsimile database	file; ~/.faxdb.	 Note that this	file is	depre-
       cated; it is described here only	because	it is still supported for com-
       patibility with older versions of the software.

       The .faxdb file is an ASCII file	with entries of	the form

	      keyword :	value

       where keyword includes:

	      Name	    a name associated with destination fax machine;

	      Company	    a company name;

	      Location	    in-company locational information, e.g.  a	build-

	      FAX-Number    phone number of fax	machine;

	      Voice-Number  voice telephone number.

       Data  is	 free  format.	Whitespace (blank, tab,	newline) can be	freely
       interspersed with tokens.  If tokens include whitespace,	they  must  be
       enclosed	in quote marks (``"'').	 The ``#'' character introduces	a com-
       ment--everything	to the end of the line is discarded.

       Entries are collected into  aggregate  records  by  enclosing  them  in
       ``[]''.	Records	can be nested to create	a hierarchy that that supports
       the inheritance of information--unspecified  information	 is  inherited
       from parent aggregate records.

       For example, a sample file might	be:
	      [	  Company:   "Silicon Graphics,	Inc."
		  Location:  "Mountain View, California"
		  [ Name: "Sam Leffler"	    FAX-Number:	+1.415.965.7824	]

       which  could  be	extended to include another person at Silicon Graphics
       with the	following:
	      [	  Company:   "Silicon Graphics,	Inc."
		  Location:  "Mountain View, California"
		  [ Name: "Sam Leffler"	    FAX-Number:	+1.415.965.7824	]
		  [ Name: "Paul	Haeberli"   FAX-Number:	+1.415.965.7824	]

       Experience indicates that the hierarchical nature of this database for-
       mat makes it difficult to maintain with automated mechanisms.  As a re-
       sult it is being	replaced by other, more	straightforward	databases that
       are managed by programs that front-end the sendfax program.

       HylaFAX	client applications can	be tailored on a per-user and per-site
       basis through configuration files.  Per-site controls are placed	in the
       file /usr/local/lib/fax/hyla.conf, while	per-user controls go in	~/.hy-
       larc.  In addition a few	programs that have many	 parameters  that  are
       specific	 to  their operation support an	additional configuration file;
       these files are identified in their manual pages.

       Configuration files have	a simple format	and  are  entirely  ASCII.   A
       configuration parameter is of the form
	    tag: value
       where a tag identifies a	parameter and a	value is either	a string, num-
       ber, or boolean value.  Comments	are introduced by the ``#''  character
       and  extend  to	the end	of the line.  String values start at the first
       non-blank character after the ``:'' and	continue  to  the  first  non-
       whitespace  character  or,  if whitespace is to be included, may	be en-
       closed in quote marks (``"'').  String values enclosed in  quote	 marks
       may  also use the standard C programming	conventions for	specifying es-
       cape codes; e.g.	``\n'' for a newline character and ``\xxx'' for	an oc-
       tal value.  Numeric values are specified	according to the C programming
       conventions (leading ``0x'' for hex, leading ``0'' for octal, otherwise
       decimal).   Boolean values are case insensitive.	 For a true value, ei-
       ther ``Yes'' or ``On'' should be	used.  For a false value,  use	``No''
       or ``Off''.

       Incoming	facsimile are received by facsimile servers and	deposited in a
       receive queue directory	on  the	 server	 machine.   Depending  on  the
       server's	configuration, files in	this directory may or may not be read-
       able by normal users.  The faxstat program can be used to view the con-
       tents of	the receive queue directory:
	      hyla% faxstat -r
	      HylaFAX scheduler	on Running
	      Modem ttyf2 (+1 510 999-0123): Running and idle

	      Protect Page  Owner	 Sender/TSI  Recvd@ Filename
	      -rw-r--	 9  fax	      1	510 5268781 05Jan96 fax00005.tif
	      -rw-r--	 8  fax	      1	510 5268781 07Jan96 fax00009.tif
	      -rw-r--	 2  fax	      1	510 5268781 07Jan96 fax00010.tif
	      -rw-r--	 3  fax	       +14159657824 08Jan96 fax00011.tif
	      -rw-r--	 2  fax	       +14159657824 08Jan96 fax00012.tif

       Consult the faxstat manual page for a more detailed description of this

       Received	facsimile are stored as	TIFF Class F files.  These  files  are
       bilevel images that are encoded using the CCITT T.4 or CCITT T.6	encod-
       ing algorithms.	The fax2ps(1) program can be used to  view  and	 print
       these  files.   A file can be viewed by converting it to	POSTSCRIPT and
       then viewing it with a suitable POSTSCRIPT previewing program, such  as
       xpsview(1)  (Adobe's  Display POSTSCRIPT-based viewer), ghostview(1) (a
       public domain previewer), or image viewer programs such	as  viewfax(1)
       (public	domain),  faxview(1)  (another	public domain TIFF viewer pro-
       gram), xv(1) (shareware and/or public domain), or xtiff(1)  (a  program
       included	 in  the  public  domain TIFF software distribution).  Consult
       your local resources to figure out what tools are available for viewing
       and printing received facsimile.

       HylaFAX	client	applications  communicate  with	servers	using either a
       special-purpose communications protocol that is modeled after  the  In-
       ternet  File  Transfer Protocol (FTP) or, when submitting alpha-numeric
       pages, the Simple Network Paging	 Protocol  (SNPP),  specified  in  RFC
       1861.   All client programs support a -v	option that can	be used	to ob-
       serve the protocol message exchanges.  In some  situations  it  may  be
       more  effective to communicate directly with a HylaFAX server using the
       client-server protocol.	This can be accomplished with an FTP or	Telnet
       client  application; though an FTP client is recommended	because	it im-
       plements	the protocol needed to obtain server status information.   For
       information  on	the  server-side support provided with HylaFAX consult
       hfaxd(8C).  For documentation on	the client-server fax protocol consult
       RFC XXXX	(to be filled in).

       This  section gives several examples of command line usage; consult the
       manual pages for	the individual commands	for information	on the options
       and program operation.

       The  following command queues the file for transmission to John
       Doe at the number (123)456-7890 using fine mode;	the  server  will  at-
       tempt to	send it	at 4:30	A.M.:
	      sendfax -a "0430"	-m -d "John Doe@1.123.456.7890"
       (the leading ``1.'' is supplied to dial area code ``123'' in the	United

       The following command generates a one-page facsimile  that  is  just  a
       cover page:
	      faxcover -t "John	Doe" -n	"(123)456-7890"
		  -c "Sorry John, I forgot the meeting..." |
		  sendfax -n -d	"(123)456-7890"
       (note  that the line was	broken into several lines solely for presenta-

       The following command displays the status of the	facsimile  server  and
       any jobs	queued for transmission:
	      faxstat -s

       The  following  command displays	the status of the facsimile server and
       any documents waiting in	the receive queue on the server	machine:
	      faxstat -r

       The following command shows how to use an FTP client program to	commu-
       nicate directly with a HylaFAX server:
	      hyla% ftp	localhost hylafax
	      Connected	to localhost.
	      220 server (HylaFAX (tm) Version 4.0beta005) ready.
	      Name (localhost:sam):
	      230 User sam logged in.
	      Remote system type is UNIX.
	      Using binary mode	to transfer files.
	      ftp> dir sendq
	      200 PORT command successful.
	      150 Opening new data connection for "sendq".
	      208  126 S    sam	5268781	      0:3   1:12   16:54 No local dialtone
	      226 Transfer complete.
	      ftp> quote jkill 208
	      200 Job 208 killed.
	      ftp> dir doneq
	      200 PORT command successful.
	      150 Opening new data connection for "doneq".
	      208  126 D    sam	5268781	      0:3   1:12	 No local dialtone
	      226 Transfer complete.
	      ftp> quote jdele 208
	      200 Job 208 deleted; current job:	(default).
	      ftp> dir docq
	      200 PORT command successful.
	      150 Opening new data connection for "docq".
	      -rw----	1      sam    11093 Jan	21 16:48
	      226 Transfer complete.
	      ftp> dele	docq/
	      250 DELE command successful.
	      ftp> dir recvq
	      200 PORT command successful.
	      150 Opening new data connection for "recvq".
	      -rw-r--	 4  fax	      1	510 5268781 30Sep95 faxAAAa006uh
	      -rw-r--	 9  fax	       +14159657824 11Nov95 faxAAAa006nC
	      -rw----	25  fax	       +14159657824 Fri08PM fax00016.tif
	      226 Transfer complete.
	      ftp> quit
	      221 Goodbye.

       The  following command shows how	to use a Telnet	client program to com-
       municate	directly with an SNPP server:
	      hyla% telnet melange.esd 444
	      Connected	to
	      Escape character is '^]'.
	      220 SNPP server (HylaFAX (tm)	Version	4.0beta010) ready.
	      login sam
	      230 User sam logged in.
	      214 The following	commands are recognized	(* =>'s	unimplemented).
	      214 2WAY*	  ALER*	  DATA	  HOLD	  LOGI	  MSTA*	  PING	  RTYP*	  STAT
	      214 ABOR	  CALL*	  EXPT*	  KTAG*	  MCRE*	  NOQU*	  QUIT	  SEND	  SUBJ
	      214 ACKR*	  COVE*	  HELP	  LEVE	  MESS	  PAGE	  RESE	  SITE
	      250 Direct comments to
	      page 5551212
	      250 Pager	ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
	      250 Message processing completed.
	      221 Goodbye.
	      Connection closed	by foreign host.

       /usr/local/bin/sendfax		     for sending facsimile
       /usr/local/bin/sendpage		     for sending alpha-numeric pages
       /usr/local/bin/fax2ps		     for converting facsimile to POSTSCRIPT
       /usr/local/bin/faxalter		     for altering queued jobs
       /usr/local/bin/faxcover		     for generating cover sheets
       /usr/local/bin/faxmail		     for converting email to POSTSCRIPT
       /usr/local/bin/faxrm		     for removing queued jobs
       /usr/local/bin/faxstat		     for facsimile server status
       /usr/local/sbin/sgi2fax		     SGI image file converter
       /usr/local/sbin/textfmt		     ASCII text	converter
       /usr/local/lib/fax/typerules	     file type and conversion rules
       /usr/local/lib/fax/pagesizes	     page size database
       /usr/local/lib/fax/	     prototype cover page
       /usr/local/lib/fax/dialrules	     optional client dialstring	rules
       /var/spool/hylafax/tmp/sndfaxXXXXXX   temporary files

       at(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1), faxs-
       tat(1),	sgi2fax(1),  faxq(8C),	viewfax(1),  hylafax-server(5F), dial-
       rules(5F), pagesizes(5F), typerules(5F),	services(4)

				  May 8, 1996		     HYLAFAX-CLIENT(1)


Want to link to this manual page? Use this URL:

home | help