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.