CUPS provides a portable printing layer for UNIX®-based operating systems. It has been developed by Easy Software Products to promote a standard printing solution for all UNIX vendors and users. CUPS provides the System V and Berkeley command-line interfaces.

CUPS uses the Internet Printing Protocol ("IPP") as the basis for managing print jobs and queues. The Line Printer Daemon ("LPD") Server Message Block ("SMB"), and AppSocket (a.k.a. JetDirect) protocols are also supported with reduced functionality. CUPS adds network printer browsing and PostScript Printer Description ("PPD") based printing options to support real-world printing under UNIX.

CUPS includes an image file RIP that supports printing of image files to non-PostScript printers. A customized version of GNU Ghostscript 7.05 for CUPS called ESP Ghostscript is available separately to support printing of PostScript files within the CUPS driver framework. Sample drivers for Dymo, EPSON, HP, and OKIDATA printers are included that use these filters.

Drivers for thousands of printers are provided with our ESP Print Pro software, available at:

    http://www.easysw.com/printpro/

CUPS is licensed under the GNU General Public License and GNU Library General Public License. Please contact Easy Software Products for commercial support and "binary distribution" rights.

Document Overview

This software programmers manual is organized into the following sections:

1 - Printing System Overview
2 - The CUPS API
3 - Writing Filters
4 - Writing Printer Drivers
5 - Writing Backends
A - Software License Agreement
B - Constants
C - Structures
D - Functions

Notation Conventions

Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below:

Example		Description

`lpstat` `lpstat(1)`		The names of commands; the first mention of a command or function in a chapter is followed by a manual page section number.

`/var` `/usr/share/cups/data/testprint.ps`		File and directory names.

`Request ID is Printer-123`		Screen output.

`lp -d printer filename ENTER`		Literal user input; special keys like `ENTER` are in ALL CAPS.

12.3		Numbers in the text are written using the period (.) to indicate the decimal point.

Abbreviations

The following abbreviations are used throughout this manual:

kb: Kilobytes, or 1024 bytes
Mb: Megabytes, or 1048576 bytes
Gb: Gigabytes, or 1073741824 bytes

Other References

CUPS Software Administrators Manual: An administration guide for the CUPS software.
CUPS Software Users Manual: An end-user guide for using the CUPS software.

1 - Printing System Overview

This chapter provides an overview of how the Common UNIX Printing System works.

The Printing Problem

For years the printing problem has plagued UNIX. Unlike Microsoft® Windows® or Mac OS, UNIX has no standard interface or system in place for supporting printers. Among the solutions currently available, the Berkeley and System V printing systems are the most prevalent.

These printing systems support line printers (text only) or PostScript printers (text and graphics), and with some coaxing they can be made to support a full range of printers and file formats. However, because each varient of the UNIX operating system uses a different printing system than the next developing printer drivers for a wide range of printers and operating systems is extremely difficult. That combined with the limited volume of customers for each UNIX varient has forced most printer vendors to give up supporting UNIX entirely.

CUPS is designed to eliminate the printing problem. One common printing system can be used by all UNIX varients to support the printing needs of users. Printer vendors can use its modular filter interface to develop a single driver program that supports a wide range of file formats with little or no effort. Since CUPS provides both the System V and Berkeley printing commands, users (and applications) can reap the benefits of this new technology with no changes.

The Technology

CUPS is based upon an emerging Internet standard called the Internet Printing Protocol. IPP has been embraced by dozens of printer and printer server manufacturers and is supported by Microsoft Windows 2000.

IPP defines a standard protocol for printing as well as managing print jobs and printer options like media size, resolution, and so forth. Like all IP-based protocols, IPP can be used locally or over the Internet to printers hundreds or thousands of miles away. Unlike other protocols, however, IPP also supports access control, authentication, and encryption, making it a much more capable and secure printing solution than older ones.

IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") which is the basis of web servers on the Internet. This allows users to view documentation, check status information on a printer or server, and manage their printers, classes, and jobs using their web browser.

CUPS provides a complete IPP/1.1 based printing system that provides Basic, Digest, and local certificate authentication and user, domain, or IP-based access control. TLS encryption will be available in future versions of CUPS.

Jobs

Each file or set of files that is submitted for printing is called a job. Jobs are identified by a unique number starting at 1 and are assigned to a particular destination, usually a printer. Jobs can also have options associated with them such as media size, number of copies, and priority.

Classes

CUPS supports collections of printers known as classes. Jobs sent to a class are forwarded to the first available printer in the class.

Filters

Filters allow a user or application to print many types of files without extra effort. Print jobs sent to a CUPS server are filtered before sending them to a printer. Some filters convert job files to different formats that the printer can understand. Others perform page selection and ordering tasks.

CUPS provides filters for printing many types of image files, HP-GL/2 files, PDF files, and text files. CUPS also supplies PostScript and image file Raster Image Processor ("RIP") filters that convert PostScript or image files into bitmaps that can be sent to a raster printer.

Backends

Backends perform the most important task of all - they send the filtered print data to the printer.

CUPS provides backends for printing over parallel, serial, and USB ports, and over the network via the IPP, JetDirect (AppSocket), and Line Printer Daemon ("LPD") protocols. Additional backends are available in network service packages such as the SMB backend included with the popular SAMBA software.

Backends are also used to determine the available devices. On startup each backend is asked for a list of devices it supports, and any information that is available. This allows the parallel backend to tell CUPS that an EPSON Stylus Color 600 printer is attached to parallel port 1, for example.

Printer Drivers

Printer drivers in CUPS consist of one of more filters specific to a printer. CUPS includes sample printer drivers for Hewlett-Packard LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, and Stylus Photo printers. While these drivers do not generate optimal output for the different printer models, they do provide basic printing and demonstrate how you can write your own printer drivers and incorporate them into CUPS.

Networking

Printers and classes on the local system are automatically shared with other systems on the network. This allows you to setup one system to print to a printer and use this system as a printer server or spool host for all of the others. Users may then select a local printer by name or a remote printer using "name@server".

CUPS also provides implicit classes, which are collections of printers and/or classes with the same name. This allows you to setup multiple servers pointing to the same physical network printer, for example, so that you aren't relying on a single system for printing. Because this also works with printer classes, you can setup multiple servers and printers and never worry about a single point of failure unless all of the printers and servers go down!

2 - The CUPS API

This chapter describes the CUPS Application Programmers Interface ("API").

The CUPS API Library

The CUPS library provides a whole collection of interfaces needed to support the internal needs of the CUPS software as well as the needs of applications, filters, printer drivers, and backends.

Unlike the rest of CUPS, the CUPS API library is provided under the GNU Library General Public License. This means that you can use the CUPS API library in both proprietary and open-source programs.

Programs that use the CUPS API library typically will include the <cups/cups.h> header file:

#include <cups/cups.h>

...

jobid = cupsPrintFile("myprinter", "filename.ps", "title",
                      num_options, options);

Use the -lcups compiler option when linking to the CUPS API library:

cc -o program program.c -lcups ENTER

Additional options and libraries may be required depending on the operating system and the location of the CUPS API library.

Detecting the CUPS API Library in GNU Autoconf

GNU autoconf is a popular configuration tool used by many programs. Add the following lines to your configure.in file to check for the CUPS API library in your configuration script:

AC_CHECK_LIB(socket,socket,
if test "$uname" != "IRIX"; then
	LIBS="-lsocket $LIBS"
else
	echo "Not using -lsocket since you are running IRIX."
fi)
AC_CHECK_LIB(nsl,gethostbyaddr,
if test "$uname" != "IRIX"; then
	LIBS="-lnsl $LIBS"
else
	echo "Not using -lnsl since you are running IRIX."
fi)

AC_CHECK_LIB(cups,httpConnect)

Printing Services

The CUPS API library provides some basic printing services for applications that need to print files.

Include Files

The include file used by all of these functions is <cups/cups.h>:

#include <cups/cups.h>

Printing a File

The CUPS API provides two functions for printing files. The first is cupsPrintFile which prints a single named file:

#include <cups/cups.h>

...

int jobid;

...

jobid = cupsPrintFile("name", "filename", "title", 0, NULL);

The name string is the name of the printer or class to print to. The filename string is the name of the file to print. The title string is the name of the print job, e.g. "Acme Word Document".

The return value is a unique ID number for the print job or 0 if there was an error.

Printing Multiple Files

The second printing function is cupsPrintFiles:

#include <cups/cups.h>

...

int        jobid;
int        num_files;
const char *files[100];
...

jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL);

Instead of passing a filename string as with cupsPrintFile() you pass a file count (num_files) and filename pointer array (files) for each file that you want to print.

As with cupsPrintFile() the return value is a unique ID for the print job.

Cancelling Jobs

The cupsCancelJob() function cancels a queued print job:

#include <cups/cups.h>

...

int jobid;
int status;
...

status = cupsCancelJob("name", jobid);

The name string specifies the destination and is used to determine the server to send the request to. The jobid value is the integer returned from a previous cupsPrintFile() or cupsPrintFiles() call.

cupsCancelJob() returns 1 if the job was successfully cancelled and 0 if there was an error.

Getting the Available Printers and Classes

The cupsGetDests() function can be used to get a list of the available printers, classes, and instances that a user has defined:

#include <cups/cups.h>

...

int         num_dests;
cups_dest_t *dests;

...

num_dests = cupsGetDests(&dests);

Each destination is stored in a cups_dest_t structure which defines the printer or class name, the instance name (if any), if it is the default destination, and the default options the user has defined for the destination:

typedef struct               /**** Destination ****/
{
  char          *name,       /* Printer or class name */
                *instance;   /* Local instance name or NULL */
  int           is_default;  /* Is this printer the default? */
  int           num_options; /* Number of options */
  cups_option_t *options;    /* Options */
} cups_dest_t;

The destinations are sorted by name and instance for your convenience. Once you have the list of available destinations, you can lookup a specific destination using the cupsGetDest() function:

#include <cups/cups.h>

...

int         num_dests;
cups_dest_t *dests;
cups_dest_t *mydest;

...

mydest = cupsGetDest("name", "instance", num_dests, dests);

The name string is the printer or class name. You can pass a value of NULL to get the default destination.

The instance string is the user-defined instance name. Pass NULL to select the default instance, e.g. "name" instead of "name/instance".

Printing with Options

All of the previous printing examples have passed 0 and NULL for the last two arguments to the cupsPrintFile() and cupsPrintFiles() functions. These last two arguments are the number of options and a pointer to the option array:

int cupsPrintFile(const char *name, const char *filename, const char *title,
                  int num_options, cups_option_t *options);
int cupsPrintFiles(const char *name, int num_files, const char **files,
                   const char *title, int num_options,
		   cups_option_t *options);

The cups_option_t structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file.

The simplest way of handling options is to use the num_options and options members of the cups_dest_t structure described earlier:

#include <cups/cups.h>

...

int         jobid;
int         num_dests;
cups_dest_t *dests;
cups_dest_t *mydest;

...

mydest = cupsGetDest("name", "instance", num_dests, dests);

jobid  = cupsPrintFile(mydest->name, "filename", "title",
                       mydest->num_options, mydest->options);

This effectively uses the options a user has previous selected without a lot of code.

Setting Printer Options

Options can also be set by your program using the cupsAddOption() function:

#include <cups/cups.h>

...

int           num_options;
cups_option_t *options;

...

num_options = 0;
options     = NULL;

...

num_options = cupsAddOption("name", "value", num_options, &options);
num_options = cupsAddOption("name", "value", num_options, &options);
num_options = cupsAddOption("name", "value", num_options, &options);
num_options = cupsAddOption("name", "value", num_options, &options);

The name string is the name of the option, and the value string is the value for that option.

Each call to cupsAddOption() returns the new number of options. Since adding two options with the same name overwrites the first value with the second, do not assume that calling cupsAddOptions() 20 times will result in 20 options.

Call cupsFreeOptions once you are done using the options:

#include <cups/cups.h>

...

int           num_options;
cups_option_t *options;

...

cupsFreeOptions(num_options, options);

Getting Errors

If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling cupsLastError() and ippErrorString(). cupsLastError() returns the last IPP error code that was encountered. ippErrorString() converts the error code to a localized message string suitable for presentation to the user:

#include <cups/cups.h>

...

int jobid;

...

if (jobid == 0)
  puts(ippErrorString(cupsLastError()));

Passwords and Authentication

CUPS supports authentication of any request, including submission of print jobs. The default mechanism for getting the username and password is to use the login user and a password from the console.

To support other types of applications, in particular Graphical User Interfaces ("GUIs"), the CUPS API provides functions to set the default username and to register a callback function that returns a password string.

The cupsSetPasswordCB() function is used to set a password callback in your program. Only one function can be used at any time.

The cupsSetUser() function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed.

The following example shows a simple password callback that gets a username and password from the user:

#include <cups/cups.h>

const char *
my_password_cb(const char *prompt)
{
  char	user[65];


  puts(prompt);

 /* Get a username from the user */
  printf("Username: ");
  if (fgets(user, sizeof(user), stdin) == NULL)
    return (NULL);

 /* Strip the newline from the string and set the user */
  user[strlen(user) - 1] = '\0';

  cupsSetUser(user);

 /* Use getpass() to ask for the password... */
  return (getpass("Password: "));
}

...

cupsSetPasswordCB(my_password_cb);

Similarly, a GUI interface could display the prompt string in a window with input fields for the username and password. The username should probably default to the value of cupsUser() to make things easier on the user.

PPD Services

CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS.

Each PPD file enumerates the available features provided by a printer, including conflict information for specific options (e.g. can't duplex output on envelopes.)

Include Files

Include the <cups/ppd.h> header file to use the PPD functions:

#include <cups/ppd.h>

This header file is also included by the <cups/cups.h> header file.

Getting a PPD File for a Printer

The cupsGetPPD() function retrieves the PPD file for the named printer or class:

#include <cups/cups.h>

...

const char *filename;

filename = cupsGetPPD("name");

The name string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".)

The return value is a pointer to a filename in static storage; this value is overwritten with each call to cupsGetPPD(). If the printer or class does not exist, a NULL pointer will be returned.

Loading a PPD File

The ppdOpenFile() function "opens" a PPD file and loads it into memory:

#include <cups/ppd.h>

...

ppd_file_t *ppd;

ppd = ppdOpenFile("filename");

The filename string is the name of the file to load, such as the value returned by the cupsGetPPD() function.

The return value is a pointer to a structure describing the contents of the PPD file or NULL if the PPD file could not be read.

Freeing PPD File Information

Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used:

#include <cups/ppd.h>

...

ppd_file_t *ppd;

...

ppdClose(ppd);

The PPD File Structure

Each PPD file contains a number of capability attributes, printer options, and conflict definitions. The page size options also include the physical margins for the printer and the minimum and maximum sizes for the printer. All of this information is stored in the ppd_file_t structure.

Capabilities

Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the ppd_file_t structure in the following members:

Member	Type	Description
`accurate_screens`	`int`	1 = supports accurate screens
`color_device`	`int`	1 = color device
`colorspace`	`ppd_cs_t`	Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N
`contone_only`	`int`	1 = printer is continuous tone only
`num_emulations emulations`	`int ppd_emul_t *`	Emulations supported by the printer
`flip_duplex`	`int`	1 = need to flip odd pages when duplexing
`num_fonts fonts`	`int char **`	The fonts available on the printer.
`jcl_begin jcl_ps jcl_end`	`char *`	Job Control Language commands for PostScript output
`landscape`	`int`	Landscape orientation, -90 or 90 degrees
`lang_encoding`	`char *`	The character used for the option strings
`lang_version`	`char *`	The language used for the options strings (English, French, etc.)
`language_level`	`int`	PostScript language level, 1 to 3
`manual_copies`	`int`	1 = Copies are done manually
`model_number`	`int`	Driver-specific model number.
`patches`	`char *`	Patch commands to send to the printer
`manufacturer`	`char *`	The Manufacturer attribute from the PPD file, if any
`modelname`	`char *`	The ModelName attribute from the PPD file
`nickname`	`char *`	The NickName attribute from the PPD file, if any
`product`	`char *`	The Product attribute from the PPD file, if any
`shortnickname`	`char *`	The ShortNickName attribute from the PPD file, if any
`throughput`	`int`	Number of pages per minute
`ttrasterizer`	`char *`	The TruType font rasterizer (Type42)
`variable_sizes`	`int`	1 = supports variable sizes

Options and Groups

PPD files support multiple options, which are stored in ppd_option_t and ppd_choice_t structures by the PPD functions.

Each option in turn is associated with a group stored in the ppd_group_t structure. Groups can be specified in the PPD file; if an option is not associated with a group then it is put in a "General" or "Extra" group depending on the option.

Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity.

Conflicts

PPD files support specification of conflict conditions between different options. Conflicts are stored in ppd_conflict_t structures which specify the options that conflict with each other.

Page Sizes

PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in ppd_size_t structures and are available in the num_sizes and sizes members of the ppd_file_t structure. You can lookup a particular page size with the ppdPageWidth(), ppdPageLength(), and ppdPageSize() functions:

#include <cups/ppd.h>

...

ppd_file_t *ppd;
ppd_size_t *size;
float      width;
float      length;

...

size   = ppdPageSize(ppd, "size");
width  = ppdPageWidth(ppd, "size");
length = ppdPageLength(ppd, "size");

The size string is the named page size option. The width and length are in points; there are 72 points per inch. The ppd_size_t structure contains the width, length, and margin information:

typedef struct    /**** Page Sizes ****/
{
  int   marked;   /* Page size selected? */
  char  name[41]; /* Media size option */
  float width,    /* Width of media in points */
        length,   /* Length of media in points */
        left,     /* Left printable margin in points */
        bottom,   /* Bottom printable margin in points */
        right,    /* Right printable margin in points */
        top;      /* Top printable margin in points */
} ppd_size_t;

Custom Page Sizes

Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If variables_sizes is non-zero, the custom_min, custom_max, and custom_margins members of the ppd_file_t structure define the limits of the variable sizes.

To get the resulting media size, use a page size string of Custom.widthxlength, where width and length are integer values in points:

Custom.612x792   [8.5 inches wide, 11 inches long]
Custom.1224x792  [17 inches wide, 11 inches long]

Marking Options

Before marking any user-defined options, call the ppdMarkDefaults() function to mark the default options from the PPD file:

#include <cups/ppd.h>

...

ppd_file_t *ppd;

...

ppdMarkDefaults(ppd);

Then call the ppdMarkOption() function to mark individual options:

#include <cups/ppd.h>

...

ppd_file_t *ppd;
int        conflicts;

...

conflicts = ppdMarkOption(ppd, "name", "value");

The name and value strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection.

CUPS also provides a convenience function for marking all options in the cups_option_t structure:

#include <cups/cups.h>

...

ppd_file_t    *ppd;
int           num_options;
cups_option_t *options;
int           conflicts;

...

conflicts = cupsMarkOptions(ppd, num_options, options);

The cupsMarkOptions() function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present.

Checking for Conflicts

The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked options.

Call the ppdConflicts() function to get the number of conflicts after you have marked all of the options:

#include <cups/cups.h>

...

ppd_file_t *ppd;
int        conflicts;

...

conflicts = ppdConflicts(ppd);

The return value is the number of conflicting options, or 0 if there are no conflicts.

3 - Writing Filters

This chapter describes how to write a file filter for CUPS.

Overview

File filters are programs that convert from one or more MIME types to another type. Filters use a common command-line and environment interface that allows them to be joined as needed to print files to any type of printer.

Security Considerations

Filters are normally run as a non-priviledged user, so the major security consideration is resource utilization - filters should not depend on unlimited amounts of memory and disk space.

Users and Groups

The default CUPS configuration runs filters as user "lp" and group "other".

Temporary Files

Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The cupsTempFile() function can be used to safely choose temporary files in this directory.

Sending Messages to the User

The CUPS scheduler collects messages sent to the standard error file by the filter. These messages are relayed to the user based upon the scheduler LogLevel directive.

The type of message is determined by an initial prefix sent on each line:

DEBUG: - a debug message
INFO: - an informational message
WARNING: - a warning message
ERROR: - an error message
PAGE: - a page accounting message

If the line of text does not begin with any of the above prefixes, it is treated as a debug message. Text following the prefix is copied to the printer-state-message attribute for the printer, and also added to the error_log unless it is an informational or page accounting message.

Page Accounting

Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form:

PAGE: page-number copy-count

The page-number field is the current page number, starting at 1. The copy-count field specifies the number of copies of that page that was produced.

Page account messages are added to the page_log file and cause the job-sheets-completed attribute to be updated for the job.

Command-Line Arguments

Every filter accepts exactly 6 or 7 command-line arguments:

printer job user title copies options [filename]

printer - The name of the printer queue (normally this is the name of the program being run)
job - The numeric job ID for the job being printed
user - The string from the originating-user-name attribute
title - The string from the job-name attribute
copies - The numeric value from the number-copies attribute
options - String representations of the job template attributes, separated by spaces. Boolean attributes are provided as "name" for true values and "noname" for false values. All other attributes are provided as "name=value" for single-valued attributes and "name=value1,value2,...,valueN" for set attributes
filename - The request file

The filename argument is only provided to the first filter in the chain; all filters must be prepared to read the print file from the standard input if the filename argument is omitted.

Copy Generation

The copies argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the filename argument is supplied. The only exception to this are filters that produce device-independent PostScript output (without any printer commands from the printer's PPD file), since the PostScript filter pstops is responsible for copy generation.

Environment Variables

Every filter receives a fixed set of environment variables that can be used by the filter:

CHARSET - The character set used by the client for this print file
CONTENT_TYPE - The original document type, such as "application/postscript"
CUPS_DATADIR - The location of CUPS data files
CUPS_SERVERROOT - The location of CUPS configuration files
DEVICE_URI - The output device URI
LANG - The language used by the client for this print file
PATH - The execution path exported to the filter
PPD - The full filename of the printer's PPD file
PRINTER - The name of the printer queue
RIP_CACHE - The maximum amount of memory each filter should use
SOFTWARE - The name of the CUPS software, typically "CUPS/1.1"
TZ - The local timezone
USER - The name of the current user

Dissecting the HP-GL/2 Filter

The HP-GL/2 filter (hpgltops) provided with CUPS is a complex program that converts HP-GL/2 files into device-independent PostScript output. Since it produces device-independent PostScript output, it does not need to handle copy generation or writing printer options from the printer's PPD file.

Initializing the Filter

The first task of any filter is to ensure that the correct number of command-line arguments are present:

if (argc < 6 || argc > 7)
{
  fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
  return (1);
}

After this you open the print file or read from the standard input as needed:

FILE *fp;

/*
 * If we have 7 arguments, print the file named on the command-line.
 * Otherwise, send stdin instead...
 */

if (argc == 6)
  fp = stdin;
else
{
 /*
  * Try to open the print file...
  */

  if ((fp = fopen(argv[6], "rb")) == NULL)
  {
    perror("ERROR: unable to open print file - ");
    return (1);
  }
}

Once the print file has been opened, options can be processed using the cupsParseOptions() and cupsGetOption() functions:

int           num_options;
cups_option_t *options;
const char    *val;

/*
 * Process command-line options and write the prolog...
 */

options     = NULL;
num_options = cupsParseOptions(argv[5], 0, &options);

if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
  shading = 0;

if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
  FitPlot = 1;

if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
  PenWidth = (float)atoi(val) * 0.001f;

After the options have been processed, the filter writes PostScript code to the standard output based on the print file, closes the print file (as needed), and returns 0 to the scheduler.

PostScript Output

Filters that produce PostScript output must generate output conforming to the Adobe Document Structuring Conventions, 3.0. In general this means the beginning of each file must begin with:

%!PS-Adobe-3.0
%%BoundingBox: left bottom right top
%%Pages: (atend)
%%EndComments

The left, bottom, right, and top values are integers in points from the lower-lefthand corner of the page.

Pages must be surrounded by:

%%Page: number number
gsave
...
grestore
showpage

And the end of each file must contain:

%%Trailer
%%Pages: number-pages
%%EOF

These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth.

4 - Writing Printer Drivers

This chapter discusses how to write a printer driver, which is a special filter program that converts CUPS raster data into the appropriate commands and data required for a printer.

Overview

Raster printers utilitize PPD files that specify one or more device-specific filters that handle converting print files for the printer. The simplest raster printer drivers provide a single filter that converts CUPS raster data to the printer's native format.

CUPS Raster Data

CUPS raster data (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters, such as pstoraster or imagetoraster.

Each page of data begins with a page dictionary structure called cups_raster_header_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth.

After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace.

Page Accounting

Printer drivers must handle all page accounting. This means they must send "PAGE:" messages to the standard error file for each page (and in many cases, copy) sent to the printer.

Color Management

Printer drivers can implement their color management via the cupsColorProfile attributes in the PPD file or internally in the driver from a device-independent colorspace. In general, color management performed by the RIP filters is more efficient than that performed inside printer drivers.

For example, the pstoraster filter often only has to perform a color conversion once each time the color is used for multiple output pixels, while the raster filter must convert every pixel on the page.

Device and Bitmap Variables

Besides the standard PostScript page device dictionary variables defined in the Adobe PostScript Level 3 reference manual, the CUPS filters support additional variables that are passed in the page device dictionary header for the page and in some cases control the type of raster data that is generated:

Variable	Type	Description
cupsWidth	read-only integer	Width of bitmap in pixels
cupsHeight	read-only integer	Height of bitmap in pixels
cupsMediaType	read-write integer	Device-specific media type code
cupsBitsPerColor	read-write integer	Number of bits per color; 1, 2, 4, and 8 are currently supported
cupsBitsPerPixel	read-only integer	Number of bits per pixel; 1 to 32
cupsBytesPerLine	read-only integer	Number of bytes per line of raster graphics
cupsColorOrder	read-write enum	The order of color values in the bitmap: `CUPS_ORDER_CHUNKED` - CMYK CMYK CMYK `CUPS_ORDER_BANDED` - CCC MMM YYY KKK `CUPS_ORDER_PLANAR` - CCC ... MMM ... YYY ... KKK ...
cupsColorSpace	read-write enum	The colorspace of the bitmap: `CUPS_CSPACE_W` - White (luminance) `CUPS_CSPACE_RGB` - Red, green, blue `CUPS_CSPACE_RGBA` - Red, green, blue, alpha `CUPS_CSPACE_K` - Black `CUPS_CSPACE_CMY` - Cyan, magenta, yellow `CUPS_CSPACE_YMC` - Yellow, magenta, cyan `CUPS_CSPACE_CMYK` - Cyan, magenta, yellow, black `CUPS_CSPACE_YMCK` - Yellow, magenta, cyan, black `CUPS_CSPACE_KCMY` - Black, cyan, magenta, yellow `CUPS_CSPACE_KCMYcm` - Black, cyan, magenta, yellow, light cyan, light magenta `CUPS_CSPACE_GMCK` - Metallic yellow (gold), metallic magenta, metallic cyan, black `CUPS_CSPACE_GMCS` - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver) `CUPS_CSPACE_WHITE` - White pigment (black as white pigment) `CUPS_CSPACE_GOLD` - Gold foil (black as gold foil) `CUPS_CSPACE_SILVER` - Silver foil (black as silver foil)
cupsCompression	read-write integer	Device-specific compression type code
cupsRowCount	read-write integer	Device-specific row count value
cupsRowFeed	read-write integer	Device-specific row feed value
cupsRowStep	read-write integer	Device-specific row step value

Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per color are transmitted to the raster driver in KCMY colorspace; the driver is responsible for producing the correct separation of normal and light cyan and magenta inks.

Dissecting the HP-PCL Driver

The HP-PCL driver provided with CUPS (rastertohp) converts bitmap data from the raster filters into HP-PCL commands for most PCL-compatible printers. The actual format of the raster data is controlled by the PPD file being used - deskjet.ppd orlaserjet.ppd.

PPD Files

PPD files play an important part of all raster printer drivers. Options defined in the PPD file contain PostScript commands that control the raster data that is sent to the printer driver.

A typical CUPS printer driver will include ColorModel, InputSlot, PageSize, PageRegion, and Resolution options. Each option is shown using the standard PPD format:

*OpenUI *PageSize/Media Size: PickOne
*OrderDependency: 10 AnySetup *PageSize
*DefaultPageSize: Letter
*PageSize Letter/US Letter: "<<
/PageSize [612 792]
/ImagingBBox null
>> setpagedevice"
*End
*PageSize Legal/US Legal: "<<
/PageSize [612 1008]
/ImagingBBox null
>> setpagedevice"
*End
*PageSize A4/A4: "<<
/PageSize [595 842]
/ImagingBBox null
>> setpagedevice"
*End
*CloseUI: *PageSize

The OpenUI keyword specifies the new option. The first name is the option with an asterisk (*) in front of it. The first name is usually followed by a slash (/) and a human-readable version of the option name.

Every option must have a default value, specified using the DefaultOption keyword.

Each option begins with the option name followed by the computer and human-readable values. The PostScript commands follow these inside double quotes. PostScript commands can be provided on a single line:

*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"

or broken down on separate lines using the End keyword to terminate them:

*PageSize A4/A4: "<<
/PageSize [595 842]
/ImagingBBox null
>> setpagedevice"
*End