The PPR Hacker's Guide

All jobs which enter the queue pass through the program called ppr. This is true even of those which pass first through the Macintosh print server, the LPR compatible server, or Samba. (These additional server components will be described later.) The program ppr reads a PostScript file and creates several files which contain the text of the job and information indexes of the job text.. These files are placed in a spool directory and an additional file, called the queue file, is created which describes the job and the options the user has selected. Once all the files are ready, ppr sends a message to the print daemon pprd telling it that a new job is in the queue. This process is illustrated in figure Figure 1.

Figure 1. A job Enters the Queue

When pprd determines that the time has come to print a file on a printer, it invokes a program called pprdrv which reads the 3 job files and reasembles them into a PostScript file. While doing so it will consult information read from the printer configuration file and the queue file and a PostScript Printer Description (PPD) file. It may also include fonts and other resources in the data stream. This process is illustrated in figure Figure 2. (The inclusion of fonts and other resources has been ommited from the figure for the sake of simplicity.)

Figure 2. PPR Prints a Job

Figure 3. Multiple Instances of pprdrv for Multiple Printers

The program pprdrv sends the file to the printer by invoking an interface program. It is the responsibility of the interface program to accept the print job on standard input, send it the printer, if possible receive any error messages, and pass them back to pprdrv by writing them to stdout.

Notice in figure Figure 3 that printing is taking place on PRINTER 1 and PRINTER 3.

PRINTER 2 is idle, so the processes necessary to print on it are shown with dotted line boxes, indicating that they do not exist at present.

Once the job has been printed, the interfaces program exits, after which pprdrv exits. The main spooling daemon, pprd detects this and removes the job from the queue and attempts to inform the user that the job is done.

When exiting, pprdrv will return an exit code which indicates to pprd whether printing was successful or not. If the exit code indicates that a problem occured which was caused by the particular job being printed, a PostScript error for instance, then the job is placed in the "arrested" state, the user who submitted it is informed, and pprd looks for another job to print on that printer. The arrested state is a special case of the "held" state. An arrested job remains in that state until it is canceled or released.

When a job is arrested, the user who submitted it is informed, however if the arrested job is subsequently deleted by an operator, the user will not be informed as he would be if a normal job of his were canceled.

If pprdrv indicates that the problem is with the printer, then the job is returned to the queue, the printer is placed in fault mode, and pprd looks for another printer on which to print the job. When pprdrv discovers a problem with a printer, it indicates to pprd whether or not it is a problem from which the printer is likely to recover without the intervention of the system operator. Problems from which it is likely to recover on its own include those which are transient or which an ordinary user might correct, such as printer-turned-off and out-of-paper. If the problem is one from which the printer may recover, then it is placed in fault-retry mode; if it is not expected to recover, it is placed in fault-no-retry mode.

In fault-retry mode, pprd tries to restart the printer at intervals. The delay before the retry is 10 seconds the first time and increases by 10 seconds after each failure until the interval reaches about 10 minutes, at which point it does not continue to increase. In fault-no-retry mode, the printer is not restarted until a system operator restarts it. An operator may restart a printer with the command ppop start printer.

When pprdrv detects a printer fault, it writes a description of it to a file in the alerts/ directory, a file which is named after the printer. At intervals, pprd may send the contents of this file to a system operator. The interval is defined in the printer configuration file. The interval is expressed as 'every N faults.' If the interval is set to 1, the alerts log is sent after each printer fault; if the interval is set to 5, the alerts log is sent after every 5th printer fault. If the interval is set to 0, the alerts are never sent.

If the alert interval is negative, it is treated differently. First of all, the absolute value is used as the alert interval. Second, the alerts are only sent to the system operator once. Third, a notice is sent to the system operator if the printer successfully prints a job after incurring at least abs(N) alerts.

Each time a fault occurs, the alert message is appended to the alert log. The exception is that if the previous alert occured more than one hour previously, the alert log is truncated to zero length and a new one started. Whether or not the alerts have been dispatched to an operator, the alert log may be read at any time with the command ppop alerts printer.

It is in the printer configuration file that the alert interval is specified, as well as the method by which alerts are to be dispatched and the address to send them to. A typical alert dispatch method (indeed, the only one supported at this time) is mail. This means that the alerts are sent by electronic mail to the indicated address. The alert parameters may be set with the ppad alerts command.

Users on the machine running PPR can submit jobs simply by running the program ppr. But, when the user is on a remote machine connected by a network to the machine with the PPR spooler, things get a little more complicated.

Accepting network jobs requires a daemon process which waits new connexions. When it receives a connexion, it must launch a server process. The server process will accept the print job and run ppr to submit it.

Each file in the directory /etc/ppr/printers/ represents one printer. It is permissible to create and edit these files manually, however the command ppad has been provided to do this automatically.

A new printer configuration file is created by the ppad interface command. The new configuration file is created by turning the arguments of the ppad interface command into a Interface: and an Address: line and appending the file /etc/ppr/newprn.conf. The newprn.conf file is normally created by the ppad new alerts command.

Any lines begining with ; or # are comments. Blank lines are ignored. All other lines should begin with a keyword which is followed by one or more values. Only the Bin: and PPDOpt: lines should occur more than once. If any other line occurs multiple times, all but the last instance are ignored.

Any line that begins with an unrecognized keyword is ignored. This is so that you can add lines of your own which will be understood and acted on by other programs. The program ppr2samba works on this principle.

Each file in the /etc/ppr/groups/ directory represents a group. It is permissible to create and edit these files manually, however it is generally more convient to use the command ppad to do it automatically. The Printer: line is the only one which should appear more than once. If any other line occurs more than once, all but the last instance are ignored. Lines with ; or # in the first column are comments. The remaining lines are of two types:

There are 11 parameters in all. That seems a lot, but it is perfectly acceptable to write an interface which uses only the first two. Most also examine parameters four through six to make sure that they are compatible with the protocol used when communicating with the printer.

If the interface program determines that the values of parameters four through six are unacceptable, it should call alert() to post an explanatory message to the printer's alert log and then exit with the code EXIT_PRNERR_NORETRY_BAD_SETTINGS.

Some of the parameters are small integers which represent enumerated values. These values are defined symbolically in the C include file include/interface.h and in the shell script fragment interface.sh.

The order to some of the parameters between 7 and 11 inclusive changed with PPR 2.00. Also, the name and semantics of what is now parameter number 7 changed slightly.

The interface command line in not particularly difficult to parse, but you might find it helpful to use the library functions which those interfaces which come with PPR and are written in C use. To use it, include the file libppr_int.h and call the function int_cmdline_set() from main() like this:

int_cmdline_set(argc, argv);

Once you have do this, the parameters will be available to you as members of the global structure int_cmdline. The structure int_cmdline is an instance of INT_CMDLINE, which is defined below:

struct INT_CMDLINE
	{
	gu_boolean probe;			/* TRUE if --probe used */
	const char *int_name;		/* example: "interfaces/atalk" */
	const char *int_basename;	/* example: "atalk" */
	const char *printer;		/* example: "myprn" */
	const char *address;		/* example: "My Laser Printer:LaserWriter@Computing Center" */
	const char *options;		/* example: "idle_status_interval=60 open_retries=5" */
	int jobbreak;				/* example: 1 (JOBBREAK_SIGNAL) */
	gu_boolean feedback;		/* example: 1 (TRUE) */
	enum CODES codes;			/* example: 3 (CODES_Binary) */
	const char *PDL;			/* example: "postscript" */
	const char *routing;		/* example: "Call David Chappell at 2114 when ready" */
	const char *jobname;		/* example: "myprn-1001.0" */
	const char *forline;		/* example: "David Chappell" */
	const char *title;			/* example: "My Print Job" */
	} ;

It is now very easy to write code that refers to the command line parameters by name. For example, if your interface program doesn't support probe mode, bidirectional communication, or the jobbreak methods signal and signal/pjl, you could put this right after the call to int_cmdline_set():

if(int_cmdline.probe)
	{
	fprintf(stderr,
		_("The interface program \"%s\" does not support probing.\n"),
		int_cmdline.int_basename
		);
	exit(EXIT_PRNERR_NORETRY_BAD_SETTINGS);
	}

if(int_cmdline.feedback)
	{
	alert(int_cmdline.printer, TRUE,
		_("The PPR interface program \"%s\" is incapable of sending feedback."),
		int_cmdline.int_basename
		);
	exit(EXIT_PRNERR_NORETRY_BAD_SETTINGS);
	}

if(int_cmdline.jobbreak == JOBBREAK_SIGNAL || int_cmdline.jobbreak == JOBBREAK_SIGNAL_PJL)
	{
	alert(int_cmdline.printer, TRUE,
		_("The jobbreak methods \"signal\" and \"signal/pjl\" are not compatible with\n"
		"the PPR interface program \"%s\"."), int_cmdline.int_basename);
	exit(EXIT_PRNERR_NORETRY_BAD_SETTINGS);
	}

The exit codes which interface programs should use are defined in include/interface.h and /usr/lib/ppr/interface.sh.

The interface program should not return any value other than those defined above. Any undefined value will be interpreted as a EXIT_PRNERR. Note that Perl's die returns the code 255, which is not among those defined above.

An interface program can post alerts to the printer's alerts log by calling the alert() function or runing the alert command. An interface program is required to do so before exiting with any of the codes whose names begin with EXIT_PRNERR.

The function alert() requires three or more parameters. The first is the name of the printer (from argv[1]). The second is a boolean. One may build up the alert message by calling alert() several times to add lines to it. This boolean should be TRUE on the first call and FALSE on subsequent calls. The third parameter is a printf() style format string. Any addition parameters are values for interpolation into the format string.

A newline will automatically be appended to the format string. Format strings containing embedded newlines are an acceptable way to create multi-line alert messages.

Here is a simplified example of how one might do this in C. It is somewhat contrived. It verifies the address by making sure that it begins with "/dev/".

if(strncmp(argv[2], "/dev/", 5) != 0)
	{
	alert(argv[1], TRUE, "Address \"%s\" is syntactically invalid.", argv[2]);
	exit(EXIT_PRNERR_BAD_SETTINGS);
	}

For interfaces written as shell scripts, the alert() has been wrapped in a tiny program. It may be used like this:

. /interface.sh

if [ "`echo $2 | cut -c1-5`" != "/dev/" ]
	then
	./alert $1 TRUE "The address \"$2\" is syntactically invalid."
	exit(EXIT_PRNERR_BAD_SETTINGS);
	fi

If your interface program supports bidirectional communication with the printer (which is refered to elsewhere as "feedback"), care should be taken to avoid situations which could cause communications to lock up. Lockups can occur if your interface program fails to give top priority to receiving messages from the printer. If the printer has a large amount of data to transmit to the interface program, its output buffer could fill. When a printer has a message to send, it will not process additional input until it has placed the message in its output buffer. If your interface program refuses to accept data from the printer until after the printer has accepted the next data block, a lockup will occur and both parties will wait forever. A particularly insidious aspect of this problem is that it will not happen every time. It is most likely to happen when the printer has a great deal of data to send back, such as query results or status messages.

This means that your interface program must place the file descriptor connected to the printer in non-blocking mode. When activity is detected (perhaps by the select() function), data that can be read from the desciptor must be read. It should then be sent out on stdout. Since pprdrv lives by the same rules, giving highest priority to the data which your interface program sends to its stdout, it is not absolutely necessary to run stdout in non-blocking mode.

Your interface program must not block on reads from stdin. This is because, after the job has been transmitted, pprdrv tries to keep the connexion open until the job is completed. It will stop sending data. But your interface program must go on relaying messages from the printer to pprdrv. These messages are used by pprdrv not only to keep the printer status up-to-date, but also to determine when the job has been completed. If your interface program blocks on stdin, then PPR will likely get stuck at the end of each job.

The interfaces tcpip and serial are good sources of example code. They share a function call int_copy_job(). This function handles correct two-way communication between stdin, stdout, and the printer file descriptor.

In the same directory you will find several PostScript files with names such as feedback_test1.ps. If you print them using your interface program, then will do things such as commanding the printer to send huge amounts of data back. They will quickly smoke out interfaces with fragile two-way communication implementions.

There are special messages which an interface program can send to pprdrv to inform it of its progress or to report the status of the printer. These messages are similiar to those which many PostScript printers send back to the computer connecting to them.

Note that an interface program is not required to send any of these messages. However, their use may result in better user feedback.

The ppad ppdq and ppad ppd query commands provide a way to automatically determine a printer's type. They use a number of techniques to accomplish this goal.

One technique is to connect to the printer and sending it query messages to which it will hopefully respond. These queries use langauges such as PostScript and PJL. These techniques do not generally change according to the connection method, so interface programs need only support two-way communication in order to support them.

But some connection methods, such as USB and IP may provide additional methods for obtaining information about the printer, such as alternative communications channels. For example, many printers which accept jobs over TCP/IP also response to SNMP queries. Since these methods depend very much on the method of connecting to the printer, probes of this type, called out-of-band probes, are implemented in interface programs.

Interface programs which support out-of-band probe will recognize and act on --probe. It will interrogate the printer in some way rather than connecting to it with the intention of transmitting a print job. The results of the probe are sent back to pprdrv as a series of PROBE: lines.

If the probe may take more than a few seconds, it is recommended that the interface immedately send a PROBE: line with no value in order to let ppad know that it supports probe mode. Otherwise, ppad may conclude that the interface program doesn't implement --probe and give up too soon.

If the interface is able to obtain information about the printer, it should report it by printing addional PROBE: lines. These show be in the form PROBE: name=value. The value should not be quoted, even if it contains spaces. Currently defined names are listed below. Since the probe feature is very new, this list is subject to change.

When running in probe mode, the interface program will be invoked with the printer name on the command line set to "-". The alert() knows about this special name. When it is asked to post an alert to the printer "-", it sends the alert to stderr instead. The result is that the messages will be visible to the user of ppad rather than being hidden away in the alert log.

One of the most noteworthy features of PPR is its ability to determine the type of the input file and automatically convert it to PostScript if necessary. The type of the input file is determined by two methods. The first method is the most reliable. The second is employed only if the first fails.

The first method is to look for a "magic number" at the start of the file. Many file format specifications dictate that files conforming to them always begin with certain signature bytes. Formats which specify a signature or magic number include DSC conforming PostScript, JFIF, GIF, PNG, DVI, WordPerfect documents, PBM, XPM and others.

If no recognized magic number is found, then the first 8192 bytes of the file are scanned and the number of times certain characters and constructs are found are counted. The things counted include ASCII control characters, non-ASCII characters, HP escape sequences, Troff-style dot commands, TeX style backslash commands, and PostScript procedure definitions. When these things have been counted, the totals are used to try to guess at the file format.

If PPR ever fails to determine a file's format correctly or you wish to print a file in a format for which auto-detection is not available, you can override the auto-detection mechanism with ppr's -T switch.

The result of automatic type detect is a file-type name such as one would use with the -T switch.

If ppr determines that the input file is not PostScript, it will seek to use a filter to convert it to PostScript. This appendix provides the information you will need to write your own PPR input filters.

The filters are found in the directory /usr/lib/ppr/filters/. Each of these files has a name that consists of filter_ followed by the PPR input type name. For example, the filter for JPEG files is called /usr/lib/ppr/filters/filter_jpeg.

A filter should read the file from STDIN and write PostScript code on STDOUT. If it must, it can write messages on STDERR. STDIN is guaranteed to be seekable. Messages sent to STDERR will go wherever STDERR was going when ppr was invoked.

The parameters are as follows:

When a filter is invoked, the environment variable IFS is set to a space and a tab, and the variable PATH is set to a value which is just adequate to find standard shell script helper programs such as test, sed, and grep. On most systems, that value of PATH is /bin:/usr/bin.

Here is an example. Suppose this line is in the printer's configuration file:

DefFiltOpts: level=2 colour=False resolution=300 freevm=1048576 mfmode=CanonCX

and the user submits a JPEG (JFIF) file with this command:

$ ppr -d myprn -o noisy=no -o 'fortran-width=130 jpeg-noisy=yes' picture.jpg

The filter will be invoked like thus:

filter_jpeg 'level=2 colour=False resolution=300 freevm=1048576 mfmode=CanonCX \
	noisy=no noisy=yes' myprn 'picture.jpg'

A filter should interpret any options it recognizes and ignore any it does not. If it finds two contradictory options, it should obey the last one. In the example above, the option noisy=yes is the one that prevails. The options freevm=1048576 and mfmodes=CanonCX would be ignored simply because the JPEG filter has no code to use them.

If the filter exits with a value other than 0, the job will not be discarded. A message may be informed by printing on stderr or invoking a responder, the exect behaviour being controled by the -e switch.

When a filter is executed, the real user id is that of the user who executed ppr. The effective user id and the saved user id's are ppr. The real group id is the same as it was when ppr was executed. The effective and saved group id's are ppop.

It is possible to determine precisely what filter is being executed with what arguments by running ppr with the -G infile:filter option.

A number of filters are supplied with PPR. PPR also includes a number of shell and Perl scripts which work together with programs such as TeX, Troff, PBMPlus, and other programs often found on Unix systems to form filters. If the supporting programs can not be found, the script filters will not be installed.

The filters supplied with PPR, together with their options are described in the ppr(1) man page, under the section for the -T switch.

It should be noted that PPR does not supply a filter for every file type which it can detect or for every value of the -T switch. If PPR does not have an appropriate filter, you may be able to supply one and place it in the filters directory.

This file resides in the directory /usr/lib/ppr/lib/. It is replaced whenever a new version of PPR is installed, so if you modify it you should keep a copy of your modifications elsewhere.

The file contains a list of PostScript font names and possible substitute fonts.

Any line that has # or ; in the first column is a comment. Blank lines are ignored. A font substitution record begins with the name of the font for which there are substitutes. The name should start in column one and be on a line by itself. The list of possible substitutes follows, one per line. Each substitute font line should start with a space or tab. You may list as many substitute fonts as you like. The first substitute font to be found in the printer's PPD file, in the cache directories or in the index created with ppr-index fonts will be used.

Here is an example of four records which indicate that the IBM Courier fonts are suitable substitutes for the Adobe Courier fonts:

Courier
	IBMCourier
Courier-Bold
	IBMCourier-Bold
Courier-Oblique
	IBMCourier-Italic
Courier-BoldOblique
	IBMCourier-BoldItalic

You have the option of specifying a PostScript transform matrix to be applied to the substitute font. Generally this will be used to adjust the width. The should appear on the substitute font line, after the substitute font name. Here is an example:

Helvetica-Condensed
	Helvetica [0.80 0 0 1 0 0]
Helvetica-Condensed-Bold
	Helvetica-Bold [0.80 0 0 1 0 0]
Helvetica-Condensed-Oblique
	Helvetica-Oblique [0.80 0 0 1 0 0]
Helvetica-Condensed-BoldOblique
	Helvetica-BoldOblique [0.80 0 0 1 0 0]

This approximates Helvetica Condensed by scaling Helvetica to 80% of its normal width. The role of the other members of the matrix, refer to the PostScript language reference manual.

This file mfmodes.conf is used by ppad when setting the default filter options. Specifically, the mfmode= option is selected with the aid of this file. The mfmode= option is used by the DVI filter to select an appropriate MetaFont mode for a given printer.

Before consulting this file, ppad reads the printer's PPD file and extracts the values from the following lines:

*Product:
*ModelName:
*NickName:
*DefaultResolution:

The extracted values are then compared to values on lines in the mfmodes.conf file. Each line in the mfmodes.conf file has the following format:

product:modelname:nickname:resolution:mfmode

The file is read top to bottom until a match is found or the end is reached. The information from the PPD file is compared to the first four fields of each line. A * may be used as a wildcard in any or all of the first four fields. When a match is found, the value from the fifth field is used as the value for the default filter option mfmode=.

LaserJet 4:*:*:*:ljfour

*:Dot Matrix 24 pin Ghostscript:*:*:NEChi
*:HP LaserJet III Ghostscript:*:*:CanonCX
*:HP DeskJet 500 Ghostscript:*:*:HPDeskJet

*:HP LaserJet III Ghostscript:*:300dpi:CanonCX
*:HP LaserJet III Ghostscript 150DPI:*:150dpi:ljlo

*:*:*:300dpi:CanonCX
*:*:*:600dpi:ljfour
*:*:*:360dpi:NEChi

Once the job submission program ppr has created the queue files it sends a command to pprd telling it that the job is there and is ready for printing or transfer to the remote system. This command takes the form:

j destination_node destination_queue id subid home_node initial_priority

The destination_node is the node to which the job should be sent. Since transmission to remote notes is not yet supported, this will always be the name of the local node. The destination_queue is the name of the print queue on the destination node. The id and subid are the queue id and the job fragment number respectively. The subid will most often be zero. The home_node is the node name of the system on which the job originated (again, the local node).

Whenever a printer or group configuration file is modified or a new one created, pprd must be directed to read it. To inform pprd that it must read a new or revised printer configuration file, a command line of this form is sent:

NP printername

To indicate that a group configuration file must be re-read or that a new group configuration file must be read for the first time:

NG groupname

Neither command is acknowledged by pprd.

The utility ppop must communicate with pprd in order to list the queue, show the status of printers, mount forms, and do other tasks. Most of these communications take the form of a query and a reply.

As currently implemented, the interprocess communications is crude but effective. The queries are sent by writing to pprd's named pipe. The replies are sent back in temporary files. The command which ppop writes to the name pipe begin with ppop's process id. After writing the command, ppop waits for a signal, USR1 to be specific. The process ID is read by ppad which creates a temporary file called /tmp/ppr-ppop-pid where pid is the process id sent by ppop. Once pprd has finished writing the reply, it closes the temporary file and sends SIGUSR1 to ppop which opens the file, deletes it, reads its contents, and formats and displays said contents.

Many of the replies take the form of a numberic exit code for ppop and a human-language message to display. Some include many additional lines of results but only if the code in the first line is zero (indicating success).

Much of the code in the parts of ppop and pprd which communication with one another was written before any attempt was mode to internationalize PPR. This is a problem because pprd may be generating messages in one language while ppop is generating them in another. The plan is to eventually eliminate all user visible messages from these files leaving only code information. At the same time ppop will be modified to digest this information and produce text in the users language.