.TH controls "" "" "System Administration"
.PC "Data base for the lp print spooler"
.B "/usr/spool/mlp/controls"
.PP
The file
.B /usr/spool/mlp/controls
is the data base for the print spooler
.BR lp .
The superuser
.B root
can modify this file, either with a text editor or (to a more
limited extent) with the command
.BR lpadmin .
.PP
The format of
.B controls
is simple.
Every blank line is ignored.
All text after the pound sign `#' is also ignored; you can use this feature
to embed comments in the file.
The rest of the file consists of commands, each of which has the format
\fIcommand\fB=\fIarguments\fR.
.PP
The following describes the commands that you can embed in
.BR controls :
.IP \fBdefault=\fIprinter\fR
This command sets the default printer, that is, the printer on which jobs
are printed when the user does not specify a printer on the
.B lp
command line.
.IP \fBdocopies=\fIstatus\fR
This command controls how
.B lp
prints multiple copies.
If it is set to
.BR on ,
then multiple copies are generated by invoking the printer's control
script for each time; if it is set to
.BR off ,
then multiple copies are printed by telling the control script to do it.
The difference in the two methods is that the former gives you more
accurate information about the status of the job.
If you wish to print many copies and you want to monitor the job's progress,
then set
.B docopies
to
.BR on .
.IP \fBfeed=\fIstatus\fR
The command
.B localfeed
tells
.B lp
whether to insert a formfeed character between printing jobs
sent to printers other than local printers.
Setting it to
.B on
tells
.B lp
to output a formfeed character; setting it to
.B off
(or deleting it) tells it not to do so.
.IP \fBlocalfeed=\fIstatus\fR
The command
.B localfeed
tells
.B lp
whether to insert a formfeed character between printing jobs
sent to a local printer.
(A
.I local
printer is one plugged into the auxiliary port of a terminal.)
Setting it to
.B on
tells
.B lp
to output a formfeed character; setting it to
.B off
(or deleting it) tells it not to do so.
.IP \fBlogroll=\fIhours\fR
This command sets the time, in hours, at which the log file
.B log
is renamed
.B log.o
and a fresh log file is begun.
This is done so the log file does not grow without bounds.
The default value is 168 hours (one week).
.IP \fBlonglife=\fIhours\fR
Set, in hours, the ``life-expectancy'' of a file with a lifetime of
.BR L .
The default is three days (72 hours).
.IP \fBprinter=\fIname\^\fB,\fIdevice\^\fB,\fIscript\fR
This command defines a printer.
.B lp
accesses a printer by its name;
it cannot access a printer unless you name it in a
.B printer
command.
.I name
names the printer.
You can name a printer anything you like, so long as it is one word.
.I device
names the device into which it is plugged.
.I script
names the file in directory
.B /usr/spool/mlp/backend
that tells how to massage the text being passed to the printer.
You can write or modify each script in that directory, and name each
script whatever you like.
Note that one physical printer can have multiple names, each using
a different script; and one script can be shared by multiple physical
printers.
.IP
The command
.DM
	printer = linenlq, /dev/lpt2, pannlq
.DE
.IP
names a printer
.B linelq
that is plugged into port
.BR /dev/lpt2 ,
and whose input is filtered through the contents of script
.BR /usr/spool/mlp/backend/pannlq .
.IP
The command
.DM
	printer = linepr, /dev/lpt2, linepr
.DE
.IP
names a printer
.B linepr
that is plugged into
.BR /dev/lpt2 ,
and whose input is filtered through the contents of script
.BR /usr/spool/mlp/backend/linepr .
.IP
Note that these examples both name the same physical device.
They differ in the scripts they use to massage their input;
this will be described in detail below.
.IP
Finally, a
.B printer
can direct its output to any device, serial or parallel, even
.BR /dev/null .
For example:
.DM
	printer=disk,/dev/null,disk
.DE
.IP
As will be shown below, the script
.B disk
writes its output into a temporary file, so you can examine it without
wasting a piece of paper.
The format of a printer-control script is described below.
.IP
You do not have to include a printer-control script in a
.B printer
command; if you do not include one, the printer daemon
.B lpsched
uses the command
.B cat
by default.
.IP \fBshortlife=\fIhours\fR
Set, in days, the ``life-expectancy'' of a file with a lifetime of
.BR S .
The default is 48 hours (two days).
.IP \fBtemplife=\fIhours\fR
Set, in minutes, the ``life-expectancy'' of a file with a lifetime of
.BR T .
The default is two hours.
.SH "Printer Control Scripts"
A printer-control script massages the text being handed to a given printer.
The printer daemon
.B lpsched
redirects the output of the script (and therefore, of every command
within the script)
to the device named on the appropriate
.B printer
command named in the file
.BR /usr/spool/mlp/controls .
.PP
For example, consider the command
.DM
	printer = linenlq, /dev/lpt2, pannlq
.DE
.PP
This command names a printer
.BR linenlq ,
declares that it is plugged into port
.BR /dev/lpq2 ,
and requests that
.B lpsched
massage input to the printer through script
.BR /usr/spool/mlp/backend/pannlq .
When
.B lpsched
processes a request that is directed to printer
.BR linelq ,
it pipes the text of the job into script
.BR pannlq ,
and redirects the output of
.B pannlq
to device
.BR /dev/lpt2 .
.PP
It is important to remember that a printer-control script is not restricted
to a few commands that the spooler understands.
Each is a true shell script
that can use any or all \*(CO commands to process text.
The limits of what a script can do are set only by your imagination.
.PP
Consider the following examples.
In the discussion, above, of the command
.BR printer ,
two scripts were mentioned:
.B pannlq
and
.BR linepr .
Both send their output to the same physical printer,
but they process the input text in different ways.
The following gives the contents of
.BR linepr :
.DM
	# filter the input through pr
	pr
.sp \n(pDu
	# throw a page at the end
	echo "\ef\ec"
.DE
.PP
This script filters its input through the \*(CO command
.BR pr ,
which paginates the text and puts a header on it.
It then echoes a formfeed character, to force the printer to throw
a blank page at the end of the job.
As in other shell scripts, a pound sign `#' introduces a comment
and blank lines are ignored.
.PP
The following gives the contents of script
.BR pannlq :
.DM
	# turn on near-letter-quality printing
	echo "\e021\e033n"
.sp \n(pDu
	pr
.sp \n(pDu
	# turn off near-letter-quality printing
	echo "\e021\e033P"
.DE
.PP
This script resembles the first, except that it includes commands
to echo the magic strings that turn on and turn off near-letter-quality
printing on this printer.
This is one small example of the flexibility you can employ in
devising a script
.PP
As with other shell scripts, you can modify the behavior of a
printer-control script by setting environmental variables.
For example, consider the following variation on the script
.BR linepr :
.DM
	if [ $HEADER ]; then
		pr -h "$HEADER"
	else
		pr
	fi
.sp \n(pDu
	# throw a page at the end
	echo "\ef\ec"
.DE
.PP	
If you have exported the environmental variable
.BR HEADER ,
then this script prints it at the top of each page; otherwise, it prints
the default header.
You can use the same technique to do other work, such as force the printing
of a banner page.
.PP
The
.B lp
spooler reserves for its own use the environmental variables
.BR MLP_COPIES ,
.BR MLP_FORMLEN ,
.BR MLP_LIFE ,
.BR MLP_PRIORITY ,
.BR MLP_SPOOL .
Your scripts can also use these variables.
For more information on what each does, see its entry in the Lexicon.
.PP
When
.B lpsched
uses a printer-control script, it passes it three arguments:
respectively, the sequence number of the print job (which identifies the
job uniquely); the name of the user; and the number of copies being printed.
You can use this information to control the printing of output; for
example, consider the following:
.DM
	for i in `from 1 to $3`
	do
		pr -h "User $2 - Copy $i of $3"
	done
	echo "\ef\ec"
.DE
.PP
Note, too, that just as each physical printer can be accessed in different
ways via different scripts, so too the same script can be used by multiple
physical printers.
If you had multiple Panasonic printers plugged into your system, you could
use the above script with each of them to massage their input appropriately.
.PP
One last example.
As noted above, the output of a printer-control
script can be directed to any device, not just a port.
(It can also be redirected to non-existent ports, so be careful when you
enter your \fBprint\fR commands.)
You can use this feature to redirect formatted text into files or other
interesting places.
Consider the following
.B printer
command:
.DM
	printer=disk,/dev/null,disk
.DE
.PP
This creates a ``printer'' named
.BR disk .
The text filtered through file
.B disk
is redirected to
.BR /dev/null .
The contents of script
.B disk
show what this device is up to:
.DM
	tee /tmp/D$$
.DE
.PP
This script uses the \*(CO command
.B tee
to redirect its input both to the standard output
(which in the case of printer
.B disk
is thrown away) and into a file in directory
.BR tmp .
You can use this command to save input for further examination later.
.PP
This discussion just scratches the surface of what you can do with the
.B lp
print spooler and its control scripts.
For more information, see the Lexicon entries for
.B printer
and
.BR lp .
.SH "See Also"
.Xr "Administering COHERENT," administe
.Xr "lp," lp
.Xr "lpadmin," lpadmin
.Xr "MLP_COPIES," mlp_copie
.Xr "MLP_FORMLEN," mlp_forml
.Xr "MLP_LIFE," mlp_life
.Xr "MLP_PRIORITY," mlp_prior
.Xr "MLP_SPOOL," mlp_spool
.Xr "printer" printer
