cups

Contents


CUPS (in progress)


Description

Currently most Linux distros and MacOS X use CUPS (Common UNIX Print System) for printing. CUPS is also available on AIX, FreeBSD, HP-UX, IRIX, NetBSD, OpenBSD, Solaris, and Tru64 UNIX. CUPS uses an extended version of the Internet Printing Protocol (IPP) to send requests from the print client, such as application, to a print server.

IPP is an IEEE Standard; Solaris 10 now provides an IPP-capable print server. However, CUPS is not included in standard UNIX base systems.


Specification Overview

The application-facing API (CUPS API and CUPS PPD API) are most likely scheduled to be included in LSB 3.2. This allows an application developer a way to access a printing system that is available on most Linux systems.


CUPS Implementation



Candidate Tracker Information



Stable

CUPS has been adding APIs rather than deprecating them and has been fairly stable. The release of CUPS 1.1.23 was Jan 03, 2005, and the CUPS 1.2 was released May 08, 2006 with no changes to the existing API.


Versions

A quick check of CUPS versions available in the 3.2 timeframe is:

CUPS Versions across distributions
Distribution CUPS version
Debian Etch 1.2.2
Fedora Core 5 1.2.2
Mandriva Free 2007 1.2.4
Redhat Enterprise Linux Client 5 1.2.2
SUSE Linux Enterprise Desktop 10 1.1.23
Ubuntu 6.06.1 1.2.2


Dependencies

The following list of dependencies is required to build the full CUPS package.

groff (for man pages)
jpeg (for printing images)
png (for printing images)
tiff (for printing images)
zlib (compression support for files, print jobs, and images)


Documentation

CUPS 1.2 User Documentation. CUPS 1.1 documentation is at the bottom of the page.


API Documentation

Included application APIs are the CUPS API and the CUPS PPD API.

Also other APIs are on the parent web page.


Related test suites

CUPS has high-level tests and many unit tests. The unit tests are not complete, but Michael Sweet (the CUPS maintainer) has offered support for adding to the tests where necessary.

According to him:

Right now we have about 80% coverage of the PPD API, and I'd guess about 20% for the convenience functions. The HTTP and IPP APIs (which would allow applications to do IPP requests) have automated tests with about 85% coverage overall.

...

For destinations:

  1. cupsGetDests() returns the correct number of printers (maybe check against the "lpstat -p" output?)
  2. cupsGetDest(NULL, NULL, num_dests, dests) should return a default destination unless none is set, in which case it should return NULL. You can loop through the dests array manually to verify this.
  3. cupsGetDest("name", NULL, num_dests, dests) should return the named destination with instance set to NULL.
  4. cupsGetDest("name", "instance", num_dests, dests) should return the named destination and instance.
  5. The list of printer names and instances should be sorted in ascending order (use strcasecmp to check)
  6. Each printer should have at least the following options: job-sheets-default, printer-info, printer-is-accepting-jobs, printer-location, printer-make-and-model, printer-state, printer-type

For options, you can test the cupsAddOption, cupsGetOption, and cupsParseOptions functions for the proper functioning for various inputs. Basically, cupsAddOption should only add non-NULL values and should never duplicate options (two adds with the same name will yield only 1 option), cupsGetOption should return the value of the named option or NULL, and cupsParseOptions() should handle parsing options in the PAPI-defined text encoding format:

     name=value
     name="value with spaces"
     name='value with spaces'
     name={name=value name=value}


Library analysis data



List of apps and libraries using this library

A list of applications that depend on CUPS was compiled from gentoo linux packaging information. (Gentoo was used because the packaging information was quickly available.)

  • checked
kdelibs
app-office/openoffice
gnustep-base/gnustep-gui
media-gfx/flphoto
net-print/libgnomecups
x11-libs/fox
x11-libs/qt
xfce-base/xfprint
  • not checked
application reason not checked
app-emulation/cedega emulator
app-emulation/wine emulator
app-emulation/winex-transgaming emulator
app-text/acroread have other adobe data
app-text/ghostscript-afpl ghostscript-esp is part of CUPS
app-text/ghostscript-esp ghostscript-esp is part of cups
app-text/ghostscript-gnu ghostscript-esp is part of cups
dev-perl/Net-CUPS not an application
gnome-base/libgnomeprint checked libgnomecups
media-gfx/gimp-print printer drivers
net-misc/nxclient commercial app
net-misc/nxserver-freenx commercial app
net-print/cups-pdf CUPS plugin
net-print/fax4cups not an application
net-print/foo2zjs not an application
net-print/foomatic-filters not an application
net-print/gqueue not an application
net-print/gtklp not an application
net-print/hpijs not an application
net-print/hplip not an application
net-print/hpoj not an application
net-print/mtink not an application
net-print/omni not an application
net-print/xpp not an application
net-wireless/bluez-utils not an application
x11-libs/qt-embedded not an application


Most commonly used interfaces



Interfaces chosen for LSB

The client side of CUPS is contained in the
CUPS API and the
CUPS PPD API.

The API documentation for CUPS is on the web and an application uses interfaces from the CUPS API and the CUPS PPD API.

Since we are trying to keep the client/application API separate from the server API, we are only using a subset of the interfaces listed on those two pages.


CUPS API

The CUPS API is located in cups/cups.h and cups/language.h. Interfaces listed in the header file that aren't included are noted at the end of this section.

The interfaces in italics are new to CUPS 1.2x.

cups/cups.h

cupsAddDest
cupsAddOption
cupsCancelJob
cupsEncryption
cupsFreeDests
cupsFreeJobs
cupsFreeOptions
cupsGetDefault
cupsGetDefault2
cupsGetDest
cupsGetDests
cupsGetDests2
cupsGetFd
cupsGetFile
cupsGetJobs
cupsGetJobs2
cupsGetOption
cupsGetPassword
cupsGetPPD
cupsGetPPD2
cupsLastError
cupsLastErrorString
cupsMarkOptions
cupsParseOptions
cupsPrintFile
cupsPrintFile2
cupsPrintFiles
cupsPrintFiles2
cupsPutFd
cupsPutFile
cupsRemoveOption
cupsServer
cupsSetDests
cupsSetDests2
cupsSetEncryption
cupsSetPasswordCB
cupsSetServer
cupsSetUser
cupsTempFd
cupsTempFile2
cupsUser

cups/language.h

cupsLangDefault
cupsLangEncoding
cupsLangFlush
cupsLangFree
cupsLangGet

Interfaces not included in CUPS API from cups.h or lang.h

Function Reason not included
cupsBackChannelRead in Filter and Backend APIs
cupsBackChannelWrite in Filter and Backend APIs
cupsDoAuthentication in HTTP and IPP section
cupsDoFileRequest in HTTP and IPP section
cupsDoRequest in HTTP and IPP section
cupsEncodeOptions in HTTP and IPP section
cupsEncodeOptions2 in HTTP and IPP section
cupsGetClasses DEPRECATED
cupsGetPrinters DEPRECATED
cupsNotifySubject undocumented
cupsNotifyText undocumented
cupsTempFile DEPRECATED
cupsLangString internal interface


CUPS PPD API

The PPD API is located in cups/ppd.h.

ppdClose
ppdCollect
ppdCollect2
ppdConflicts
ppdEmit
ppdEmitAfterOrder
ppdEmitFd
ppdEmitJCL
ppdEmitJCLEnd
ppdEmitString
ppdErrorString
ppdFindAttr
ppdFindChoice
ppdFindCustomOption
ppdFindCustomParam
ppdFindMarkedChoice
ppdFindNextAttr
ppdFindOption
ppdFirstCustomParam
ppdFirstOption
ppdIsMarked
ppdLastError
ppdLocalize
ppdMarkDefaults
ppdMarkOption
ppdNextCustomParam
ppdNextOption
ppdOpen
ppdOpen2
ppdOpenFd
ppdOpenFile
ppdPageLength
ppdPageSize
ppdPageWidth
ppdSetConformance


Interfaces not used in the previously listed apps

The following tables list interfaces that were not found in the gentoo applications listed above. The CUPS API functions are mostly used, but only about half of the PPD API functions are used.

Unused API CUPS functions

Most of the CUPS API functions are used by the applications in the "gentoo list." The list shows that older versions of updated functions are always used at this time, (e.g. cupsGetDests rather than cupsGetDests2) and this could be due to slow adoption of newer functions. All three deprecated interfaces are unused. And then finally cupsLangFlush is unused, probably because a single language is used in the print job and everything is destroyed after use rather than flushed during use.

Function extra info
cupsGetClasses DEPRECATED
cupsGetDefault2 new in CUPS 1.1.21 - using cupsGetDefault
cupsGetDests2 new in CUPS 1.1.21 - using cupsGetDests
cupsGetFile new in CUPS 1.1.20 - using httpGet
cupsGetJobs2 new in CUPS 1.1.21 - using cupsGetJobs
cupsGetPPD2 new in CUPS 1.1.21 - using cupsGetPPD
cupsGetPrinters DEPRECATED
cupsLangFlush no need to flush the language cache?
cupsPrintFile2 new in CUPS 1.1.21 - using cupsPrintFile
cupsPrintFiles2 new in CUPS 1.1.21 - using cupsGetFiles
cupsPutFile new in CUPS 1.1.20
cupsSetDests2 new in CUPS 1.1.21 - using cupsSetDests
cupsSetEncryption using cupsEncryption?
cupsTempFile DEPRECATED

Unused API PPD functions

Only 8 out of 35 PPD functions are used by the sampled applications. The parsing of PPD options is fairly straightforward and can be performed by a small subset of functions.

Functions used:

ppdClose()
ppdFindAttr() CUPS 1.1.19
ppdFindOption()
ppdMarkDefaults()
ppdMarkOption()
ppdOpen()
ppdOpenFile()
ppdPageSize()

Functions unused

ppdCollect 
ppdConflicts 
ppdEmit 
ppdEmitFd 
ppdEmitJCL 
ppdErrorString new in CUPS 1.1.19
ppdFindChoice 
ppdFindMarkedChoice 
ppdFindNextAttr new in CUPS 1.1.19
ppdIsMarked 
ppdLastError new in CUPS 1.1.19
ppdOpenFd 
ppdPageLength 
ppdPageWidth 
ppdSetConformance new in CUPS 1.1.20


Candidate Interfaces to be Tested



Other information

A generic API for print services PAPI is being developed by OpenPrinting Workgroup of the LF. However, PAPI is missing printer description infrastructure such as PPD access functions. PAPI is not included in all the mainstream Linux distros so it is not a candidate for inclusion in LSB 3.2.

The renderer in CUPS requires linking with with libcupsimage, and the licensing requires a fee or the release of the source code (Note: Easy Software Products has since retroactively changed the libcupsimage license to LGPL, allowing developers to provide drivers linked to it at no charge...) An option to CUPS renderer is the OpenPrinting Print Driver API (PDAPI) that was developed by Japanese printer manufacturers. [1]

Glue code for OpenPrinting Vector is currently included in ESP Ghostscript (development discontinued) and in GPL Ghostscript so it is included in the latest versions of most distros.

Groups: