CUPS Interface Design Description
Author: Easy Software Products

# Scope

## Identification

This interface design description document provides detailed file formats, message formats, and program conventions for the Common UNIX Printing System ("CUPS") Version 1.0.

## System Overview

The Common UNIX Printing System provides a portable printing layer for UNIX® 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 (IETF-IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD, RFC1179), Server Message Block (SMB), and AppSocket protocols are also supported with reduced functionality.

CUPS adds network printer browsing and PostScript Printer Description ("PPD")-based printing options to support real world applications under UNIX.

CUPS also includes a customized version of GNU GhostScript (currently based off GNU GhostScript 4.03) and an image file RIP that can be used to support non-PostScript printers.

## Document Overview

This interface design description document is organized into the following sections:

- 1 - Scope
- 2 - References
- 3 - Internal Interfaces
- 4 - External Interfaces
- 5 - Directories
- A - Glossary

# References

## CUPS Documentation

The following CUPS documentation is referenced by this document:

- CUPS-CMP-1.0: CUPS Configuration Management Plan
- CUPS-IDD-1.0: CUPS System Interface Design Description
- CUPS-SAM-1.0.x: CUPS Software Administrators Manual
- CUPS-SDD-1.0: CUPS Software Design Description
- CUPS-SPM-1.0: CUPS Software Programming Manual
- CUPS-SSR-1.0: CUPS Software Security Report
- CUPS-STP-1.0: CUPS Software Test Plan
- CUPS-SUM-1.0.x: CUPS Software Users Manual
- CUPS-SVD-1.0.x: CUPS Software Version Description

## Other Documents

The following non-CUPS documents are referenced by this document:

- IEEE 1387.4, System Administration: Printing (draft)
- IPP/1.0: Additional Optional Operations - Set 1
- RFC 1179, Line Printer Daemon Protocol
- RFC 2565, IPP/1.0: Encoding and Transport
- RFC 2566, IPP/1.0: Model and Semantics
- RFC 2639, IPP/1.0: Implementers Guide

# Internal Interfaces

## Character Set Files

The character set files define a mapping between 8-bit characters and the Unicode character set. They are named using the ISO standard number defined for the character set. Each file consists of up to 256 lines of ASCII text. Each line consists of two hexadecimal numbers; the first number is the character number in the character set (0x00 to 0xff), and the second number is the Unicode character number (0x0000 to 0xffff).

## Language Files

The language files define the default character set and a collection of text messages in that language. They are named by prefixing the string "cups_" to the front of the language specifier (e.g. "cups_en", "cups_fr", etc.) Each file consists of two or more lines of ASCII text.

The first line identifies the character set to be used for the messages. The currently recognized values are:

- us-ascii
- utf-8
- iso-8859-1
- iso-8859-2
- iso-8859-3
- iso-8859-4
- iso-8859-5
- iso-8859-6
- iso-8859-7
- iso-8859-8
- iso-8859-9
- iso-8859-14
- iso-8859-15

The second and succeeding lines define text messages. If the message text is preceded by a number, then the current message number is updated and the text after the number is used.

## MIME Files

CUPS uses two MIME files in its standard configuration.

### mime.types

The mime.types file defines the recognized file types and consists of 1 or more lines of ASCII text. Comment lines start with the pound ("#") character. The backslash ("\") character can be used at the end of a line to continue that line to the next.

Each non-blank line starts with a MIME type identifier ("super/type") as registered with the IANA. All text following the MIME type is treated as a series of type recognition rules:

    mime-type := super "/" type { SP rule }*
    super := { "a-z" | "A-Z" }*
    type := { "a-z" | "A-Z" | "-" | "." | "0-9" }*
    rule := { extension | match | operator | "(" rule ")" }*
    extension := { "a-z" | "A-Z" | "0-9" }*
    match := "match(" regexp ")" |
             "ascii(" offset "," length ")" |
    	 "printable(" offset "," length ")" |
    	 "string(" offset "," string ")" |
    	 "char(" offset "," value ")" |
    	 "short(" offset "," value ")" |
    	 "int(" offset "," value ")" |
    	 "locale(" string ")"
    operator := "+" |	[ logical AND ]
                "," | SP    [ logical OR ]
    	    "!"         [ unary NOT ]

The `int` and `short` rules match look for integers in network byte order (a.k.a. big-endian) with the most-significant byte first.

### mime.convs

The mime.types file defines the recognized file filters and consists of 1 or more lines of ASCII text. Comment lines start with the pound ("#") character.

Each non-blank line starts with two MIME type identifiers ("super/type") representing the source and destination types. Following the MIME types are a cost value (0 to 100) and the filter program to use. If the filter program is not specified using the full path then it must reside in the CUPS filter directory.

## PostScript Printer Description Files

The PostScript Printer Description (PPD) file format is described in Adobe TechNote #5003: PostScript Printer Description File Format Specification Version 4.3.

### CUPS Extensions to PPD Files

CUPS adds several new attributes that are described below.

#### cupsFilter

This string attribute provides a conversion rule of the form:

    source/type cost program

The destination type is assumed to the printer's type. If a printer supports the source type directly the special filter program "-" may be specified.

#### cupsManualCopies

This boolean attribute notifies the RIP filters that the destination printer does not support copy generation in hardware. The default value is false.

#### cupsModelNumber

This integer attribute specifies a printer-specific model number. This number can be used by a filter program to adjust the output for a specific model of printer.

#### cupsProfile

This string attribute specifies a color profile of the form:

    resolution/type density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22

The resolution and type values may be "-" to act as a wildcard. Otherwise they must match one of the `Resolution` or `MediaType` attributes defined in the PPD file.

The density and gamma values define gamma and density adjustment function such that:

    f(x) = density * xgamma

The m00 through m22 values define a 3x3 transformation matrix for the CMY color values. The density function is applied after the CMY transformation.

#### cupsVersion

This required attribute describes which version of the CUPS IDD was used for the PPD file extensions. Currently it must be the string "1.0".

## Scheduler Configuration Files

The scheduler reads three configuration files that define the available printers, classes, and services:

classes.conf
  This file defines all of the printer classes known to the system.
cupsd.conf
  This file defines the files, directories, passwords, etc. used by the scheduler.
printers.conf
  This file defines all of the printers known to the system.

### classes.conf

The classes.conf file consists of 1 or more lines of ASCII text. Comment lines start with the pound ("#") character.

Each non-blank line starts with the name of a configuration directive followed by its value. The following directives are understood:

Directive | Description
--- | ---
<Class name> </Class> | Surrounds a class definition.
<DefaultClass name> </Class> | Surrounds a class definition for the default destination.
Accepting | Specifies whether the class is accepting new jobs. May be the names "Yes" or "No".
Info | A textual description of the class.
Location | A textual location of the class.
MoreInfo | A URL pointing to additional information on the class.
Printer | Specifies a printer that is a member of the class.

### cupsd.conf

The cupsd.conf file consists of 1 or more lines of ASCII text. Comment lines start with the pound ("#") character.

Each non-blank line starts with the name of a configuration directive followed by its value. The following directives are understood:

Directive | Default | Description
--- | --- | ---
AccessLog | logs/access_log | Specifies the location of the access log file.
Allow | - | Allows connections from the specified host, network, or domain.
AuthClass | - | Specifies what level of authentication is required; may be either "User", "System", or "Group".
AuthType | None | Specifies the type of authentication to perform; may be either "None" or "Basic".
BrowseAddress | 255.255.255.255 | Specifies a broadcast address to send CUPS browsing packets to.
BrowseInterval | 30 | Specifies the number of seconds between browsing updates.
BrowsePort | 631 | Specifies the UDP port number to use for browse packets.
BrowseTimeout | 300 | Specifies the number of seconds to wait until remote destinations are removed from the local destination list.
Browsing | On | Specifies whether or not printer and class browsing is enabled; can be "On" or "Off".
DefaultCharset | iso-8859-1 | Specifies the default character set.
DefaultLanguage | current locale | Specifies the default language.
Deny | - | Refuses connections from the specified host, network, or domain.
DocumentRoot | /usr/share/cups/doc | Specifies the document data root directory.
ErrorLog | logs/error_log | Specifies the error log file location.
Group | root, sys, system | Specifies the group name or ID that is used when running external programs.
HostNameLookups | Off | Specifies whether or not to perform reverse IP address lookups to get the actual hostname; may be "On" or "Off". Hostname lookups can significantly degrade the performance of the CUPS server if one or more DNS servers is not functioning properly.
ImplicitClasses | On | Specifies whether or not to automatically create printer classes when more than one printer or class of the same name is detected on the network; may be "On" or "Off".
KeepAlive | On | Specifies whether or not to use the HTTP Keep-Alive feature; may be "On" or "Off".
KeepAliveTimeout | 30 | Specifies the amount of time to keep the HTTP connection alive before closing it.
<Location path> </Location> | - | Specifies a location to restrict access to.
LogLevel | info | Controls the amount of information that is logged in the error log file. Can be one of "debug", "info", "warn", "error", or "none", in decreasing order or verbosity.
MaxClients | 100 | Specifies the maximum number of simultaneous active clients. This value is internally limited to 1/3 of the total number of availabel file descriptors.
MaxLogSize | 0 | Specifies the maximum size of the access, error, and page log files in bytes. If set to 0 then no maximum size is set. Log files are rotated automatically when this size is exceeded.
MaxRequestSize | 0 | Specifies the maximum size of HTTP requests in bytes. If set to 0 then there is no maximum.
Order | Allow,Deny | Specifies the order of Allow and Deny directive processing; can be "Deny,Allow" to implicitly deny hosts unless they are allowed by an Allow line, or "Allow,Deny" to implicitly allow hosts unless they are denied by a Deny line.
PageLog | logs/page_log | Specifies the location of the page log file.
Port | 631 | Specifies a port number to listen to for HTTP connections.
RIPCache | 8m | Specifies the size of the memory cache in bytes that is used by RIP filters.
ServerAdmin | root@ServerName | Specifies the person to contact with problems.
ServerName | hostname | Specifies the hostname that is supplied to HTTP clients. This is also used to determine the default CUPS server for the CUPS IPP client applications.
ServerRoot | /var/cups | Specifies the root directory for server data files.
SystemGroup | root, sys, system | Specifies the group name used for System class authentication.
TempDir | /var/tmp | Specifies the temporary directory to use.
Timeout | 300 | The timeout in seconds before client connections are closed in the middle of a request.
User | lp | Specifies the user that is used when running external programs.

### printers.conf

The printers.conf file consists of 1 or more lines of ASCII text. Comment lines start with the pound ("#") character.

Each non-blank line starts with the name of a configuration directive followed by its value. The following directives are understood:

Directive | Description
--- | ---
Accepting | Specifies whether the printer is accepting new jobs. May be the names "Yes" or "No".
<DefaultPrinter name> </Printer> | Surrounds the printer definition for a default destination.
DeviceURI | Specifies the device-uri attribute for the printer.
Info | A textual description of the printer.
Location | A textual location of the printer.
MoreInfo | A URL pointing to additional information on the printer.
<Printer name> </Printer> | Surrounds the printer definition.
State | Specifies the initial state of the printer; can be "Idle" or "Stopped".

# External Interfaces

## AppSocket Protocol

The AppSocket protocol is an 8-bit clean TCP/IP socket connection. The default IP service port is 9100. The URI method name is "socket".

## CUPS Browsing Protocol

The CUPS Browsing Protocol is a UDP/IP-based broadcast service. By default this service operates on IP service port 631.

Each broadcast packet describes the state of a single printer or class and is an ASCII text string of up to 1450 bytes ending with a newline (0x0a). The string is formatted as follows:

    type SP state SP uri NL

The state and uri values correspond to the IPP `printer-state` and `printer-uri-supported` attributes.

The type value is a hexadecimal number string representing capability/type bits:

Bit | Description
--- | ---
0 | 0 = printer 1 = class
1 | 0 = local 1 = remote (always 1)
2 | 1 = can print B&W
3 | 1 = can print color
4 | 1 = can duplex
5 | 1 = can staple
6 | 1 = can do fast copies
7 | 1 = can do fast collating
8 | 1 = can punch holes
9 | 1 = can cover
10 | 1 = can bind
11 | 1 = can sort
12 | 1 = can print up to 9x14 inches
13 | 1 = can print up to 18x24 inches
14 | 1 = can print up to 36x48 inches
15 | 1 = can print variable sizes

## CUPS PostScript File

CUPS PostScript files are device-dependent Adobe PostScript program files. The PostScript language is described in the Adobe PostScript Language Reference Manual, Third Edition.

The MIME type for CUPS PostScript files is `application/vnd.cups-postscript`.

## CUPS Raster File

CUPS raster files are device-dependent raster image files that contain a PostScript page device dictionary and device-dependent raster imagery for each page in the document. These files are used to transfer raster data from the PostScript and image file RIPs to device-dependent filters that convert the raster data to a printable format.

A raster file begins with a four byte synchronization word: 0x52615374 ("RaSt") for big-endian architectures and 0x74536152 ("tSaR") for little-endian architectures. The writer of the raster file will use the native word order, and the reader is responsible for detecting a reversed word order file and swapping bytes as needed. The CUPS Interface Library raster functions perform this function automatically.

Following the synchronization word are a series of raster pages. Each page starts with a page device dictionary header and is followed immediately by the raster data for that page.

Bytes | Description | Values
--- | --- | ---
0-63 | MediaClass | Nul-terminated ASCII string
64-127 | MediaColor | Nul-terminated ASCII string
128-191 | MediaType | Nul-terminated ASCII string
192-255 | OutputType | Nul-terminated ASCII string
256-259 | AdvanceDistance | 0 to 232 - 1 points
260-263 | AdvanceMedia | 0 = Never advance roll 1 = Advance roll after file 2 = Advance roll after job 3 = Advance roll after set 4 = Advance roll after page
264-267 | Collate | 0 = do not collate copies 1 = collate copies
268-271 | CutMedia | 0 = Never cut media 1 = Cut roll after file 2 = Cut roll after job 3 = Cut roll after set 4 = Cut roll after page
272-275 | Duplex | 0 = Print single-sided 1 = Print double-sided
276-283 | HWResolution | Horizontal and vertical resolution in dots-per-inch.
284-299 | ImagingBoundingBox | Four integers giving the left, bottom, right, and top positions of the page bounding box in points
300-303 | InsertSheet | 0 = Do not insert separator sheets 1 = Insert separator sheets
304-307 | Jog | 0 = Do no jog pages 1 = Jog pages after file 2 = Jog pages after job 3 = Jog pages after set
308-311 | LeadingEdge | 0 = Top edge is first 1 = Right edge is first 2 = Bottom edge is first 3 = Left edge is first
312-319 | Margins | Left and bottom origin of image in points
320-323 | ManualFeed | 0 = Do not manually feed media 1 = Manually feed media
324-327 | MediaPosition | Input slot position from 0 to N
328-331 | MediaWeight | Media weight in grams per meter squared
332-335 | MirrorPrint | 0 = Do not mirror prints 1 = Mirror prints
336-339 | NegativePrint | 0 = Do not invert prints 1 = Invert prints
340-343 | NumCopies | 1 to 232 - 1
344-347 | Orientation | 0 = Do not rotate page 1 = Rotate page counter-clockwise 2 = Turn page upside down 3 = Rotate page clockwise
348-351 | OutputFaceUp | 0 = Output face down 1 = Output face up
352-359 | PageSize | Width and length in points
360-363 | Separations | 0 = Print composite image 1 = Print color separations
364-367 | TraySwitch | 0 = Do not change trays if selected tray is empty 1 = Change trays if selected tray is empty
368-371 | Tumble | 0 = Do not rotate even pages when duplexing 1 = Rotate even pages when duplexing
372-375 | cupsWidth | Width of page image in pixels
376-379 | cupsHeight | Height of page image in pixels
380-383 | cupsMediaType | Driver-specific 0 to 232 - 1
384-387 | cupsBitsPerColor | 1, 2, 4, 8 bits
388-391 | cupsBitsPerPixel | 1 to 32 bits
392-395 | cupsBytesPerLine | 1 to 232 - 1 bytes
396-399 | cupsColorOrder | 0 = chunky pixels (CMYK CMYK CMYK) 1 = banded pixels (CCC MMM YYY KKK) 2 = planar pixels (CCC... MMM... YYY... KKK...)
400-403 | cupsColorSpace | 0 = white 1 = RGB 2 = RGBA 3 = black 4 = CMY 5 = YMC 6 = CMYK 7 = YMCK 8 = KCMY 9 = KCMYcm
404-407 | cupsCompression | Driver-specific 0 to 232 - 1
408-411 | cupsRowCount | Driver-specific 0 to 232 - 1
412-415 | cupsRowFeed | Driver-specific 0 to 232 - 1
416-419 | cupsRowStep | Driver-specific 0 to 232 - 1

The MIME type for CUPS Raster files is `application/vnd.cups-raster`.

## CUPS Raw Files

Raw files are printer-dependent print files that are in a format suitable to the destination printer (e.g. HP-PCL, HP-RTL, etc.) The MIME type for CUPS Raw files is `application/vnd.cups-raw`.

## Internet Printing Protocol

The Internet Printing Protocol is described by the following RFCs:

- RFC 2565: Internet Printing Protocol/1.0: Encoding and Transport
- RFC 2566: Internet Printing Protocol/1.0: Model and Semantics
- RFC 2567: Design Goals for an Internet Printing Protocol
- RFC 2568: Rationale for the Structure of the Model and Protocol for the Internet Printing Protocol
- RFC 2569: Mapping between LPD and IPP Protocols

The URI method name for IPP is "ipp".

CUPS defines the following extension operations to IPP.

### Get Default Destination (CUPS_GET_DEFAULT = 0x4001)

The get default destination operation returns the printer attributes for the system default printer or class. The only required attributes are `attributes-charset` and `attributes-natural-language`.

Get default destination will only return `ipp-ok`.

### Get Printers (CUPS_GET_PRINTERS = 0x4002)

The get printers operation returns the printer attributes for all printers known to the system. The only required attributes are `attributes-charset` and `attributes-natural-language`.

Get printers will only return `ipp-ok`.

### Add Printer (CUPS_ADD_PRINTER = 0x4003)

The add printer operation adds or replaces the specified printer. The `attributes-charset`, `attributes-natural-language` and `printer-uri` attributes are required.

The `printer-location`, `printer-info`, `printer-more-info`, and `device-uri` attributes are required when initially adding a printer and optional when modifying a printer.

A PPD file or System V interface script may follow the IPP request body. If a valid interface script or PPD file is not provided then the printer is treated as a generic PostScript device.

Add printer will return `ipp-ok`, `ipp-not-authorized`, `ipp-bad-request`, or `ipp-attributes`.

### Delete Printer (CUPS_DELETE_PRINTER = 0x4004)

The delete printer operation removes the specified printer. The only required attributes are `attributes-charset`, `attributes-natural-language`, and `printer-uri`.

Delete printer will return `ipp-ok`, `ipp-not-found`, or `ipp-not-authorized`.

### Get Classes (CUPS_GET_CLASSES = 0x4005)

The get classes operation returns the printer attributes for all classes known to the system. The only required attributes are `attributes-charset` and `attributes-natural-language`.

Get classes will only return `ipp-ok`.

### Add Class (CUPS_ADD_CLASS = 0x4006)

The add class operation adds or replaces the specified class. The `attributes-charset`, `attributes-natural-language`, and `printer-uri` attributes are required.

The `printer-location`, `printer-info`, `printer-more-info`, and `member-uris` attributes are required when initially adding a printer and optional when modifying a printer.

Add class will return `ipp-ok`, `ipp-not-authorized`, `ipp-bad-request`, or `ipp-attributes`.

### Delete Class (CUPS_DELETE_CLASS = 0x4007)

The delete class operation removes the specified class. The only required attributes are `attributes-charset`, `attributes-natural-language`, and `printer-uri`.

Delete class will return `ipp-ok`, `ipp-not-found`, or `ipp-not-authorized`.

### Accept Jobs (CUPS_ACCEPT_JOBS = 0x4008)

The accept jobs operation allows jobs to be accepted by the specified destination. The only required attributes are `attributes-charset`, `attributes-natural-language`, and `printer-uri`.

Accept jobs will return `ipp-ok`, `ipp-not-found`, or `ipp-not-authorized`.

### Reject Jobs (CUPS_REJECT_JOBS = 0x4009)

The reject jobs operation prevents jobs from being accepted by the specified destination. The only required attributes are `attributes-charset`, `attributes-natural-language`, and `printer-uri`.

Reject jobs will return `ipp-ok`, `ipp-not-found`, or `ipp-not-authorized`.

### Set Default Destination (CUPS_SET_DEFAULT = 0x400A)

The set default destination operation returns the printer attributes for the system default printer or class. The only required attributes are `attributes-charset`, `attributes-natural-language`, and `printer-uri`.

Set default destination will return `ipp-ok`, `ipp-not-authorized`, `ipp-bad-request`, or `ipp-not-found`.

## Line Printer Daemon Protocol

The Line Printer Daemon (LPD) protocol is described by RFC 1179: Line Printer Daemon Protocol.

The URI method name for LPD is "lpd".

## Server Message Block Protocol

The Server Message Block (SMB) and related Common Internet File System (CIFS) protocols are described at http://anu.samba.org/cifs.

The URI method name for SMB is "smb".

# 5 - Directories

/usr/bin
  The `cancel`, `lp`, `lpq`, `lpr`, `lprm`, and `lpstat` commands reside here.
/usr/sbin
  The `accept`, `cupsd`, `lpadmin`, `lpc`, and `reject` commands reside here.
/usr/share/cups
  This is the root directory of the CUPS static data.
/usr/share/cups/data
  The character set and filter data files reside here.
/usr/share/cups/fonts
  The `pstoraster` font files reside here.
/usr/share/cups/model
  The sample PPD files reside here.
/usr/share/cups/pstoraster
  The `pstoraster` data files reside here.
/var/cups
  This is the root directory of the CUPS scheduler.
/var/cups/backend
  The backend filters reside here.
/var/cups/cgi-bin
  The CGI programs reside here.
/var/cups/conf
  The scheduler configuration and MIME files reside here.
/var/cups/doc
  The scheduler documentation files reside here.
/var/cups/filter
  The file filters reside here.
/var/cups/interfaces
  System V interface scripts reside here.
/var/cups/logs
  The `access_log`, `error_log`, and `page_log` files reside here.
/var/cups/ppd
  This directory contains PPD files for each printer.
/var/cups/requests
  This directory contains pending print job files.

# Glossary

## 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.

## 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 Printer 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
PCL
  Page Control Language
PPD
  PostScript Printer Description
SMB
  Server Message Block
TFTP
  Trivial File Transfer Protocol