#CONTENTS
CUPS Software Design Description
CUPS Software Design Description
CUPS-SDD-1.1
Easy Software Products
Copyright 1997-2005, All Rights Reserved
Table of Contents
#1
1 Scope
#1_1
1.1 Identification
#1_2
1.2 System Overview
#1_3
1.3 Document Overview
#2
2 References
#2_1
2.1 CUPS Documentation
#2_2
2.2 Other Documents
#3
3 Design Overview
#3_1
3.1 Backends
#3_1_1
3.1.1 ipp
#3_1_2
3.1.2 lpd
#3_1_3
3.1.3 parallel
#3_1_4
3.1.4 serial
#3_1_5
3.1.5 socket
#3_1_6
3.1.6 usb
#3_2
3.2 Berkeley Commands
#3_2_1
3.2.1 lpc
#3_2_2
3.2.2 lpq
#3_2_3
3.2.3 lpr
#3_2_4
3.2.4 lprm
#3_3
3.3 CGI
#3_3_1
3.3.1 admin.cgi
#3_3_2
3.3.2 classes.cgi
#3_3_3
3.3.3 jobs.cgi
#3_3_4
3.3.4 printers.cgi
#3_4
3.4 CUPS Application Programmers Interface
#3_4_1
3.4.1 Convenience Functions
#3_4_2
3.4.2 HTTP Functions
#3_4_3
3.4.3 IPP Functions
#3_4_4
3.4.4 Language Functions
#3_4_5
3.4.5 PPD Functions
#3_5
3.5 CUPS Imaging Library
#3_5_1
3.5.1 Colorspace Conversion Functions
#3_5_2
3.5.2 Color Management Functions
#3_5_3
3.5.3 Image Management Functions
#3_5_4
3.5.4 Scaling Functions
#3_5_5
3.5.5 Image File Functions
#3_5_6
3.5.6 Raster Functions
#3_6
3.6 Daemons
#3_6_1
3.6.1 Line Printer Daemon
#3_6_2
3.6.2 Polling Daemon
#3_7
3.7 Filters
#3_7_1
3.7.1 hpgltops
#3_7_2
3.7.2 imagetops
#3_7_3
3.7.3 imagetoraster
#3_7_4
3.7.4 pdftops
#3_7_5
3.7.5 pstops
#3_7_6
3.7.6 pstoraster
#3_7_7
3.7.7 rastertoepson
#3_7_8
3.7.8 rastertohp
#3_7_9
3.7.9 texttops
#3_8
3.8 Scheduler
#3_8_1
3.8.1 Authorization
#3_8_2
3.8.2 Classes
#3_8_3
3.8.3 Client
#3_8_4
3.8.4 Configuration
#3_8_5
3.8.5 Devices
#3_8_6
3.8.6 Directory Services
#3_8_7
3.8.7 IPP
#3_8_8
3.8.8 Jobs
#3_8_9
3.8.9 Logging
#3_8_10
3.8.10 Main
#3_8_11
3.8.11 MIME
#3_8_12
3.8.12 PPDs
#3_8_13
3.8.13 Printers
#3_9
3.9 System V Commands
#3_9_1
3.9.1 accept
#3_9_2
3.9.2 cancel
#3_9_3
3.9.3 disable
#3_9_4
3.9.4 enable
#3_9_5
3.9.5 lp
#3_9_6
3.9.6 lpadmin
#3_9_7
3.9.7 lpinfo
#3_9_8
3.9.8 lpmove
#3_9_9
3.9.9 lpoptions
#3_9_10
3.9.10 lpstat
#3_9_11
3.9.11 reject
#4
A Glossary
#4_1
A.1 Terms
#4_2
A.2 Acronyms
1 Scope
1.1 Identification
This software design description document provides general information
on the architecture and coding of the Common UNIX Printing System
("CUPS") Version 1.1.
1.2 System Overview
CUPS provides a portable printing layer for UNIX®-based operating
systems. It has been developed by
http://www.easysw.com
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/
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.
1.3 Document Overview
This software design description document is organized into the
following sections:
1 - Scope
2 - References
3 - Design Overview
A - Glossary
2 References
2.1 CUPS Documentation
The following CUPS documentation is referenced by this document:
CUPS-CMP-1.1: CUPS Configuration Management Plan
CUPS-IDD-1.1: CUPS System Interface Design Description
CUPS-IPP-1.1: CUPS Implementation of IPP
CUPS-SAM-1.1.x: CUPS Software Administrators Manual
CUPS-SDD-1.1: CUPS Software Design Description
CUPS-SPM-1.1.x: CUPS Software Programming Manual
CUPS-SSR-1.1: CUPS Software Security Report
CUPS-STP-1.1: CUPS Software Test Plan
CUPS-SUM-1.1.x: CUPS Software Users Manual
CUPS-SVD-1.1: CUPS Software Version Description
2.2 Other Documents
The following non-CUPS documents are referenced by this document:
http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf
Adobe PostScript Printer Description File Format Specification, Version
4.3.
http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf
Adobe PostScript Language Reference, Third Edition.
IPP/1.1: Implementers Guide
http://www.ietf.org/rfc/rfc1179.txt
RFC 1179, Line Printer
Daemon Protocol
http://www.ietf.org/rfc/rfc2396.txt
RFC 2396, Uniform
Resource Identifiers (URI): Generic Syntax
http://www.ietf.org/rfc/rfc2567.txt
RFC 2567, Design Goals
for an Internet Printing Protocol
http://www.ietf.org/rfc/rfc2568.txt
RFC 2568, Rationale
for the Structure of the Model and Protocol for the Internet Printing
Protocol
http://www.ietf.org/rfc/rfc2569.txt
RFC 2569, Mapping
between LPD and IPP Protocols
http://www.ietf.org/rfc/rfc2616.txt
RFC 2616, Hypertext
Transfer Protocol -- HTTP/1.1
http://www.ietf.org/rfc/rfc2617.txt
RFC 2617, HTTP
Authentication: Basic and Digest Access
Authentication
http://www.ietf.org/rfc/rfc2910.txt
RFC 2910, IPP/1.1:
Encoding and Transport
http://www.ietf.org/rfc/rfc2911.txt
RFC 2911, IPP/1.1:
Model and Semantics
http://www.ietf.org/rfc/rfc3380.txt
RFC 3380, IPP: Job and
Printer Set Operations
3 Design Overview
CUPS is composed of 9 software sub-systems that operate together to
perform common printing tasks:
Backends
Berkeley Commands
CGI
CUPS Application Programmers Interface
CUPS Imaging Library
Daemons
Filters
Scheduler
System V Commands
3.1 Backends
The backends implement communications over a number of different
interfaces. All backends are called with a common set of arguments:
Device URI - the Uniform Resource Identifier for the output device
(e.g.
parallel:/dev/plp
,
ipp://hostname/resource
).
Job Identifier - the job identifier for this job (integer).
User Name - the user associated with this job (name string).
Title - the title/job-name associated with this job (name string).
Copies - the number of copies required (integer).
Options - the options associated with this job (space separated
option strings).
Filename (optional) - the file to print; if this option is not
specified, the backend must read the print file from the standard
input.
Backends are named using the scheme of the URI, so a URI of
"ipp://hostname/resource" would be processed by the "ipp" backend.
3.1.1 ipp
The ipp backend sends the specified job to a network printer or host
using the Internet Printing Protocol. The URI is as specified by the
printer-uri-supported
attribute from the printer or host.
3.1.2 lpd
The lpd backend sends the specified job to a network printer or host
using the Line Printer Daemon protocol. The URI is of the form:
lpd://hostname/queue
3.1.3 parallel
The parallel backend sends the specified job to a local printer
connected via the specified parallel port device. The URI is of the
form:
parallel:/dev/file
3.1.4 serial
The serial backend sends the specified job to a local printer
connected via the specified serial port device. The URI is of the form:
serial:/dev/file?option[+option+...]
The options can be any combination of the following:
baud=
rate
- Sets the baud rate for the device.
bits=
7 or 8
- Sets the number of data bits.
parity=
even
- Sets even parity checking.
parity=
odd
- Sets odd parity checking.
parity=
none
- Turns parity checking off.
flow=dtrdsr
- Turns DTR/DSR (hardware) flow
control on.
flow=hard
- Turns RTS/CTS (hardware) flow
control on.
flow=none
- Turns flow control off.
flow=rtscts
- Turns RTS/CTS (hardware) flow
control on.
flow=xonxoff
- Turns XON/XOFF (software) flow
control on.
3.1.5 socket
The socket backend sends the specified job to a network host using
the AppSocket protocol commonly used by Hewlett-Packard and Tektronix
printers. The URI is of the form:
socket://hostname[:port]
The default port number is 9100.
3.1.6 usb
The usb backend sends the specified job to a local printer connected
via the specified usb port device. The URI is of the form:
usb:/dev/file
3.2 Berkeley Commands
The Berkeley commands provide a simple command-line interface to CUPS
to submit and control print jobs. It is provided for compatibility with
existing software that is hardcoded to use the Berkeley commands.
3.2.1 lpc
The lpc command allows users and administrators to check the status and
control print queues. The version provided with CUPS supports the
following commands:
quit - Quits the lpc command.
status - Shows the status of printers and jobs in the queue.
3.2.2 lpq
The lpq command shows the current queue status.
3.2.3 lpr
The lpr command submits a job for printing. The CUPS version of lpr
silently ignores the "i", "t", "m", "h", and "s" options.
3.2.4 lprm
The lprm removes one or more print jobs.
3.3 CGI
The Common Gateway Interface (CGI) programs provide a web-based
status interface to monitor the status of printers, classes, and jobs.
Each of the CGIs utilize HTML template files that can be customized to
provide alternate appearances.
3.3.1 admin.cgi
The admin CGI provides administration interfaces for printers and
classes. The user can add, modify, delete, start, stop, and configure
printers and classes using "wizard" interfaces.
3.3.2 classes.cgi
The classes CGI lists the available printer classes and any pending
jobs for the class. The user can click on individual classes to limit
the display and click on jobs to see the job status.
3.3.3 jobs.cgi
The jobs CGI lists the queued print jobs in order of priority. The
list can be limited by printer or job.
3.3.4 printers.cgi
The printers CGI lists the available printer queues and any pending
jobs for the printer. The user can click on individual printers to
limit the display and click on jobs to see the job status.
3.4 CUPS Application Programmers Interface
The CUPS Application Programmers Interface ("API") provides common
convenience, HTTP, IPP, language, and PPD functions used by the CUPS
software.
3.4.1 Convenience Functions
Convenience functions are provided to submit an IPP request, send a
print file, cancel a job, get a list of available printers, get a list
of available classes, get the default printer or class, get the default
server name, get the local username, and get a password string.
3.4.2 HTTP Functions
The HTTP functions provide functions to connect to HTTP servers,
issue requests, read data from a server, and write data to a server.
3.4.3 IPP Functions
The IPP function provide functions to manage IPP request data and
attributes, read IPP responses from a server, and write IPP requests to
a server.
3.4.4 Language Functions
The language functions provide a standard interface for retrieving
common textual messages for a particular locale and determining the
correct encoding (e.g. US ASCII, UTF-8, ISO-8859-1, etc.)
3.4.5 PPD Functions
The PostScript Printer Description functions manage PPD files, select
options, check for option conflicts, and emit selected options in the
correct order.
3.5 CUPS Imaging Library
The CUPS imaging library provides colorspace conversion, color
management, image management, scaling, image file, and raster functions
used by the CUPS raster filters.
3.5.1 Colorspace Conversion Functions
The colorspace conversion functions handle conversion of grayscale
and RGB colors to grayscale, RGB, K, CMY, CMYK, and CMYKcm colorspaces.
3.5.2 Color Management Functions
The color management functions handle gamut mapping and density
correction. These are integrated with the colorspace conversion
functions so that colorspace conversion and color management are
processed in a single step.
3.5.3 Image Management Functions
The image management functions manage a tiled image database that is
swapped to/from disk as needed.
3.5.4 Scaling Functions
The scaling functions provide image scaling services using
nearest-neighbor sampling and bilinear interpolation as appropriate.
3.5.5 Image File Functions
The image file functions handle loading of all image file formats.
3.5.6 Raster Functions
The raster functions manage streams of CUPS raster data (described in
the Interface Design Document) used by non-PostScript printer drivers
and raster filters.
3.6 Daemons
The daemons provide additional network functions for the scheduler.
Currently only two daemons are provided with CUPS.
3.6.1 Line Printer Daemon
The line printer daemon provides remote LPD client support and is run
by the
inetd(8)
daemon as needed.
3.6.2 Polling Daemon
The polling daemon is used to poll a remote server for a list of
available printers and provide it to the scheduler for addition. A
separate polling daemon is run by the scheduler for every remote system
listed for polling in the scheduler configuration file.
3.7 Filters
The filters implement file conversion services for CUPS. All filters
are called with a common set of arguments:
Printer name - the name of the destination printer (name string).
Job Identifier - the job identifier for this job (integer).
User Name - the user associated with this job (name string).
Title - the title/job-name associated with this job (name string).
Copies - the number of copies required (integer).
Options - the options associated with this job (space separated
option strings).
Filename (optional) - the file to print; if this option is not
specified, the filter must read the input file from the standard input.
Filters are added to the MIME conversion data file and implement all
necessary conversions from one file type to another.
3.7.1 hpgltops
The hpgltops filter converts HP-GL/2 files into PostScript.
3.7.2 imagetops
The imagetops filter converts image files into PostScript.
3.7.3 imagetoraster
The imagetoraster filter converts image files into CUPS raster data.
3.7.4 pdftops
The pdftops filter converts PDF files into PostScript.
3.7.5 pstops
The pstops filter inserts printer-specific commands from PPD files
and performs page filtering as requested by the user.
3.7.6 pstoraster
The pstoraster filter converts PostScript program data into CUPS
raster data.
3.7.7 rastertoepson
The rastertoepson filter handles converting CUPS raster data to ESC/P
and supports both color and black-and-white printers.
3.7.8 rastertohp
The rastertohp filter handles converting CUPS raster data to HP-PCL
and supports both color and black-and-white printers.
3.7.9 texttops
The texttops filter converts text files into PostScript.
3.8 Scheduler
The scheduler is a fully-functional HTTP/1.1 and IPP/1.1 server that
manages the printers, classes, and jobs in the system. It also handles
a simple broadcast-based directory service so that remote print queues
and classes can be accessed transparently from the local system.
3.8.1 Authorization
The authorization module is responsible for performing access control
and authentication for all HTTP and IPP requests entering the system.
3.8.2 Classes
The classes module is responsible for managing printer classes in the
system. Each class is a collection of local and/or remote printers. The
classes module also reads and writes the classes configuration file.
3.8.3 Client
The client module is responsible for all HTTP client communications.
It handles listening on selected interfaces, accepting connections from
prospective clients, processing incoming HTTP requests, and sending
HTTP responses to those requests. The client module also is responsible
for executing the external CGI programs as needed to support web-based
printer, class, and job status monitoring and administration.
Once authorized, all IPP requests are sent to the IPP module.
3.8.4 Configuration
The configuration module is responsible for reading the CUPS
configuration file and initializing the appropriate data structures and
values. The configuration module also stops CUPS services before
reading the configuration file and restarts them after the
configuration file has been read.
3.8.5 Devices
The devices module is responsible for managing the list of available
devices for the CUPS-Get-Devices operation.
3.8.6 Directory Services
The directory services module sends and recieves printer state
information over a broadcast socket. Remote printers and classes are
automatically added to or removed from the local printer and class
lists as needed.
The directory services module can only recieve printer state
information over a single UDP port, however it can broadcast to
multiple addresses and ports as needed.
3.8.7 IPP
The IPP module handles IPP requests and acts accordingly. URI
validation is also performed here, as a client can post IPP data to any
URI on the server which might sidestep the access control or
authentication of the HTTP server.
3.8.8 Jobs
The jobs module manages print jobs, starts filter and backend
processes for jobs to be printed, and monitors status messages from
those filters and backends.
3.8.9 Logging
The logging module manages the access, error, and page log files that
are generated by the scheduler.
3.8.10 Main
The main module is responsible for timing out and dispatching input
and output for client connections. It also watches for incoming
SIGHUP
and
SIGCHLD
signals, reloads the server
configuration files as needed, and handles child process errors and
exits.
3.8.11 MIME
The Multimedia Internet Mail Exchange module manages a MIME type and
conversion database that supports file typing by extension and content
and least-cost file filtering from a source to a destination file type.
3.8.12 PPDs
The PPDs module is responsible for managing the list of available PPD
files for the CUPS-Get-PPDs operation.
3.8.13 Printers
The printers module is responsible for managing printers and PPD
files in the system. The printers module also reads and writes the
printers configuration file.
3.9 System V Commands
The System V commands provide a robust command-line interface to CUPS
to submit and control printers and jobs.
3.9.1 accept
The accept command tells the scheduler to accept new jobs for
specific printers.
3.9.2 cancel
The cancel command tells the scheduler to cancel one or more jobs
that are queued for printing.
3.9.3 disable
The disable command tells the scheduler to stop printing jobs on the
specified printers.
3.9.4 enable
The enable command tells the scheduler to start printing jobs on the
specified printers.
3.9.5 lp
The lp command submits submits files for printing. Unlike the
standard System V lp command, a single CUPS lp command will generate a
separate job ID for each file that is printed. Also, the Solaris "f",
"H", "P", "S", and "y" options are silently ignored.
3.9.6 lpadmin
The lpadmin command manages printer queues and classes. The Solaris
"A", "F", "I", "M", "P", "Q", "S", "T", "U", "W", "f", "l", "m", "o",
"s", "t", and "u" options are not supported, and new options "P" (PPD
file) and "E" (enable and accept) are provided to configure
CUPS-specific features.
3.9.7 lpinfo
The lpinfo command lists the available PPD files or devices as
selected by the user.
3.9.8 lpmove
The lpmove command moves a print job to a new destination.
3.9.9 lpoptions
The lpoptions command manages user-defined printers and options.
3.9.10 lpstat
The lpstat command lists printers, classes, and jobs as requested by
the user.
3.9.11 reject
The reject command tells the scheduler not to accept new jobs for
specific printers.
A Glossary
A.1 Terms
C
A computer language.
parallel
Sending or receiving data more than 1 bit at a time.
pipe
A one-way communications channel between two programs.
serial
Sending or receiving data 1 bit at a time.
socket
A two-way network communications channel.
A.2 Acronyms
ASCII
American Standard Code for Information Interchange
CUPS
Common UNIX Printing System
ESC/P
EPSON Standard Code for Printers
FTP
File Transfer Protocol
HP-GL
Hewlett-Packard Graphics Language
HP-PCL
Hewlett-Packard Page Control Language
HP-PJL
Hewlett-Packard Printer Job Language
IETF
Internet Engineering Task Force
IPP
Internet Printing Protocol
ISO
International Standards Organization
LPD
Line Printer Daemon
MIME
Multimedia Internet Mail Exchange
PPD
PostScript Printer Description
SMB
Server Message Block
TFTP
Trivial File Transfer Protocol
