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

FreeBSD Manual Pages


home | help
MAGICFILTER(5)		      File Formats Manual		MAGICFILTER(5)

       magicfilter - format of printer description files.

       The printer description files are simple	m4 macro files that are	merged
       with a template-file inside magicfilter to produce a list of rules  for
       printing	out files of various types.

       A  printer  description file provides macro definitions for magicfilter
       to merge	with its built-in configuration	file.  The macros that	magic-
       filter needs are	as follows

	      This  is	the  company  that  makes the printer in question (not
	      needed for generic filters, like the postscript filters.)

       define(Printer, `Printer')dnl
	      This is a	short description of  the  printer.   For  a  specific
	      printer,	it  is the name	of the printer (eg: 600	DPI LaserJet 4
	      series with Postscript ) and for a generic printer, it's	a  de-
	      scription	 of  what  the printer is (eg: 600 DPI PostScript-only
	      printer )

	      This is the dots per inch	that the printer is capable of	print-

	      This  is	set  to	 true if the printer handles PostScript, false

	      This is set to true if the printer handles H-P PCL.

	      This is set to true if the printer handles H-P Printer Job  Lan-

	      This is set to true if the printer supports PCL5E.

	      This  is	the  device  name to use when filtering	through	Ghost-
	      Script.  This (or	PS_OPTIONS, if you're using some  sort	of  gs
	      script) is needed	to print most formats on non-postscript	print-

	      Set this to false	if your	printer	cannot handle text,  but  must
	      have it formatted	in some	way.  PostScript-only printers require
	      this, and	use pstext or enscript to format plain text for	print-

	      This option makes	magicfilter send all printer-ready output (see
	      HANDLE_TEXT, below, for the exception to this rule)  to  command
	      for printing instead of just dumping the printer-ready output to
	      stdout.  This is useful when you wish to use a networked printer
	      but your printer server software doesn't allow you to put	a fil-
	      ter on a remote printer.

       define(HANDLE_TEXT,`action command')dnl
	      If the printer needs any special processing to do	text, it  will
	      be set here.  This is used on H-P	printers, for example, to spit
	      out PCL reset codes before printing out plain text.   NOTE  that
	      HANDLE_TEXT  overrides  PRINTER  --  this	is so you can redirect
	      output to	different printer devices for output that  needs  pro-
	      cessing  and  output  that  is  plain text.  Also	note that HAN-
	      DLE_TEXT does not	use the	same sort  of  argument	 that  PRINTER
	      does;  PRINTER  expects  a command (like lpr -Pfoolp) while HAN-
	      DLE_TEXT expects an action followed by a	command	 (like	filter
	      'printer reset' 'page flush'),  and  that	the action must	be one
	      of filter, ffilter, cat, or pipe.	  Any  other  action  is  very
	      likely to	result in a printer filter that	takes a	lot of time to
	      reject your printer jobs.

       The configuration file is used by magicfilter to	redirect various types
       of data to the various conversion utilities.  The configuration file is
       fed to m4 along with the	printer	description file mentioned in the sec-
       tion  above,  and  is  parsed  by magicfilter to	figure out what	can be
       printed to a file.  The unformatted printer description file  (/usr/lo-
       cal/etc/,	 or  a	internal  default  template  is	 an m4
       sourcefile that contains	a sequence of lines of the form:

       /pattern/ action/hint/	arguments

       where the /pattern/ is compared against what file (1)  reports  as  the
       filetype,  action  is  what should be done with it, /hint/ (optionally)
       tells magicfilter what format the processed file	is, and	arguments  are
       passed to the action.

       Blank  lines and	lines with a hash mark (#) as the first	nonblank char-
       acter are ignored.  A line may be continued onto	the next line by  end-
       ing the line in a backslash (\).

       For  ambiguous  matches,	the first match	is used.  Hence, the most spe-
       cific match should always be placed first in the	file.  There is	no de-
       fault  pattern -- if the	file type is not matched, magicfilter will re-
       ject the	print request.	If you wish a default pattern, you can use  an
       empty pattern to	do something like:

       //   pipe /usr/local/libexec/magicfilter/textonly

       To  use	Ed Lim's textonly program to print the file out	after a	little
       paranoia	to make	sure that it's not a binary.

       magicfilter provides the	following options for the  facility  field  in
       the configuration file:

       cat [prefix [suffix]]
	      Copy  the	 input	to the output without any conversion, like the
	      cat command.  If the optional  prefix  and  suffix  strings  are
	      specified,  they	are transmitted	to the printer immediately be-
	      fore and after the data itself.  The prefix and  suffix  strings
	      can  include escape sequences like \e (escape) To	specify	a suf-
	      fix without a prefix, specify an empty prefix string enclosed in
	      double quotes (i.e. "").

       text [prefix [suffix]]
	      Copy the input to	the output, but	add carriage return characters
	      before every line	feed and form feed character in	the file,  and
	      a	 line  feed-form feed sequence at end of file.	The prefix and
	      suffix arguments are treated the same way	as for the cat	facil-
	      ity; the suffix, if present, is added after the final line feed-
	      form feed	sequence.

	      Same as the text facility, except	 add  an  ASCII	 EOT  (Ctrl-D)
	      character	 to  the  end  of  the	data.	This lets a PostScript
	      printer know that	the end	of the job has been reached.  This  is
	      functionally equivalent to the command

	      text "" \004

       ignore Ignore the job; do not provide any output	whatsoever.

       reject message
	      Same  as	the ignore facility, but attempt to send an email mes-
	      sage to the user who submitted the job to	inform that a job  has
	      been rejected and	why.

       filter command
	      Run  the	given  command,	feeding	it the input data, and sending
	      the output data  to  the	printer.   The	environment  variables
	      LPUSER,  LPHOST, and LPINDENT are	set to the values of the user,
	      host and indent options passed to	magicfilter.   To  get	around
	      the way some filters ( ghostscript) promiscuously	mix output and
	      error messages when they direct their output to stdout,  setting
	      the  magic cookie	${FIFO}	in the argument	list of	a filter ( for
	      postscript, -sOutputFile=${FIFO})	will cause magicfilter to gen-
	      erate  a fifo and	copy from that fifo to stdout, redirecting the
	      stdout from the filter to	stderr instead.	 Since the command  is
	      fed  to /bin/sh it may contain shell special characters, and the
	      sequences	$LPUSER, $LPHOST, and $LPINDENT	can be used to	access
	      the values of the	passed environment variables.  If the lpd dae-
	      mon on the system	is LPRng, the following	environment  variables
	      are  also	 available,  see  the OPTIONS section for details: LP-
	      LPACCT, and ZOPT.

       pipe command
	      Same  as the filter facility, except that	the output data	is fed
	      back into	magicfilter for	reprocessing.  This is used for	exter-
	      nal  filter  programs  which  themselves do not produce a	format
	      that the printer can accept, but which can be  futher  processed
	      to obtain	such a format.

       ffilter command

       fpipe command
	      Same  as	the  filter  and pipe facilities, respectively,	except
	      that the input is	written	to a temporary file before  being  fed
	      to the filter program given by command.  This is useful for pro-
	      grams which require seekable input, such as dvips, or which need
	      to do multiple passes over an input file,	such as	grog.  The en-
	      vironment	variable FILE is set to	the name of the	temporary file
	      (and,  like  the	other  ones, it	can be accessed	on the command
	      line as $FILE).

       Using the pipe facility together	with zcat or gunzip lets you transpar-
       ently print compressed files.

       The pbmplus or netpbm collections of image conversion utilities contain
       a large number of very useful external filter programs.

       You will	probably want to examine the sample  configuration  files  in-
       cluded with the magicfilter distribution	before creating	your own.

       Note  that the .def files are processed by m4 so	you need to pay	atten-
       tion to what they contain if you	write your own.	  In  particular,  you
       should  carefully  avoid	 using constructs that look like m4 macros and
       you need	to use the escapes \{ for (, \}	for ), \- for ', and \+	for `.
       Failing	to  do	that may result	in unexpected things happening to your
       printer (most likely nothing printing with no error  messages  at  all,
       but  it's  equally  possible  that the printer will print something you
       don't particularly want it to print.)

       Currently, there	is no protection against the pipe or fpipe  facilities
       going into an infinite loop.

       Magicfilter  is developed with some fairly ancient and creaky printers,
       so many of the fancier features supported here  are  less  well	tested
       than I would like.

       The  documentation  for the reject action lies when it says that	it at-
       tempts to send mail to the person who sent the rejected job.

       H. Peter	Anvin <>, David Parsons <>

       printcap(5), lpr(8), dvips(1), grog(1), gs(1), gzip(1), troff(1).

2002/12/14			 Version 2.3.h			MAGICFILTER(5)


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

home | help