CUPS Software Programmers Manual
CUPS-SPM-1.1.21
Easy Software Products
Copyright 1997-2004, All Rights Reserved
This software programmers manual provides software programming information for the Common UNIX Printing System ("CUPS") Version 1.1.21.
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.
This software programmers manual is organized into the following sections:
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. |
This chapter provides an overview of how the Common UNIX Printing System works.
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.
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.
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.
CUPS supports collections of printers known as classes. Jobs sent to a class are forwarded to the first available printer in the class.
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 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 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.
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!
This chapter describes the CUPS Application Programmers Interface ("API").
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.
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)
The CUPS API library provides some basic printing services for applications that need to print files.
The include file used by all of these functions is
<cups/cups.h>:
#include <cups/cups.h>
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.
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.
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.
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".
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.
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);
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()));
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.
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 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.
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.
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.
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);
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.
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
| int
| Emulations supported by the printer |
flip_duplex | int | 1 = need to flip odd pages when duplexing |
num_fonts
| int
| The fonts available on the printer. |
jcl_begin
| 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 |
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.
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.
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;
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]
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.
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.
This chapter describes how to write a file filter for CUPS.
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.
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.
The default CUPS configuration runs filters as user "lp" and group "other".
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.
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 messageINFO: - an informational messageWARNING: - a warning messageERROR: - an error messagePAGE: - a page accounting messageIf 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 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.
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 printeduser - The string from the originating-user-name
attributetitle - The string from the job-name
attributecopies - The numeric value from the number-copies
attributeoptions - 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 attributesfilename - The request fileThe 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.
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.
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 fileCONTENT_TYPE - The original document type, such as
"application/postscript"CUPS_DATADIR - The location of CUPS data filesCUPS_SERVERROOT - The location of CUPS configuration
filesDEVICE_URI - The output device URILANG - The language used by the client for this print
filePATH - The execution path exported to the filterPPD - The full filename of the printer's PPD filePRINTER - The name of the printer queueRIP_CACHE - The maximum amount of memory each filter
should useSOFTWARE - The name of the CUPS software, typically
"CUPS/1.1"TZ - The local timezoneUSER - The name of the current userThe 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.
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.
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.
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.
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 (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.
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.
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.
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:
|
| cupsColorSpace | read-write enum | The colorspace of
the bitmap:
|
| 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.
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 or
laserjet.ppd.
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
The choice of the two formats is usually esthetic. However, each line in a PPD file must not exceed 255 characters, so if your PostScript commands are long you may need to break them up on separate lines.
As with any filter, your printer driver should handle raster data
from a filename specified on the command-line or from the standard
input. The cupsRasterOpen()
function opens a raster stream for printing:
int fd; /* File descriptor */
cups_raster_t *ras; /* Raster stream for printing */
/*
* Check for valid arguments...
*/
if (argc < 6 || argc > 7)
{
/*
* We don't have the correct number of arguments; write an error message
* and return.
*/
fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
return (1);
}
/*
* Open the page stream...
*/
if (argc == 7)
{
if ((fd = open(argv[6], O_RDONLY)) == -1)
{
perror("ERROR: Unable to open raster file - ");
sleep(1);
return (1);
}
}
else
fd = 0;
ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
Once you have opened the raster stream you just need to read each page and print it:
cups_raster_header_t header;
int y;
unsigned char data[8192];
while (cupsRasterReadHeader(ras, &header))
{
... initialize the printer ...
for (y = header.cupsHeight; y > 0; y ++)
{
cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
... send raster line to printer ...
}
}
After you have processed all pages, close the raster stream and return:
cupsRasterClose(ras); return (0);
This chapter describes how to write a backend for CUPS. Backends communicate directly with printers and allow printer drivers and filters to send data using any type of connection transparently.
Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements.
Backends are run as the root user, so special care must be taken to avoid potential security violations. In particular, remember that a backend will be able to manipulate disk files, devices, and other resources that potentially could damage a system or printer.
Besides the standard filter arguments, backends are also run with no arguments to get a list of available devices. This discovery process is described later in this chapter.
Like filters, backends should send multiple copies of the print file only if a filename is supplied on the command-line. Otherwise the backend should assume that the upstream filter has already added the necessary commands or data to produce the multiple copies.
Backend filters generally do not do page accounting, however they should at a minimum produce a single page message for each copy that is produced when a filename is present on the command-line. This is because the user selected "raw" printing and no other accounting information is possible.
Backends that talk to local character or block devices should open
the device file in exclusive mode (O_EXCL) to cooperate
with other printers defined for the same device.
All backends must retry connections to the device. This includes backends that talk to local character or block devices, as the user may define more than one printer queue pointing at the same physical device.
To prevent excess CPU utilitization, the backend should go to sleep for an amount of time between retries; the CUPS-supplied backends retry once every 30 seconds.
The serial port backend provides support for serial printers. Since it does everything a good backend needs to do, it provides an excellent example of what to do.
As previously noted, backends are special filter programs that talk to printer devices. Another task a backend must perform is to list the available devices it supports. The backend lists the available devices when no additioanl arguments are supplied on the command-line (i.e. just the command name...)
The serial backend lists devices by looking at serial port files in the /dev directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist.
Once it finds a serial port it writes a single line for each port to the standard output file. Each line looks like this:
serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
The first word "serial" is the device class; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes:
After the device class is the device URI, in this case "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by the user to select this port. For serial ports, the "baud=115200" specifies the maximum baud rate supported by the port - the actual value will vary based on the speed the user selects for the printer.
The last two strings are the model and description for the port. The "Unknown" string means that the printer model is unknown - some devices are able to provide a make and model such as "HP DeskJet" that allows users and software to choose an appropriate printer driver more easily. Both the model and description must be enclosed inside double quotes.
As noted previously, all backends should open device files in
exclusive mode, and retry as needed until the port is available. The
serial port does this using a do-while loop:
do
{
if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
{
if (errno == EBUSY)
{
fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
sleep(30);
}
else
{
perror("ERROR: Unable to open serial port device file");
return (1);
}
}
}
while (fd < 0);
If the port is busy or in use by another process, the backend will go to sleep for 30 seconds and try again. If another error is detected a message is sent to the user and the backend aborts the print job until the problem can be corrected.
Network and character devices pose an interesting problem when writing data to the port - they may not be able to write all of the bytes in your buffer before returning. To work around this problem you must loop until all bytes have been written:
while (nbytes > 0)
{
if ((wbytes = write(fd, bufptr, nbytes)) < 0)
if (errno == ENOTTY)
wbytes = write(fd, bufptr, nbytes);
if (wbytes < 0)
{
perror("ERROR: Unable to send print file to printer");
break;
}
nbytes -= wbytes;
bufptr += wbytes;
}
The check for the ENOTTY error is needed on some
platforms to clear an error from a previous ioctl() call.
Once you have sent the print file, return 0 if the file printed successfully or 1 if it did not. This will allow the scheduler to stop the print job if there is a device error, preserving the print job for later printing once the problem has been corrected.
Copyright 1997-2004 by Easy Software Products
44141 AIRPORT VIEW DR STE 204
HOLLYWOOD, MARYLAND 20636-3142 USA
Voice: +1.301.373.9600
Email: cups-info@cups.org
WWW: http://www.cups.org
The Common UNIX Printing SystemTM, ("CUPSTM"), is provided under the GNU General Public License ("GPL") and GNU Library General Public License ("LGPL"), Version 2, with exceptions for Apple operating systems and the OpenSSL toolkit. A copy of the exceptions and licenses follow this introduction.
The GNU LGPL applies to the CUPS API library, located in the "cups" subdirectory of the CUPS source distribution and in the "cups" include directory and library files in the binary distributions. The GNU GPL applies to the remainder of the CUPS distribution, including the "pdftops" filter which is based upon Xpdf and the CUPS imaging library.
For those not familiar with the GNU GPL, the license basically allows you to:
What this license does not allow you to do is make changes or add features to CUPS and then sell a binary distribution without source code. You must provide source for any new drivers, changes, or additions to the software, and all code must be provided under the GPL or LGPL as appropriate. The only exceptions to this are the portions of the CUPS software covered by the Apple operating system license exceptions outlined later in this license agreement.
The GNU LGPL relaxes the "link-to" restriction, allowing you to develop applications that use the CUPS API library under other licenses and/or conditions as appropriate for your application.
In addition, as the copyright holder of CUPS, Easy Software Products grants the following special exceptions:
This file is subject to the Apple OS-Developed Software exception.
No developer is required to provide these exceptions in a derived work.
Easy Software Products has trademarked the Common UNIX Printing System, CUPS, and CUPS logo. You may use these names and logos in any direct port or binary distribution of CUPS. Please contact Easy Software Products for written permission to use them in derivative products. Our intention is to protect the value of these trademarks and ensure that any derivative product meets the same high-quality standards as the original.
Easy Software Products also sells rights to the CUPS source code under a binary distribution license for vendors that are unable to release source code for their drivers, additions, and modifications to CUPS under the GNU GPL and LGPL. For information please contact us at the address shown above.
The Common UNIX Printing System provides a "pdftops" filter that is based on the Xpdf software. For binary distribution licensing of this software, please contact:
Derek B. Noonburg
Email: derekn@foolabs.com
WWW: http://www.foolabs.com/xpdf/
Easy Software Products sells software support for CUPS as well as a commercial printing product based on CUPS called ESP Print Pro. You can find out more at our web site:
http://www.easysw.com/
Version 2, June 1991
Copyright 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
Version 2, June 1991
Copyright (C) 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.]
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.
This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.
For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.
Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.
Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license.
The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.
Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.
However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.
The precise terms and conditions for copying, distribution and modification follow. Pay close