CUPS Software Design Description


CUPS-SDD-1.0
Easy Software Products
Copyright 1997-1999, All Rights Reserved

Table of Contents



1 Scope 2 References 3 Design Overview A Glossary
GIF89a¯ÿòÌÌÌ™™™fff333ÿÿÿÿÿÿÿÿÿ!ù,¯ÿBþXºÜþ0ÊI«½8ëÍ»ÿ`(Ždižhª2€0p,Ïtmßx®ï ;±Ýíˆndý !¸ ž³wà…MƒƒY~¿{,gÚ\‚äé Œ×Ø(tÙî!Ï=Ñ.ûz¯áÑŸ:ì;Ã9qöíÉë]/¿ºÉ¤Et/†'Îþt9ÀØ–ž_ÙÇ\|W•wArö¸Ý2Ô× tN°0Tï}¡û‰$!‚yMxî)ˆš‰Ôø@nB°U½ÊwE„§!ŠF H L8B c‰;ždŠ-æDVWdг€h±äÚ“P¶%#(4Fiå•Ï\hŠ:Re!\ÒÄ—X^¦%€¥À-$E€Ö/úHŽšlââöÌQX ¸1Nô¯b"œŠüjåÁÂE0…È8ö5GkZ|ÒÁwt„C»ÔQSÇo6ÔÙ[W„$²*Ž+4Pb-8¹P1þ'8"‘ФÄ$ Cyê‘„)>ãŠtè`Ð3‡‹¾z"«rE'Âqfä°Ë ‘qÂ\|€„Ž¡ôö»%É(.—bڽȀíÉ`{¬EÇ1w’ »[Hß`(B6ö“  †')ÊRŽÎa[ÃrbC!Tå°Œ 2Q·ÈHZê#–®üË/àô¯FÝê(Û²% ºXË9öÀbÁ4f.ù-oý™XËB…IÎÒ7¹*@ÃÓŽÍT€hà‘ÌWâ™Ã$f:µyžn†ó†r„'téKv` Ç+dª– œ79sò|'=×¢Ìx¶òœÿ„¦œˆeÎ;*à$þ” IÝÆaÏ{–3ŽÅÁ P“ÍS[ÙL¨3©òQ7éÆò#ãûô0F×ðsE°t§@‘ØQÜ´´ ©:3ÓRíd ¥*MITnŒ£¨H]ØQÁd @òþ—¬rMœŽaO rë^yÀ·(¸îéêû$uDòrã/a,I.°ÙUÀœb hˆ`¾B ë" Ü`HØxȸo1þ[á\8f^æ|\ý‚¢¢zø0(ˆ\ {ƒÄgäÞõ€çâ§Á˜0*\³n¼‹m¶/Äeª±ÿ†ì Ç,½DN2€œº+ùÉ|í0L¡Le*ð¸Ã>­2ëf,eIPOËÅàr—±”80SAŸcFªatç»ãy¤¸ršçÌ¡5ïoõËsžï|¿8˙Φ¬þ,ï¼èà)ÁÌ;øk¡—†dDpÑòø2¢qfHã!Ë“~ÙŸ-í 'g:,æ4y?ýäP‹Z›ž#ÏÕ´Î5AK‰k]ûš›ÒKõ¯‡më€õzØÈƫ؎Ý>B{PЪ.6hf]º?©ÌIŽuO„íM‚ÌÇÜcµ3˜ 61‹NÒ[†W£ ¦m¿­{ÂPâvζKnUˆ[ ònĽ±÷n?l:Áž3ušë¬sP[ÿnn¾çP…WõÔFj[Â÷ ¹vÏ™à‰˜xú'ˆ£ÀÀ†p¸4.êãKÇ¿ÂÁ±o§¢ü"Á|Nk`îʘ  jl©ÌuˆËi™0pmC´«+‰÷6¤2­éÏe`(ŽJ]¥iõð3ƒØí"p|ª!:qøFس 6£ @­,þŠqüãoÌÇ®žÖüV“¶QÇ›Evî¹²É8ÙªS"æÀç‡x± àþ‡>—Iãg ïÝ>Y‰çN80æ§ ±¾GLLìÕµ…(1Þ¼!8}þ¬“*…ª‰Ùì:e»´œ ª¿ên_6ÂÃSÀ`eG;Ö„CƒCcˆ¿‡4¸yeî¯Í)oøByRm½0?íLîÅ`QÿjÓÙ/ºôÓN|Ý þÙAÜŒÁ¸D5©D aævx ?жx°DM@•!h‰àÈ€Ž§® • á×B`ð¤ªE?›“”Þdƒ"8$Ý`Ki0…OðƒnΓ±µvtžè€I([,¹Ndɨh\'6X Pã—Š‰Éøt ¢‘¥˜¬è €ˆ†Ky™FˆŒë`š”yƒ„¨š €š‰ƒM©‡øFQhY„ 9¶X¯×–í4š¤™Y\)"¹AN]‰xéz÷Gq07)©ñ™•Y€r°ŒŽi‹ z ™ÇäFÍÉT–ù› ËŽC œwI›üX]‹¹\ëY]þf lïYbj8ŸÈuœbŸÍÅtú©fÞןfBI—“*øé:ÛØUj Ò ˆõ¹ Õp $(~ ¡Ú ¡gù{îpZI?¡ƒîÀv:“a¦˜6¢§Ô]Ý‘(ªê)!ŸÚ¢: jwµ¡4ÚvíHÛǘ9ºXhó•üù£¥Á¢VÉ{Dº2š‰(°¤3š¤a÷ +У¥“p¢þò4Vº—  E´¥è¤k°7ºhT*€¿èw`ÚžiÄ …S¦Ʀmê Nêƒ#ú¢f€ xê†ý 8z©7uÚp{Ú=~]7`«h‡ÚsÚg:…zd˜ó§ÎA-vþAñr¦'–AÚ)9–š¢âSi;£…š 1ªo"ª ¦J;“º rº8Ui|é>¡Úœú “ë¥Dfný2»ƒ–0j«®»ºK;zë¢Íö»—!µ—S»³r>K+6ˆ‹¨XÒ»; CÈ 8Ê;¢»ÃÛ/Œ‹¥ž!¬s½VR½óõÏ‹Oâ[/çK¨þ˜Ñ:Í‹\Ý+ Sc:ïËž’º¶ë9Æ» ô 8ly$ 8©ÙÅmX2Ùh>—?¯!šHüÁ^LsP,Ÿ«Y‹âá¿ÿtšì‚£Y r¦Éš¥9ÇjžÄ8-ÆÇŒ¶iêPÂbA˜ù‰Ã¸š»³7RœCWRoìŠå MŒŠ”åt™ Œ›réÉq å>}Lê}ÎǨ 5:àŒ|"þÇwÐsøæNΰ¹#R>~-N‰®èƒ ßcðÞÚÎÑ¥®åGÎâ툉Ýè*‚¸ =‚ž ºëâ…­ëÀ>Û·žën^žmèÊëð¼ã>å×Λ«}êØ÷ “Œ¬ËIÁ·AÔNÍëv>]t.âÚLЫþíï¾ñnäÖÜæs¹¿±â°+† ¬UØïî•.ç¬ÎìÍ.è´ÞŠG=ðù‚§ž¯”ë^äÛ®êh-‹êê!i!ÕvMíiªîþ¾òîá/þÑ-OÖGð,oñº!å’gOâ POìOôBþÈàhâ+?ï>ßÊVHÀsaõ™€õ$óSîõ—»ó8.žß¹ ~áßÈ©ö»]ò3ëÆt_÷[ïôb¯ç‚Ü÷Õ«@u™ð;zܘ‘Ü@óŽ2’?ùƒ¸ÙlùF ¶™¯ù›N ž0œú£¶¤ÿ0#9:ß§½ž©Ÿ\#ÃÙæó2é+û‚ÀÓ¸_äM/ÓtaÚý3”]Ù«¿¸iîaF>ª}ŒØvÍïMÍ÷Ðëä©îrÜŒöqñ_ÀüªrâF®ò ýþ¸—hT_ã4sx”ýÝî)ç.QgûàŸÏ%ì‹}i´ASû|þð@QÜ $J9€»-̱÷ÜôMØ‘hZ˜¦:°œ*ÏlßxÒ|ϼ¡ÅLÀ ¬Áfù9BÑdìÁ|«VV„¢“énKv kB_ƒg 3ʳ8#Þ¬L=0;J¤äÈ@¤F|'i~±© žaÊŠÆg;d*3²”©bPÏ¢TäHô¦?[† ÄäƒhN6ZM¢D:c*BR!$±ckƒ’V­-uÛ@[øp„Ÿ]¼8ö-1{TήWÏ2ñ Šp=¸q«Ñ½es.‰„4+#Ëe¦¥W5µekxr䛓/XÍš5Iǃ=kÝúµì˰ûN–2qŦyZ£QŽ›ÇÞtxŠäcK—Ííɹ iþ¡9¼m1oñ¢©/²8îìSté4l’Wm¾9óéÖÛÐãã{{üzÞ¿çøêöÞzà}œàL¨ "˜ ÄÐsà¶PGLUúå`MÞ  ¡†9¬§Û{pX¸¡wÚw߇¡¨ ‰í "MUXNx +l´á¦ j²F:Á.êÆÛj¤³Búî ¼Ê«/£Ö’[н#í+ð¥ænJÞ¸«æ;ð©õ‹¨ _ËðÄŠÒ»*º? ƒÂwœÃyzh±°Øzl2,#oZ2È›r|òË‚°¼$Ç)ë óÍÙÔ,éfs€1Î@/øîÏPõÌiÐH·ðÃBkLtÒP¯bôS;NÝWÔXÏ ó’dlÍtÖ`°tžOc óÅa§}AÄ›²1vËjÇmþu+`ÍÍÁ·qwü6˜‚ì½sÞXŸ¨Ë$xM6àP³-iÉSÚ½AÙˆïë84–ø=xä8^!ä*L>Þ˜ƒk¹Œ({Iè^!ḘN$ê «®ç!ºû‚ÿÝ ë¯ßoî—Oü¨¾ÿî9í]ñÞ{ñÙÊ®ãlhŽ(èÌÃê¼~ÔS¢|öÕŸzýw¬Ë§|øÝ—*½ŒÈ×­|úåwzþæ“)Nrû¾Ê?*ô¥ ¿*÷ô7ú½~Múúú÷ª÷Ɉ•S3x*ûíP”ùH£°°àó(è¾í-Jƒú™ åAF{#\”g…Áœ)!),Ô #ÓÂǼjþ1œŒþh©²K„9$ƒYè)Ž ˆA È —‡)#1‰Óp"˜ð'Ã%n‰P´‡Ù¨-‹1³¢^\%ƈÔp„CLÖ5Ã

1 Scope

1.1 Identification

This software design description document provides detailed information on the architecture and coding of the Common UNIX Printing System ("CUPS") Version 1.0.

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

1.3 Document Overview

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

2 References

2.1 CUPS Documentation

The following CUPS documentation is referenced by this document:

2.2 Other Documents

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

3 Design Overview

CUPS is composed of 7 software sub-systems that operate together to perform common printing tasks:

3.1 Backends

The backends implement communications over a number of different interfaces. All backends are called with a common set of arguments: Backends are named using the method 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:

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:

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: The options can be any combination of the following:

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: The default port number is 9100.

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 hard coded 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:

3.2.2 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.3 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.

3.3.1 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.2 jobs.cgi

The jobs CGI lists the queued print jobs in order of priority. The list can be limited by printer or job. When the user displays the status of an individual print job all job options are displayed.

3.3.3 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 Interface Library

The CUPS interface library provides common convenience, HTTP, IPP, language, MIME, PPD, and raster 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, ISO-8859-1, etc.)

3.4.5 MIME Functions

The Multimedia Internet Mail Exchange functions manage 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.4.6 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.4.7 Raster Functions

The raster functions manage streams of CUPS raster data (described in the Interface Design Document) used by non-PostScript printer drivers.

3.5 Filters

The filters implement file conversion services for CUPS. All filters are called with a common set of arguments: Filters are added to the MIME conversion data file and implement all necessary conversions from one file type to another.

3.5.1 hpgltops

The hpgltops filter converts HP-GL/2 files into PostScript.

3.5.2 imagetops

The imagetops filter converts image files into PostScript.

3.5.3 imagetoraster

The imagetoraster filter converts image files into CUPS raster data.

3.5.4 pstops

The pstops filter inserts printer-specific commands from PPD files and performs page filtering as requested by the user.

3.5.5 pstoraster

The pstoraster filter converts PostScript program data into CUPS raster data.

3.5.6 rastertohp

The rastertohp filter handles converting CUPS raster data to HP PCL and supports both color and black-and-white printers.

3.5.7 texttops

The texttops filter converts text files into PostScript.

3.6 Scheduler

The scheduler is a fully-functional HTTP/1.1 and IPP/1.0 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.6.1 Authorization

The authorization module is responsible for performing access control and authentication for all HTTP and IPP requests entering the system.

3.6.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.6.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.

Once authorized, all IPP requests are sent to the IPP module.

3.6.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.6.5 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.6.6 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.6.7 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.6.8 Logging

The logging module manages the access, error, and page log files that are generated by the scheduler.

3.6.9 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.6.10 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.7 System V Commands

The System V commands provide a robust command-line interface to CUPS to submit and control printers and jobs.

3.7.1 accept

The accept command tells the scheduler to accept new jobs for specific printers.

3.7.2 cancel

The cancel command tells the scheduler to cancel one or more jobs that are queued for printing.

3.7.3 disable

The disable command tells the scheduler to stop printing jobs on the specified printers.

3.7.4 enable

The enable command tells the scheduler to start printing jobs on the specified printers.

3.7.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.7.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), "F" (filter), and "E" (enable and accept) are provided to configure CUPS-specific features such as PPD file and conversion filters.

3.7.7 lpstat

The lpstat command lists printers, classes, and jobs as requested by the user.

3.7.8 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 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