doc/sdd.shtml

   1 <HTML>
   2 <HEAD>
   3         <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
   4         <META NAME="DOCNUMBER" CONTENT="CUPS-SDD-1.2">
   5         <META NAME="Author" CONTENT="Easy Software Products">
   6         <TITLE>CUPS Software Design Description</TITLE>
   7 </HEAD>
   8 <BODY>
   9
  10 <H1>Scope</H1>
  11
  12 <H2>Identification</H2>
  13
  14 This software design description document provides general information
  15 on the architecture and coding of the Common UNIX Printing System
  16 (&quot;CUPS&quot;) Version 1.2.
  17
  18 <EMBED SRC="system-overview.shtml">
  19
  20 <H2>Document Overview</H2>
  21
  22 This software design description document is organized into the
  23 following sections:
  24
  25 <UL>
  26
  27         <LI>1 - Scope
  28
  29         <LI>2 - References
  30
  31         <LI>3 - Design Overview
  32
  33         <LI>A - Glossary
  34
  35 </UL>
  36
  37 <EMBED SRC="references.shtml">
  38
  39 <H1>Design Overview</H1>
  40
  41 CUPS is composed of 9 software sub-systems that operate together to
  42 perform common printing tasks:
  43
  44 <UL>
  45
  46         <LI>Backends
  47
  48         <LI>Berkeley Commands
  49
  50         <LI>CGI
  51
  52         <LI>CUPS Application Programmers Interface
  53
  54         <LI>CUPS Imaging Library
  55
  56         <LI>Daemons
  57
  58         <LI>Filters
  59
  60         <LI>Scheduler
  61
  62         <LI>System V Commands
  63
  64 </UL>
  65
  66 <H2>Backends</H2>
  67
  68 The backends implement communications over a number of different interfaces.
  69 All backends are called with a common set of arguments:
  70
  71 <UL>
  72
  73         <LI>Device URI - the Uniform Resource Identifier for the output device
  74         (e.g. <CODE>parallel:/dev/plp</CODE>,
  75         <CODE>ipp://hostname/resource</CODE>).
  76
  77         <LI>Job Identifier - the job identifier for this job (integer).
  78
  79         <LI>User Name - the user associated with this job (name string).
  80
  81         <LI>Title - the title/job-name associated with this job (name string).
  82
  83         <LI>Copies - the number of copies required (integer).
  84
  85         <LI>Options - the options associated with this job (space separated
  86         option strings).
  87
  88         <LI>Filename (optional) - the file to print; if this option is not
  89         specified, the backend must read the print file from the standard
  90         input.
  91
  92 </UL>
  93
  94 <P>Backends are named using the scheme of the URI, so a URI of
  95 "ipp://hostname/resource" would be processed by the "ipp" backend.
  96
  97 <H3>ipp</H3>
  98
  99 <P>The ipp backend sends the specified job to a network printer or host using
 100 the Internet Printing Protocol.  The URI is as specified by the
 101 <CODE>printer-uri-supported</CODE> attribute from the printer or host.
 102
 103 <H3>lpd</H3>
 104
 105 <P>The lpd backend sends the specified job to a network printer or host using
 106 the Line Printer Daemon protocol.  The URI is of the form:
 107
 108 <UL><PRE>lpd://hostname/queue
 109 </PRE></UL>
 110
 111 <H3>parallel</H3>
 112
 113 <P>The parallel backend sends the specified job to a local printer connected
 114 via the specified parallel port device.  The URI is of the form:
 115
 116 <UL><PRE>parallel:/dev/file
 117 </PRE></UL>
 118
 119 <H3>serial</H3>
 120
 121 <P>The serial backend sends the specified job to a local printer connected
 122 via the specified serial port device.  The URI is of the form:
 123
 124 <UL><PRE>serial:/dev/file?option[+option+...]
 125 </PRE></UL>
 126
 127 The options can be any combination of the following:
 128
 129 <UL>
 130
 131         <LI><CODE>baud=<I>rate</I></CODE> - Sets the baud rate for the device.
 132
 133         <LI><CODE>bits=<I>7 or 8</I></CODE> - Sets the number of data bits.
 134
 135         <LI><CODE>parity=<I>even</I></CODE> - Sets even parity checking.
 136
 137         <LI><CODE>parity=<I>odd</I></CODE> - Sets odd parity checking.
 138
 139         <LI><CODE>parity=<I>none</I></CODE> - Turns parity checking off.
 140
 141         <LI><CODE>flow=dtrdsr<I></I></CODE> - Turns DTR/DSR (hardware) flow
 142         control on.
 143
 144         <LI><CODE>flow=hard<I></I></CODE> - Turns RTS/CTS
 145         (hardware) flow control on.
 146
 147         <LI><CODE>flow=none<I></I></CODE> - Turns flow control off.
 148
 149         <LI><CODE>flow=rtscts<I></I></CODE> - Turns RTS/CTS
 150         (hardware) flow control on.
 151
 152         <LI><CODE>flow=xonxoff<I></I></CODE> - Turns XON/XOFF
 153         (software) flow control on.
 154
 155 </UL>
 156
 157 <H3>socket</H3>
 158
 159 <P>The socket backend sends the specified job to a network host using the
 160 AppSocket protocol commonly used by Hewlett-Packard and Tektronix
 161 printers.  The URI is of the form:
 162
 163 <UL><PRE>socket://hostname[:port]
 164 </PRE></UL>
 165
 166 The default port number is 9100.
 167
 168 <H3>usb</H3>
 169
 170 <P>The usb backend sends the specified job to a local printer connected
 171 via the specified usb port device.  The URI is of the form:
 172
 173 <UL><PRE>usb:/dev/file
 174 </PRE></UL>
 175
 176 <H2>Berkeley Commands</H2>
 177
 178 <P>The Berkeley commands provide a simple command-line interface to CUPS
 179 to submit and control print jobs. It is provided for compatibility with
 180 existing software that is hardcoded to use the Berkeley commands.
 181
 182 <H3>lpc</H3>
 183
 184 The lpc command allows users and administrators to check the status and
 185 control print queues.  The version provided with CUPS supports the following
 186 commands:
 187
 188 <UL>
 189
 190         <LI>quit - Quits the lpc command.
 191
 192         <LI>status - Shows the status of printers and jobs in the queue.
 193
 194 </UL>
 195
 196 <H3>lpq</H3>
 197
 198 <P>The lpq command shows the current queue status.
 199
 200 <H3>lpr</H3>
 201
 202 <P>The lpr command submits a job for printing.  The CUPS version of lpr silently
 203 ignores the "i", "t", "m", "h", and "s" options.
 204
 205 <H3>lprm</H3>
 206
 207 <P>The lprm removes one or more print jobs.
 208
 209 <H2>CGI</H2>
 210
 211 <P>The Common Gateway Interface (CGI) programs provide a web-based
 212 status interface to monitor the status of printers, classes, and jobs.
 213 Each of the CGIs utilize HTML template files that can be customized to
 214 provide alternate appearances.
 215
 216 <H3>admin.cgi</H3>
 217
 218 <P>The admin CGI provides administration interfaces for printers and
 219 classes. The user can add, modify, delete, start, stop, and configure
 220 printers and classes using "wizard" interfaces.
 221
 222 <H3>classes.cgi</H3>
 223
 224 <P>The classes CGI lists the available printer classes and any pending
 225 jobs for the class.  The user can click on individual classes to limit
 226 the display and click on jobs to see the job status.
 227
 228 <H3>jobs.cgi</H3>
 229
 230 <P>The jobs CGI lists the queued print jobs in order of priority.  The
 231 list can be limited by printer or job.
 232
 233 <H3>printers.cgi</H3>
 234
 235 <P>The printers CGI lists the available printer queues and any pending
 236 jobs for the printer.  The user can click on individual printers to
 237 limit the display and click on jobs to see the job status.
 238
 239 <H2>CUPS Application Programmers Interface</H2>
 240
 241 <P>The CUPS Application Programmers Interface ("API") provides common
 242 convenience, HTTP, IPP, language, and PPD functions used by the CUPS
 243 software.
 244
 245 <H3>Convenience Functions</H3>
 246
 247 <P>Convenience functions are provided to submit an IPP request, send a
 248 print file, cancel a job, get a list of available printers, get a list
 249 of available classes, get the default printer or class, get the default
 250 server name, get the local username, and get a password string.
 251
 252 <H3>HTTP Functions</H3>
 253
 254 <P>The HTTP functions provide functions to connect to HTTP servers,
 255 issue requests, read data from a server, and write data to a server.
 256
 257 <H3>IPP Functions</H3>
 258
 259 <P>The IPP function provide functions to manage IPP request data and
 260 attributes, read IPP responses from a server, and write IPP requests to
 261 a server.
 262
 263 <H3>Language Functions</H3>
 264
 265 <P>The language functions provide a standard interface for retrieving
 266 common textual messages for a particular locale and determining the
 267 correct encoding (e.g. US ASCII, UTF-8, ISO-8859-1, etc.)
 268
 269 <H3>PPD Functions</H3>
 270
 271 <P>The PostScript Printer Description functions manage PPD files,
 272 select options, check for option conflicts, and emit selected options
 273 in the correct order.
 274
 275 <H2>CUPS Imaging Library</H2>
 276
 277 <P>The CUPS imaging library provides colorspace conversion, color
 278 management, image management, scaling, image file, and raster functions
 279 used by the CUPS raster filters.
 280
 281 <H3>Colorspace Conversion Functions</H3>
 282
 283 <P>The colorspace conversion functions handle conversion of grayscale
 284 and RGB colors to grayscale, RGB, K, CMY, CMYK, and CMYKcm colorspaces.
 285
 286 <H3>Color Management Functions</H3>
 287
 288 <P>The color management functions handle gamut mapping and density
 289 correction. These are integrated with the colorspace conversion
 290 functions so that colorspace conversion and color management are
 291 processed in a single step.
 292
 293 <H3>Image Management Functions</H3>
 294
 295 <P>The image management functions manage a tiled image database that is
 296 swapped to/from disk as needed.
 297
 298 <H3>Scaling Functions</H3>
 299
 300 <P>The scaling functions provide image scaling services using
 301 nearest-neighbor sampling and bilinear interpolation as appropriate.
 302
 303 <H3>Image File Functions</H3>
 304
 305 <P>The image file functions handle loading of all image file formats.
 306
 307 <H3>Raster Functions</H3>
 308
 309 <P>The raster functions manage streams of CUPS raster data (described
 310 in the Interface Design Document) used by non-PostScript printer
 311 drivers and raster filters.
 312
 313 <H2>Daemons</H2>
 314
 315 <P>The daemons provide additional network functions for the scheduler.
 316 Currently only two daemons are provided with CUPS.
 317
 318 <H3>Line Printer Daemon</H3>
 319
 320 <P>The line printer daemon provides remote LPD client support and is
 321 run by the <CODE>inetd(8)</CODE> daemon as needed.
 322
 323 <H3>Polling Daemon</H3>
 324
 325 <P>The polling daemon is used to poll a remote server for a list of
 326 available printers and provide it to the scheduler for addition. A
 327 separate polling daemon is run by the scheduler for every remote
 328 system listed for polling in the scheduler configuration file.
 329
 330 <H2>Filters</H2>
 331
 332 <P>The filters implement file conversion services for CUPS. All filters
 333 are called with a common set of arguments:
 334
 335 <UL>
 336
 337         <LI>Printer name - the name of the destination printer (name string).
 338
 339         <LI>Job Identifier - the job identifier for this job (integer).
 340
 341         <LI>User Name - the user associated with this job (name string).
 342
 343         <LI>Title - the title/job-name associated with this job (name string).
 344
 345         <LI>Copies - the number of copies required (integer).
 346
 347         <LI>Options - the options associated with this job (space separated
 348         option strings).
 349
 350         <LI>Filename (optional) - the file to print; if this option is not
 351         specified, the filter must read the input file from the standard
 352         input.
 353
 354 </UL>
 355
 356 <P>Filters are added to the MIME conversion data file and implement all
 357 necessary conversions from one file type to another.
 358
 359 <H3>hpgltops</H3>
 360
 361 <P>The hpgltops filter converts HP-GL/2 files into PostScript.
 362
 363 <H3>imagetops</H3>
 364
 365 <P>The imagetops filter converts image files into PostScript.
 366
 367 <H3>imagetoraster</H3>
 368
 369 <P>The imagetoraster filter converts image files into CUPS raster data.
 370
 371 <H3>pdftops</H3>
 372
 373 <P>The pdftops filter converts PDF files into PostScript.
 374
 375 <H3>pstops</H3>
 376
 377 <P>The pstops filter inserts printer-specific commands from PPD files and
 378 performs page filtering as requested by the user.
 379
 380 <H3>pstoraster</H3>
 381
 382 <P>The pstoraster filter converts PostScript program data into CUPS
 383 raster data.
 384
 385 <H3>rastertoepson</H3>
 386
 387 <P>The rastertoepson filter handles converting CUPS raster data to
 388 ESC/P and supports both color and black-and-white printers.
 389
 390 <H3>rastertohp</H3>
 391
 392 <P>The rastertohp filter handles converting CUPS raster data to HP-PCL
 393 and supports both color and black-and-white printers.
 394
 395 <H3>texttops</H3>
 396
 397 <P>The texttops filter converts text files into PostScript.
 398
 399 <H2>Scheduler</H2>
 400
 401 <P>The scheduler is a fully-functional HTTP/1.1 and IPP/1.1 server that
 402 manages the printers, classes, and jobs in the system.  It also handles
 403 a simple broadcast-based directory service so that remote print queues
 404 and classes can be accessed transparently from the local system.
 405
 406 <H3>Authorization</H3>
 407
 408 <P>The authorization module is responsible for performing access
 409 control and authentication for all HTTP and IPP requests entering the
 410 system.
 411
 412 <H3>Classes</H3>
 413
 414 <P>The classes module is responsible for managing printer classes in
 415 the system. Each class is a collection of local and/or remote
 416 printers.  The classes module also reads and writes the classes
 417 configuration file.
 418
 419 <H3>Client</H3>
 420
 421 <P>The client module is responsible for all HTTP client
 422 communications.  It handles listening on selected interfaces, accepting
 423 connections from prospective clients, processing incoming HTTP
 424 requests, and sending HTTP responses to those requests.  The client
 425 module also is responsible for executing the external CGI programs as
 426 needed to support web-based printer, class, and job status monitoring
 427 and administration.
 428
 429 <P>Once authorized, all IPP requests are sent to the IPP module.
 430
 431 <H3>Configuration</H3>
 432
 433 <P>The configuration module is responsible for reading the CUPS
 434 configuration file and initializing the appropriate data structures and
 435 values.  The configuration module also stops CUPS services before
 436 reading the configuration file and restarts them after the
 437 configuration file has been read.
 438
 439 <H3>Devices</H3>
 440
 441 <P>The devices module is responsible for managing the list of available
 442 devices for the CUPS-Get-Devices operation.
 443
 444 <H3>Directory Services</H3>
 445
 446 <P>The directory services module sends and recieves printer state
 447 information over a broadcast socket.  Remote printers and classes are
 448 automatically added to or removed from the local printer and class
 449 lists as needed.
 450
 451 <P>The directory services module can only recieve printer state information
 452 over a single UDP port, however it can broadcast to multiple addresses and
 453 ports as needed.
 454
 455 <H3>IPP</H3>
 456
 457 <P>The IPP module handles IPP requests and acts accordingly.  URI
 458 validation is also performed here, as a client can post IPP data to any
 459 URI on the server which might sidestep the access control or
 460 authentication of the HTTP server.
 461
 462 <H3>Jobs</H3>
 463
 464 <P>The jobs module manages print jobs, starts filter and backend
 465 processes for jobs to be printed, and monitors status messages from
 466 those filters and backends.
 467
 468 <H3>Logging</H3>
 469
 470 <P>The logging module manages the access, error, and page log files
 471 that are generated by the scheduler.
 472
 473 <H3>Main</H3>
 474
 475 <P>The main module is responsible for timing out and dispatching input
 476 and output for client connections.  It also watches for incoming
 477 <CODE>SIGHUP</CODE> and <CODE>SIGCHLD</CODE> signals, reloads the
 478 server configuration files as needed, and handles child process errors
 479 and exits.
 480
 481 <H3>MIME</H3>
 482
 483 <P>The Multimedia Internet Mail Exchange module manages a MIME type and
 484 conversion database that supports file typing by extension and content
 485 and least-cost file filtering from a source to a destination file type.
 486
 487 <H3>PPDs</H3>
 488
 489 <P>The PPDs module is responsible for managing the list of available
 490 PPD files for the CUPS-Get-PPDs operation.
 491
 492 <H3>Printers</H3>
 493
 494 <P>The printers module is responsible for managing printers and PPD
 495 files in the system. The printers module also reads and writes the
 496 printers configuration file.
 497
 498 <H2>System V Commands</H2>
 499
 500 <P>The System V commands provide a robust command-line interface to
 501 CUPS to submit and control printers and jobs.
 502
 503 <H3>accept</H3>
 504
 505 <P>The accept command tells the scheduler to accept new jobs for specific
 506 printers.
 507
 508 <H3>cancel</H3>
 509
 510 <P>The cancel command tells the scheduler to cancel one or more jobs that are
 511 queued for printing.
 512
 513 <H3>disable</H3>
 514
 515 <P>The disable command tells the scheduler to stop printing jobs on the
 516 specified printers.
 517
 518 <H3>enable</H3>
 519
 520 <P>The enable command tells the scheduler to start printing jobs on the
 521 specified printers.
 522
 523 <H3>lp</H3>
 524
 525 <P>The lp command submits submits files for printing.  Unlike the standard
 526 System V lp command, a single CUPS lp command will generate a separate
 527 job ID for each file that is printed. Also, the Solaris "f", "H", "P", "S",
 528 and "y" options are silently ignored.
 529
 530 <H3>lpadmin</H3>
 531
 532 <P>The lpadmin command manages printer queues and classes.  The Solaris
 533 "A", "F", "I", "M", "P", "Q", "S", "T", "U", "W", "f", "l", "m", "o",
 534 "s", "t", and "u" options are not supported, and new options "P" (PPD
 535 file) and "E" (enable and accept) are provided to configure
 536 CUPS-specific features.
 537
 538 <H3>lpinfo</H3>
 539
 540 <P>The lpinfo command lists the available PPD files or devices as selected
 541 by the user.
 542
 543 <H3>lpmove</H3>
 544
 545 <P>The lpmove command moves a print job to a new destination.
 546
 547 <H3>lpoptions</H3>
 548
 549 <P>The lpoptions command manages user-defined printers and options.
 550
 551 <H3>lpstat</H3>
 552
 553 <P>The lpstat command lists printers, classes, and jobs as requested by the
 554 user.
 555
 556 <H3>reject</H3>
 557
 558 <P>The reject command tells the scheduler not to accept new jobs for specific
 559 printers.
 560
 561 <EMBED SRC="glossary.shtml">
 562
 563 </BODY>
 564 </HTML>