An Overview of the LP Print Service

The LP print service is a set of software utilities that allows users to print files while they continue to work. Originally, it was called the LP spooler. (Spool is an acronym for system peripheral operation off-line. LP stood for line printer, but its meaning now includes many other types of printers, like laser printers.)

The print service consists of the LP print service software, any print filters (programs that process data before printing) you may provide, and the hardware (the printer, workstation, and network connections).

The following section describes the functions provided by the LP print service. Then, the section "The Structure of the LP Print Service" on page 308 describes the directory structure and commands.

Functions Provided by the LP Print Service

The LP print service performs the following functions:

• Administers files and schedules local print requests
• Schedules network requests
• Filters files (if necessary) so that they print properly
• Starts programs that interface with the printers
• Tracks the status of jobs
• Tracks forms mounted on the printer
• Tracks print wheels currently mounted
• Delivers alerts to mount new forms or different print wheels
• Delivers alerts about printing problems

Administering Files and Scheduling Local Print Requests

The LP print service has a scheduler daemon called lpsched. The scheduler daemon updates the LP system files with information about printer setup and configuration.

The lpsched daemon also schedules all local print requests, as shown in Figure B-1, regardless of whether the requests are issued by users from an application or from the command line. In addition, the scheduler tracks the status of printers and filters. When a printer finishes printing a request, the scheduler schedules the next request, if there is one in the queue.

Figure B-1 lpsched

Each print client and print server must have only one LP scheduler running. The scheduler is started when a system is booted (or enters run level 2) by the control script /etc/rc2.d/S80lp. Without rebooting the systems, you can

stop the scheduler with the /usr/lib/lp/lpshut command and restart the scheduler with the lpsched command. The scheduler for each system manages requests issued to the system by the lp commands.

Scheduling Network Print Requests

Each print client and print server must have one or more lpNet daemons. The lpNet daemon schedules network print requests. The lpNet daemon is started when a system is booted. If you stop and restart the scheduler (using the lpshut and lpsched commands), the lpNet daemon is also stopped and restarted.

The lpNet daemon needs a configured port monitor and registered listen services to handle incoming network requests on each print server running SunOS 5.x system software.

Filtering Print Files

Print filters are programs on the print server that convert the content of a to-be-printed file from one format to another. The LP print service uses filters to:

• Convert a file from one data format to another so that it can be printed properly on a specific type of printer
• Handle the special modes of printing that users may request using the -y option to the lp command, for example, two-sided printing, landscape printing, draft- or letter-quality printing
• Detect printer faults and notify the LP print service of them so that the print service can deliver alerts

Not every print filter can perform all these tasks. However, because each task is printer-specific, the task can be implemented separately.

A print filter can be as simple or as complex as needed. SunOS 5.x system software provides print filters in the /usr/lib/lp/postscript directory that cover most PostScript printing situations--where the destination printer requires the data to be in PostScript format. You have to create and add filters to the system for non-PostScript printers.

A set of print filter descriptor files are provided in the /etc/lp/fd directory. These descriptor files describe the characteristics of the filter (for example, fast or slow filter), and point to the filter program (for example, /usr/lib/lp/postscript/postdaisy).

Starting the Printer Interface Program

The LP print service interacts with other parts of the operating system. It uses a standard printer interface program to:

• Initialize the printer port, if necessary. The standard printer interface program uses the stty command to initialize the printer port.
• Initialize the printer. The standard printer interface program uses the terminfo database and the TERM shell variable to find the appropriate control sequences.
• Print a banner page, if necessary.
• Print the correct number of copies specified by the print request.

The LP print service uses the standard interface program (found in the /usr/lib/lp/model directory) unless you specify a different one. You can create custom interface programs, but you must be careful that the custom program does not terminate the connection to the printer or interfere with proper printer initialization.

Tracking the Status of Print Jobs

The lpsched daemon on both the print server and print client keeps a log of each print request that it processes and notes any errors that occurred during the printing process. This log is kept in the /var/lp/logs/lpsched file. Every night, the lp cron job renames /var/lp/logs/lpsched to a new file lpsched.n and starts a new log file. If errors occur or jobs disappear from the print queue, you can use the log files to determine what lpsched has done with a printing job.

Tracking Forms

The LP print service helps you (the system administrator) track which forms are mounted on each printer, and notifies you when it cannot find the description of how to print on the form. You are responsible for creating form

descriptions and mounting and unmounting the paper form in each printer, either as part of setting up a printer or in response to alerts from the LP print service.

Users can specify the form on which they want a job to print. You (root) can mount a specific form and then tell the LP print service that the form is available and on which printer it is mounted. Or users can submit print requests specifying a particular form, and whether or not the form is mounted. When the LP print service receives the request, it sends an alert message to the system administrator (root) requesting that the form be mounted.

Tracking Print Wheels

The procedure for tracking print wheels is similar to the procedure for tracking forms. Some printers (usually letter-quality printers) have removable print heads, like daisy wheels or print balls, that provide a particular font or character set. A user can request a named character set. If that character set is not available, the LP print service notifies the system administrator (root) of the request. The job is stored in the print queue until the print wheel is changed.

Receiving Printing Problem Alerts

The LP print service performs sophisticated error checking. If a printing problem occurs, alerts are sent to the originator of a print request, or to the system administrator, depending on the nature of the problem and what is required to fix it. Users are notified when a print request cannot be completed. If users request it, they are notified by email when a job is successfully completed. Administrators are alerted to problems with printers, and to requests for filters, forms, or character sets.

For problems that require an administrator's attention, the LP print service default is to write an alert message to the system administrator's console window (that is, to the terminal on which root is logged in).

As the system administrator, you can change the alert policy to receive alert messages via:

• Electronic mail
• Program of your choice

Or, you can choose to receive no alerts when printing problems occur.

The Structure of the LP Print Service

This section explains the structure and directory hierarchy for the LP print service. The many files of the LP print service are distributed among seven directories, as shown in Table B-1.

Table B-1

Directory	Contents
/usr/bin	The lp, lpstat, enable, and disable commands
/etc/lp	A hierarchy of LP configuration files
/usr/share/lib	The terminfo database directory
/usr/sbin	The LP commands
/usr/lib/lp	The LP daemons; directories for binary files and PostScript filters; and the model directory (which contains the standard printer interface program)
/var/lp/logs lpNet lpsched.n requests.n	The logs for LP activities Messages from lpNet Messages from lpsched Information about completed print requests
/var/spool/lp	The spooling directory where files are queued for printing

User Commands

The /usr/bin directory contains the lp and lpstat commands, with which users submit and monitor print requests. The directory also contains the enable and disable commands, with which printers are enabled and disabled.

A user can customize a print request by using options to the lp command: specifying forms, character sets, filters, titles, banners, and so forth. Table B-2 summarizes the frequently used options for the lp command. You can use these options individually or combine them in any order on the command line. When combining options, use a space between each option and repeat the dash (-). For example, the following command specifies a destination printer, requests email notification, and prints six copies of a file.

% lp -d printer-name -m -n6 filename

Table B-2 lp

Option	Description
-d	Destination. Specifies a destination printer by name.
-m	Mail. Sends email to the user that submitted the print request when the file has printed successfully.
-n	Number. Specifies the number of copies to be printed.
-t	Title. Specifies a title for a print request (printed only on the banner page).
-o nobanner	Option. Suppresses printing of the banner page for an individual request.
-c	Copy. Copies the file before printing.
-w	Write. Writes a message to root's terminal when the file has printed successfully.

See lp(1) for a complete list of options.

LP Configuration Files

The scheduler stores configuration information in LP configuration files located in the /etc/lp directory, as described in Table B-3. These configuration files serve the function of the /etc/printcap file in SunOS 4.1.

---

Note - You can check the contents of these files, but you should not edit them directly. Instead, use the LP administrative commands, described in "LP Administrative Commands" on page 313, provide input for the configuration files in the /etc/lp directory. The lpsched daemon administers and updates the configuration files. Instead, use the administrative commands any time you need to update any configuration file.

---

The following table describes the contents of the /etc/lp directory.

Table B-3 /etc/lp

File	Type	Description
Systems	ASCII file	Names of systems defined using the lpsystem command. Includes every remote system with which the local system can exchange print requests.
classes	Directory	Files identifying classes provided by the lpadmin -c command.
default	ASCII file	Name of the default destination provided by the lpadmin -d command.
fd	Directory	Description of existing filters.
filter.table	File	Print filter lookup table.
forms	Directory	Location to put files for each form. Initially, this directory is empty.
interfaces	Directory	Printer interface program files.
logs	Link to /var/lp/logs	Log files of printing activities.
model	Link to /usr/lib/lp/model	The standard printer interface program.
printers	Directory	Directories for each (remote or local) printer. Each directory contains configuration information and alert files for an individual printer.
pwheels	Directory	Print wheel or cartridge files.

The printers directory has a subdirectory for each printer (local or remote) known to the system. The following example shows the printers subdirectories of printers sparc1 and luna.

%ls -l /etc/lp/printers drwxrwxr-x 2 lp lp 512 Jan 23 23:53 luna drwxrwxr-x 2 lp lp 512 Jan 11 17:50 sparc1

Within each of the printer-specific directories, the following files can describe the printer:

• alert.sh - Shell to execute in response to alerts
• alert.vars - Alert variables
• configuration - Configuration file
• users.deny - List of users to whom printer access is denied
• comment - Printer description

The configuration file for the printer luna, /etc/lp/printers/luna/configuration, would typically appear as follows:

Banner: on: Always Content types: PS Device: /dev/term/b Interface: /usr/lib/lp/model/standard Printer type: PS Modules: default

Printer Definitions

The /usr/share/lib directory contains the terminfo database directory, which contains definitions for many types of terminals and printers. The LP print service uses information in the terminfo database to initialize a printer, to establish a selected page size, character pitch, line pitch, and character set, as well as to communicate the sequence of codes to a printer.

Each printer is identified in the terminfo database with a short name. See "Directory Structure of the terminfo Database" on page 84 for a description of the structure of the terminfo database. If necessary, you can add entries to the terminfo database, but it is a tedious and time-consuming process. See "Adjusting the terminfo Database for an Unsupported Printer" on page 327.

Daemons and LP Internal Files

The /usr/lib/lp directory contains daemons and files used by the LP print service, as described in Table B-4.

Table B-4 /usr/lib/lp

File	Type	Description
bin	Directory	Contains files for generating printing alerts, slow filters, and queue management programs.
lpNet	Daemon	Controls LP requests for network printing.
lpdata	ELF executable file	Lists LP print service configuration information (interactive command).
lpsched	Daemon	Manages scheduling of LP print requests.
model	Directory	Contains the standard printer interface program.
postscript	Directory	Contains all PostScript filter programs provided by the SunOS 5.x LP print service. These filters come with descriptor files in the /etc/lp/fd directory that tell the LP print service the characteristics of the filters and where to locate them.

LP Administrative Commands

The commands used to set up and administer the LP print service are in the /usr/sbin directory, as shown in Table B-5.

Table B-5 lp/usr/sbin

Command	Purpose
accept	Accepts print requests into the printer's queue.
lpadmin	Defines printer names, printer types, file content types, print classes, printer devices, and printer comments; removes printers or print classes; specifies fault recovery, interface programs (either custom or standard), printing options, banner/no banner; mounts forms; mounts print wheels or cartridges; defines allow and deny user lists.
lpfilter	Adds, changes, deletes, and lists filters.
lpforms	Adds, changes, deletes, and lists forms.
lpmove	Moves queued print requests from one printer to another.
lpshut	Halts the LP print service. (lpsched, which starts the LP print service, is in the /usr/lib/lp directory.)
lpsystem	Registers print servers and print clients with the LP print service.
lpusers	Sets queue priorities for users.
reject	Rejects print requests into the printer's queue

Log Files

The LP print service maintains two sets of log files:

• A list of current requests that are in the print queue (/var/spool/lp)
• An ongoing history of print requests (/var/lp/logs/requests)

Print Queue Logs The scheduler for each system keeps a log of print requests in the directories /var/spool/lp/tmp/system and /var/spool/lp/requests/system. Each print request has two files (one in each directory) that contain information about the request. The information in the /var/spool/lp/requests/system

directory can be accessed only by root or lp. The information in the /var/spool/lp/tmp/system can be accessed only by the user who submitted the request, root, or lp.

The following example shows the contents of the /var/spool/lp/tmp/terra directory:

terra% ls /var/spool/lp/tmp/terra 20-0 21-0 terra% cat 21-0 C 1 D slw2 F /etc/default/login P 20 t simple U tamiro s 0x1000

These files remain in their directories only as long as the print request is in the queue. Once the request is finished, the information in the files is combined and appended to the file /var/lp/logs/requests, which is described in the next section.

Use the information in the /var/spool/lp logs if you need to track the status of a print request that is currently in the queue.

History Logs The LP print service records a history of printing services in three log files: lpNet, lpsched, and requests. These log files are located in the /var/lp/logs directory. You can use the information in these logs to diagnose and troubleshoot printing problems. Here is an example of the contents of the /var/lp/logs directory:

# cd /var/lp/logs # ls lpNet lpsched.1 requests requests.2 lpsched lpsched.2 requests.1 #

The files with the .1 and .2 suffixes are copies of the previous day's logs. Each day, the lp cron job cleans out the lpsched and requests log files and keeps copies for two days. See "How to Monitor and Clean Out Log Files" on page 122 for suggestions on modifying the cron job for cleaning out the requests log.

The two most important log files for troubleshooting are:

• The lpNet log, which contains information about network printing
• The lpsched log, which contains information about local printing requests

The requests log contains information about print requests that are completed and no longer in the print queue. Once a request is finished printing, the information in the /var/spool/lp log files is combined and appended to the /var/lp/logs/requests log.

The requests log has a simple structure, so that you can extract data using common UNIX shell commands. Requests are listed in the order they are printed, and are separated by lines showing their request IDs. Each line below the separator line is marked with a single letter that identifies the kind of information contained in that line. Each letter is separated from the data by a single space.

Here is an example of the contents of a requests log:

# pwd /var/lp/logs # tail requests.2 z slw2 C 1 D slw2 F /etc/motd P 20 t simple U irving s 0x0100 #

= slw2-20, uid 200, gid 200, size 5123, Mon Nov 18 01:24:01 EST 1994

Table B-6 shows the letter codes in the LP requests log.

Table B-6 requests

Letter	Content of Line
=	The separator line. It contains the following items: request ID, the user ID (UID) and group IDs (GIDs) of the user, the total number of bytes in the original (unfiltered) file size, and the time when the request was queued.
C	The number of copies printed.
D	The printer or class destination or the word any.
F	The name of the file printed. The line is repeated for each file printed; files were printed in the order shown.
f	The name of the form used.
H	One of three types of special handling: resume, hold, and immediate. The only useful value found in this line will be immediate.
N	The type of alert used when the print request was successfully completed. The type is the letter M if the user was notified by email or W if the user was notified by a message to the terminal.
O	The printer-dependent -o options (for example, nobanner).
P	The priority of the print request.
p	The list of pages printed.
r	A single-letter line that is included if the user asked for "raw" processing of the files (the -r option of the lp command).
S	The character set, print wheel, or cartridge used.
s	The outcome of the request, shown as a combination of individual bits expressed in hexadecimal form. Several bits are used internally by the print service. The bits and what they mean are describe in Table B-7.
T	The title placed on the banner page.
t	The type of content found in the files.
U	The name of the user who submitted the print request.

Table B-6 requests

Letter	Content of Line
x	The slow filter used for the print request.
Y	The list of special modes for the print filters used to print the request.
z	The printer used for the request. This printer differs from the destination (the D line) if the request was queued for any printer or a class of printers, or if the request was moved to another destination.

Table B-7

Outcome Codes	Description
0x0001	The request was held pending resume.
0x0002	Slow filtering is running.
0x0004	Slow filtering finished successfully.
0x0008	The request is on the printer.
0x0010	Printing finished successfully.
0x0020	The request was held pending user change.
0x0040	The request was canceled.
0x0080	The request will print next.
0x0100	The request failed filtering or printing.
0x0200	The request is in transit to a remote printer.
0x0400	The user will notified.
0x0800	A notification is running.
0x1000	A remote system has accepted the request.
0x2000	The administrator placed a hold on the request.
0x4000	The printer had to change filters.
0x8000	The request is temporarily stopped.

Spooling Directories

Files queued for printing are stored in the /var/spool/lp directory until they are printed, which may be only seconds. Table B-8 shows the contents of the /var/spool/lp directory.

Table B-8 /var/spool/lp

File	Type	Description
SCHEDLOCK	File	Lock file for the scheduler. Check for this file if the scheduler dies and will not restart.
admins	Directory	Link to /etc/lp.
bin	Directory	Link to /usr/lib/lp/bin.
fifos	Directory	Pipes that convey networked print requests to and from the lpNet daemon.
logs	Link	Link to ../lp/logs where completed print requests are logged.
model	Link	Link to /usr/lib/lp/model.
requests	Directory	Directory that contains subdirectories for each configured printer where print requests are logged until printed. Users cannot access this log.
system	Directory	A print status file for the system.
temp	Link	Link to /var/spool/lp/tmp/printer-name, which contains the spooled requests.
tmp	Directory	Directory for each configured printer where print requests are logged until printed. Changes to existing print requests are also recorded in this log.

Understanding How the Print Service Works

This section describes what happens to a local print request from the time it is submitted by the user until it is printed successfully. It also explains how printing works between SunOS 4.1 and SunOS 5.x systems.

Local Printing

Figure B-2 shows what happens when a user submits a request to print a PostScript file on a local printer, which is a printer connected to the user's system. All processing happens on the local system; no network printing software is used.

Figure B-2

Remote Printing

Figure B-3 shows what happens when a user on a SunOS 5.x print client submits a print request to a SunOS 4.1 print server. The lpsched daemon handles the local part of the print request, and the lpNet daemon and its child process handle the network communication between the two systems.

Figure B-3

Figure B-4 shows a SunOS 4.1 print client submitting a print request to a SunOS 5.x print server. The lpd daemon handles the local part of the print request and the connection to the print server. The Service Access Facility network listen process on the server waits for network printing requests and sends them to the lpNet daemon. The lpNet daemon and its child processes hand the request over to the lpsched daemon, which processes the request on the print server

Figure B-4

Figure B-5 shows what happens when a user of a SunOS 5.x print client submits a print request to a SunOS 5.x print server. The lpsched daemon on the print client handles the local part of each print request. Then lpsched passes the request to the lpNet daemon on the print client, which spawns a child process that communicates with the print server. The Service Access Facility network listen service on the print server monitors network printing requests and sends them to the lpNet daemon on the print server. The lpNet daemon and its child processes send the request to the lpsched daemon on the print server, which processes the print request.

Figure B-5

About Customizing the LP Print Service

Although the LP print service is designed to be flexible enough to handle most printers and printing needs, it does not handle every possible situation. You may have a printing request that is not accommodated by the standard features of the LP print service. Or you may have a printer that does not quite fit into the way the LP print service handles printers.

You can customize the LP print service in the following ways:

• Adjust the printer port characteristics
• Adjust the terminfo database
• Customize the printer interface program
• Create a print filter
• Define a form

Adjusting Printer Port Characteristics

The printer port characteristics set by the LP print service must be compatible with the printer communication settings.

If the default printer port settings provided by the LP print service do not work with a printer, refer to the printer manual to find out what settings the printer requires from the LP print service. See Table B-13 for a list of the stty settings most frequently used by the LP print service. See the manual page for the stty(1) command for a complete list of options.

Adjusting the terminfo Database for an Unsupported Printer

The LP print service uses an interface program and the terminfo database to initialize each printer and establish a selected page size, character pitch, line pitch, and character set.

Each printer is identified in the terminfo database with a short name. The name required by the terminfo database is identical to the kind of name used to set the TERM shell variable. This name is also the printer type you specify when setting up a printer. For example, the entries for different types of PostScript printers are in /usr/share/lib/terminfo/P. The default entries provided with the SunOS 5.x system are PS (for PostScript) and PSR (for

PostScript Reverse). For more information about finding entries in the terminfo database, see "Printer Entries in the terminfo Database on page 84.

If you cannot find a terminfo entry for your printer, you still may be able to use the printer with the LP print service, without automatic selection of page size, pitch, and character sets. However, you may have trouble keeping the printer set in the correct modes for each print request.

If there is no terminfo entry for your type of printer, you can either customize the interface program used with the printer or add an entry to the terminfo database.

The terminfo database contains hundreds of items defined for each terminal or printer. The LP print service, however, uses fewer than 50 of these items. Table B-14 on page 346 lists the required items.

Customizing the Printer Interface Program

Any printer interface program performs the following tasks:

• It initializes the printer port, if necessary. The standard printer interface program uses the stty command to initialize the printer port.
• It initializes the printer hardware. The standard printer interface program gets the control sequences from the terminfo database and the TERM shell variable.
• It prints a banner page, if necessary.
• It prints the number of copies specified by the print request.

---

Caution - If you have a printer interface program from a release of UNIX System V prior to Release 3.2, it will probably work with the SunOS 5.x LP print service. However, several -o options have been standardized in the SunOS 5.x print service and will be passed to every printer interface program. These options may interfere with similarly named options used by the old interface.

---

The LP print service, not a printer interface program, is responsible for opening the printer port. The printer port is given to the printer interface program as standard output, and the printer is identified as the "controlling terminal" for the printer interface program so that a "hang-up" of the port will cause a SIGHUP signal to be sent to the printer interface program.

If you have a printer that is not supported by the standard printer interface program, you can furnish your own printer interface program. You can copy the standard program, and then tell the LP print service to use it for a specified printer. But first, you need to understand what is in the standard program. The following section describes the standard program.

The Standard Printer Interface Program

The standard (model) printer interface program, /usr/lib/lp/model/standard, is used by the LP print service to set the printing defaults shown in Table B-9.

Table B-9

Characteristic	Default Setting
Default filter	None
Character pitch	None
Line pitch	None
Page width	None
Page length	None
Character set	None
stty options	9600 cs8 -cstopb -parenb -parodd ixon -ixany opost -olcuc onlcr -ocrnl -onocr -onlret -ofill nl0 cr0 tab0 bs0 vt0 ff0
Exit code	0

Customizing stty Modes If you need to change the terminal characteristics, like baud rate or output options, look for the section of the standard printer interface program that begins with the following comment:

## Initialize the printer port

Exit Codes When printing is complete, your interface program should exit with a code that shows the status of the print job. The exit code is the last entry in the printer interface program.

Table B-10 shows the exit codes and how they are interpreted by the LP print service.

Table B-10

Code	Meaning to the LP Print Service
0	The print request has been successfully completed. If a printer fault occurred, it has been cleared.
1 to 127	A problem was encountered when printing a request (for example, too many non-printable characters, or the request exceeds the printer capabilities). The LP print service notifies the person who submitted the request that there was an error when printing it. This error will not affect future print requests. If a printer fault has occurred, it has been cleared.
128	This code is reserved for internal use by the LP print service. Interface programs must not exit with this code.
129	A printer fault was encountered when printing the request. This fault will affect future print requests. If the fault recovery for the printer directs the LP print service to wait for the administrator to fix the problem, the LP print service disables the printer. If the fault recovery is to continue printing, the LP print service will not disable the printer, but it will try printing again in a few minutes.
>129	These codes are reserved for internal use by the LP print service. Interface programs must not exit with codes in this range.

If the program exits with a code of 129, the system administrator (root) is alerted of a printer fault. Unfortunately, if the printer interface program exits, the LP print service must also reprint the request from the beginning, after the fault has been cleared. If you do not want the entire request to be reprinted,

you can have the interface program send a fault message to the LP print service, but wait for the fault to clear. When the fault clears, the interface program can resume printing the file. When printing is finished, the printer interface program can give a zero exit code, just as if the fault had never occurred. An added advantage to this approach is that the interface program can detect when the fault is cleared automatically, so that the administrator does not need to re-enable the printer.

Fault Messages You can use the lp.tell program to send fault messages to the LP print service. This program is referenced by the LPTELL shell variable in the standard printer interface code. The program takes standard input and sends it to the LP print service, where it is put into the message that alerts the administrator to the printer fault. If its standard input is empty, lp.tell does not initiate an alert. For an example of how the lp.tell program is used, examine the standard printer interface code immediately after the following comment:

# Here's where we set up the $LPTELL program to capture fault
messages

If you use the special exit code 129 or the lp.tell program, the printer interface program does not need to disable the printer itself. The interface program can disable the printer directly, but doing so will override the fault-alerting mechanism. Alerts are sent only if the LP print service detects that the printer has a fault, and the special exit code and the lp.tell program are its main detection tools.

If the LP print service has to interrupt the printing of a file at any time, it kills the interface program with a signal TERM (trap number 15, see kill(1) and signal(3B)). If the printer interface program dies from receipt of any other signal, the LP print service assumes that future print requests will not be affected, and continues to use the printer. The LP print service notifies the person who submitted the request that the request has not been finished successfully.

When the interface is first invoked, the signals HUP, INT, QUIT, and PIPE (trap numbers 1, 2, 3, and 13) are ignored. The standard interface changes this so that these signals are trapped at appropriate times. The standard interface interprets receipt of these signals as warnings that the printer has a problem; when it receives a signal, it issues a fault alert.

Using a Customized Printer Interface Program You can create a customized printer interface program and use it in place of the standard printer interface program on the print server. To do so, you have to use the lpadmin command to register the program with the LP print service for a specific printer.

Creating a New Print Filter

A filter is used by the LP print service each time it has to print a type of file that is not acceptable to a printer. Creating a new print filter is not easy, and usually requires extensive experimentation. A print filter can be as simple or as complex as needed. Filters contain input types, output types, and complex options that provide a language to process command-line arguments within the filter.

The SunOS 5.x print service provides filter programs in the /usr/lib/lp/postscript directory. These filters cover most PostScript printing situations--where the destination printer requires the data to be in PostScript format. A set of filter descriptor files are provided in the /etc/lp/fd directory. These files describe the characteristics of the filters (for example, fast or slow filter), and point to the filter programs (for example, /usr/lib/lp/postscript/postdaisy).

If you have non-PostScript printers, you have to create and add print filters as required. First, you need to understand what print filters are and the requirements that must be met by a filter program.

Understanding Print Filters

This section describes different types of filters, how they convert file content, handle special modes, and detect printer faults.

Types of Filters There are two types of print filters: fast filters and slow filters.

Fast filters do not require much processing time to prepare a file for printing. In addition, they must have access to the printer when they run. A print filter that detects printer faults must be a fast filter. Any filter that uses the PRINTER keyword as a filter option must be installed as a fast filter.

Slow filters require a lot of processing time to prepare a file for printing. In addition, slow filters do not require access to the printer when they run. Slow filters are run in the background so that they do not tie up a printer, allowing other files that do not need slow filtering to be printed. Slow filters that are specified by users (using the -y option to the lp command) must be run on the system where the print request was issued. The LP print service cannot pass values for filters to remote systems. It can, however, match a file content type to a content type on a remote system. If you want to activate special filter modes on a remote system, you must do so by specifying content types (instead of slow filters) that tell the LP print service to match input types and output types.

Converting Files The LP print service uses print filters to convert files from one content type to another. You can specify the file content types for each printer. When a user submits a file, specifying its content type, the LP print service finds a printer that can print files of that content type. Because many applications can generate files for various printers, this is often sufficient. However, some applications may generate files that cannot be printed on any available printers.

Each time the LP print service receives a request to print a type of file that is in a format that cannot be accepted directly by a printer, the LP print service tries to match the content type of the print request with the content type of the available (or specified) printer. If there is a match, the file can be sent directly to the printer without filtering. If no match is found, or if the content type specifies that a filter be used, the LP print service tries to match the content type of the file with the input content type of available filters, and match the output type of the filter with the content type of the printer. When an appropriate filter is found, the print request is passed through the filter.

Handling Special Printing Modes A print filter handles special modes and requests to print specific pages. A special printing mode is needed to print any characteristics of print requests that require a customized filter. Filters handle the following characteristics:

• Printer type
• Character pitch
• Line pitch
• Page length

• Page width
• Pages to print
• Character set
• Form name
• Number of copies

The LP print service provides default settings for these characteristics; however, a print filter may handle some characteristics more efficiently. For example, some printers can handle multiple copies more efficiently than the LP print service, in which case, you may want to provide a filter for multiple-copy page control.

Detecting Printer Faults Each printer has its own way of detecting printer faults and transmitting fault signals to the LP print service. The LP print service only checks for hang-ups (loss of carrier) and excessive delays in printing.

Some printers provide good fault coverage and can send a message describing the reason for a fault. Other printers indicate a fault by using signals other than the signals indicating loss of carrier signal or shut off of data flow. A filter is required to interpret this additional printer fault information.

A filter can also put a print request on hold, wait for a printer fault to clear, and then resume printing. In this way, the print request that was interrupted does not need to be reprinted in its entirety. Only a filter that knows the control sequences used by a printer can determine where to break a file into pages. Consequently, only such a filter can find the place in the file where printing should start again when a fault is cleared.

When a print filter generates messages, those messages are handled by the LP print service, and alerts are sent to the system administrator, if alerts are enabled. See "Setting Printer Fault Alerts" on page 156.

Requirements for a Print Filter Program

A print filter can be simple or complex, but it has to meet the following requirements:

• The filter should get the contents of a file from its standard input and send the converted file to the standard output.

• A program cannot be used as a filter if it references external files. You may be tempted to use a program like troff, nroff, or a similar word processing program as a filter. The LP print service does not recognize references to other files, known as include files, from a filter program. Because troff and nroff allow include files, they may fail when used as filters. If the program needs other files to complete its processing, it should not be used as a filter.
• The filter should not depend on files that normally would not be accessible to a user. If a filter fails when run directly by a user, it will fail when run by the LP print service.
• A slow filter can send messages about errors in the file to standard error. A fast filter should not. Error messages from a slow filter are collected and sent to the user who submitted the print request.
• If a slow filter dies because it received a signal, the print request is stopped and the user who submitted the request is notified. Likewise, if a slow filter exits with a non-zero exit code, the print request is stopped and the user is notified. The exit codes from fast filters are treated differently.

If you want the filter to detect printer faults, the filter must also meet the following requirements:

• If possible, the filter should wait for a fault to be cleared before exiting. Additionally, it should continue to print at the top of the page where printing stopped after the fault clears. If the administrator does not want this contingency followed, the LP print service will stop the filter before alerting the administrator.
• The filter should send printer fault messages to its standard error as soon as the fault is recognized. It does not have to exit, but rather it can wait for the fault to be cleared.
• The filter should not send messages about errors in the file to standard error. These messages should be included in the standard output, where they can be read by the user.
• The filter should exit with a zero exit code if the file is finished printing (even if errors in the file have prevented it from being printed correctly).
• The filter should exit with a non-zero exit code only if a printer fault has prevented it from finishing a print request.
• When added to the filter table, the filter must be added as a fast filter.

Defining a Print Filter

When defining a new print filter, in addition to writing a filter program, you must define the characteristics of its use to the LP print service:

• Name of the filter program to run
• The types of input it accepts
• The types of output it produces
• The types of printers to which it can send jobs
• The names of specific printers to which it can send jobs
• The type of filter (either fast or slow)
• Options

You can type the characteristics as direct input to the lpfilter command. You also can create a file that specifies the filter's characteristics, and use the file name as input to the lpfilter command. Such a file is called a filter descriptor file and should be located in the /etc/lp/fd directory. These files are not the filters themselves, but rather point to the filters.

Whether you store the information in a file, or enter it directly on the command line, use the following format:

Command: command-pathname [options] Input types: input-type-list Output types: output-type-list Printer types: printer-type-list Printers: printer-list Filter type: fast or slow Options: template-list

The information can be arranged in any order, and not all the information is required. When you do not specify values, those shown in Table B-11 are assigned by default. They are not very useful, which is why you should specify explicit values.

Table B-11 lpfilter

Item	Default
Input types	any
Output type	any

Table B-11 lpfilter

Item	Default
Printer types	any
Printers	any
Filter type	slow

The filter characteristics are defined as follows:

• Command - The full path of the filter program. If there are any fixed options that the program always needs, include them here.
• Input types - The list of file content types that the print filter can process. The LP print service does limit the number of input types, but most filters can accept only one type. Several file types may be similar enough that the filter can deal with them. You can use whatever names you like, using a maximum of 14 alphanumeric characters and dashes. Do not use underscores as part of the input type name.

  Because the LP print service uses these names to match a filter to a file type, follow a consistent naming convention. For example, if more than one filter can accept the same input type, use the same name for that input type when you specify it for each filter. Inform your users of these names so they know how to identify the file type when submitting a file for printing.

• Output types - The list of file types that the filter can produce as output. For each input type, the filter produces a single output type. The output type may vary, however, from job to job. The name of the output type is restricted to 14 alphanumeric characters and dashes.

  The output type names should either match the types of available (local or remote) printers, or match the input types handled by other filters. The LP print service groups filters in a shell pipeline if it finds that several passes by different filters are needed to convert a file. It is unlikely that you will need this level of sophistication, but the LP print service allows it. Try to find a set of filters that takes as input types all the different files the users may want printed, and that converts those files directly into file types the printer can handle.

• Printer types - The list of printer types into which the print filter can convert files. For most printers and filters, you can leave this part of the filter definition blank, because it is identical to the list of output types. But it can be different. For example, you could have a printer with a single printer

type for purposes of initialization, but which can recognize several different file content types. Essentially, this printer has an internal filter that converts the various file types into one that it can handle. Thus, a filter may produce one of several output types that match the file types that the printer can handle. The print filter should be marked as working with that printer type. As another example, you may have two different models of printers that are listed as accepting the same file types. Due to slight differences in manufacture, however, one printer deviates in the results it produces. You label the printers as being of different printer types, say A and B, where B is the one that deviates. You create a filter that adjusts files to account for the deviation produced by printers of type B. Because this filter is needed only for those printer types, you would list it as working only on type B printers.

• Printers - Usually, a print filter should be able to work with all printers that accept its output, so you can usually skip this part of the filter definition. You may, however, have some printers that are or inappropriate for the output that the filter produces. For example, you may want to dedicate one printer for fast turnaround, only sending files that require no filtering to that printer. Other printers of identical type may be used for files that need extensive filtering before they can be printed.
• Filter type - The LP print service recognizes fast and slow filters. Fast filters incur little overhead when preparing a file for printing, and they must have access to the printer when they run. A filter that is supposed to detect printer faults must be a fast filter. A filter that uses the PRINTER keyword as a filter option must be a fast filter.

  Slow filters incur lots of overhead in preparing a file, and do not require access to a printer to run. The LP print service runs slow filters in the background, without tying up a printer. Files that do not need slow filtering can move ahead in the print queue, and printers are not left idle while a slow filter works on one file.

  Slow filters that are invoked by printing modes (using the -y option of the lp command), must be run on the system from which the print request originated. The LP print service cannot pass values for modes to print servers. It can, however, match a file content type (specified after the -T option of the lp command) to a content type on a print server. Therefore, if you want to activate special modes on a print server, you must specify content types that permit the LP print service to match input types and output types.

• Options - Options specify how different types of information are converted into command line arguments to the filter command. This information may include specifications from a user (with the print request), the printer definition, and the specifications implemented by any filters used to process the request.

Defining Print Filter Options With Templates There are 13 sources of information, each of which is represented by a keyword. Each option is defined in a template. A template is a statement in a filter definition that defines an option to be passed to the filter command, based on the value of one of the characteristics of the filter. A template has the following format:

The options specified in a filter definition may include none, all, or any subset of the 13 keywords. In addition, a single keyword may be defined more than once, if multiple definitions are required for a complete filter definition. See Table B-12 for a description of the 13 keywords.

A print filter definition can include more than one template. Multiple templates are entered on a single line and separated with commas, or they are entered on separate lines, preceded by the Options: prefix.

The format of a template is as follows:

keyword pattern = replacement

The keyword identifies the type of option being registered for a particular characteristic of the filter.

The pattern is specific option for the keyword. The replacement is what happens when the keyword has the noted value.

For an example of how an option is defined for a particular filter, suppose you want to have the print service scheduler assign print requests to filters following this criteria:

• If the type of OUTPUT to be produced by the filter is impress, then pass the -I option to the filter.
• If the type of OUTPUT to be produced by the filter is postscript, then pass the -P option to the filter.

To specify these criteria, provide the following templates as options to the lpfilter command:

Options: OUTPUT impress=-I, OUTPUT postscript=-P

If the Options: line becomes too long, put each template on a separate line, as follows:

Options: OUTPUT impress=-I Options: OUTPUT postscript=-P

In both templates, the keyword is defined as OUTPUT. In the first template, the pattern is impress and the value of the replacement is -I. In the second template, the value of pattern is postscript and the value of replacement is -P.

The 13 keywords shown in Table B-12 are available for defining Options in a print filter definition.

Table B-12

Characteristic	Keyword	Possible Patterns	Example
Content type (input)	INPUT	content-type	troff
Content type (output)	OUTPUT	content-type	postscript, impress
Printer type	TERM	printer-type	att495
Printer name	PRINTER	printer-name	lp1
Character pitch	CPI	scaled-decimal	10
Line pitch	LPI	scaled-decimal	6
Page length	LENGTH	scaled-decimal	66
Page width	WIDTH	scaled-decimal	80
Pages to print	PAGES	page-list	1-5,13-20
Character set	CHARSET	character-set	finnish

Table B-12

Characteristic	Keyword	Possible Patterns	Example
Form name	FORM	form-name	invoice2
Number of copies	COPIES	integer	3
Special modes	MODES	mode	landscape

To find out which values to supply for each type of template (that is, for the pattern and replacement arguments for each keyword), consider the following:

• The values for the INPUT and OUTPUT templates come from the file content type that needs to be converted by the filter, and the output type that has to be produced by the filter, respectively.
• The value for the TERM template is the printer type.
• The value for the PRINTER template is the name of the printer that will be used to print the final output.
• The values for the CPI, LPI, LENGTH, and WIDTH templates come from the user's print request, the form being used, or the default values for the printer.
• The value for the PAGES template is a list of pages that should be printed. Typically, it is a list of page ranges separated by commas. Each page range consists of a pair of numbers separated by a dash, or a single number. (For example, 1-5,6,8,10 indicates pages 1 through 5, plus pages 6, 8, and 10). However, whatever value was given in the -P option to a print request is passed unchanged.
• The value for the CHARSET template is the name of the character set to be used.
• The value for the FORM template is the name of the form requested by the -f option of the lp command (the command used to submit a print request).
• The value of the COPIES template is the number of copies of the file to print. If the filter uses this template, the LP print service will reduce to one the number of copies of the filtered file it prints, since this "single copy" includes the multiple copies produced by the filter.

• The value of the MODES template comes from the -y option of the lp command. Because a user can specify several -y options, there may be several values for the MODES template. The values will be applied in the left-to-right order given by the user.

The replacement part of a template shows how the value of a template should be given to the filter program. It is typically a literal option, sometimes with the placeholder asterisk (*) included to show where the value goes. The pattern and replacement also can use the regular expression syntax of ed(1) for more complex conversion of user input options into filter options. All regular expression syntax of ed(1) is supported, including the \( ... \) and \n constructions, which can be used to extract portions of the pattern for copying into the replacement, and the &, which can be used to copy the entire pattern into the replacement.

---

Note - If a comma or an equals sign (=) is included in a pattern or a replacement, precede it with a backslash (\). A backslash in front of any of these characters is removed when the pattern or replacement is used.

---

Creating a New Printer Form

When you want to provide a new form, you must define its characteristics by entering information about nine required characteristics (page length, page width, and so on) as input to the lpforms command. The LP print service uses this information for two purposes:

• To initialize the printer so that printing is done properly on the form
• To send reminders to the system administrator about how to handle the form

Before running the lpforms command, gather the following information about the new form:

• Page length - The length of the form, or the length of each page in a multipage form. This information can be the number of lines, or the size in inches or centimeters.
• Page width - The width of the form, in characters, inches, or centimeters.

• Number of pages - The number of pages in a multipage form. The LP print service uses this number with a print filter (if available) to restrict the alignment pattern to a length of one form. See the description of alignment pattern below. If no filter is available, the LP print service does not truncate the output.
• Line pitch - A measurement of how close lines appear on the form. This is also called leading. It is the distance between two lines, from baseline to baseline, measured by either lines per inch or lines per centimeter.
• Character pitch - A measurement of how close together characters appear on the form. It is the distance between characters, measured by either characters per inch or characters per centimeter.
• Character set choice - The character set, print wheel, or font cartridge that should be used when this form is used. Users may choose a different character set for their own print requests when using this form, or you can insist that only one character set be used.
• Ribbon color - If the form should always be printed using a certain color ribbon, the LP print service can give a mount alert message indicating which color to use.
• Comment - Any remarks that might help users understand the form. For example, the remarks could indicate the name of the form, its revision, its purpose, or restrictions on its use.
• Alignment pattern - A sample file that the LP print service uses to fill one blank form. When mounting the form, you can print this pattern on the form to align it properly. You can also define a content type for this pattern so that the print service knows how to print it.

---

Note - The LP print service does not try to mask sensitive information in the alignment pattern. If you do not want sensitive information printed on sample forms--for example when you align checks--then you should mask the appropriate data. The LP print service keeps the alignment pattern stored in a safe place, where only those logged in as root or lp can read it.

---

When you have gathered the information for the form, you enter it as input to the lpforms command. You should record this information first in a separate file so you can edit it before entering it with lpforms. You can then use the file as input instead of typing each piece of information separately after a prompt.

Instructions for Customizing the LP Print Service

This section includes instructions for the following tasks:

• Adjusting the printer port characteristics
• Adjusting the terminfo database for an unsupported printer
• Providing a custom printer interface program
• Providing a new print filter
• Providing a new form

For many tasks, you will find an example of user input and system output after the instructions.

· How to Adjust the Printer Port Characteristics

1. On the system to which the printer is connected, become root or lp.

2. Type lpadmin -p printer-name -o "stty=options" and press Return. You can change more than one stty option setting by enclosing the options in single quotation marks and separating the options by spaces. The following table shows the default settings used by the LP print service. Change them as needed.

Table B-13 stty

Option	Meaning
9600	Set baud to 9600
cs8	Set 8-bit bytes
-cstopb	Send one stop bit per byte
-parity	Do not generate parity
ixon	Enable XON/XOFF (also known as START/STOP or DC1/DC3)
opost	Do "output post-processing" using the settings listed below:
-olcuc	Do not map lowercase to uppercase
onlcr	Change line feed to carriage return/line feed
-ocrnl	Do not change carriage returns into line feeds
-onocr	Output carriage returns even at column 0
n10	No delay after line feeds

Table B-13 stty

Option	Meaning
cr0	No delay after carriage returns
tab0	No delay after tabs
bs0	No delay after backspaces
vt0	No delay after vertical tabs
ff0	No delay after form feeds

Example of Adjusting the Printer Port Characteristics

For example, suppose your printer requires you to enable parity, set it to odd, and set a 7-bit character size. You would type the following command:

terra% su Password: # lpadmin -p luna -o "stty='parenb parodd cs7'"

The stty option parenb enables parity checking/generation, parodd sets odd parity generation, and cs7 sets the character size to 7 bits.

For example, suppose your printer requires you to enable hardware flow control. You would type the following command:

terra% su Password: # lpadmin -p oak -o "stty='parenb parodd cs7'"

The stty option parenb enables parity checking/generation, parodd sets odd parity generation, and cs7 sets the character size to 7 bits.

· How to Adjust the terminfo Database for an Unsupported Printer

1. Determine a correct TERM name for the printer.

a. On the system to which the printer is connected, type cd /usr/share/lib/terminfo and press Return. b. Type ls -l * and press Return.

The file names shown in the listing are all valid TERM variables. These are the printer types you can specify when setting up a printer. Use them as a guide for picking a name for the printer. You should make sure none of the existing entries will support the new printer (by trying to set up the printer with an entry for a similar printer, if there are any).

2. Construct a database entry for a new printer.

   The following table shows the items you must define in the terminfo entry to add a new printer to the LP print service. For more details about the structure of the terminfo database, see terminfo(4).

Table B-14 terminfo

Item		Meaning
Booleans:	cpix	Changing character pitch changes resolution
	daisy	Printer needs operator to change character set
	lpix	Changing line pitch changes resolution
Numbers:	bufsx cols	Number of bytes buffered before printing Number of columns in a line
	cps	Average print rate in characters per second
	it	Tabs initially every n spaces
	lines	Number of lines on a page
	orc	Horizontal resolution, in units per character
	orhi	Horizontal resolution, in units per inch
	orl	Vertical resolution, in units per line
	orvi	Vertical resolution, in units per inch
Strings:	chr	Change horizontal resolution
	cpi	Change number of characters per inch

Table B-14 terminfo

Item		Meaning
	cr	Carriage return
	csnm	List of character set names
	cudl	Down one line
	cud	Move carriage down n lines
	cuf	Move carriage right n columns
	cvr	Change vertical resolution
	ff	Page eject
	hpa	Horizontal position absolute
	ht	Tab to next 8-space Tab stop
	if	Name of initialization file
	iprog	Path name of initializing program
	is1	Printer initialization string
	is2	Printer initialization string
	is3	Printer initialization string
	lpi	Change number of lines per inch
	mgc	Clear all margins (top, bottom, and sides)
	rep	Repeat a character n times
	rwidm	Disable double-wide printing
	scs	Select character set
	scsd	Start definition of a character set
	slines	Set page length to n lines per page
	smgl	Set left margin at current column
	smglp	Set left margin
	smgr	Set right margin at current column
Strings:	smgrp smglr	Set right margin Set both left and right margins

Table B-14 terminfo

Item		Meaning
	msgt	Set top margin at current line
	smgtp	Set top margin
	smgb	Set bottom margin at current line
	smgbp	Set bottom margin
	smgtb	Set both top and bottom margins
	swidm	Enable double-wide printing
	vpa	Vertical position absolute

3. Type tic filename and press Return.

   When you have created a file containing the new entry, you need to compile it into the database using the tic(1M) program.

4. Stop the LP print service by typing lpshut and press Return.

5. Restart the LP print service by typing lpsched and press Return. The new information is registered with the LP print service.

· How to Provide a Custom Printer Interface Program

To customize the standard interface program: 1. On the print server, become root or lp.

2. Type cp /var/spool/lp/model/standard custom-filename and press Return.

   This copies the standard printer interface program.

3. Change the copy of the standard printer interface program to fit your particular needs.

   Refer to the description of the program in the section "The Standard Printer Interface Program" on page 329 to determine what you need to change.

4. Type lpadmin -p printer-name -i custom-filename and press Return to tell the LP print service to use the custom program.

   You have to tell the LP print service to use the custom printer interface program; otherwise, the standard printer interface program is used. The custom printer interface program is registered with the LP print service, and will be used by that printer when users submit print requests.

To use a customized interface program for another printer: * Type lpadmin -p printer-name1 -e printer-name2 and press Return. After you have created a custom printer interface program, you can use it for other printers. The printer interface program from printer-name2 is registered with the LP print service for printer-name1. Note that the program is still registered with the LP print service for printer-name2.

· How to Provide a New Print Filter

1. On the print server or print client, become root or lp.

2. Write a print filter program.

   It would be difficult to give you a step-by-step procedure for this. Read the information in the section "Creating a New Print Filter" on page 332 for guidelines. The filter program is a binary executable. By convention, filter programs for PostScript printers are located in the /usr/lib/lp/postscript directory. You should put programs you create under /usr/lib/lp in a directory of your choosing.

3. Create a print filter definition.

   You should save the printer definition in a text file. By convention, filter definitions are located in the /etc/lp/fd directory and are identified with the .fd suffix. The definition tells the LP print service about the filter, what program to run, what kind of conversion it does, on so on. The filter definition has the following format:

Command: command-pathname [options] Input types: input-type-list Output types: output-type-list Printer types: printer-type-list Printers: printer-list Filter type: fast or slow Options: template-list

4. Add the print filter to the LP print service, using the definition from a file, or enter it directly at the command line.

   This step registers the new filter with the LP print service.

   a. To use a file, type lpfilter -f filter-name -F filename.fd and press Return.

   The filter definition from the file named is added to the /etc/lp/filter.table file using the filter name you specify.

terra# lpfilter -f daisytroff -F /etc/lp/fd/daisytroff.fd

b. To enter the definition, type lpfilter -f filter-name - filter-definition and press Control-d.

The filter definition you type is added to the /etc/lp/filter.table file using the filter name you specify.

Examples of Print Filter Definitions

Print Filter to Convert N37 or Nlp to simple To provide the following filter definition for a filter called col, you would type:

Input types: N37, Nlp, simple Output types: simple Command: /usr/bin/col Options: TERM 450 = -b, MODES expand = -x Options: INPUT simple = -p -f

---

Note - If you provide more than one definition (that is, more than one line) for any filter characteristic other than Options, only the second definition will be used by the print service.

---

After you register this definition with the print service by entering it as input to the lpfilter command, users' print requests will be handled as follows:

• When a user enters this command:

% lp -y expand report.dec10

The filter command is run with the following arguments:

/usr/bin/col -x -p -f

• When a user enters this command:

% lp -T N37 -y expand report.dec10

The filter command is run with the following arguments:

/usr/bin/col -x

• When the default printer is not of type 450 and a user enters this command:

% lp -y expand -T 450 report.dec10

The filter command is run with the following arguments:

/usr/bin/col -b -x

Print Filter to Convert From troff to PostScript In this example, the filter program is called /usr/lib/lp/postscript/dpost. It takes one input type, troff, produces a postscript output, and works with any printer of type PS (for PostScript). You have decided that users need to give just the abbreviations port or land when they ask for the paper orientation to be portrait mode or landscape mode, respectively. Because these options are not intrinsic to the LP print service, users must specify them using the -y option to the lp command.

The print filter definition would look like this:

Input types: troff Output types: postscript Printer types: PS Filter type: slow Command: /usr/lib/lp/postscript/dpost Options: LENGTH * = -l* Options: MODES port = -pp, MODES land = -pl

A user submitting a troff file type for printing on a PostScript printer (type PS), with requests for landscape orientation and a page length of 60 lines, would type the following command:

% lp -T troff -o length=60 -y land -d printer-name filename

Then the dpost filter would be invoked by the LP print service to convert the file as follows:

/usr/lib/lp/postscript/dpost -l60 -pl printer-name filename

Add the following option template to the previous example:

Options: MODES group \=\([1-9]\) = -n\l

This template converts a MODES option of this form:

-y group=number

Into filter options:

-nnumber

So, if a user gives the following command:

% lp -y group=4

The dpost command includes the following options:

-n4

For additional examples, become root and run the command:

# lpfilter -f all -l

This command will list all of the currently installed print filters.

· How to Provide a New Form

1. Determine the definition and name to use for the new form.

   The form name can be anything you choose, as long as it does not contain more than 14 alphanumeric characters and underscores. The information must be in the following format:

Page length: scaled number Page width: scaled number Number of pages: integer Line pitch: scaled number Character pitch: scaled number Character set choice: character-set-name [,mandatory] Ribbon color: ribbon-color Comment: informal notes about the form Alignment pattern: [content-type] alignment pattern

The optional phrase [,mandatory] means that the user cannot override the character set choice in the form. The content-type can be given, although this is optional, with an alignment pattern. If this attribute is given, the print service uses it to determine, as necessary, how to filter and print the file.

With two exceptions, the information may appear in any order. The exceptions are the Alignment pattern (which must always be last), and the comment (which must always follow the line with the Comment: prompt). If the comment contains a line beginning with a key phrase (like Page length, Page width, and so on), precede that line with a > character so the key phrase is not at the beginning of the line. The initial > character is stripped from the comment and is not displayed.

Not all of the information must be given. When you do not specify values for the items listed in Table B-15, the default values are assigned.

Table B-15

Item	Default
Page length	66 lines
Page width	80 columns
Number of pages	1
Line pitch	6 lines per inch
Character pitch	10 characters per inch
Character set choice	Any
Ribbon color	Any
Comment	(No default)
Alignment pattern	(No default)

2. On the print server or print client, become root or lp.

3. (Optional) Create a file containing the new form definition.

4. Add the form to the LP print service, using the definition from a file, or enter it directly in the command line.

• To use the definition from a file, type lpforms -f form-name -F filename and press Return.

  The form is registered with the LP print service. The form definition from the file named is added to the /etc/lp/forms/form-name directory under the file named description.

terra# lpforms -f medical -F /etc/lp/forms/medical.fmd

* To enter the definition directly, type lpforms -f form-name -form-definition and press Control-d.

The form is registered with the LP print service. The form definition you type is added to the /etc/lp/forms/form-name directory under the file named description.

5. Type lpadmin -p printer-name -f allow:form-list and press Return. The printer now has access to the specified forms. You can specify all for form-list to grant access to all the available forms. By default a printer does not have access to any forms. The form-list is a list of forms separated by commas with no spaces. If you use spaces to separate names, enclose the word allow: and the list of forms in double quotation marks.

terra# lpadmin -p luna -f allow:medical,dental,check