From: jlovell Date: Sat, 4 Mar 2006 15:56:42 +0000 (+0000) Subject: Load cups into easysw/current. X-Git-Tag: release-1.6.3~245 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4744bd907e6750c26bba4354d986e342406147ca;p=thirdparty%2Fcups.git Load cups into easysw/current. git-svn-id: svn+ssh://src.apple.com/svn/cups/easysw/current@75 a1ca3aef-8c08-0410-bb20-df032aa958be --- diff --git a/CGI.txt b/CGI.txt deleted file mode 100644 index 337acb8913..0000000000 --- a/CGI.txt +++ /dev/null @@ -1,81 +0,0 @@ -CGI - CUPS v1.1.21 - 06/29/2004 -------------------------------- - -This file describes the experimental scripting/CGI support -provided by CUPS starting with CUPS 1.1.19. - -WARNING: CGI support is not complete; you may run into problems -and limitations in the implementation of CGI in CUPS that are -not present in full-featured web servers like Apache. - - -OVERVIEW OF CGI SUPPORT IN CUPS - -CUPS has traditionally provided a dynamic web interface through -four CGI programs that are executed when users open special -directories on the CUPS server. Each CGI performs -administration, class, job, and printer functions as directed by -the user, but the actual programs that are run and functions -that are available are limited to those that were originally -designed into the scheduler. - -Starting with CUPS 1.1.19, support is now available for CGI -programs and specific scripting languages, currently Java, Perl, -PHP, and Python. The interpreters for these languages are -currently configured at compile time. Future versions may -expand the interface to allow for generic support of scripting -languages similar to the Apache "AddHandler" directive, but with -external programs instead of modules. - -The following MIME types are reserved for the CGI support in -CUPS (the names have been chosen to mirror those used by -Apache): - - application/x-httpd-cgi CGI script/program - application/x-httpd-java Java program - application/x-httpd-perl Perl script - application/x-httpd-php PHP script - application/x-httpd-python Python script - -In order to enable the corresponding type, you must create a new -/etc/cups/cgi.types file which maps the filename extensions to -the appropriate MIME type, for example: - - application/x-httpd-cgi cgi - application/x-httpd-php php - -CGI scripts/programs (application/x-httpd-cgi) also must have -execution permissions to be treated as a CGI script or program. - - -LIMITATIONS - -CUPS implements most of the CGI/1.1 specification, with the -following limitations: - - - No Location: redirection support. - - No PATH_INFO or PATH_TRANSLATED support. - - Limited HTTP field support; only the Content-Length - (CONTENT_LENGTH), Cookie (HTTP_COOKIE), and User-Agent - (HTTP_USER_AGENT) fields are placed in environment - variables at this time. - - -REPORTING PROBLEMS - -If you have problems, READ THE DOCUMENTATION FIRST! If the -documentation does not solve your problems please send an email -to "cups-support@cups.org". Include your operating system and -version, compiler and version, and any errors or problems you've -run into. The "/var/log/cups/error_log" file should also be sent, -as it often helps to determine the cause of your problem. - -If you are running a version of Linux, be sure to provide the -Linux distribution you have, too. - -Please note that the "cups-support@cups.org" email address goes -to the CUPS developers; they are busy people, so your email may -go unanswered for days or weeks. In general, only general build -or distribution problems will actually get answered - for -end-user support see the "README.txt" for a summary of the -resources available. diff --git a/ENCRYPTION.txt b/ENCRYPTION.txt deleted file mode 100644 index e0e3ba9ffd..0000000000 --- a/ENCRYPTION.txt +++ /dev/null @@ -1,142 +0,0 @@ -ENCRYPTION - CUPS v1.1.20 - 11/24/2003 --------------------------------------- - -This file describes the encryption support provided by CUPS. - -WARNING: CLIENTS CURRENTLY TRUST ALL CERTIFICATES FROM SERVERS. -This makes the CUPS client applications vulnerable to "man in -the middle" attacks, so we don't recommend using this to do -remote administration over WANs at this time. - -Future versions of CUPS will keep track of server certificates -and provide a callback/confirmation interface for accepting new -certificates and warning when a certificate has changed. - - -LEGAL STUFF - -BEFORE USING THE ENCRYPTION SUPPORT, PLEASE VERIFY THAT IT IS -LEGAL TO DO SO IN YOUR COUNTRY. CUPS by itself doesn't include -any encryption code, but it can link against the OpenSSL, GNU -TLS, or CDSA libraries which do. - - -OVERVIEW OF ENCRYPTION SUPPORT IN CUPS - -CUPS supports SSL/2.0, SSL/3.0, and TLS/1.0 encryption using -keys as large as 128-bits. Encryption support is provided via -the OpenSSL, GNU TLS, or CDSA libraries and some new hooks in -the CUPS code. - -CUPS provides support for dedicated (https) and "upgrade" (TLS) -encryption of sessions. The "HTTP Upgrade" method is described -in RFC 2817; basically, the client can be secure or unsecure, -and the client or server initiates an upgrade to a secure -connection via some new HTTP fields and status codes. The HTTP -Upgrade method is new and no browsers we know of support it yet. -Stick with "https" for web browsers. - -The current implementation is very basic. The CUPS client -software (lp, lpr, etc.) uses encryption as requested by the -user or server. - -The user can specify the "-E" option with the printing commands -to force encryption of the connection. Encryption can also be -specified using the Encryption directive in the client.conf file -or in the CUPS_ENCRYPTION environment variable: - - Never - - Never do encryption. - - Always - - Always do SSL/TLS encryption using the https scheme. - - IfRequested - - Upgrade to TLS encryption if the server asks for it. - This is the default setting. - - Required - - Always upgrade to TLS encryption as soon as the - connection is made. This is different than the "Always" - mode above since the connection is initially unsecure - and the client initiates the upgrade to TLS encryption. - (same as using the "-E" option) - -These keywords are also used in the cupsd.conf file to secure -particular locations. To secure all traffic on the server, listen -on port 443 (https port) instead of port 631 and change the "ipp" -service listing (or add it if you don't have one) in /etc/services -to 443. To provide both secure and normal methods, add a line -reading: - - SSLPort 443 - -to /etc/cups/cupsd.conf. - - -BEFORE YOU BEGIN - -You'll need the OpenSSL, GNU TLS, or CDSA libraries from: - - http://www.openssl.org/ - http://www.gnutls.org/ - http://www.intel.com/labs/archive/cdsa.htm - - -CONFIGURING WITH ENCRYPTION SUPPORT - -Once you have the OpenSSL, GNU TLS, or CDSA libraries installed, -you'll need to configure CUPS to use it with the "--enable-ssl" -option: - - ./configure --enable-ssl - -If the library stuff is not in a standard location, make sure to -define the CFLAGS, CXXFLAGS, and LDFLAGS environment variables -with the appropriate compiler and linker options first. - - -GENERATING A SERVER CERTIFICATE AND KEY - -The following OpenSSL command will generate a server certificate -and key that you can play with. Since the certificate is not -properly signed it will generate all kinds of warnings in -Netscape and MSIE: - - openssl req -new -x509 -keyout /etc/cups/ssl/server.key \ - -out /etc/cups/ssl/server.crt -days 365 -nodes - - chmod 600 /etc/cups/ssl/server.* - -The "-nodes" option prevents the certificate and key from being -encrypted. The cupsd process runs in the background, detached -from any input source; if you encrypt these files then cupsd -will not be able to load them! - -Send all rants about non-encrypted certificate and key files to -/dev/null. It makes sense to encrypt user files, but not for -files used by system processes/daemons... - - -REPORTING PROBLEMS - -If you have problems, READ THE DOCUMENTATION FIRST! If the -documentation does not solve your problems please send an email -to "cups-support@cups.org". Include your operating system and -version, compiler and version, and any errors or problems you've -run into. The "/var/log/cups/error_log" file should also be sent, -as it often helps to determine the cause of your problem. - -If you are running a version of Linux, be sure to provide the -Linux distribution you have, too. - -Please note that the "cups-support@cups.org" email address goes -to the CUPS developers; they are busy people, so your email may -go unanswered for days or weeks. In general, only general build -or distribution problems will actually get answered - for -end-user support see the "README.txt" for a summary of the -resources available. diff --git a/INSTALL.txt b/INSTALL.txt index fd2e5ec576..86b6c66aab 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -1,190 +1,174 @@ -INSTALL - CUPS v1.2.0a1 - 01/07/2003 ------------------------------------- +INSTALL - CUPS v1.2b1 - 2006-03-03 +---------------------------------- This file describes how to compile and install CUPS from source code. For more information on CUPS see the file called "README.txt". A complete change log can be found in "CHANGES.txt". -**** IF YOU HAVE A NON-POSTSCRIPT PRINTER, YOU WILL ALSO **** -**** NEED TO INSTALL ESP GHOSTSCRIPT OR A PATCHED VERSION **** -**** OF THE STANDARD GHOSTSCRIPT RELEASES. **** +**** IF YOU HAVE A NON-POSTSCRIPT PRINTER, YOU WILL ALSO **** +**** NEED TO INSTALL ESP GHOSTSCRIPT AFTER YOU INSTALL CUPS **** BEFORE YOU BEGIN -You'll need ANSI-compliant C and C++ compilers, plus a make -program and Bourne shell. The GNU compiler tools work well - -we've tested the current CUPS code against GCC 2.95.x with -excellent results. + You'll need ANSI-compliant C and C++ compilers, plus a make + program and Bourne shell. The GNU compiler tools work well - + we've tested the current CUPS code against several versions + of GCC with excellent results. -The makefiles used by the project should work with all versions -of make. We've tested them with GNU make as well as the make -programs shipped by Compaq, HP, SGI, and Sun. FreeBSD users -should use GNU make (gmake). + The makefiles used by the project should work with all + versions of make. We've tested them with GNU make as well as + the make programs shipped by Compaq, HP, SGI, and Sun. + FreeBSD users should use GNU make (gmake). -Besides these tools you'll want the following libraries: + Besides these tools you'll want the JPEG, PNG, TIFF, and ZLIB + libraries for image support, the CDSA, GNU TLS, or OpenSSL + libraries for encryption support, and the OpenLDAP and + OpenSLP libraries for directory services support. CUPS will + compile and run without these, however you'll miss out on + many of the features provided by CUPS. - - JPEG 6b or higher - - PNG 1.0.6 or higher - - TIFF 3.4 or higher - - ZLIB 1.1.3 or higher + Also, please note that CUPS no longer includes the + Ghostscript- based pstoraster filter. You *must* download + ESP Ghostscript separately from the CUPS web site if you want + to print PostScript files to non-PostScript printers. -CUPS will compile and run without these, however you'll miss out on -many of the features provided by CUPS. -Also, please note that CUPS no longer includes the Ghostscript- -based pstoraster filter. You *must* download Ghostscript -separately and patch it using the files in the pstoraster -subdirectory, or download the ESP Ghostscript distribution from -the CUPS web site. For more information see the README file in -the pstoraster subdirectory. +COMPILING FROM SUBVERSION + The CUPS Subversion repository doesn't hold a copy of the + pre-built configure script. You'll need to run the GNU + autoconf software (2.52 or higher) before compiling the + software from Subversion: -COMPILING FROM CVS - -The CUPS CVS repository doesn't hold a copy of the pre-built -configure script. You'll need to run the GNU autoconf software -(2.52 or higher) before compiling the software from CVS: - - autoconf ENTER + autoconf -f CONFIGURATION -CUPS uses GNU autoconf, so you should find the usual "configure" -script in the main CUPS source directory. To configure CUPS for -your system, type: - - ./configure ENTER - -The default installation will put the CUPS software in the -"/etc", "/usr", and "/var" directories on your system, which -will overwrite any existing printing commands on your system. -Use the "--prefix" option to install the CUPS software in -another location: - - ./configure --prefix=/some/directory ENTER + CUPS uses GNU autoconf, so you should find the usual + "configure" script in the main CUPS source directory. To + configure CUPS for your system, type: -If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in -a system default location (typically "/usr/include" and -"/usr/lib") you'll need to set the CFLAGS, CXXFLAGS, DSOFLAGS, -and LDFLAGS environment variables prior to running configure: + ./configure - setenv CFLAGS "-I/some/directory" ENTER - setenv CXXFLAGS "-I/some/directory" ENTER - setenv DSOFLAGS "-L/some/directory" ENTER - setenv LDFLAGS "-L/some/directory" ENTER - ./configure ... ENTER + The default installation will put the CUPS software in the + "/etc", "/usr", and "/var" directories on your system, which + will overwrite any existing printing commands on your system. + Use the "--prefix" option to install the CUPS software in + another location: -or: + ./configure --prefix=/some/directory - CFLAGS="-I/some/directory"; export CFLAGS ENTER - CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER - DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER - LDFLAGS="-L/some/directory"; export LDFLAGS ENTER - ./configure ... ENTER + To see a complete list of configuration options, use the + --help option: -To enable support for encryption, you'll also want to add the -"--enable-ssl" option: + ./configure --help - ./configure --enable-ssl + If any of the dependent libraries are not installed in a + system default location (typically "/usr/include" and + "/usr/lib") you'll need to set the CFLAGS, CPPFLAGS, + CXXFLAGS, DSOFLAGS, and LDFLAGS environment variables prior + to running configure: -SSL and TLS support require the OpenSSL library, available at: + setenv CFLAGS "-I/some/directory" + setenv CPPFLAGS "-I/some/directory" + setenv CXXFLAGS "-I/some/directory" + setenv DSOFLAGS "-L/some/directory" + setenv LDFLAGS "-L/some/directory" + ./configure ... - http://www.openssl.org + or: -If the OpenSSL header files and libraries are not in a standard -location, specify the locations of these files using the ---with-openssl-includes and --with-openssl-libs directives: + CFLAGS="-I/some/directory" \ + CPPFLAGS="-I/some/directory" \ + CXXFLAGS="-I/some/directory" \ + DSOFLAGS="-L/some/directory" \ + LDFLAGS="-L/some/directory" \ + ./configure ... - ./configure --enable-ssl \ - --with-openssl-includes=/foo/bar/include \ - --with-openssl-libs=/foo/bar/lib + Once you have configured things, just type: -See the file "ENCRYPTION.txt" for information on using the -encryption support in CUPS. + make ENTER -Once you have configured things, just type: + or if you have FreeBSD, NetBSD, or OpenBSD type: - make ENTER + gmake ENTER -or if you have FreeBSD, NetBSD, or OpenBSD type: - - gmake ENTER - -to build the software. + to build the software. INSTALLING THE SOFTWARE -Once you have built the software you need to install it. The -"install" target provides a quick way to install the software on -your local system: + Once you have built the software you need to install it. The + "install" target provides a quick way to install the software + on your local system: - make install ENTER + make install ENTER -or for FreeBSD, NetBSD, or OpenBSD: + or for FreeBSD, NetBSD, or OpenBSD: - gmake install ENTER + gmake install ENTER -You can also build binary packages that can be installed on other -machines using the RPM spec file ("cups.spec") or EPM list file -("cups.list"). The latter also supports building of binary RPMs, -so it may be more convenient to use - we use EPM to build all of -our binary distributions. + You can also build binary packages that can be installed on + other machines using the RPM spec file + ("packaging/cups.spec") or EPM list file + ("packaging/cups.list"). The latter also supports building + of binary RPMs, so it may be more convenient to use - we use + EPM to build all of our binary distributions. -You can find the RPM software at: + You can find the RPM software at: - http://www.rpm.org + http://www.rpm.org/ -The EPM software is at: + The EPM software is available at: - http://www.easysw.com/epm/ + http://www.easysw.com/epm/ CREATING BINARY DISTRIBUTIONS WITH EPM -The top level makefile supports generation of many types of binary -distributions using EPM. To build a binary distribution type: + The top level makefile supports generation of many types of binary + distributions using EPM. To build a binary distribution type: - make ENTER + make ENTER -or + or - gmake ENTER + gmake ENTER -for FreeBSD, NetBSD, and OpenBSD. The target is one of -the following: + for FreeBSD, NetBSD, and OpenBSD. The target is one of + the following: - epm - Builds a portable shell script and tar file based - distribution. This format will also backup your - existing printing system if you decide to remove - CUPS at some future time. - aix - Builds an AIX binary distribution. - bsd - Builds a *BSD binary distribution. - deb - Builds a Debian binary distribution. - depot - Builds a HP-UX binary distribution. - pkg - Builds a Solaris binary distribution. - rpm - Builds a RPM binary distribution. - tardist - Builds an IRIX binary distribution. + epm - Builds a script + tarfile package + aix - Builds an AIX package + bsd - Builds a *BSD package + deb - Builds a Debian package + depot - Builds a HP-UX package (also swinstall) + inst - Builds an IRIX package (also tardist) + osx - Builds a MacOS X package + pkg - Builds a Solaris package + rpm - Builds a RPM package + setld - Build a Tru64 UNIX package + slackware - Build a Slackware package + swinstall - Build a HP-UX package (also depot) + tardist - Builds an IRIX package (also inst) REPORTING PROBLEMS -If you have problems, READ THE DOCUMENTATION FIRST! If the -documentation does not solve your problems please send an email -to "cups-support@cups.org". Include your operating system and -version, compiler and version, and any errors or problems you've -run into. The "/var/log/cups/error_log" file should also be sent, -as it often helps to determine the cause of your problem. - -If you are running a version of Linux, be sure to provide the -Linux distribution you have, too. - -Please note that the "cups-support@cups.org" email address goes -to the CUPS developers; they are busy people, so your email may -go unanswered for days or weeks. In general, only general build -or distribution problems will actually get answered - for -end-user support see the "README.txt" for a summary of the -resources available. + If you have problems, READ THE DOCUMENTATION FIRST! If the + documentation does not solve your problems, please post a + message on the "cups.general" forum at: + + http://www.cups.org/newsgroups.php + + Include your operating system and version, compiler and + version, and any errors or problems you've run into. The + "config.log" file and the output from the configure script + and make should also be sent, as it often helps to determine + the cause of your problem. + + If you are running a version of Linux, be sure to provide the + Linux distribution you have, too. diff --git a/LICENSE.txt b/LICENSE.txt index 12e4af6bcd..797ee5db95 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -128,8 +128,8 @@ is based on the Xpdf software. For binary distribution licensing of this software, please contact: Derek B. Noonburg - Email: derekn@foolabs.com - WWW: http://www.foolabs.com/xpdf/ + Email: derekn@glyphandcog.com + WWW: http://www.glyphandcog.com/ SUPPORT diff --git a/Makefile b/Makefile index 053f65f7fe..3535a9fde9 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 5185 2006-02-26 15:27:14Z mike $" +# "$Id: Makefile 5217 2006-03-02 21:24:01Z mike $" # # Top-level Makefile for the Common UNIX Printing System (CUPS). # @@ -146,36 +146,18 @@ check test: all # -# Make software distributions using EPM (http://www.easysw.com/epm)... +# Make software distributions using EPM (http://www.easysw.com/epm/)... # EPMFLAGS = -v -aix: - epm $(EPMFLAGS) -f aix cups packaging/cups.list - -bsd: - epm $(EPMFLAGS) -f bsd cups packaging/cups.list +aix bsd deb depot inst osx pkg rpm setld slackware swinstall tardist: + epm $(EPMFLAGS) -f $@ cups packaging/cups.list epm: epm $(EPMFLAGS) cups packaging/cups.list -rpm: - epm $(EPMFLAGS) -f rpm cups packaging/cups.list - -deb: - epm $(EPMFLAGS) -f deb cups packaging/cups.list - -depot: - epm $(EPMFLAGS) -f depot cups packaging/cups.list - -pkg: - epm $(EPMFLAGS) -f pkg cups packaging/cups.list - -tardist: - epm $(EPMFLAGS) -f tardist cups packaging/cups.list - # -# End of "$Id: Makefile 5185 2006-02-26 15:27:14Z mike $". +# End of "$Id: Makefile 5217 2006-03-02 21:24:01Z mike $". # diff --git a/README.txt b/README.txt index c2f9648324..28c192d368 100644 --- a/README.txt +++ b/README.txt @@ -1,290 +1,204 @@ -README - CUPS v1.2.0b1 - 01/10/2006 ------------------------------------ - -***************************************************************** -***************************************************************** -**** **** -**** WARNING: THIS IS BETA RELEASE SOFTWARE AND MAY BE **** -**** TOTALLY UNSTABLE. DO NOT USE IN ENVIRONMENTS **** -**** WHERE RELIABLE SOFTWARE IS REQUIRED! **** -**** **** -***************************************************************** -***************************************************************** +README - CUPS v1.2b1 - 2006-03-03 +--------------------------------- Looking for compile instructions? Read the file "INSTALL.txt" instead... -***************************************************************** -***************************************************************** -**** **** -**** IF YOU HAVE A NON-POSTSCRIPT PRINTER, YOU WILL ALSO **** -**** NEED TO INSTALL ESP GHOSTSCRIPT OR A PATCHED VERSION **** -**** OF A STANDARD GHOSTSCRIPT RELEASE. **** -**** **** -***************************************************************** -***************************************************************** - INTRODUCTION -CUPS provides a portable printing layer for UNIX(r)-based -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 ("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 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/ - -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. - - -SYSTEM REQUIREMENTS - -Binary distributions require a minimum of 10MB of free disk -space. We do not recommend using CUPS on a workstation with less -than 32MB of RAM or a PC with less than 16MB of RAM. - -If you are installing from source you'll need ANSI-compliant C -and C++ compilers and optionally one or more image file support -libraries. Complete source installation instructions can be -found in the file "INSTALL.txt". - - -SOFTWARE REQUIREMENTS - -The following operating system software is required to install -one of the binary distributions from Easy Software Products: + CUPS provides a portable printing layer for UNIX(r)-based + 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. - - AIX 4.3 or higher - - HP-UX 11.00 or higher - - IRIX 6.5 or higher - - Linux 2.4 with glibc 2.2 or higher - - Solaris 7 or higher (SPARC or Intel) + 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 GPL Ghostscript 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. -INSTALLING "PORTABLE" CUPS DISTRIBUTIONS + Drivers for thousands of printers are provided with our ESP + Print Pro software, available at: -We are currently distributing "portable" CUPS binary -distributions in TAR format with installation and removal -scripts generated by our ESP Package Manager (EPM) software, -which is available from: + http://www.easysw.com/printpro/ - http://www.easysw.com/epm - -WARNING: Installing CUPS will overwrite your existing printing -system. Backup files are made by the installation script and -restored by the removal script, so if you experience problems -you should be able to remove the CUPS software to restore your -previous configuration. However, Easy Software Products makes -no warranty for this and will not be liable for any lost -revenues, etc. - -To install the CUPS software you will need to be logged in as -root (doing an "su" is good enough). Once you are the root -user, run the installation script with: - - ./cups.install ENTER - -After asking you a few yes/no questions the CUPS software will -be installed and the scheduler will be started automatically. - - -INSTALLING HOST-SPECIFIC (RPM, DEBIAN, ETC.) DISTRIBUTIONS - -The host-specific distributions use the operating system -software installation tools. To install a host-specific -distribution please consult the CUPS Software Administrators -Manual or your operating system documentation. + 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. READING THE DOCUMENTATION -Once you have installed the software you can access the -documentation (and a bunch of other stuff) on-line at: + Once you have installed the software you can access the + documentation (and a bunch of other stuff) on-line at: - http://localhost:631 + http://localhost:631/ -If you're having trouble getting that far, the documentation is -located in the "/usr/share/doc/cups" directory in the binary -distributions, and under the "doc" directory in the source -archives. + If you're having trouble getting that far, the documentation + is located under the "doc/help" directory. -Please read the documentation before asking questions. + Please read the documentation before asking questions. GETTING SUPPORT AND OTHER RESOURCES -If you have problems, READ THE DOCUMENTATION FIRST! We also -provide many discussion forums which are available at: + If you have problems, READ THE DOCUMENTATION FIRST! We also + provide many discussion forums which are available at: - http://www.cups.org/newsgroups.php + http://www.cups.org/newsgroups.php -Commercial support (with a guaranteed response time) is available -from Easy Software Products. For more information see: + Commercial support (with a guaranteed response time) is + available from Easy Software Products. For more information + see: - http://www.easysw.com/cups/ + http://www.easysw.com/cups/ -See the CUPS web site at "http://www.cups.org/" for other site -links. + See the CUPS web site at "http://www.cups.org/" for other + site links. SETTING UP PRINTER QUEUES USING YOUR WEB BROWSER -CUPS 1.2 includes a web-based administration tool that allows you -to manage printers, classes, and jobs on your server. To access -the printer administration tools open the following URL in your -browser: + CUPS 1.2 includes a web-based administration tool that allows + you to manage printers, classes, and jobs on your server. + Open the following URL in your browser to access the printer + administration tools: - http://localhost:631/admin + http://localhost:631/admin/ -You will be asked for the administration password (root or any -other user in the sys/system/root group on your system) and then -shown a menu of available functions. + DO NOT use the hostname for your machine - it will not work + with the default CUPS configuration. To enable + administration access on other addresses, check the "Allow + Remote Administration" box and click on the "Change Settings" + button. -DO NOT use the hostname for your machine - it will not work with -the default CUPS configuration. To enable administration access -on other addresses, consult the CUPS Software Administrators -Manual. + You will be asked for the administration password (root or + any other user in the sys/system/root group on your system) + when performing any administrative function. SETTING UP PRINTER QUEUES FROM THE COMMAND-LINE -CUPS works best with PPD (PostScript Printer Description) -files. In a pinch you can also use System V style printer -interface scripts. - -Six sample PPD files are provided with this distribution that -utilize the PostScript and image file RIPs and the sample EPSON -and HP printer drivers. To add the sample DeskJet driver to the -system for a printer connected to the parallel port, use one of -the following commands: - - HP-UX: + CUPS works best with PPD (PostScript Printer Description) + files. In a pinch you can also use System V style printer + interface scripts. - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/c2t0d0_lp -E + CUPS includes several sample PPD files you can use: - IRIX: + Driver PPD File + ----------------------------- ------------ + Dymo Label Printers dymo.ppd + EPSON Stylus Color Series stcolor.ppd + EPSON Stylus Photo Series stphoto.ppd + EPSON Stylus New Color Series stcolor2.ppd + EPSON Stylus New Photo Series stphoto2.ppd + EPSON 9-pin Series epson9.ppd + EPSON 24-pin Series epson24.ppd + HP DeskJet Series deskjet.ppd + HP LaserJet Series laserjet.ppd + OKIDATA 9-Pin Series okidata9.ppd + OKIDATA 24-Pin Series okidat24.ppd + Zebra EPL1 Label Printer zebraep1.ppd + Zebra EPL2 Label Printer zebraep2.ppd + Zebra ZPL Label Printer zebra.ppd - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/plp -E + Run the "lpinfo" command to list the available printers: - Linux: + lpinfo -v - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp0 -E - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp1 -E - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp2 -E + Then use the correct URI to add the printer using the + "lpadmin" command: - Solaris: + lpadmin -p printername -E -v URI -m filename.ppd - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/bpp0 -E - /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/ecpp0 -E + Network printers typically use "socket" or "lpd" URIs: -Similarly, for the other sample drivers you can use: + lpadmin -p printername -E -v socket://11.22.33.44 -m filename.ppd + lpadmin -p printername -E -v lpd://11.22.33.44/ -m filename.ppd - Driver PPD File - ----------------------------- ------------ - Dymo Label Printers dymo.ppd - EPSON Stylus Color Series stcolor.ppd - EPSON Stylus Photo Series stphoto.ppd - EPSON Stylus New Color Series stcolor2.ppd - EPSON Stylus New Photo Series stphoto2.ppd - EPSON 9-pin Series epson9.ppd - EPSON 24-pin Series epson24.ppd - HP DeskJet Series deskjet.ppd - HP New DeskJet Series deskjet2.ppd - HP LaserJet Series laserjet.ppd - OKIDATA 9-Pin Series okidata9.ppd - OKIDATA 24-Pin Series okidat24.ppd + The sample drivers provide basic printing capabilities, but + generally do not exercise the full potential of the printers + or CUPS. For fully-functional commercial printer drivers + check out our ESP Print Pro software at: -These sample drivers provide basic printing capabilities, but -generally do not exercise the full potential of the printers or -CUPS. For commercial printer drivers check out our ESP Print -Pro software at: - - http://www.easysw.com/printpro/ + http://www.easysw.com/printpro/ PRINTING FILES -CUPS provides both the System V "lp" and Berkeley "lpr" commands -for printing: + CUPS provides both the System V "lp" and Berkeley "lpr" + commands for printing: - lp filename - lpr filename + lp filename + lpr filename -Both the "lp" and "lpr" commands support printing options for -the driver: + Both the "lp" and "lpr" commands support printing options for + the driver: - lp -omedia=A4 -oresolution=600dpi filename - lpr -omedia=A4 -oresolution=600dpi filename + lp -omedia=A4 -oresolution=600dpi filename + lpr -omedia=A4 -oresolution=600dpi filename -CUPS recognizes many types of images files as well as PDF, -PostScript, HP-GL/2, and text files, so you can print those -files directly rather than through an application. + CUPS recognizes many types of images files as well as PDF, + PostScript, HP-GL/2, and text files, so you can print those + files directly rather than through an application. -If you have an application that generates output specifically -for your printer then you need to use the "-oraw" or "-l" -options: + If you have an application that generates output specifically + for your printer then you need to use the "-oraw" or "-l" + options: - lp -oraw filename - lpr -l filename + lp -oraw filename + lpr -l filename -This will prevent the filters from misinterpreting your print -file. + This will prevent the filters from misinterpreting your print + file. LEGAL STUFF -CUPS is Copyright 1993-2006 by Easy Software Products. CUPS, -the CUPS logo, and the Common UNIX Printing System are the -trademark property of Easy Software Products. + CUPS is Copyright 1993-2006 by Easy Software Products. CUPS, + the CUPS logo, and the Common UNIX Printing System are the + trademark property of Easy Software Products. -The MD5 Digest code is Copyright 1999 Aladdin Enterprises. + The MD5 Digest code is Copyright 1999 Aladdin Enterprises. -The PDF filter (pdftops) is based on the Xpdf software, -Copyright 1996-2005 by Derek B. Noonburg. + The PDF filter (pdftops) is based on the Xpdf software, + Copyright 1996-2005 by Derek B. Noonburg. -This software is based in part on the work of the Independent -JPEG Group. + This software is based in part on the work of the Independent + JPEG Group. -CUPS is provided under the terms of the GNU General Public -License and GNU Library General Public License. This program is -distributed in the hope that it will be useful, but WITHOUT ANY -WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the "LICENSE.html", -"LICENSE.txt", or "cups.license" files for more information. + CUPS is provided under the terms of the GNU General Public + License and GNU Library General Public License. This program + is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + "doc/help/license.html" or "LICENSE.txt" files for more + information. -For commercial licensing information, please contact: + For commercial licensing information, please contact: - Attn: CUPS Licensing Information - Easy Software Products - 44141 Airport View Drive, Suite 204 - Hollywood, Maryland 20636 USA + Attn: CUPS Licensing Information + Easy Software Products + 44141 Airport View Drive, Suite 204 + Hollywood, Maryland 20636 USA - Voice: +1.301.373.9600 - Email: cups-info@cups.org - WWW: http://www.cups.org + Voice: +1.301.373.9600 + Email: cups-info@cups.org + WWW: http://www.cups.org/ -Note that commercial licensors may also require a license from -Derek B. Noonburg who developed the Xpdf software used to print -PDF files. + Note that commercial licensors may also require a license from + Derek B. Noonburg who developed the Xpdf software used to print + PDF files. diff --git a/cgi-bin/classes.c b/cgi-bin/classes.c index 2aa9bed788..d7fd569e79 100644 --- a/cgi-bin/classes.c +++ b/cgi-bin/classes.c @@ -1,5 +1,5 @@ /* - * "$Id: classes.c 5160 2006-02-24 01:14:18Z mike $" + * "$Id: classes.c 5202 2006-02-28 19:37:03Z mike $" * * Class status CGI for the Common UNIX Printing System (CUPS). * @@ -84,8 +84,13 @@ main(int argc, /* I - Number of command-line arguments */ */ if ((pclass = getenv("PATH_INFO")) != NULL) + { pclass ++; + if (!*pclass) + pclass = NULL; + } + /* * See who is logged in... */ @@ -458,5 +463,5 @@ show_class(http_t *http, /* I - Connection to server */ /* - * End of "$Id: classes.c 5160 2006-02-24 01:14:18Z mike $". + * End of "$Id: classes.c 5202 2006-02-28 19:37:03Z mike $". */ diff --git a/cgi-bin/help.c b/cgi-bin/help.c index efee0fe5b9..6dc512eadf 100644 --- a/cgi-bin/help.c +++ b/cgi-bin/help.c @@ -56,6 +56,7 @@ main(int argc, /* I - Number of command-line arguments */ directory[1024]; /* Directory */ cups_file_t *fp; /* Help file */ char line[1024]; /* Line from file */ + int printable; /* Show printable version? */ /* @@ -64,6 +65,8 @@ main(int argc, /* I - Number of command-line arguments */ cgiInitialize(); + printable = cgiGetVariable("PRINTABLE") != NULL; + /* * Set the web interface section... */ @@ -92,7 +95,7 @@ main(int argc, /* I - Number of command-line arguments */ { perror(filename); - cgiStartHTML("Help"); + cgiStartHTML(cgiText(_("Help"))); cgiSetVariable("ERROR", "Unable to load help index!"); cgiCopyTemplateLang("error.tmpl"); cgiEndHTML(); @@ -133,7 +136,7 @@ main(int argc, /* I - Number of command-line arguments */ { perror(filename); - cgiStartHTML("Help"); + cgiStartHTML(cgiText(_("Help"))); cgiSetVariable("ERROR", "Unable to access help file!"); cgiCopyTemplateLang("error.tmpl"); cgiEndHTML(); @@ -143,7 +146,7 @@ main(int argc, /* I - Number of command-line arguments */ if ((n = helpFindNode(hi, helpfile, NULL)) == NULL) { - cgiStartHTML("Help"); + cgiStartHTML(cgiText(_("Help"))); cgiSetVariable("ERROR", "Help file not in index!"); cgiCopyTemplateLang("error.tmpl"); cgiEndHTML(); @@ -162,7 +165,10 @@ main(int argc, /* I - Number of command-line arguments */ * Send a standard page header... */ - cgiStartHTML(n->text); + if (printable) + puts("Content-Type: text/html;charset=utf-8\n"); + else + cgiStartHTML(n->text); } else { @@ -170,7 +176,7 @@ main(int argc, /* I - Number of command-line arguments */ * Send a standard page header... */ - cgiStartHTML("Help"); + cgiStartHTML(cgiText(_("Help"))); } /* @@ -311,7 +317,10 @@ main(int argc, /* I - Number of command-line arguments */ * Show the search and bookmark content... */ - cgiCopyTemplateLang("help-header.tmpl"); + if (!helpfile || !printable) + cgiCopyTemplateLang("help-header.tmpl"); + else + cgiCopyTemplateLang("help-printable.tmpl"); /* * If we are viewing a file, copy it in now... @@ -353,7 +362,10 @@ main(int argc, /* I - Number of command-line arguments */ * Send a standard trailer... */ - cgiEndHTML(); + if (!printable) + cgiEndHTML(); + else + puts("\n"); /* * Delete the index... diff --git a/cgi-bin/printers.c b/cgi-bin/printers.c index 0b4a3a8cba..74b950d56d 100644 --- a/cgi-bin/printers.c +++ b/cgi-bin/printers.c @@ -1,5 +1,5 @@ /* - * "$Id: printers.c 5160 2006-02-24 01:14:18Z mike $" + * "$Id: printers.c 5202 2006-02-28 19:37:03Z mike $" * * Printer status CGI for the Common UNIX Printing System (CUPS). * @@ -87,8 +87,13 @@ main(int argc, /* I - Number of command-line arguments */ */ if ((printer = getenv("PATH_INFO")) != NULL) + { printer ++; + if (!*printer) + printer = NULL; + } + /* * See who is logged in... */ @@ -633,5 +638,5 @@ show_printer(http_t *http, /* I - Connection to server */ /* - * End of "$Id: printers.c 5160 2006-02-24 01:14:18Z mike $". + * End of "$Id: printers.c 5202 2006-02-28 19:37:03Z mike $". */ diff --git a/cups/http.c b/cups/http.c index da2279344c..dc0da38927 100644 --- a/cups/http.c +++ b/cups/http.c @@ -1,5 +1,5 @@ /* - * "$Id: http.c 5200 2006-02-28 00:10:32Z mike $" + * "$Id: http.c 5222 2006-03-03 18:57:56Z mike $" * * HTTP routines for the Common UNIX Printing System (CUPS). * @@ -2278,7 +2278,7 @@ http_setup_ssl(http_t *http) /* I - HTTP connection */ gnutls_init(&(conn->session), GNUTLS_CLIENT); gnutls_set_default_priority(conn->session); gnutls_credentials_set(conn->session, GNUTLS_CRD_CERTIFICATE, *credentials); - gnutls_transport_set_ptr(conn->session, http->fd); + gnutls_transport_set_ptr(conn->session, (gnutls_transport_ptr)http->fd); if ((gnutls_handshake(conn->session)) != GNUTLS_E_SUCCESS) { @@ -2754,5 +2754,5 @@ http_write_ssl(http_t *http, /* I - HTTP connection */ /* - * End of "$Id: http.c 5200 2006-02-28 00:10:32Z mike $". + * End of "$Id: http.c 5222 2006-03-03 18:57:56Z mike $". */ diff --git a/doc/Makefile b/doc/Makefile index 443fda185b..ddfe235a33 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 5192 2006-02-27 03:08:47Z mike $" +# "$Id: Makefile 5224 2006-03-04 02:00:43Z mike $" # # Documentation makefile for the Common UNIX Printing System (CUPS). # @@ -29,64 +29,71 @@ include ../Makedefs # LANGUAGES = ja -WEBPAGES = cups.css cupsdoc.css index.html robots.txt +WEBPAGES = \ + cups.css \ + cups-printable.css \ + favicon.ico \ + index.html \ + robots.txt WEBBUTTONS = \ - images/accept-jobs.gif \ - images/add-class.gif \ - images/add-printer.gif \ - images/add-this-printer.gif \ - images/cancel.gif \ - images/cancel-all-jobs.gif \ - images/cancel-job.gif \ - images/change-settings.gif \ - images/clean-print-heads.gif \ - images/continue.gif \ - images/delete-class.gif \ - images/delete-printer.gif \ - images/edit-configuration-file.gif \ - images/export-samba.gif \ - images/help.gif \ - images/hold-job.gif \ - images/manage-classes.gif \ - images/manage-jobs.gif \ - images/manage-printers.gif \ - images/manage-server.gif \ - images/modify-class.gif \ - images/modify-printer.gif \ - images/move-job.gif \ - images/move-jobs.gif \ - images/print-self-test-page.gif \ - images/print-test-page.gif \ - images/publish-printer.gif \ - images/reject-jobs.gif \ - images/release-job.gif \ - images/restart-job.gif \ - images/save-changes.gif \ - images/search.gif \ - images/set-allowed-users.gif \ - images/set-as-default.gif \ - images/set-printer-options.gif \ - images/show-active.gif \ - images/show-all.gif \ - images/show-completed.gif \ - images/show-next.gif \ - images/show-previous.gif \ - images/sort-ascending.gif \ - images/sort-descending.gif \ - images/start-class.gif \ - images/start-printer.gif \ - images/stop-class.gif \ - images/stop-printer.gif \ - images/unpublish-printer.gif \ - images/use-default-config.gif \ - images/view-access-log.gif \ - images/view-error-log.gif \ - images/view-page-log.gif + images/button-accept-jobs.gif \ + images/button-add-class.gif \ + images/button-add-printer.gif \ + images/button-add-this-printer.gif \ + images/button-cancel.gif \ + images/button-cancel-all-jobs.gif \ + images/button-cancel-job.gif \ + images/button-change-settings.gif \ + images/button-clean-print-heads.gif \ + images/button-clear.gif \ + images/button-continue.gif \ + images/button-delete-class.gif \ + images/button-delete-printer.gif \ + images/button-edit-configuration-file.gif \ + images/button-export-samba.gif \ + images/button-help.gif \ + images/button-hold-job.gif \ + images/button-manage-classes.gif \ + images/button-manage-jobs.gif \ + images/button-manage-printers.gif \ + images/button-manage-server.gif \ + images/button-modify-class.gif \ + images/button-modify-printer.gif \ + images/button-move-job.gif \ + images/button-move-jobs.gif \ + images/button-print-self-test-page.gif \ + images/button-print-test-page.gif \ + images/button-publish-printer.gif \ + images/button-reject-jobs.gif \ + images/button-release-job.gif \ + images/button-restart-job.gif \ + images/button-save-changes.gif \ + images/button-search.gif \ + images/button-set-allowed-users.gif \ + images/button-set-as-default.gif \ + images/button-set-printer-options.gif \ + images/button-show-active.gif \ + images/button-show-all.gif \ + images/button-show-completed.gif \ + images/button-show-next.gif \ + images/button-show-previous.gif \ + images/button-sort-ascending.gif \ + images/button-sort-descending.gif \ + images/button-start-class.gif \ + images/button-start-printer.gif \ + images/button-stop-class.gif \ + images/button-stop-printer.gif \ + images/button-unpublish-printer.gif \ + images/button-use-default-config.gif \ + images/button-view-access-log.gif \ + images/button-view-error-log.gif \ + images/button-view-page-log.gif \ + images/button-view-printable-version.gif WEBIMAGES = \ - favicon.ico \ images/bottom-left.gif \ images/bottom-right.gif \ images/classes.gif \ + images/cups-block-diagram.gif \ images/esp-logo.gif \ images/happy.gif \ images/logo.gif \ @@ -97,9 +104,14 @@ WEBIMAGES = \ images/tab-right.gif \ images/top-left.gif \ images/top-middle.gif \ - images/top-right.gif + images/top-right.gif \ + images/web-add-this-printer.gif \ + images/web-password.gif \ + images/web-printer-driver.gif \ + images/web-printer-status.gif \ + images/web-set-printer-options.gif \ + images/web-test-page.gif HELPFILES = \ - help/access_log-reference.html \ help/api-array.html \ help/api-cups.html \ help/api-filedir.html \ @@ -107,30 +119,26 @@ HELPFILES = \ help/api-httpipp.html \ help/api-ppd.html \ help/api-raster.html \ - help/classes-conf-reference.html \ - help/client-conf-reference.html \ - help/cupsd-conf-reference.html \ - help/error_log-reference.html \ - help/page_log-reference.html \ - help/printers-conf-reference.html \ - help/subscriptions-conf-reference.html \ + help/cgi.html \ + help/glossary.html \ + help/license.html \ help/man-accept.html \ help/man-backend.html \ help/man-cancel.html \ help/man-classes.conf.html \ help/man-client.conf.html \ - help/man-cupsaddsmb.html \ help/man-cups-config.html \ - help/man-cupsd.html \ - help/man-cupsd.conf.html \ - help/man-cupsenable.html \ help/man-cups-lpd.html \ help/man-cups-polld.html \ + help/man-cupsaddsmb.html \ + help/man-cupsd.conf.html \ + help/man-cupsd.html \ + help/man-cupsenable.html \ help/man-cupstestppd.html \ help/man-filter.html \ + help/man-lp.html \ help/man-lpadmin.html \ help/man-lpc.html \ - help/man-lp.html \ help/man-lpinfo.html \ help/man-lpmove.html \ help/man-lpoptions.html \ @@ -143,11 +151,26 @@ HELPFILES = \ help/man-mime.types.html \ help/man-printers.conf.html \ help/network.html \ + help/options.html \ help/overview.html \ + help/ref-access_log.html \ + help/ref-classes-conf.html \ + help/ref-client-conf.html \ + help/ref-cupsd-conf.html \ + help/ref-error_log.html \ + help/ref-page_log.html \ + help/ref-printers-conf.html \ + help/ref-subscriptions-conf.html \ + help/security.html \ + help/spec-cmp.html \ help/spec-command.html \ + help/spec-design.html \ help/spec-ipp.html \ help/spec-ppd.html \ + help/spec-raster.html \ + help/spec-stp.html \ help/standard.html \ + help/translation.html \ help/whatsnew.html @@ -184,9 +207,13 @@ install: all done for lang in $(LANGUAGES); do \ $(INSTALL_DIR) -m 755 $(DOCDIR)/$$lang/images; \ - $(INSTALL_MAN) $$lang/index.html $(DOCDIR)/$$lang; \ + if test -f $$lang/index.html; then \ + $(INSTALL_MAN) $$lang/index.html $(DOCDIR)/$$lang; \ + fi \ for file in $(WEBBUTTONS); do \ - $(INSTALL_MAN) $$lang/$$file $(DOCDIR)/$$lang/images; \ + if test -f $$lang/$$file; then \ + $(INSTALL_MAN) $$lang/$$file $(DOCDIR)/$$lang/images; \ + fi \ done \ done diff --git a/doc/cmp.html b/doc/cmp.html deleted file mode 100644 index 7bd293c56f..0000000000 --- a/doc/cmp.html +++ /dev/null @@ -1,755 +0,0 @@ - - - -CUPS Configuration Management Plan - - - - - - - -
CUPS Configuration Management Plan
-

CUPS Configuration Management Plan


-CUPS-CMP-1.1
-Easy Software Products
-Copyright 1997-2005, All Rights Reserved
-
-
-

Table of Contents

-
-
1 Scope - -2 References - -3 File Management - -4 Trouble Report Processing - -5 Software Releases - -A Glossary - -B Coding Requirements - -C Software Trouble Report Form
-

1 Scope

-

1.1 Identification

-

This configuration management plan document provides the guidelines - for development and maintenance of the Common UNIX Printing System - ("CUPS") Version 1.1 software.

-

1.2 System Overview

-

CUPS provides a portable printing layer for UNIX®-based 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 ("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/
-
-

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 configuration management document is organized into the - following sections:

-
    -
  • 1 - Scope
    • -
  • 2 - References
    • -
  • 3 - File Management
    • -
  • 4 - Trouble Report Processing
    • -
  • 5 - Software Releases
    • -
  • A - Glossary
    • -
  • B - Coding Requirements
    • -
-

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:

- -

3 File Management

-

3.1 Directory Structure

-

Each source file shall be placed a sub-directory corresponding to the - software sub-system it belongs to ("scheduler", "cups", etc.) To remain - compatible with older UNIX filesystems, directory names shall not - exceed 16 characters in length.

-

3.2 Source Files

-

Source files shall be documented and formatted as described in - Appendix B, Coding Requirements. To remain compatible with older UNIX - filesystems, source file names shall not exceed 16 characters in - length.

-

3.3 Configuration Management

-

Source files shall be placed under the control of the Concurrent - Versions System ("CVS") software. Source files shall be "checked in" - with each change so that modifications can be tracked.

-

Documentation on the CVS software is included with the whitepaper, - "CVS II: Parallelizing Software Development".

-

4 Trouble Report Processing

-

A Software Trouble Report ("STR") shall be submitted every time a - user or vendor experiences a problem with the CUPS software. Trouble - reports are maintained in a database with one of the following states:

-
    -
  1. STR is closed with complete resolution
    2. -
  2. STR is closed without resolution
    3. -
  3. STR is active
    4. -
  4. STR is pending (new STR or additional information available)
    5. -
-

Trouble reports shall be processed using the following steps.

-

4.1 Classification

-

When a trouble report is received it must be classified at one of the - following priority levels:

-
    -
  1. Request for enhancement, e.g. asking for a feature
    2. -
  2. Low, e.g. a documentation error or undocumented side-effect
    3. -
  3. Moderate, e.g. unable to print a file or unable to compile the - software
    4. -
  4. High, e.g. unable to print to a printer or key functionality not - working
    5. -
  5. Critical, e.g. unable to print at all
    6. -
-

Level 4 and 5 trouble reports must be resolved in the next software - release. Level 1 to 3 trouble reports are scheduled for resolution in a - specific release at the discretion of the release coordinator.

-

The scope of the problem should also be determined as:

-
    -
  1. Specific to a machine or printer
    2. -
  2. Specific to an operating system
    3. -
  3. Applies to all machines, printers, and operating systems
    4. -
-

4.2 Identification

-

Once the level and scope of the trouble report is determined the - software sub-system(s) involved with the problem are determined. This - may involve additional communication with the user or vendor to isolate - the problem to a specific cause.

-

When the sub-system(s) involved have been identified, an engineer - will then determine the change(s) needed and estimate the time required - for the change(s).

-

4.3 Correction

-

Corrections are scheduled based upon the severity and complexity of - the problem. Once all changes have been made, documented, and tested - successfully a new software release snapshot is generated. Additional - tests are added as necessary for proper testing of the changes.

-

4.4 Notification

-

The user or vendor is notified when the fix is available or if the - problem was caused by user error.

-

5 Software Releases

-

5.1 Version Numbering

-

CUPS uses a three-part version number separated by periods to - represent the major, minor, and patch release numbers:

-
-    MAJOR.MINOR.PATCH
-    1.1.0
-
-

Beta-test releases are indentified by appending the letter B followed - by the build number:

-
-    MAJOR.MINOR.PATCHbBUILD
-    1.1.0b1
-
-

Release candidates are indentified by appending the letters RC - followed by the build number:

-
-    MAJOR.MINOR.PATCHrcBUILD
-    1.1.0rc1
-
-

A CVS snapshot is generated for every beta and final release and uses - the version number preceded by the letter "v" and with the decimal - points replaced by underscores:

-
-    v1_1_0b1
-    v1_1_0rc1
-    v1_1_0
-
-

Each change that corrects a fault in a software sub-system increments - the patch release number. If a change affects the overall software - design of CUPS then the minor release number will be incremented and - the patch release number reset to 0. If CUPS is completely redesigned - the major release number will be incremented and the minor and patch - release numbers reset to 0:

-
-    1.1.0b1    First beta release
-    1.1.0b2    Second beta release
-    1.1.0rc1   First release candidate
-    1.1.0rc2   Second release candidate
-    1.1.0      First production release
-    1.1.1b1    First beta of 1.1.1
-    1.1.1rc1   First release candidate of 1.1.1
-    1.1.1      Production release of 1.1.1
-    1.1.2b1    First beta of 1.1.2
-    1.1.2rc1   First release candidate of 1.1.2
-    1.1.2      Production release of 1.1.2
-    2.0.0b1    First beta of 2.0.0
-    2.0.0rc1   First release candidate of 2.0.0
-    2.0.0      Production release of 2.0.0
-
-

5.2 Generation

-

Software releases shall be generated for each successfully completed - software trouble report. All object and executable files shall be - deleted prior to performing a full build to ensure that source files - are recompiled.

-

5.3 Testing

-

Software testing shall be conducted according to the CUPS Software - Test Plan, CUPS-STP-1.1. Failed tests cause STRs to be generated to - correct the problems found.

-

5.4 Releases

-

When testing has been completed successfully a new distribution image - is created from the current CVS code "snapshot". No release shall - contain software that has not passed the appropriate software tests. - Three types of releases are used, beta, release candidate, and - production, and are released using the following basic schedule: -

- - - - - - - - -
WeekVersionDescription
T-6 weeks1.1.0b1First beta
T-5 weeks1.1.0b2Second beta
T-4 weeks1.1.0b3Third beta
T-3 weeks1.1.0rc1First release candidate
T-2 weeks1.1.0rc2Second release candidate
T-0 weeks1.1.0Production
-
-

-

Beta releases are typically used prior to new major and minor version - releases. At least one release candidate is generated prior to each - production release.

-

5.4.1 Beta Releases

-

Beta releases are generated when substantial changes have been made - that may affect the reliability of the software. Beta releases may - cause loss of data, functionality, or services and are provided for - testing by qualified individuals.

-

Beta releases are an OPTIONAL part of the release process and are - generated as deemed appropriate by the release coordinator. Functional - changes may be included in subsequent beta releases until the first - release candidate.

-

5.4.2 Release Candidates

-

Release candidates are generated at least two weeks prior to a - production release. Release candidates are targeted for end-users that - wish to test new functionality or bug fixes prior to the production - release. While release candidates are intended to be substantially - bug-free, they may still contain defects and/or not compile on specific - platforms.

-

At least one release candidate is REQUIRED prior to any production - release. The distribution of a release candidate marks the end of any - functional improvements. Release candidates are generated at weekly - intervals until all level 4/5 trouble reports are resolved.

-

5.4.3 Production Releases

-

Production releases are generated after a successful release - candidate and represent a stable release of the software suitable for - all users.

-

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

B Coding Requirements

-

These coding requirements provide detailed information on source file - formatting and documentation content. These guidelines shall be applied - to all C and C++ source files provided with CUPS. Source code for other - languages should conform to these requirements as allowed by the - language.

-

B.1 Source Files

-

B.1.1 Naming

-

All source files names shall be 16 characters or less in length to - ensure compatibility with older UNIX filesystems. Source files - containing functions shall have an extension of ".c" for ANSI C and - ".cxx" for C++ source files. All other "include" files shall have an - extension of ".h".

-

B.1.2 Documentation

-

The top of each source file shall contain a header giving the name of - the file, the purpose or nature of the source file, the copyright and - licensing notice, and the functions contained in the file. The file - name and revision information is provided by the CVS "$Id$" tag:

-
-    /*
-     * "$Id$"
-     *
-     *   Description of file contents.
-     *
-     *   Copyright 1997-2005 by Easy Software Products, all rights
-     *   reserved.
-     *
-     *   These coded instructions, statements, and computer programs are
-     *   the property of Easy Software Products and are protected by
-     *   Federal copyright law.  Distribution and use rights are outlined
-     *   in the file "LICENSE.txt" which should have been included with
-     *   this file.  If this file is missing or damaged please contact
-     *   Easy Software Products at:
-     *
-     *       Attn: CUPS Licensing Information
-     *       Easy Software Products
-     *       44141 Airport View Drive, Suite 204
-     *       Hollywood, Maryland 20636 USA
-     *
-     *       Voice: (301) 373-9600
-     *       EMail: cups-info@cups.org
-     *         WWW: http://www.cups.org
-     *
-     * Contents:
-     *
-     *   function1() - Description 1.
-     *   function2() - Description 2.
-     *   function3() - Description 3.
-     */
-
- - -

For source files that are subject to the Apple OS-Developed Software - exception, the following additional comment should appear after the - contact information:

-
-     *   This file is subject to the Apple OS-Developed Software exception.
-
-

The bottom of each source file shall contain a trailer giving the - name of the file using the CVS "$Id$" tag. The primary purpose of this - is to mark the end of a source file; if the trailer is missing it is - possible that code has been lost near the end of the file:

-
-    /*
-     * End of "$Id$".
-     */
-
-

B.2 Functions

-

B.2.1 Naming

-

Functions with a global scope shall be capitalized ("DoThis", - "DoThat", "DoSomethingElse", etc.) The only exception to this rule - shall be the CUPS interface library functions which may begin with a - prefix word in lowercase ("cupsDoThis", "cupsDoThat", etc.)

-

Functions with a local scope shall be declared "static" and be - lowercase with underscores between words ("do_this", "do_that", - "do_something_else", etc.)

-

B.2.2 Documentation

-

Each function shall begin with a comment header describing what the - function does, the possible input limits (if any), and the possible - output values (if any), and any special information needed:

-
-    /*
-     * 'do_this()' - Compute y = this(x).
-     *
-     * Notes: none.
-     */
-
-    static float     /* O - Inverse power value, 0.0 <= y <= 1.1 */
-    do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
-    {
-      ...
-      return (y);
-    }
-
-

Return/output values are indicated using an "O" prefix, input values - are indicated using the "I" prefix, and values that are both input and - output use the "IO" prefix for the corresponding in-line comment.

-

B.3 Methods

-

B.3.1 Naming

-

Methods shall be in lowercase with underscores between words - ("do_this", "do_that", "do_something_else", etc.)

-

B.3.2 Documentation

-

Each method shall begin with a comment header describing what the - method does, the possible input limits (if any), and the possible - output values (if any), and any special information needed:

-
-    /*
-     * 'class::do_this()' - Compute y = this(x).
-     *
-     * Notes: none.
-     */
-
-    float                   /* O - Inverse power value, 0.0 <= y <= 1.0 */
-    class::do_this(float x) /* I - Power value (0.0 <= x <= 1.0) */
-    {
-      ...
-      return (y);
-    }
-
-

Return/output values are indicated using an "O" prefix, input values - are indicated using the "I" prefix, and values that are both input and - output use the "IO" prefix for the corresponding in-line comment.

-

B.4 Variables

-

B.4.1 Naming

-

Variables with a global scope shall be capitalized ("ThisVariable", - "ThatVariable", "ThisStateVariable", etc.) The only exception to this - rule shall be the CUPS interface library global variables which must - begin with the prefix "cups" ("cupsThisVariable", "cupsThatVariable", - etc.) Global variables shall be replaced by function arguments whenever - possible.

-

Variables with a local scope shall be lowercase with underscores - between words ("this_variable", "that_variable", etc.) Any local - variables shared by functions within a source file shall be declared - "static".

-

B.4.2 Documentation

-

Each variable shall be declared on a separate line and shall be - immediately followed by a comment block describing the variable:

-
-    int this_variable;   /* The current state of this */
-    int that_variable;   /* The current state of that */
-
-

B.5 Types

-

B.5.1 Naming

-

All type names shall be lowercase with underscores between words and - "_t" appended to the end of the name ("this_type_t", "that_type_t", - etc.)

-

B.5.2 Documentation

-

Each type shall have a comment block immediately before the typedef:

-
-    /*
-     * This type is for CUPS foobar options.
-     */
-    typedef int cups_this_type_t;
-
-

B.6 Structures

-

B.6.1 Naming

-

All structure names shall be lowercase with underscores between words - and "_str" appended to the end of the name ("this_struct_str", - "that_struct_str", etc.)

-

B.6.2 Documentation

-

Each structure shall have a comment block immediately before the - struct and each member shall be documented in accordance with the - variable naming policy above:

-
-    /*
-     * This structure is for CUPS foobar options.
-     */
-    struct cups_this_struct_str
-    {
-      int this_member;   /* Current state for this */
-      int that_member;   /* Current state for that */
-    };
-
-

B.7 Classes

-

B.7.1 Naming

-

All class names shall be lowercase with underscores between words - ("this_class", "that_class", etc.)

-

B.7.2 Documentation

-

Each class shall have a comment block immediately before the class - and each member shall be documented in accordance with the variable - naming policy above:

-
-    /*
-     * This class is for CUPS foobar options.
-     */
-    class cups_this_class
-    {
-      int this_member;   /* Current state for this */
-      int that_member;   /* Current state for that */
-    };
-
-

B.8 Constants

-

B.8.1 Naming

-

All constant names shall be uppercase with underscored between words - ("THIS_CONSTANT", "THAT_CONSTANT", etc.) Constants defined for the CUPS - interface library must begin with an uppercase prefix - ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.)

-

Typed enumerations shall be used whenever possible to allow for type - checking by the compiler.

-

B.8.2 Documentation

-

Comment blocks shall immediately follow each constant:

-
-    enum
-    {
-      CUPS_THIS_TRAY,   /* This tray */
-      CUPS_THAT_TRAY    /* That tray */
-    };
-
-

B.9 Code

-

B.9.1 Documentation

-

All source code shall utilize block comments within functions to - describe the operations being performed by a group of statements:

-
-    /*
-     * Clear the state array before we begin...
-     */
-
-    for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
-      array[i] = STATE_IDLE;
-
-    /*
-     * Wait for state changes...
-     */
-
-    do
-    {
-      for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
-	if (array[i] != STATE_IDLE)
-	  break;
-
-      if (i == (sizeof(array) / sizeof(array[0])))
-	sleep(1);
-    } while (i == (sizeof(array) / sizeof(array[0])));
-
-

B.9.2 Style

-

B.9.2.a Indentation

-

All code blocks enclosed by brackets shall begin with the opening - brace on a new line. The code then follows starting on a new line after - the brace and is indented 2 spaces. The closing brace is then placed on - a new line following the code at the original indentation:

-
-    {
-      int i; /* Looping var */
-
-     /*
-      * Process foobar values from 0 to 999...
-      */
-
-      for (i = 0; i < 1000; i ++)
-      {
-	do_this(i);
-	do_that(i);
-      }
-    }
-
-

Single-line statements following "do", "else", "for", "if", and - "while" shall be indented 2 spaces as well. Blocks of code in a - "switch" block shall be indented 4 spaces after each "case" and - "default" case:

-
-    switch (array[i])
-    {
-      case STATE_IDLE :
-	  do_this(i);
-	  do_that(i);
-	  break;
-      default :
-	  do_nothing(i);
-	  break;
-    }
-
-

B.9.2.b Spacing

-

A space shall follow each reserved word ("if", "while", etc.) Spaces - shall not be inserted between a function name and the arguments in - parenthesis.

-

B.9.2.c Return Values

-

Parenthesis shall surround values returned from a function using - "return":

-
-    return (STATE_IDLE);
-
-

B.9.2.d Loops

-

Whenever convenient loops should count downward to zero to improve - program performance:

-
-    for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
-      array[i] = STATE_IDLE;
-
-

C Software Trouble Report Form

-
- - - - - - - - - - - - - - -
Summary of Problem: -_____________________________________________
 
Problem Severity: -__1Request for enhancement, e.g. asking for a feature
__2Low, e.g. a documentation error or undocumented - side-effect
__3Moderate, e.g. unable to print a file or unable to - compile the software
__4High, e.g. unable to print to a printer or key - functionality not working
__5Critical, e.g. unable to print at all
 
Problem Scope: -__1Machine or printer
__2Operating System
__3All machines, printers, or operating systems
 
Detailed Description of Problem:_____________________________________________ -
_____________________________________________ -
_____________________________________________ -
_____________________________________________ -
_____________________________________________
-
- - diff --git a/doc/cmp.pdf b/doc/cmp.pdf deleted file mode 100644 index 47b50ffe31..0000000000 Binary files a/doc/cmp.pdf and /dev/null differ diff --git a/doc/cmp.shtml b/doc/cmp.shtml deleted file mode 100644 index 360d985ef0..0000000000 --- a/doc/cmp.shtml +++ /dev/null @@ -1,737 +0,0 @@ - - - - - - CUPS Configuration Management Plan - - - -

Scope

- -

Identification

- -

This configuration management plan document provides the -guidelines for development and maintenance of the Common UNIX -Printing System ("CUPS") Version 1.2 software. - - - -

Document Overview

- -

This configuration management document is organized into the -following sections: - -

    -
  • 1 - Scope
    • -
  • 2 - References
    • -
  • 3 - File Management
    • -
  • 4 - Trouble Report Processing
    • -
  • 5 - Software Releases
    • -
  • A - Glossary
    • -
  • B - Coding Requirements
    • -
- - - -

File Management

- -

Directory Structure

- -

Each source file shall be placed a sub-directory -corresponding to the software sub-system it belongs to -("scheduler", "cups", etc.) To remain compatible with older UNIX -filesystems, directory names shall not exceed 16 characters in -length. - -

Source Files

- -

Source files shall be documented and formatted as described -in Appendix B, Coding Requirements. To remain compatible with -older UNIX filesystems, source file names shall not exceed 16 -characters in length. - -

Configuration Management

- -

Source files shall be placed under the control of the -Concurrent Versions System ("CVS") software. Source files shall -be "checked in" with each change so that modifications can be -tracked. - -

Documentation on the CVS software is included with the -whitepaper, "CVS II: Parallelizing Software Development". - -

Trouble Report Processing

- -

A Software Trouble Report ("STR") shall be submitted every -time a user or vendor experiences a problem with the CUPS -software. Trouble reports are maintained in a database with one -of the following states: - -

    -
  1. STR is closed with complete resolution
    2. -
  2. STR is closed without resolution
    3. -
  3. STR is active, waiting on information from submitter
    4. -
  4. STR is pending with additional information from submitter
    5. -
  5. STR is newly submitted
    6. -
- -

Trouble reports shall be processed using the following steps. - -

Classification

- -

When a trouble report is received it must be classified at -one of the following priority levels: - -

    - -
  1. Request for enhancement, e.g. asking for a - feature
    2. - -
  2. Low, e.g. a documentation error or undocumented - side-effect
    3. - -
  3. Moderate, e.g. unable to print a file or unable to - compile the software
    4. - -
  4. High, e.g. unable to print to a printer or key - functionality not working
    5. - -
  5. Critical, e.g. unable to print at all
    6. - -
- -

Level 4 and 5 trouble reports must be resolved in the next -software release. Level 1 to 3 trouble reports are scheduled for -resolution in a specific release at the discretion of the -release coordinator. - -

The scope of the problem should also be determined as: - -

    -
  1. Specific to a machine or printer
    2. -
  2. Specific to an operating system
    3. -
  3. Applies to all machines, printers, and operating systems
    4. -
- -

Identification

- -

Once the level and scope of the trouble report is determined -the software sub-system(s) involved with the problem are -determined. This may involve additional communication with the -user or vendor to isolate the problem to a specific cause. - -

When the sub-system(s) involved have been identified, an -engineer will then determine the change(s) needed and estimate -the time required for the change(s). - -

Correction

- -

Corrections are scheduled based upon the severity and -complexity of the problem. Once all changes have been made, -documented, and tested successfully a new software release -snapshot is generated. Additional tests are added as necessary -for proper testing of the changes. - -

Notification

- -

The user or vendor is notified when the fix is available or -if the problem was caused by user error. - -

Software Releases

- -

Version Numbering

- -

CUPS uses a three-part version number separated by periods to -represent the major, minor, and patch release numbers: - -

-    MAJOR.MINOR.PATCH
-    1.1.0
-
- -

Beta-test releases are indentified by appending the letter B -followed by the build number: - -

-    MAJOR.MINOR.PATCHbBUILD
-    1.1.0b1
-
- -

Release candidates are indentified by appending the letters -RC followed by the build number: - -

-    MAJOR.MINOR.PATCHrcBUILD
-    1.1.0rc1
-
- -

A CVS snapshot is generated for every beta and final release -and uses the version number preceded by the letter "v" and with -the decimal points replaced by underscores: - -

-    v1_1_0b1
-    v1_1_0rc1
-    v1_1_0
-
- -

Each change that corrects a fault in a software sub-system -increments the patch release number. If a change affects the -overall software design of CUPS then the minor release number -will be incremented and the patch release number reset to 0. If -CUPS is completely redesigned the major release number will be -incremented and the minor and patch release numbers reset to 0: - -

-    1.1.0b1    First beta release
-    1.1.0b2    Second beta release
-    1.1.0rc1   First release candidate
-    1.1.0rc2   Second release candidate
-    1.1.0      First production release
-    1.1.1b1    First beta of 1.1.1
-    1.1.1rc1   First release candidate of 1.1.1
-    1.1.1      Production release of 1.1.1
-    1.1.2b1    First beta of 1.1.2
-    1.1.2rc1   First release candidate of 1.1.2
-    1.1.2      Production release of 1.1.2
-    2.0.0b1    First beta of 2.0.0
-    2.0.0rc1   First release candidate of 2.0.0
-    2.0.0      Production release of 2.0.0
-
- -

Generation

- -

Software releases shall be generated for each successfully -completed software trouble report. All object and executable -files shall be deleted prior to performing a full build to -ensure that source files are recompiled.

- -

Testing

- -

Software testing shall be conducted according to the CUPS -Software Test Plan, CUPS-STP-1.1. Failed tests cause STRs to be -generated to correct the problems found.

- -

Releases

- -

When testing has been completed successfully a new -distribution image is created from the current CVS code -"snapshot". No release shall contain software that has not -passed the appropriate software tests. Three types of releases -are used, beta, release candidate, and production, and are -released using the following basic schedule: - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WeekVersionDescription
T-6 weeks1.1.0b1First beta
T-5 weeks1.1.0b2Second beta
T-4 weeks1.1.0b3Third beta
T-3 weeks1.1.0rc1First release candidate
T-2 weeks1.1.0rc2Second release candidate
T-0 weeks1.1.0Production
- -

Beta releases are typically used prior to new major and minor -version releases. At least one release candidate is generated -prior to each production release.

- -

Beta Releases

- -

Beta releases are generated when substantial changes have -been made that may affect the reliability of the software. Beta -releases may cause loss of data, functionality, or services and -are provided for testing by qualified individuals.

- -

Beta releases are an OPTIONAL part of the release process and -are generated as deemed appropriate by the release coordinator. -Functional changes may be included in subsequent beta releases -until the first release candidate.

- -

Release Candidates

- -

Release candidates are generated at least two weeks prior to -a production release. Release candidates are targeted for -end-users that wish to test new functionality or bug fixes prior -to the production release. While release candidates are intended -to be substantially bug-free, they may still contain defects -and/or not compile on specific platforms. - -

At least one release candidate is REQUIRED prior to any -production release. The distribution of a release candidate -marks the end of any functional improvements. Release candidates -are generated at weekly intervals until all level 4/5 trouble -reports are resolved. - -

Production Releases

- -

Production releases are generated after a successful release -candidate and represent a stable release of the software -suitable for all users. - - - -

Coding Requirements

- -

These coding requirements provide detailed information on -source file formatting and documentation content. These -guidelines shall be applied to all C and C++ source files -provided with CUPS. Source code for other languages should -conform to these requirements as allowed by the language. - -

Source Files

- -

Naming

- -

All source files names shall be 16 characters or less in -length to ensure compatibility with older UNIX filesystems. -Source files containing functions shall have an extension of -".c" for ANSI C and ".cxx" for C++ source files. All other -"include" files shall have an extension of ".h". - -

Documentation

- -

The top of each source file shall contain a header giving the -name of the file, the purpose or nature of the source file, the -copyright and licensing notice, and the functions contained in -the file. The file name and revision information is provided by -the CVS "$Id$" tag: - -

-    /*
-     * "$Id$"
-     *
-     *   Description of file contents.
-     *
-     *   Copyright 1997-2005 by Easy Software Products, all rights
-     *   reserved.
-     *
-     *   These coded instructions, statements, and computer programs are
-     *   the property of Easy Software Products and are protected by
-     *   Federal copyright law.  Distribution and use rights are outlined
-     *   in the file "LICENSE.txt" which should have been included with
-     *   this file.  If this file is missing or damaged please contact
-     *   Easy Software Products at:
-     *
-     *       Attn: CUPS Licensing Information
-     *       Easy Software Products
-     *       44141 Airport View Drive, Suite 204
-     *       Hollywood, Maryland 20636 USA
-     *
-     *       Voice: (301) 373-9600
-     *       EMail: cups-info@cups.org
-     *         WWW: http://www.cups.org
-     *
-     * Contents:
-     *
-     *   function1() - Description 1.
-     *   function2() - Description 2.
-     *   function3() - Description 3.
-     */
-
- - -

For source files that are subject to the Apple OS-Developed Software -exception, the following additional comment should appear after the -contact information: - -

-     *   This file is subject to the Apple OS-Developed Software exception.
-
- -

The bottom of each source file shall contain a trailer giving -the name of the file using the CVS "$Id$" tag. The primary -purpose of this is to mark the end of a source file; if the -trailer is missing it is possible that code has been lost near -the end of the file: - -

-    /*
-     * End of "$Id$".
-     */
-
- -

Functions

- -

Naming

- -

Functions with a global scope shall be capitalized ("DoThis", -"DoThat", "DoSomethingElse", etc.) The only exception to this -rule shall be the CUPS interface library functions which may -begin with a prefix word in lowercase ("cupsDoThis", -"cupsDoThat", etc.) - -

Functions with a local scope shall be declared "static" and -be lowercase with underscores between words ("do_this", -"do_that", "do_something_else", etc.) - -

Documentation

- -

Each function shall begin with a comment header describing -what the function does, the possible input limits (if any), and -the possible output values (if any), and any special information -needed: - -

-    /*
-     * 'do_this()' - Compute y = this(x).
-     *
-     * Notes: none.
-     */
-
-    static float     /* O - Inverse power value, 0.0 <= y <= 1.1 */
-    do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
-    {
-      ...
-      return (y);
-    }
-
- -

Return/output values are indicated using an "O" prefix, input -values are indicated using the "I" prefix, and values that are -both input and output use the "IO" prefix for the corresponding -in-line comment. - -

Methods

- -

Naming

- -

Methods shall be in lowercase with underscores between words -("do_this", "do_that", "do_something_else", etc.) - -

Documentation

- -

Each method shall begin with a comment header describing what -the method does, the possible input limits (if any), and the -possible output values (if any), and any special information -needed: - -

-    /*
-     * 'class::do_this()' - Compute y = this(x).
-     *
-     * Notes: none.
-     */
-
-    float                   /* O - Inverse power value, 0.0 <= y <= 1.0 */
-    class::do_this(float x) /* I - Power value (0.0 <= x <= 1.0) */
-    {
-      ...
-      return (y);
-    }
-
- -

Return/output values are indicated using an "O" prefix, input -values are indicated using the "I" prefix, and values that are -both input and output use the "IO" prefix for the corresponding -in-line comment. - -

Variables

- -

Naming

- -

Variables with a global scope shall be capitalized -("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The -only exception to this rule shall be the CUPS interface library -global variables which must begin with the prefix "cups" -("cupsThisVariable", "cupsThatVariable", etc.) Global variables -shall be replaced by function arguments whenever possible. - -

Variables with a local scope shall be lowercase with -underscores between words ("this_variable", "that_variable", -etc.) Any local variables shared by functions within a source -file shall be declared "static". - -

Documentation

- -

Each variable shall be declared on a separate line and shall -be immediately followed by a comment block describing the -variable: - -

-    int this_variable;   /* The current state of this */
-    int that_variable;   /* The current state of that */
-
- -

Types

- -

Naming

- -

All type names shall be lowercase with underscores between -words and "_t" appended to the end of the name ("this_type_t", -"that_type_t", etc.) - -

Documentation

- -

Each type shall have a comment block immediately before the -typedef: - -

-    /*
-     * This type is for CUPS foobar options.
-     */
-    typedef int cups_this_type_t;
-
- -

Structures

- -

Naming

- -

All structure names shall be lowercase with underscores -between words and "_str" appended to the end of the name -("this_struct_str", "that_struct_str", etc.) - -

Documentation

- -

Each structure shall have a comment block immediately before -the struct and each member shall be documented in accordance -with the variable naming policy above: - -

-    /*
-     * This structure is for CUPS foobar options.
-     */
-    struct cups_this_struct_str
-    {
-      int this_member;   /* Current state for this */
-      int that_member;   /* Current state for that */
-    };
-
- -

Classes

- -

Naming

- -

All class names shall be lowercase with underscores between -words ("this_class", "that_class", etc.) - -

Documentation

- -

Each class shall have a comment block immediately before the -class and each member shall be documented in accordance with the -variable naming policy above: - -

-    /*
-     * This class is for CUPS foobar options.
-     */
-    class cups_this_class
-    {
-      int this_member;   /* Current state for this */
-      int that_member;   /* Current state for that */
-    };
-
- -

Constants

- -

Naming

- -

All constant names shall be uppercase with underscored -between words ("THIS_CONSTANT", "THAT_CONSTANT", etc.) Constants -defined for the CUPS interface library must begin with an -uppercase prefix ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", -etc.) - -

Typed enumerations shall be used whenever possible to allow -for type checking by the compiler. - -

Documentation

- -

Comment blocks shall immediately follow each constant: - -

-    enum
-    {
-      CUPS_THIS_TRAY,   /* This tray */
-      CUPS_THAT_TRAY    /* That tray */
-    };
-
- -

Code

- -

Documentation

- -

All source code shall utilize block comments within functions -to describe the operations being performed by a group of -statements: - -

-    /*
-     * Clear the state array before we begin...
-     */
-
-    for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
-      array[i] = STATE_IDLE;
-
-    /*
-     * Wait for state changes...
-     */
-
-    do
-    {
-      for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
-	if (array[i] != STATE_IDLE)
-	  break;
-
-      if (i == (sizeof(array) / sizeof(array[0])))
-	sleep(1);
-    } while (i == (sizeof(array) / sizeof(array[0])));
-
- -

Style

- -

Indentation

- -

All code blocks enclosed by brackets shall begin with the -opening brace on a new line. The code then follows starting on a -new line after the brace and is indented 2 spaces. The closing -brace is then placed on a new line following the code at the -original indentation: - -

-    {
-      int i; /* Looping var */
-
-     /*
-      * Process foobar values from 0 to 999...
-      */
-
-      for (i = 0; i < 1000; i ++)
-      {
-	do_this(i);
-	do_that(i);
-      }
-    }
-
- -

Single-line statements following "do", "else", "for", "if", -and "while" shall be indented 2 spaces as well. Blocks of code -in a "switch" block shall be indented 4 spaces after each "case" -and "default" case: - -

-    switch (array[i])
-    {
-      case STATE_IDLE :
-	  do_this(i);
-	  do_that(i);
-	  break;
-      default :
-	  do_nothing(i);
-	  break;
-    }
-
- -

Spacing

- -

A space shall follow each reserved word ("if", "while", etc.) -Spaces shall not be inserted between a function name and the -arguments in parenthesis. - -

Return Values

- -

Parenthesis shall surround values returned from a function -using "return": - -

-    return (STATE_IDLE);
-
- -

Loops

- -

Whenever convenient loops should count downward to zero to -improve program performance: - -

-    for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
-      array[i] = STATE_IDLE;
-
- -

Software Trouble Report Form

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Summary of Problem:_____________________________________________
 
Problem Severity:__1Request for enhancement, e.g. asking for a - feature
__2Low, e.g. a documentation error or undocumented - side-effect
__3Moderate, e.g. unable to print a file or unable to - compile the software
__4High, e.g. unable to print to a printer or key - functionality not working
__5Critical, e.g. unable to print at all
 
Problem Scope:__1Machine or printer
__2Operating System
__3All machines, printers, or operating systems
 
Detailed Description of Problem:_____________________________________________ -
_____________________________________________ -
_____________________________________________ -
_____________________________________________ -
_____________________________________________
- - - diff --git a/doc/cups-printable.css b/doc/cups-printable.css new file mode 100644 index 0000000000..5019a4aaf5 --- /dev/null +++ b/doc/cups-printable.css @@ -0,0 +1,126 @@ +BODY { + font-family: sans-serif; +} + +H1, H2, H3, H4, H5, H6, P, TD, TH { + font-family: sans-serif; +} + +KBD { + font-family: monospace; + font-weight: bold; +} + +PRE { + font-family: monospace; +} + +PRE.command { + margin-left: 36pt; +} + +P.command { + font-family: monospace; + margin-left: 36pt; +} + +P.formula { + font-style: italic; + margin-left: 36pt; +} + +BLOCKQUOTE { + background: #cccccc; + border: solid thin #999999; + padding: 10pt; +} + +A:link, A:visited { + text-decoration: none; + font-weight: bold; +} + +A:link:hover, A:visited:hover, A:active { + text-decoration: underline; + font-weight: bold; +} + +SUB, SUP { + font-size: 50%; +} + +DIV.table TABLE { + border: solid thin #999999; + border-spacing: 0; + margin-left: auto; + margin-right: auto; +} + +DIV.table CAPTION { + caption-side: top; + font-size: 120%; + font-style: italic; + font-weight: bold; + margin-left: auto; + margin-right: auto; +} + +DIV.table TABLE TD { + border: solid thin #cccccc; + padding-top: 5pt; +} + +DIV.table TABLE TH { + background: #cccccc; + border: none; + border-bottom: solid thin #999999; +} + +TH.label { + padding-top: 5pt; + text-align: right; + vertical-align: top; +} + +HR { + border: solid thin; +} + +SPAN.info { + background: #000000; + border: thin solid #000000; + color: #ffffff; + font-size: 80%; + font-style: italic; + font-weight: bold; + white-space: nowrap; +} + +H3 SPAN.info { + float: right; + font-size: 100%; +} + +H2.title, H3.title { + border-bottom: solid 2pt #000000; + page-break-before: always; +} + +DT { + margin-left: 36pt; + margin-top: 12pt; +} + +DD { + margin-left: 54pt; +} + +P.summary { + margin-left: 54pt; + font-family: monospace; +} + +SPAN.message { + font-style: italic; + font-size: smaller; +} diff --git a/doc/cups.css b/doc/cups.css index 329c1f5b05..298e66f392 100644 --- a/doc/cups.css +++ b/doc/cups.css @@ -33,8 +33,13 @@ P.command { margin-left: 36pt; } +P.formula { + font-style: italic; + margin-left: 36pt; +} + BLOCKQUOTE { - background: #cccc99; + background: #bbbb88; border: solid thin #999966; padding: 10pt; } @@ -60,7 +65,7 @@ TR.sel TD { padding: 4pt; } -A.unsel { +A.unsel, A.unsel:visited { background-color: #666633; color: #e8e8b8; } @@ -135,7 +140,7 @@ DIV.table TABLE TH { } TH.label { - padding-top: 10pt; + padding-top: 5pt; text-align: right; vertical-align: top; } diff --git a/doc/cupsdoc.css b/doc/cupsdoc.css deleted file mode 100644 index 333f20144d..0000000000 --- a/doc/cupsdoc.css +++ /dev/null @@ -1,9 +0,0 @@ -H1 { font-family: sans-serif } -H2 { font-family: sans-serif } -H3 { font-family: sans-serif } -H4 { font-family: sans-serif } -H5 { font-family: sans-serif } -H6 { font-family: sans-serif } -SUP { font-family: sans-serif; font-size: 6pt } -PRE { margin-left: 2em } -CODE { font-weight: bold } diff --git a/doc/figures.sc b/doc/figures.sc deleted file mode 100644 index f51e814a63..0000000000 Binary files a/doc/figures.sc and /dev/null differ diff --git a/doc/glossary.shtml b/doc/glossary.shtml deleted file mode 100644 index 2cc0c1c893..0000000000 --- a/doc/glossary.shtml +++ /dev/null @@ -1,73 +0,0 @@ -

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 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 - -
diff --git a/doc/help/glossary.html b/doc/help/glossary.html new file mode 100644 index 0000000000..44dba31c70 --- /dev/null +++ b/doc/help/glossary.html @@ -0,0 +1,219 @@ + + + + Glossary + + + +

A

+ +
+ +
ASCII +
American Standard Code for Information Interchange + +
+ + +

C

+ +
+ +
C +
A computer language + +
Character Set +
The association of numbers with specific printed or + displayed characters or symbols + +
CUPS +
Common UNIX Printing System + +
+ + +

E

+ +
+ +
ESC/P +
EPSON Standard Code for Printers + +
+ + +

F

+ +
+ +
FTP +
File Transfer Protocol + +
+ + +

G

+ +
+ +
GIF +
Graphics Interchange Format + +
+ + +

H

+ +
+ +
HP-GL +
Hewlett-Packard Graphics Language + +
HP-PCL +
Hewlett-Packard Page Control Language + +
HP-PJL +
Hewlett-Packard Printer Job Language + +
+ + +

I

+ +
+ +
IETF +
Internet Engineering Task Force + +
IP +
Internet Protocol + +
IPv4 +
Internet Protocol, version 4; IPv4 addresses are 32-bits in + length and often look like "nnn.nnn.nnn.nnn" and "127.0.0.1" + +
IPv6 +
Internet Protocol, version 6: IPv6 addresses are 128-bits in + length and look like "xxxx::xxxx:xxxx:xxxx:xxxx" and "::1" + +
IPP +
Internet Printing Protocol + +
ISO +
International Standards Organization + +
+ + +

J

+ +
+ +
JFIF +
JPEG File Interchange Format + +
JPEG +
Joint Photographic Experts Group + +
+ + +

L

+ +
+ +
LPD +
Line Printer Daemon + +
+ + +

M

+ +
+ +
MIME +
Multimedia Internet Mail Exchange + +
+ + +

P

+ +
+ +
parallel +
Sending or receiving data more than 1 bit at a time + +
PDF +
Portable Document Format + +
pipe +
A one-way communications channel between two programs + +
PNG +
Portable Network Graphics + +
PostScript +
A page description language that is most often used + for printing + +
PPD +
PostScript Printer Description + +
+ + +

S

+ +
+ +
SCSI +
Small Computer Systems Interface + +
serial +
Sending or receiving data 1 bit at a time + +
SMB +
Server Message Block + +
socket +
A two-way network communications channel + +
+ + +

T

+ +
+ +
TCP +
Transmission Control Protocol + +
TFTP +
Trivial File Transfer Protocol + +
TIFF +
Tagged Image File Format + +
+ + +

U

+ +
+ +
UDP +
Unicast Datagram Protocol + +
Unicode +
A universal character set for all languages of the + world + +
UTF-8 +
Unicode Transfer Format 8-Bit + +
+ + + diff --git a/LICENSE.html b/doc/help/license.html similarity index 95% rename from LICENSE.html rename to doc/help/license.html index 2008a63120..888da5fc73 100644 --- a/LICENSE.html +++ b/doc/help/license.html @@ -1,11 +1,9 @@ + - Software License Agreement - Common UNIX Printing System + Software License Agreement - - - -

Common UNIX Printing System License Agreement

+

Copyright 1997-2006 by Easy Software Products
44141 AIRPORT VIEW DR STE 204
@@ -15,24 +13,24 @@ Voice: +1.301.373.9600
Email: cups-info@cups.org
WWW: http://www.cups.org -

Introduction

+

Introduction

The Common UNIX Printing SystemTM, ("CUPSTM"), is provided under the GNU General Public License ("GPL") and GNU Library General Public License ("LGPL"), Version 2, with exceptions for Apple operating systems and the OpenSSL toolkit. A copy of the exceptions and licenses follow -this introduction. +this introduction.

The GNU LGPL applies to the CUPS API library, located in the "cups" subdirectory of the CUPS source distribution and in the "cups" include directory and library files in the binary distributions. The GNU GPL applies to the remainder of the CUPS distribution, including the "pdftops" filter which is based upon -Xpdf and the CUPS imaging library. +Xpdf and the CUPS imaging library.

For those not familiar with the GNU GPL, the license basically -allows you to: +allows you to:

    @@ -50,24 +48,25 @@ allows you to:
-

What this license does not allow you to do is make +

What this license does not allow you to do is make changes or add features to CUPS and then sell a binary -distribution without source code. You must provide source for -any new drivers, changes, or additions to the software, and all -code must be provided under the GPL or LGPL as appropriate. The -only exceptions to this are the portions of the CUPS software -covered by the Apple operating system license exceptions -outlined later in this license agreement. +distribution without source code. You must provide source for any +new drivers, changes, or additions to the software, and all code +must be provided under the GPL or LGPL as appropriate. The only +exceptions to this are the portions of the CUPS software covered +by the Apple operating system license exceptions outlined later +in this license agreement.

The GNU LGPL relaxes the "link-to" restriction, allowing you -to develop applications that use the CUPS API library under -other licenses and/or conditions as appropriate for your -application. +to develop applications that use the CUPS API library under other +licenses and/or conditions as appropriate for your +application.

-

License Exceptions

+ +

License Exceptions

In addition, as the copyright holder of CUPS, Easy Software -Products grants the following special exceptions: +Products grants the following special exceptions:

    @@ -133,48 +132,51 @@ Products grants the following special exceptions:

No developer is required to provide these exceptions in a -derived work. +derived work.

+ -

Trademarks

+

Trademarks

Easy Software Products has trademarked the Common UNIX -Printing System, CUPS, and CUPS logo. You may use these names -and logos in any direct port or binary distribution of CUPS. -Please contact Easy Software Products for written permission to -use them in derivative products. Our intention is to protect the -value of these trademarks and ensure that any derivative product -meets the same high-quality standards as the original. +Printing System, CUPS, and CUPS logo. You may use these names and +logos in any direct port or binary distribution of CUPS. Please +contact Easy Software Products for written permission to use them +in derivative products. Our intention is to protect the value of +these trademarks and ensure that any derivative product meets the +same high-quality standards as the original.

-

Binary Distribution Rights

+ +

Binary Distribution Rights

Easy Software Products also sells rights to the CUPS source code under a binary distribution license for vendors that are unable to release source code for their drivers, additions, and -modifications to CUPS under the GNU GPL and LGPL. For -information please contact us at the address shown above. +modifications to CUPS under the GNU GPL and LGPL. For information +please contact us at the address shown above.

The Common UNIX Printing System provides a "pdftops" filter that is based on the Xpdf software. For binary distribution -licensing of this software, please contact: +licensing of this software, please contact:

Derek B. Noonburg
-Email: derekn@foolabs.com
-WWW: http://www.foolabs.com/xpdf/ +Email: derekn@glyphandcog.com
+WWW: http://www.glyphandcog.com/
-

Support

-

Easy Software Products sells software support for CUPS as -well as a commercial printing product based on CUPS called ESP -Print Pro. You can find out more at our web site: +

Support

+ +

Easy Software Products sells software support for CUPS as well +as a commercial printing product based on CUPS called ESP Print +Pro. You can find out more at our web site:

- -

GNU GENERAL PUBLIC LICENSE

+ +

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991 @@ -186,7 +188,7 @@ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. -

Preamble

+

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public @@ -236,8 +238,8 @@ patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow. -

GNU GENERAL PUBLIC LICENSE
-TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

+

GNU GENERAL PUBLIC LICENSE
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    @@ -447,7 +449,7 @@ of promoting the sharing and reuse of software generally.
-

NO WARRANTY

+

NO WARRANTY

    @@ -473,9 +475,9 @@ POSSIBILITY OF SUCH DAMAGES.
-

END OF TERMS AND CONDITIONS

+

END OF TERMS AND CONDITIONS

-

How to Apply These Terms to Your New Programs

+

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it @@ -538,8 +540,7 @@ by James Hacker. Ty Coon, President of Vice - -

GNU LIBRARY GENERAL PUBLIC LICENSE

+

GNU LIBRARY GENERAL PUBLIC LICENSE

Version 2, June 1991 @@ -553,7 +554,7 @@ of this license document, but changing it is not allowed. numbered 2 because it goes with version 2 of the ordinary GPL.] -

Preamble

+

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public @@ -643,7 +644,7 @@ works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. -

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

+

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License Agreement applies to any software library which @@ -1013,9 +1014,9 @@ FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. -

END OF TERMS AND CONDITIONS

+

END OF TERMS AND CONDITIONS

-

How to Apply These Terms to Your New Libraries

+

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that diff --git a/doc/help/options.html b/doc/help/options.html new file mode 100644 index 0000000000..8602247ebd --- /dev/null +++ b/doc/help/options.html @@ -0,0 +1,474 @@ + + + + Printing and Options + + + +

CUPS provides both the System V (lp(1)) and Berkeley (lpr(1)) printing commands for printing +files. In addition, it supported a large number of standard and +printer-specific options that allow you to control how and where +files are printed.

+ + +

Printing Files

+ +

CUPS understands many different types of files directly, +including text, PostScript, PDF, and image files. This allows you +to print from inside your applications or at the command-line, +whichever is most convenient! Type either of the following +commands to print a file to the default (or only) printer on the +system:

+ +
+lp filename
+lpr filename
+
+ +

Choosing a Printer

+ +

Many systems will have more than one printer available to the +user. These printers can be attached to the local system via a +parallel, serial, or USB port, or available over the network. Use +the lpstat(1) command to see a list +of available printers:

+ +
+lpstat -p -d
+
+ +

The -p option specifies that you want to see a +list of printers, and the -d option reports the +current default printer or class.

+ +

Use the -d option with the lp command to +print to a specific printer:

+ +
+lp -d printer filename
+
+ +

or the -P option with the lpr command:

+ +
+lpr -P printer filename
+
+ +

Setting the Default Printer

+ +

If you normally use a particular printer, you can tell CUPS to +use it by default using the lpoptions(1) command:

+ +
+lpoptions -d printer
+
+ +

Printing the Output of a Program

+ +

Both the lp and lpr commands support printing +from the standard input:

+ +
+program | lp
+program | lp -d printer
+program | lpr
+program | lpr -P printer
+
+ +

If the program does not provide any output, then nothing will +be queued for printing.

+ +

Specifying Printer Options

+ +

For many types of files, the default printer options may be +sufficient for your needs. However, there may be times when you +need to change the options for a particular file you are +printing.

+ +

The lp and lpr commands allow you to pass +printer options using the -o option:

+ +
+lp -o landscape -o scaling=75 -o media=A4 filename.jpg
+lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
+
+ +

The available printer options vary depending on the printer. +The standard options are described in the "Standard Printing Options" section +below.

+ +

Printing Multiple Copies

+ +

Both the lp and lpr commands have options for +printing more than one copy of a file:

+ +
+lp -n num-copies filename
+lpr -#num-copies filename
+
+ +

Copies are normally not collated for you. Use the +-o Collate=True option to get collated copies:

+ +
+lp -n num-copies -o Collate=True filename
+lpr -#num-copies -o Collate=True filename
+
+ + +

Canceling a Print Job

+ +

The cancel(1) and lprm(1) commands cancel a print job:

+ +
+cancel job-id
+lprm job-id
+
+ +

The job-id is the number that was reported to you by +the lp command. You can also get the job ID using the lpq(1) or lpstat commands:

+ +
+lpq
+lpstat
+
+ + +

Standard Printing Options

+ +

The following options apply when printing all types of +files.

+ +

Selecting the Media Size, Type, and Source

+ +

The -o media=xyz option sets the media size, +type, and/or source:

+ +
+lp -o media=Letter filename
+lp -o media=Letter,MultiPurpose filename
+lpr -o media=Letter,Transparency filename
+lpr -o media=Letter,MultiPurpose,Transparency filename
+
+ +

The available media sizes, types, and sources depend on the +printer, but most support the following options (case is not +significant):

+ +
    + +
  • Letter - US Letter (8.5x11 inches, or 216x279mm) + +
  • Legal - US Legal (8.5x14 inches, or 216x356mm) + +
  • A4 - ISO A4 (8.27x11.69 inches, or 210x297mm) + +
  • COM10 - US #10 Envelope (9.5x4.125 inches, or + 241x105mm) + +
  • DL - ISO DL Envelope (8.66x4.33 inches, or 220x110mm) + +
  • Transparency - Transparency media type or source + +
  • Upper - Upper paper tray + +
  • Lower - Lower paper tray + +
  • MultiPurpose - Multi-purpose paper tray + +
  • LargeCapacity - Large capacity paper tray + +
+ +

The actual options supported are defined in the printer's PPD +file in the PageSize, InputSlot, and +MediaType options. You can list them using the +lpoptions(1) command:

+ +
+lpoptions -p printer -l
+
+ +

Setting the Orientation

+ +

The -o landscape option will rotate the page 90 +degrees to print in landscape orientation:

+ +
+lp -o landscape filename
+lpr -o landscape filename
+
+ +

The -o orientation-requested=N option rotates the +page depending on the value of N:

+ +
    + +
  • -o orientation-requested=3 - portrait + orientation (no rotation)
    • + +
  • -o orientation-requested=4 - landscape + orientation (90 degrees)
    • + +
  • -o orientation-requested=5 - reverse + landscape or seascape orientation (270 degrees)
    • + +
  • -o orientation-requested=6 - reverse + portrait or upside-down orientation (180 degrees)
    • + +
+ +

Printing On Both Sides of the Paper

+ +

The -o sides=two-sided-short-edge and -o +sides=two-sided-long-edge options will enable two-sided +printing on the printer if the printer supports it. The -o +sides=two-sided-short-edge option is suitable for +landscape pages, while the -o +sides=two-sided-long-edge option is suitable for portrait +pages:

+ +
+lp -o sides=two-sided-short-edge filename
+lp -o sides=two-sided-long-edge filename
+lpr -o sides=two-sided-long-edge filename
+
+ +

The default is to print single-sided:

+ +
+lp -o sides=one-sided filename
+lpr -o sides=one-sided filename
+
+ +

Selecting the Banner Page(s)

+ +

The -o jobsheets=start,end option sets the banner +page(s) to use for a job:

+ +
+lp -o job-sheets=none filename
+lp -o job-sheets=standard filename
+lpr -o job-sheets=classified,classified filename
+
+ +

If only one banner file is specified, it will be printed +before the files in the job. If a second banner file is +specified, it is printed after the files in the job.

+ +

The available banner pages depend on the local system +configuration; CUPS includes the following banner files:

+ +
    + +
  • none - Do not produce a banner page. + +
  • classified - A banner page with a "classified" + label at the top and bottom. + +
  • confidential - A banner page with a + "confidential" label at the top and bottom. + +
  • secret - A banner page with a "secret" label + at the top and bottom. + +
  • standard - A banner page with no label at the + top and bottom. + +
  • topsecret - A banner page with a "top secret" + label at the top and bottom. + +
  • unclassified - A banner page with an + "unclassified" label at the top and bottom. + +
+ +

Selecting a Range of Pages

+ +

The -o page-ranges=pages option selects a range +of pages for printing:

+ +
+lp -o page-ranges=1 filename
+lp -o page-ranges=1-4 filename
+lp -o page-ranges=1-4,7,9-12 filename
+lpr -o page-ranges=1-4,7,9-12 filename
+
+ +

As shown above, the pages value can be a single page, a +range of pages, or a collection of page numbers and ranges separated by +commas. The pages will always be printed in ascending order, regardless +of the order of the pages in the page-ranges option. + +

The default is to print all pages. + +

Selecting Even or Odd Pages

+ +

Use the -o page-set=set option to select the even or odd pages:

+ +
+lp -o page-set=odd filename
+lp -o page-set=even filename
+lpr -o page-set=even filename
+
+ +

The default is to print all pages. + +

N-Up Printing

+ +

The -o number-up=value option selects N-Up +printing. N-Up printing places multiple document pages on a +single printed page. CUPS supports 1, 2, 4, 6, 9, and 16-Up +formats; the default format is 1-Up:

+ +
+lp -o number-up=1 filename
+lp -o number-up=2 filename
+lp -o number-up=4 filename
+lpr -o number-up=16 filename
+
+ +

The -o page-border=value option chooses the +border to draw around each page:

+ +
    +
  • -o page-border=double; draw two hairline borders around each page
    • +
  • -o page-border=double-thick; draw two 1pt borders around each page
    • +
  • -o page-border=none; do not draw a border (default)
    • +
  • -o page-border=single; draw one hairline border around each page
    • +
  • -o page-border=single-thick; draw one 1pt border around each page
    • +
+ +

The -o number-up-layout=value option chooses the +layout of the pages on each output page:

+ +
    +
  • -o number-up-layout=btlr; Bottom to top, left to right
    • +
  • -o number-up-layout=btrl; Bottom to top, right to left
    • +
  • -o number-up-layout=lrbt; Left to right, bottom to top
    • +
  • -o number-up-layout=lrtb; Left to right, top to bottom (default)
    • +
  • -o number-up-layout=rlbt; Right to left, bottom to top
    • +
  • -o number-up-layout=rltb; Right to left, top to bottom
    • +
  • -o number-up-layout=tblr; Top to bottom, left to right
    • +
  • -o number-up-layout=tbrl; Top to bottom, right to left
    • +
+ +

Scaling to Fit

+ +

The -o fitplot option specifies that the document +should be scaled to fit on the page:

+ +
+lp -o fitplot filename
+lpr -o fitplot filename
+
+ +

The default is to use the size specified in the file.

+ +
Note: This feature depends upon an accurate size in +the print file. If no size is given in the file, the page may be +scaled incorrectly!
+ +

Raw or Unfiltered Output

+ +

The -o raw option allows you to send files +directly to a printer without filtering. This is sometimes +required when printing from applications that provide their own +"printer drivers" for your printer:

+ +
+lp -o raw filename
+lpr -o raw filename
+
+ +

The -l option can also be used with the +lpr command to send files directly to a printer:

+ +
+lpr -l filename
+
+ + +

Text Options

+ +

CUPS supports several options that are only used when printing +plain text files. These options have absolutely no effect on +PostScript, PDF, HP-GL/2, or image files.

+ +

Setting the Number of Characters Per Inch

+ +

The -o cpi=value option sets the number of +characters per inch:

+ +
+lp -o cpi=10 filename
+lp -o cpi=12 filename
+lpr -o cpi=17 filename
+
+ +

The default characters per inch is 10.

+ +

Setting the Number of Lines Per Inch

+ +

The -o lpi=value option sets the number of lines +per inch:

+ +
+lp -o lpi=6 filename
+lpr -o lpi=8 filename
+
+ +

The default lines per inch is 6.

+ +

Setting the Number of Columns

+ +

The -o columns=value option sets the number of +text columns:

+ +
+lp -o columns=2 filename
+lpr -o columns=3 filename
+
+ +

The default number of columns is 1.

+ +

Setting the Page Margins

+ +

Normally the page margins are set to the hard limits of the +printer. Use the -o page-left=value, -o +page-right=value, -o page-top=value, and +-o page-bottom=value options to adjust the page +margins:

+ +
+lp -o page-left=value filename
+lp -o page-right=value filename
+lp -o page-top=value filename
+lp -o page-bottom=value filename
+lpr -o page-left=value -o page-right=value -o page-top=value -o page-bottom=value filename
+
+ +

The value argument is the margin in points; each +point is 1/72 inch or 0.35mm.

+ +

Pretty Printing

+ +

The -o prettyprint option puts a header at the +top of each page with the page number, job title (usually the +filename), and the date. Also, C and C++ keywords are +highlighted, and comment lines are italicized:

+ +
+lp -o prettyprint filename
+lpr -o prettyprint filename
+
+ + + diff --git a/doc/help/overview.html b/doc/help/overview.html index 20641e04ca..38f57eb3da 100644 --- a/doc/help/overview.html +++ b/doc/help/overview.html @@ -5,500 +5,104 @@ -

Printing within UNIX has historically been done using one of -two printing systems - the Berkeley Line Printer Daemon (LPD) -[RFC1179] and the AT&T Line Printer system. These printing -systems were designed in the 70's for printing text to line -printers; vendors have since added varying levels of support for -other types of printers.

- -

Replacements for these printing systems have emerged [LPRng, -Palladin, PLP], however none of the replacements change the -fundamental capabilities of these systems.

- -

Over the years several attempts at developing a standard -printing interface have been made, including the draft POSIX -Printing standard developed by the Institute of Electrical and -Electronics Engineers, Inc. (IEEE) [IEEE-1387.4] and Internet -Printing Protocol (IPP) developed by the Internet Engineering -Task Force (IETF) through the Printer Working Group (PWG) -[IETF-IPP]. The POSIX printing standard defines a common set of -command-line tools as well as a C interface for printer -administration and print jobs, but has been shelved by the -IEEE.

- -

The Internet Printing Protocol defines extensions to the -HyperText Transport Protocol 1.1 [RFC2616] to provide support -for remote printing services. IPP/1.1 was accepted by the IETF -as a proposed standard in ??? of ???. Unlike POSIX Printing, IPP -enjoys widespread industry support and has become the standard -network printing solution for all operating systems.

- -

CUPS uses IPP/1.1 to provide a complete, modern printing -system for UNIX that can be extended to support new printers, -devices, and protocols while providing compatibility with -existing UNIX applications. CUPS is free software provided under -the terms of the GNU General Public License and GNU Library -General Public License.

- -

History

- -

The first production release of CUPS (based on IPP/1.0) was -released in October of 1999. Version 1.1 of CUPS was released in -August of 2002 ???? and added support for IPP/1.1.

- -

CUPS 1.2 is based on IPP/1.1 and adds many of the functional -enhancements that have been requested by our users. As with CUPS -1.1, CUPS 1.2 will be followed by patch releases that address -any problems found with the software. New features will be put -in the 1.3 release to follow.

- -

Design Overview

- -

Like most printing systems, CUPS is designed around a central -print scheduling process that dispatches print jobs, processes -administrative commands, provides printer status information to -local and remote programs, and informs users as needed. Figure 1 -shows the basic organization of CUPS.

- -

CUPS Block Diagram
-Figure 1 - CUPS Block Diagram

- -

Scheduler

- -

The scheduler is a HTTP/1.1 server application that handles -HTTP requests. Besides handling printer requests via IPP POST -requests, the scheduler also acts as a full-featured web server -for documentation, status monitoring, and administration.

- -

The scheduler also manages a list of available printers on -the LAN and dispatches print jobs as needed using the -appropriate filters and backends.

- -

Configuration Files

- -

The configuration files consist of:

- -
    - -
  • The HTTP server configuration file.
    • - -
  • Printer and class definition files.
    • - -
  • MIME type and conversion rule files.
    • - -
  • PostScript Printer Description (PPD) files.
    • - -
- -

The HTTP server configuration file is purposely similar to -the Apache server configuration file and defines all of the -access control properties for the server.

- -

The printer and class definition files list the available -printer queues and classes. Printer classes are collections of -printers. Jobs sent to a class are forwarded to the first -available printer in the class, round-robin fashion.

- -

The MIME type files list the supported MIME types -(text/plain, application/postscript, etc.) and "magic' rules for -automatically detecting the format of a file. These are used by -the HTTP server to determine the Content-Type field for -GET and HEAD requests and by the IPP request -handler to determine the file type when a Print-Job or -Send-File request is received with a -document-format of -application/octet-stream.

- -

The MIME conversion rule files list the available filters. -The filters are used when a job is dispatched so that an -application can send a convenient file format to the printing -system which then converts the document into a printable format -as needed. Each filter has a relative cost associated with it, -and the filtering algorithm chooses the set of filters that will -convert the file to the needed format with the lowest total -"cost".

- -

The PPD files describe the capabilities of all printers, not -just PostScript printers. There is one PPD file for each -printer. PPD files for non-PostScript printers define additional -filters through cupsFilter attributes to support -printer drivers.

- -

CUPS API

- -

The CUPS API contains CUPS-specific convenience functions for -queuing print jobs, getting printer information, accessing -resources via HTTP and IPP, and manipulating PPD files. Unlike -the rest of CUPS, the CUPS API is provided under the terms of -the GNU LGPL so it may be used by non-GPL applications.

- -

Berkeley and System V Commands

- -

CUPS provides the System V and Berkeley command-line -interfaces for submitting jobs and checking the printer status. -The lpstat and lpc status commands -also show network printers ("printer@server") when printer -browsing is enabled.

- -

The System V administation commands are supplied for managing -printers and classes. The Berkeley printer administration tool -(lpc) is only supported in a "read-only' mode to -check the current status of the printer queues and -scheduler.

- -

Filters

- -

A filter program reads from the standard input or from a file -if a filename is supplied. All filters must support a common set -of options including printer name, job ID, username, job title, -number of copies, and job options. All output is sent to the -standard output.

- -

Filters are provided for many file formats and include image -file and PostScript raster filters that support non-PostScript -printers. Multiple filters are run in parallel to produce the -required output format.

- -

The PostScript raster filter is based on the ESP Ghostscript -core. Instead of using the Ghostscript printer drivers, the CUPS -filter uses a generic CUPS raster printer driver and -CUPS-compliant front-end to support any kind of raster printer. -This allows the same printer driver filter to be used for -printing raster data from any filter.

- -
Talk about Apple's use of CUPS...
- -

CUPS Imaging

- -

The CUPS Imaging library provides functions for managing -large images, doing colorspace conversion and color management, -scaling images for printing, and managing raster page streams. -It is used by the CUPS image file filters, the PostScript RIP, -and all raster printers drivers.

- -

Backends

- -

A backend program is a special filter that sends print data -to a device or network connection. Backends for parallel, -serial, USB, LPD, IPP, and AppSocket (JetDirect) connections are -provided in CUPS 1.2.

- -

SAMBA version 2.0.6 and higher includes a SMB backend -(smbspool(1)) that can be used for printing to -Windows.

- -

Network Printing

- -

Traditionally, network printing has been one of the hardest -things to get working under UNIX. One reason is because each -vendor added their own extensions to the LPD protocol (the -previous standard for network printing), making cross-platform -printing difficult if not impossible.

- -

Another reason is that you have to administer every network -printer on every client machine. In some cases you can "clone' -the printer configuration from a "master' client to each of the -others, but even that can be time-consuming and error-prone. -Something better is needed.

- -

CUPS provides "printer browsing", which allows clients to -automatically see and use printers from any server on a LAN. -This means that you only need to configure the server and the -clients will automatically see the printers and classes on -it.

- -

In addition, CUPS can automatically merge multiple identical -network printers into "implicit classes". This allows clients to -send jobs to the implicit class and have them print on the first -available printer or server. In addition, failsafe and -load-balancing functions are enabled simply by defining the same -printer on multiple servers!

- -

New Features in CUPS 1.2

- -

CUPS 1.2 includes many new features and capabilities: - -

    - -
  1. Backends - -
  2. Banner Page Support - -
  3. Digest Authentication - -
  4. Directory Services - -
  5. Directory Structure Changes - -
  6. Documentation - -
  7. Drivers - -
  8. Filters - -
  9. IPP Support - -
  10. Job Persistence - -
  11. LPD Client Support - -
  12. User-Defined Printers and Options - -
  13. Web Administration Interface - -
- -

1. Backends

- -

CUPS 1.2 implements a new backend interface for retrieving a -list of available devices for CUPS clients. This allows -administration interfaces to query the CUPS scheduler for a list -of available devices, automatically configure printers if the -device identification information is available, and present the -user with a list of available devices rather than relying on the -user to know what devices are configured on the system.

- -

The new release also includes a backend for USB printers -under *BSD and Linux. Support for USB under Solaris 8 will be -provided in a subsequent patch release.

- -

2. Banner Page Support

- -

CUPS 1.2 includes support for banner pages at the beginning -and end of a job. Banner pages may be of any file format and -support variable substitution for job titles, usernames, etc. -Default banner pages are associated with each printer and can be -overridden with command-line options by the user.

- -

3. Digest Authentication

- -

Digest authentication provides a more secure method of -authenticating access to the printing system. Unlike Basic -authentication, Digest authentication does not send passwords -"in the clear' so it is more difficult to gain unauthorized -access to your system.

- -

CUPS 1.2 implements Digest authentication using a special MD5 -password file instead of the UNIX password file. This file is -managed using the new lppasswd command.

- -

4. Directory Services

- -

CUPS 1.2 adds new directory service ("printer browsing") -features to make using CUPS on large LANs and WANs easier. You -can now poll a remote server for printer information and relay -it to the LAN as well as restrict what printer information is -processed (e.g. to "hide" servers, domains, or networks that you -don't want to see.)

- -

5. Directory Structure Changes

- -

CUPS 1.2 now uses a directory structure that complies with -the Filesystem Hierarchy Standard (FHS), version 2.0. This -should make integration into existing Linux and *BSD -distributions a lot easier.

- -

6. Documentation

- -

The CUPS 1.2 documentation has gone through many revisions, -including a completely rewritten administrators manual, a new -programmers manual, and an IPP implementation reference -manual.

- -

7. Drivers

- -

CUPS 1.2 includes drivers for EPSON dot-matrix and inkjet -printers. As with the HP PCL drivers, the EPSON drivers don't -necessarily provide the best possible output for each printer -but should provide adequate printing quality for general -day-to-day printing.

- -

8. Filters

- -

CUPS 1.2 includes new image, PostScript, PDF, and text -filters. The image filters have been upgraded to support Windows -BMP and Alias PIX files.

- -

The PostScript filter is now based off ESP Ghostscript. The -new filter provides much better performance with -higher-resolution printers and supports all Level 3 PostScript -language features.

- -

The new PDF filter is based off the excellent Xpdf software -from Derek Noonburg and supports automatic page scaling. The new -filter is a faster, smaller, more reliable replacement for the -GNU Ghostscript PDF filtering that was used in CUPS 1.0.

- -

The new text filter now supports bidirectional text and can -embed fonts as needed.

- -

9. IPP Support

- -

Probably the least visible portion of CUPS is the IPP -support. CUPS 1.1 implements all of the required IPP/1.1 -operations and attributes and most of the optional ones. The -optional Create-Job and Send-File operations are now -implemented, allowing for better System V printing system -compatibility (one job ID per lp command) and support -for banner pages.

- -

10. Job Persistence

- -

CUPS 1.2 supports job persistence. This means that jobs are -preserved even after a reboot, a feature that was sorely missing -from CUPS 1.0.

- -

In addition, CUPS 1.2 allows you to keep job information -after the job has printed. The basic post-job persistence mode -provides a job history (number of pages printed, time job was -printed, etc.) but does not preserve the actual job files. This -can be changed to discard all information after a job is printed -or keep the job files after printing so you can reprint a job at -some later time.

- -

11. LPD Client Support

- -

By popular request, CUPS 1.2 supports LPD-based clients using -a new mini-daemon that handles LPD requests and passes them on -to the main server.

- -

12. User-Defined Printers and Options

- -

CUPS 1.2 includes support for user-defined printers and -options via a new lpoptions command. User-defined -printers are special instances of the available printers (e.g. -"printer/instance" or "printer@server/instance") that can have -their own default options such as media size, resolution, and so -forth. The lpoptions command can also be used to set a -different default printer queue.

- -

13. Web Administration Interface

- -

CUPS 1.0 provided a simple class, job, and printer monitoring -interface for web browsers. CUPS 1.2 replaces this interface -with an enhanced administration interface that allows you to -add, modify, delete, configure, and control classes, jobs, and -printers.

- -

Software Using CUPS

- -

A lot has happened since CUPS 1.0 came out, and many software -packages are supporting CUPS. We have contributed code to the -SAMBA team to support CUPS, and parts of that are already -available in SAMBA 2.0.6 and 2.0.7. With any luck the final -pieces that provide a complete integration with SAMBA will be -available in the next release of SAMBA.

- -

Two graphical interfaces have appeared on the scene that use -CUPS as well. The KUPS project provides a KDE-based interface -for CUPS and can be found at:

- -
-    http://kups.sourceforge.net
-
- -

The X Printing Panel (XPP) project provides a graphical -printing panel for CUPS and can be found at:

- -
-    http://www.phy.uni-bayreuth.de/till/xpp/
-
- -

Numerous other filters, drivers, tutorials, etc. have been -made available on the CUPS Links web page, available at:

- -
-    http://www.cups.org/links.php
-
- -

Finally, our own ESP Print Pro software uses CUPS to provide -drivers for thousands of printers and can be found at:

- -
-    http://www.easysw.com/printpro
-
- -

Operating Systems Using CUPS

- -

One of our goals has always been to get as many UNIX/Linux -distributions using CUPS as possible. Debian is currently -providing CUPS as part of its stable distribution, and many -other distributions are considering it in their next -releases.

- -

Summary

- -

The Common UNIX Printing System provides a modern printing -interface for UNIX applications that is both flexible and -user-friendly. The software provides System V and Berkeley -compatible command-line interfaces to ensure compatibility with -existing applications. CUPS 1.2 adds many new features that make -it an even better choice for printing under UNIX.

- -

Who to Contact

- -

For more information on CUPS please contact us at: - -

-    Attn: CUPS Information
-    Easy Software Products
-    44141 Airport View Drive Suite 204
-    Hollywood, Maryland 20636-3142 USA
-
-    +1.301.373.9600
-
-    cups-info@cups.org
-
- -

References

- -
- -
IEEE-1387.4
- -
System Administration - Part 4: Printing Interfaces - (draft)
- -
IETF-IPP
- -
Internet Printing Protocol/1.1
- -
LPRng
- -
An enhanced, extended, and portable implementation - of the Berkeley LPR print spooler functionality
- -
Palladin
- -
A printing system developed at the Massachussetts - Institute of Technology
- -
PLP
- -
The Portable Line Printer spooler system
- -
RFC1179
- -
Line Printer Daemon Protocol
- -
RFC2046
- -
Multipurpose Internet Mail Extensions (MIME) Part - Two: Media Types
- -
RFC2616
- -
Hypertext Transfer Protocol -- HTTP/1.1
- -
- -

Trademarks

- -

The Common UNIX Printing System, CUPS, and the CUPS logo are -the trademark property of Easy Software Products. All other -trademarks are the property of their respective owners.

+

The Common UNIX Printing SystemTM, or CUPS, is the +software you use to print from applications like the web browser +you are using to read this page. It converts the page +descriptions produced by your application (put a paragraph +here, draw a line there, and so forth) into something your +printer can understand and then sends the information to the +printer for printing.

+ +

Now, since every printer manufacturer does things differently, +printing can be very complicated. CUPS does its best to hide this +from you and your application so that you can concentrate on +printing and less on how to print. Generally, the only +time you need to know anything about your printer is when you use +it for the first time, and even then CUPS can often figure things +out on its own.

+ +

How Does It Work?

+ +

The first time you print to a printer, CUPS creates a +queue to keep track of the current status of the printer +(everything OK, out of paper, etc.) and any pages you have +printed. Most of the time the queue points to a printer connected +directly to your computer via a USB or parallel port, however it +can also point to a printer on your network, a printer on the +Internet, or multiple printers depending on the configuration. +Regardless of where the queue points, it will look like +any other printer to you and your applications.

+ +

Every time you print something, CUPS creates a job +which contains the queue you are sending the print to, the name +of the document you are printing, and the page descriptions. Job +are numbered (queue-1, queue-2, and so forth) so you can monitor +the job as it is printed or cancel it if you see a mistake. When +CUPS gets a job for printing, it determines the best programs +(filters, printer drivers, port +monitors, and backends) to convert the pages into a +printable format and then runs them to actually print the +job.

+ +

When the print job is completely printed, CUPS removes the job +from the queue and moves on to any other jobs you have submitted. +You can also be notified when the job is finished, or if there +are any errors during printing, in several different ways.

+ +

Where Do I Begin?

+ +

Click on the Administration tab at the +top of this page. If you have a printer connected to a USB or +parallel port, you will see it listed as a new printer - click on +the Add This Printer button, verify the printer driver +CUPS has chosen for you, and click on the Add Printer +button. If you do not see your printer listed, or if you have a +network printer, click on the Add Printer button and +follow the prompts.

+ +
If you are asked for a username and password, enter +your login username and password or the "root" username and +password. On MacOS X, the login username (or "short name") is +typically your first name in lowercase.
+ +

After the printer is added, CUPS will ask you to set the +default printer options (paper size, output mode, etc.) for the +printer. Make any changes as needed and then click on the +Set Printer Options button to save them.

+ +

Finally, click on the Print Test Page button to +print a simple test page and verify that everything is working +properly.

+ +

Once you have added the printer, you can print to it from any +application.

+ + + + + + + + + + + + + + +
CUPS Administration Web Page
+Figure 1: The CUPS Administration Web Page		CUPS Driver Selection Web Page
+Figure 2: The CUPS Driver Selection Web Page
CUPS Password Dialog
+Figure 3: The CUPS Password Dialog		CUPS Set Printer Options Web Page
+Figure 4: The CUPS Set Printer Options Web Page
CUPS Printer Status Page
+Figure 5: The CUPS Printer Status Page		CUPS Printer Test Page
+Figure 6: The CUPS Printer Test Page
diff --git a/doc/help/access_log-reference.html b/doc/help/ref-access_log.html similarity index 96% rename from doc/help/access_log-reference.html rename to doc/help/ref-access_log.html index e4ce813b1c..5ed47821be 100644 --- a/doc/help/access_log-reference.html +++ b/doc/help/ref-access_log.html @@ -38,7 +38,7 @@ localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"

The host field will normally only be an IP address unless you have enabled the HostNameLookups +HREF="ref-cupsd-conf.html#HostNameLookups">HostNameLookups directive in the cupsd.conf file or if the IP address corresponds to your local machine.

@@ -101,7 +101,7 @@ request, as follows:

  • 413 - Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize + HREF="ref-cupsd-conf.html#MaxRequestSize">MaxRequestSize allows.
  • 426 - Upgrading to TLS-encrypted diff --git a/doc/help/classes-conf-reference.html b/doc/help/ref-classes-conf.html similarity index 98% rename from doc/help/classes-conf-reference.html rename to doc/help/ref-classes-conf.html index eba834d18d..24622b08b8 100644 --- a/doc/help/classes-conf-reference.html +++ b/doc/help/ref-classes-conf.html @@ -176,7 +176,7 @@ error policy:

  • retry-job - Retry the job after waiting for N seconds; the cupsd.conf JobRetryInterval + HREF="ref-cupsd-conf.html#JobRetryInterval">JobRetryInterval directive controls the value of N
  • stop-printer - Stop the printer and keep @@ -343,7 +343,7 @@ sets the current operation policy:

    The default policy is named "default". All policies correspond to those defined using the cupsd.conf Policy +HREF="ref-cupsd-conf.html#Policy">Policy directive.

    This directive must appear inside a The error_log file lists messages from the scheduler - errors, warnings, etc. The LogLevel +HREF="ref-cupsd-conf.html#LogLevel">LogLevel directive controls which messages are logged:

    diff --git a/doc/help/page_log-reference.html b/doc/help/ref-page_log.html similarity index 100% rename from doc/help/page_log-reference.html rename to doc/help/ref-page_log.html diff --git a/doc/help/printers-conf-reference.html b/doc/help/ref-printers-conf.html similarity index 99% rename from doc/help/printers-conf-reference.html rename to doc/help/ref-printers-conf.html index 226a766d0f..bb9754bdc4 100644 --- a/doc/help/printers-conf-reference.html +++ b/doc/help/ref-printers-conf.html @@ -180,7 +180,7 @@ error policy:

  • retry-job - Retry the job after waiting for N seconds; the cupsd.conf JobRetryInterval + HREF="ref-cupsd-conf.html#JobRetryInterval">JobRetryInterval directive controls the value of N
  • stop-printer - Stop the printer and keep @@ -347,7 +347,7 @@ sets the current operation policy:

    The default policy is named "default". All policies correspond to those defined using the cupsd.conf Policy +HREF="ref-cupsd-conf.html#Policy">Policy directive.

    This directive must appear inside a + + + Server Security + + + +

    In the default "standalone" configuration, there are few +potential security risks - the CUPS server does not accept remote +connections, and only accepts shared printer information from the +local subnet. When you share printers and/or enable remote +adminstration, you expose your system to potential unauthorized +access. This help page provides an analysis of possible CUPS +security concerns and describes how to better secure your +server.

    + +

    Authentication Issues

    + +

    When you enable remote administration, the server will use +Basic authentication for adminstration tasks. The current CUPS +server supports Basic, Digest, and local certificate +authentication:

    + +
      + +
    1. Basic authentication essentially places the clear + text of the username and password on the network. + +

      Since CUPS uses the system username and password + account information, the authentication information could + be used to gain access to possibly privileged accounts on + the server.

      + +

      Recommendation: Enable encryption to hide the + username and password information.

      2. + +
    2. Digest authentication uses an MD5 checksum of the + username, password, and domain ("CUPS"), so the original + username and password is not sent over the network. + +

      The current implementation does not authenticate the + entire message and uses the client's IP address for the + nonce value, making it possible to launch "man in the + middle" and replay attacks from the same client.

      + +

      Recommendation: Enable encryption to hide the + username and password information.

      3. + +
    3. Local certificate authentication passes 128-bit + "certificates" that identify an authenticated user. + Certificates are created on-the-fly from random data and + stored in files under /var/run/cups/certs. + They have restricted read permissions: root + + system-group(s) for the root certificate, and lp + + system-group(s) for CGI certificates. + +

      Because certificates are only available on the local + system, the CUPS server does not accept local + authentication unless the client is connected to the + loopback interface (127.0.0.1 or ::1) or domain + socket.

      + +

      Recommendation: Ensure that unauthorized users + are not added to the system group(s).

      4. + +
    + +

    Denial of Service Attacks

    + +

    When printer sharing or remote administration is enabled, the +CUPS server, like all Internet services, is vulnerable to a +variety of denial of service attacks:

    + +
      + +
    1. Establishing multiple connections to the server until + the server will accept no more. + +

      This cannot be protected against by any known + software. The MaxClientsPerHost directive + can be used to configure CUPS to limit the number of + connections allowed from a single host, however that does + not prevent a distributed attack.

      + +

      Recommendation: Limit access to trusted systems + and networks.

      2. + +
    2. Repeatedly opening and closing connections to the + server as fast as possible. + +

      There is no easy way of protecting against this in the + CUPS software. If the attack is coming from outside the + local network, it may be possible to filter such an + attack. However, once the connection request has been + received by the server it must at least accept the + connection to find out who is connecting.

      + +

      Recommendation: None.

      3. + +
    3. Flooding the network with broadcast packets on port + 631. + +

      It might be possible to disable browsing if this + condition is detected by the CUPS software, however if + there are large numbers of printers available on the + network such an algorithm might think that an attack was + occurring when instead a valid update was being + received.

      + +

      Recommendation: Block browse packets from + foreign or untrusted networks using a router or + firewall.

      4. + +
    4. Sending partial IPP requests; specifically, sending + part of an attribute value and then stopping + transmission. + +

      The current code will wait up to 1 second before + timing out the partial value and closing the connection. + This will slow the server responses to valid requests and + may lead to dropped browsing packets, but will otherwise + not affect the operation of the server.

      + +

      Recommendation: Block IPP packets from foreign + or untrusted networks using a router or + firewall.

      5. + +
    5. Sending large/long print jobs to printers, preventing + other users from printing. + +

      There are limited facilities for protecting against + large print jobs (the MaxRequestSize + attribute), however this will not protect printers from + malicious users and print files that generate hundreds or + thousands of pages.

      + +

      Recommendation: Restrict printer access to + known hosts or networks, and add user-level access + controls as needed for expensive printers.

      6. + +
    + +

    Encryption Issues

    + +

    CUPS supports 128-bit SSL 3.0 and TLS 1.0 encryption of +network connections via the OpenSSL, GNU TLS, and CDSA encryption +libraries. In additional to the potential security issues posed +by the SSL and TLS protocols, CUPS currently has the following +additional issue:

    + +
      + +
    1. Certification validation/revocation; currently CUPS + does not validate or revoke server or client certificates + when establishing a secure connection. This can + potentially lead to "man in the middle" and + impersonation/spoofing attacks over unsecured networks. + Future versions of CUPS will support both validation and + revocation of server certificates. + +

      Recommendation: Do not depend on encryption for + security when connecting to servers over the Internet or + untrusted WAN links.

      2. + +
    + + + diff --git a/doc/help/spec-cmp.html b/doc/help/spec-cmp.html new file mode 100644 index 0000000000..b4e798286e --- /dev/null +++ b/doc/help/spec-cmp.html @@ -0,0 +1,1277 @@ + + + + CUPS Configuration Management Plan + + + +

    This configuration management plan documents the guidelines +and processes we use when developing and maintaining the Common +UNIX Printing System ("CUPS") and related software. Our goal is +to provide reliable and efficient software and documentation that +addresses the needs of our users.

    + +

    Communication

    + +

    How to Contact the Developers

    + +

    The CUPS +Forums are the primary means of asking questions and +informally discussing issues and feature requests with the CUPS +developers. Table 1 shows the available forums and their +focus:

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 1: CUPS Forums
    ForumFocus/Purpose
    cups.bugsDiscussion of bugs and issues in the CUPS + software
    cups.commitReport of all commits to the Subversion repository + (read-only)
    cups.ddkUsage and development questions for the CUPS Driver + Development Kit
    cups.developmentDevelopment questions and discussion of new features + in the CUPS software
    cups.generalUsage questions for the CUPS software
    + +

    How to Submit a Bug Report or Feature Request

    + +

    The CUPS "Bugs & +Features" page provides access to the CUPS software +trouble report database and is the formal way to submit a +bug report or feature request to the CUPS developers. Please +note, however, that we do not provide answers to usage +questions or resolve problems in third-party software on this +page - use the CUPS Forums for that instead.

    + +

    Unlike discussions that occur on the CUPS Forums, formal bug +reports and feature requests must be acted on by the CUPS +developers. This does not mean that every bug report is resolved +or every feature request is implemented, but we do respond and +keep track of them all for posterity.

    + +
    Please use the search feature of the Bugs & +Features page before submitting a new bug report or feature +request. If you see an existing report that matches your issue, +please post a message to that report ("I have this issue as +well", "I would also like to see", etc.) rather than submitting a +new report. This helps speed the resolution of your issue by +reducing the CUPS developers' work load.
    + +

    How to Prepare a Patch

    + +

    When submitting a bug report or feature request, you can +include patch files that resolve the bug or implement the feature +to speed the inclusion of that bug fix or feature in a new CUPS +release. For changes to existing files, we prefer a unified diff +against the current Subversion trunk branch, which can +be generated easily using the following Subversion command:

    + +
    +svn diff >filename.patch
+
    + +

    If you produce a patch using a released source archive, use +one of the following commands instead:

    + +
    +diff -u oldfilename filename >filename.patch
+
+diff -urN olddirectory directory >filename.patch
+
    + +

    New files and files with significant changes can be submitted +in their entirety, however that may delay the adoption of your +changes.

    + +
    Patches and files must conform to the standards +outlined in the "Coding Guidelines" and "Makefile Guidelines" sections in this +document. In addition, since Easy Software Products provides CUPS +under multiple licenses, we require that you assign the copyright +for your changes and files to us for inclusion in +CUPS.
    + + +

    Software Development Practices

    + +

    Version Numbering

    + +

    CUPS uses a three-part version number separated by periods to +represent the major, minor, and patch release numbers. Major +release numbers indicate large design changes or +backwards-incompatible changes to the CUPS API or CUPS Imaging +API. Minor release numbers indicate new features and other +smaller changes which are backwards-compatible with previous CUPS +releases. Patch numbers indicate bug fixes to the previous +release.

    + +
    When we talk about compatibility, we are talking +about binary compatibility for public APIs and output format +compatibility for program interfaces. Changes to configuration +file formats or the default behavior of programs are not +generally considered incompatible as the upgrade process can +normally address such changes gracefully.
    + +

    Production releases use the plain version numbers:

    + +
    +MAJOR.MINOR.PATCH
+1.0.0
+1.0.1
+1.0.2
+...
+1.1.0
+...
+1.1.23
+1.2.0
+1.2.1
+...
+1.3.0
+...
+2.0.0
+
    + +

    The first production release in a MAJOR.MINOR series +(MAJOR.MINOR.0) is called a feature release. Feature releases are +the only releases that may contain new features. Subsequent +production releases in a MAJOR.MINOR series may only contain bug +fixes.

    + +
    We did not hold to this limitation in the CUPS 1.1 +series for a variety of reasons. Starting with CUPS 1.2, the "no +new features in a patch release" policy will be strictly +enforced. This should yield more frequent minor releases with +fewer new features (and interactions!) to +validate/test.
    + +

    Beta-test releases are identified by appending the letter B +to the major and minor version numbers followed by the beta +release number:

    + +
    +MAJOR.MINORbNUMBER
+1.2b1
+
    + +

    Release candidates are identified by appending the letters RC +to the major and minor version numbers followed by the release +candidate number:

    + +
    +MAJOR.MINORrcNUMBER
+1.2rc1
+
    + +

    Developer snapshots are identified by appending the letters +SVN-R to the major and minor version numbers followed by the +revision number:

    + +
    +MAJOR.MINORsvn-rREV
+1.2svn-r1234
+
    + +

    Beta-test releases, release candidates, and developer +snapshots are only created for new minor releases. Once a +production release has been made (MAJOR.MINOR.0), subsequent +patch releases are issues without preliminary beta or release +testing.

    + +

    Version Control (Subversion)

    + +

    The CUPS source files are managed by the Subversion ("SVN") +software, available at:

    + +
    +subversion.tigris.org
+
    + +

    Source files are "checked in" with each change so that +modifications can be tracked, and each checkin must reference any +applicable STRs. The following format must be used for +commit log messages:

    + +
    +Summary of the change ("fix PostScript printing bug") along
+with corresponding STRs ("STR #1, STR #6")
+
+foo.cxx:
+    - function(): Detailed list of changes
+    - function2(): Detailed list of changes
+    - Summary of design changes ("added new foo struct")
+
+bar.h:
+    - More detailed changes
+
    + +

    Primary development occurs on the trunk branch, +with changes merged back to release branches as needed. Table 2 +shows the URLs developers use for the various CUPS subprojects +and branches:

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 2: CUPS Subversion URLs
    URLPurpose
    https://svn.easysw.com/public/cups/trunk/Primary CUPS development branch
    https://svn.easysw.com/public/cups/branches/CUPS maintenance branches (merge-only)
    https://svn.easysw.com/public/cups/tags/CUPS release tags (read-only)
    https://svn.easysw.com/public/cupsddk/trunk/Primary CUPS DDK development branch
    https://svn.easysw.com/public/cupsddk/branches/CUPS DDK maintenance branches (merge-only)
    https://svn.easysw.com/public/cupsddk/tags/CUPS DDK release tags (read-only)
    https://svn.easysw.com/public/espgs/trunk/Primary ESP Ghostscript development branch
    https://svn.easysw.com/public/espgs/branches/ESP Ghostscript maintenance branches (merge-only)
    https://svn.easysw.com/public/espgs/tags/ESP Ghostscript release tags (read-only)
    https://svn.easysw.com/public/windows/trunk/Primary CUPS Windows Driver development branch
    https://svn.easysw.com/public/windows/branches/CUPS Windows Driver maintenance branches (merge-only)
    https://svn.easysw.com/public/windows/tags/CUPS Windows Driver release tags (read-only)
    + +

    The branch for a MAJOR.MINOR release are created when the +first production release (MAJOR.MINOR.0) is made using the name +"branch-MAJOR.MINOR". Release tags are created for every beta, +candidate, and production release using the name +"release-MAJOR.MINOR.PATCHbNUMBER", +"release-MAJOR.MINOR.PATCHrcNUMBER", or +"release-MAJOR.MINOR.PATCH", respectively. No release tags are +created for developer snapshots.

    + + +

    Files and Directories

    + +

    File and directory names may not exceed 16 characters in +length to ensure compability with older UNIX filesystems. In +addition, to avoid problems with case-insensitive filesystems, +you may not use names which differ only by case, for example +"ReadMe" and "README" are not allowed in the same directory.

    + +

    Source files must be documented and formatted as described in +"Coding Requirements". Make files must +follow the guidelines in "Makefile +Guidelines".

    + + +

    Build System

    + +

    The CUPS build system uses GNU autoconf to +tailor the library to the local operating system. Project files +for major IDEs are also provided for Microsoft +Windows®. To improve portability, makefiles must +not make use of the unique features offered by GNU make. See the Makefile Guidelines section for a +description of the allowed make features and makefile +guidelines.

    + +

    Additional GNU build programs such as GNU automake and +GNU libtool +must not be used. GNU automake produces non-portable makefiles +which depend on GNU-specific extensions, and GNU libtool is not +portable or reliable enough for CUPS.

    + + +

    Packaging

    + +

    Source packages are created using the +tools/makesrcdist script in the Subversion repository. +The script optionally uses a version number argument:

    + +
    +tools/makesrcdist
+tools/makesrcdist version
+
    + +

    When run with no arguments, the script creates a snapshot of +the current working copy and names it using the highest revision +number in the WC, for example +"/tmp/cups-1.2svn-r1234-source.tar.bz2" and +"/tmp/cups-1.2svn-r1234-source.tar.gz". When run with two +arguments, the script creates a release tag in the repository and +exports that tag, creating the files +"/tmp/cups-version-source.tar.bz2" and +"/tmp/cups-version-source.tar.gz".

    + +

    Binary packages are not generally distributed by the CUPS +team, however the packaging/cups.spec and +packaging/cups.list files may be used to create binary +packages on Linux, MacOS X, and UNIX. The +packaging/cups.spec file produces a binary package +using the rpmbuild(8) software:

    + +
    +rpmbuild -ta cups-version-source.tar.gz
+
    + +

    The cups.list file is generated by the +configure script and produces binary packages for many +platforms using the EPM software. Table 3 shows the targets that +are available for each type of binary package:

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 3: Binary Package Targets
    TargetType of Package
    aixAIX installp
    bsd*BSD pkg_install
    debDebian dpkg
    depotHP-UX swinstall
    epmPortable tarball with install script
    instIRIX inst/tardist
    osxMacOS X Install
    pkgSolaris pkgadd
    rpmRPM binary
    setldTru64 UNIX setld
    slackwareSlackware install
    swinstallHP-UX swinstall
    tardistIRIX inst/tardist
    + +

    Finally, the tools/testrpm and +tools/testosx scripts can be used to create binary +packages from the current working copy for testing on Linux and +MacOS X, respectively:

    + +
    +tools/testrpm
+sudo rpm -U /usr/src/redhat/RPMS/i386/cups*.rpm
+
+sudo tools/testosx
+open cups.pkg
+
    + + +

    Testing

    + +

    Software testing is conducted according to the CUPS Software Test Plan. This testing is +automated via the top-level makefile test target:

    + +
    +make test
+
    + +

    The test environment allows for both short-term automated +testing and long-term testing and development without the +automated test script.

    + + +

    Trouble Report Processing

    + +

    A Software Trouble Report ("STR") must be submitted every time +a user or vendor experiences a problem with the CUPS software. +Trouble reports are maintained on the Bugs & +Features page with one of the following states:

    + +
      + +
    1. STR is closed with complete resolution
      2. + +
    2. STR is closed without resolution
      3. + +
    3. STR is active, waiting on information from submitter
      4. + +
    4. STR is pending with additional information from submitter
      5. + +
    5. STR is newly submitted
      6. + +
    + +

    Trouble reports are processed using the following steps.

    + +
      + +
    1. Classification + +

      When a trouble report is received it must be classified at one +of the following priority levels:

      + +
        + +
      1. Request for enhancement, e.g. asking for a + feature + +
      2. Low, e.g. a documentation error or undocumented + side-effect + +
      3. Moderate, e.g. unable to print a file or unable to + compile the software + +
      4. High, e.g. unable to print to a printer or key + functionality not working + +
      5. Critical, e.g. unable to print at all + +
      + +

      Level 4 and 5 trouble reports must be resolved in the next +software release. Level 2 and 3 trouble reports are scheduled for +resolution in a specific release at the discretion of the release +coordinator. Level 1 trouble reports are scheduled for resolution +in a future feature release.

      + +

      The scope of the problem is also determined as:

      + +
        + +
      1. Specific to a machine or printer + +
      2. Specific to an operating system + +
      3. Applies to all machines, printers, and operating systems + +
      + +
    2. Identification + +

      Once the level and scope of the trouble report is determined +the software sub-system(s) involved with the problem are +determined. This may involve additional communication with the +user or vendor to isolate the problem to a specific cause.

      + +

      When the sub-system(s) involved have been identified, an +engineer will then determine the change(s) needed and estimate +the time required for the change(s).

      + +
    3. Correction + +

      Corrections are scheduled based upon the severity and +complexity of the problem. Once all changes have been made, +documented, and tested successfully a new software release +snapshot is generated. Additional tests are added as necessary +for proper testing of the changes.

      + +
    4. Notification + +

      The user or vendor is notified when the fix is available or if +the problem was caused by user error.

      + +
    + + +

    Release Management

    + +

    When testing has been completed successfully, a new source +package is created using the tools/makesrcdist script. +Three types of releases, beta, candidate, and production, are +created and released to the public using the basic schedule in +Table 4. At least one beta and one release candidate must be +created prior to a production release, and there must be at least +two weeks between the last beta and first candidate and last +candidate and first production release.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table: CUPS Basic Release Schedule
    WeekVersionDescription
    T-6 weeks1.2b1First beta release
    T-5 weeks1.2b2Second beta release
    T-3 weeks1.2rc1First release candidate
    T-2 weeks1.2rc2Second release candidate
    T-0 weeks1.2.0Production (feature) release
    + + +

    Coding Guidelines

    + +

    These coding guidelines provide detailed information on source +file formatting and documentation content and must be applied to +all C and C++ source files provided with CUPS. Source code for +other languages should conform to these guidelines as allowed by +the language.

    + +

    Source Files

    + +

    All source files names shall be 16 characters or less in +length to ensure compatibility with older UNIX filesystems. +Source files containing functions shall have an extension of ".c" +for ANSI C and ".cxx" for C++ source files. All other "include" +files shall have an extension of ".h".

    + +

    The top of each source file shall contain a header giving the +name of the file, the purpose or nature of the source file, the +copyright and licensing notice, and the functions contained in +the file. The file name and revision information is provided by +the Subversion "$Id$" tag:

    + +
    +/*
+ * "$Id$"
+ *
+ *   Description of file contents.
+ *
+ *   Copyright yyyy-YYYY by Easy Software Products, all rights
+ *   reserved.
+ *
+ *   These coded instructions, statements, and computer programs are
+ *   the property of Easy Software Products and are protected by
+ *   Federal copyright law.  Distribution and use rights are outlined
+ *   in the file "LICENSE.txt" which should have been included with
+ *   this file.  If this file is missing or damaged please contact
+ *   Easy Software Products at:
+ *
+ *       Attn: CUPS Licensing Information
+ *       Easy Software Products
+ *       44141 Airport View Drive, Suite 204
+ *       Hollywood, Maryland 20636 USA
+ *
+ *       Voice: (301) 373-9600
+ *       EMail: cups-info@cups.org
+ *         WWW: http://www.cups.org/
+ *
+ * Contents:
+ *
+ *   function1() - Description 1.
+ *   function2() - Description 2.
+ *   function3() - Description 3.
+ */
+
    + +

    For source files that are subject to the Apple OS-Developed +Software exception, the following additional comment should +appear after the contact information:

    + +
    + *   This file is subject to the Apple OS-Developed Software exception.
+
    + +

    The bottom of each source file shall contain a trailer giving +the name of the file using the Subversion "$Id$" tag. The +primary purpose of this is to mark the end of a source file; if +the trailer is missing it is possible that code has been lost +near the end of the file:

    + +
    +/*
+ * End of "$Id$".
+ */
+
    + +

    Functions

    + +

    Functions with a global scope shall have a lowercase prefix +followed by capitalized words ("cupsDoThis", "cupsDoThat", +"cupsDoSomethingElse", etc.) Private global functions shall begin +with a leading underscore ("_cupsDoThis", "_cupsDoThat", +etc.)

    + +

    Functions with a local scope shall be declared "static" and be +lowercase with underscores between words ("do_this", "do_that", +"do_something_else", etc.)

    + +

    Each function shall begin with a comment header describing +what the function does, the possible input limits (if any), and +the possible output values (if any), and any special information +needed:

    + +
    +/*
+ * 'do_this()' - Compute y = this(x).
+ *
+ * Notes: none.
+ */
+
+static float                            /* O - Inverse power value, 0.0 <= y <= 1.1 */
+do_this(float x)                        /* I - Power value (0.0 <= x <= 1.1) */
+{
+  ...
+  return (y);
+}
+
    + +

    Return/output values are indicated using an "O" prefix, input +values are indicated using the "I" prefix, and values that are +both input and output use the "IO" prefix for the corresponding +in-line comment.

    + +

    The Mini-XML documentation generator also understands the following +special text in the function description comment:

    + +
      + +
    • @since CUPS version@ - Marks the + function as new in the specified version of CUPS.
      • + +
    • @deprecated@ - Marks the function as + deprecated (not recommended for new development and + scheduled for removal)
      • + +
    + +

    Variables

    + +

    Variables with a global scope shall be capitalized +("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The +only exception to this rule shall be the CUPS interface library +global variables which must begin with the prefix "cups" +("cupsThisVariable", "cupsThatVariable", etc.) Global variables +shall be replaced by function arguments whenever possible.

    + +

    Variables with a local scope shall be lowercase with +underscores between words ("this_variable", "that_variable", +etc.) Any local variables shared by functions within a source +file shall be declared "static".

    + +

    Each variable shall be declared on a separate line and shall +be immediately followed by a comment block describing the +variable:

    + +
    +int this_variable;   /* The current state of this */
+int that_variable;   /* The current state of that */
+
    + +

    Types

    + +

    All type names shall be lowercase with underscores between +words and "_t" appended to the end of the name +("cups_this_type_t", "cups_that_type_t", etc.) Type names must +start with a prefix, typically "cups" or the name of the program, +to avoid conflicts with system types. Private type names must +start with an underscore ("_cups_this_t", "_cups_that_t", +etc.)

    + +

    Each type shall have a comment block immediately after the +typedef:

    + +
    +typedef int cups_this_type_t;           /* This type is for CUPS foobar options. */
+
    + +

    Structures

    + +

    All structure names shall be lowercase with underscores +between words and "_s" appended to the end of the name +("cups_this_s", "cups_that_s", etc.) Structure names must start +with a prefix, typically "cups" or the name of the program, to +avoid conflicts with system types. Private structure names must +start with an underscore ("_cups_this_s", "_cups_that_s", +etc.)

    + +

    Each structure shall have a comment block immediately after +the struct and each member shall be documented in accordance with +the variable naming policy above:

    + +
    +struct cups_this_struct_s               /* This structure is for CUPS foobar options. */
+{
+  int this_member;                      /* Current state for this */
+  int that_member;                      /* Current state for that */
+};
+
    + +

    Constants

    + +

    All constant names shall be uppercase with underscored between +words ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.) +Constants must begin with an uppercase prefix, typically "CUPS" +or the program name.

    + +

    Typed enumerations shall be used whenever possible to allow +for type checking by the compiler.

    + +

    Comment blocks shall immediately follow each constant:

    + +
    +enum
+{
+  CUPS_THIS_TRAY,                       /* This tray */
+  CUPS_THAT_TRAY                        /* That tray */
+};
+
    + +

    Code

    + +

    All source code shall utilize block comments within functions +to describe the operations being performed by a group of +statements; avoid putting a comment per line unless absolutely +necessary, and then consider refactoring the code so that it is +not necessary:

    + +
    +/*
+ * Clear the state array before we begin...
+ */
+
+for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
+  array[i] = STATE_IDLE;
+
+/*
+ * Wait for state changes...
+ */
+
+do
+{
+  for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
+    if (array[i] != STATE_IDLE)
+      break;
+
+  if (i == (sizeof(array) / sizeof(array[0])))
+    sleep(1);
+} while (i == (sizeof(array) / sizeof(array[0])));
+
    + +

    Indentation

    + +

    All code blocks enclosed by brackets shall begin with the +opening brace on a new line. The code then follows starting on a +new line after the brace and is indented 2 spaces. The closing +brace is then placed on a new line following the code at the +original indentation:

    + +
    +{
+  int i; /* Looping var */
+
+ /*
+  * Process foobar values from 0 to 999...
+  */
+
+  for (i = 0; i < 1000; i ++)
+  {
+    do_this(i);
+    do_that(i);
+  }
+}
+
    + +

    Single-line statements following "do", "else", "for", "if", +and "while" shall be indented 2 spaces as well. Blocks of code +in a "switch" block shall be indented 4 spaces after each "case" +and "default" case:

    + +
    +switch (array[i])
+{
+  case STATE_IDLE :
+      do_this(i);
+      do_that(i);
+      break;
+  default :
+      do_nothing(i);
+      break;
+}
+
    + +

    Spacing

    + +

    A space shall follow each reserved word ("if", "while", etc.) +Spaces shall not be inserted between a function name and the +arguments in parenthesis.

    + +

    Return Values

    + +

    Parenthesis shall surround values returned from a function +using "return":

    + +
    +return (CUPS_STATE_IDLE);
+
    + +

    Loops

    + +

    Whenever convenient loops should count downward to zero to +improve program performance:

    + +
    +for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
+  array[i] = CUPS_STATE_IDLE;
+
    + +

    Makefile Guidelines

    + +

    The following is a guide to the makefile-based build system +used by CUPS. These standards have been developed over the years +to allow CUPS to be built on as many systems and environments as +possible.

    + +

    General Organization

    + +

    The CUPS source code is organized functionally into a +top-level makefile, include file, and subdirectories each with +their own makefile and dependencies files. The ".in" files are +template files for the autoconf software and are +used to generate a static version of the corresponding file.

    + +

    Makefile Documentation

    + +

    Each make file must start with the standard CUPS header +containing the Subversion "$Id$" keyword, description of the +file, and CUPS copyright and license notice:

    + +
    +#
+# "$Id$"
+#
+#   Makefile for ...
+#
+#   Copyright yyyy-YYYY by Easy Software Products, all rights
+#   reserved.
+#
+#   These coded instructions, statements, and computer programs are
+#   the property of Easy Software Products and are protected by
+#   Federal copyright law.  Distribution and use rights are outlined
+#   in the file "LICENSE.txt" which should have been included with
+#   this file.  If this file is missing or damaged please contact
+#   Easy Software Products at:
+#
+#       Attn: CUPS Licensing Information
+#       Easy Software Products
+#       44141 Airport View Drive, Suite 204
+#       Hollywood, Maryland 20636 USA
+#
+#       Voice: (301) 373-9600
+#       EMail: cups-info@cups.org
+#         WWW: http://www.cups.org/
+#
+
    + +

    The end of each makefile must have a comment saying:

    + +
    +#
+# End of "$Id$".
+#
+
    + +

    The purpose of the trailer is to indicate the end of the +makefile so that truncations are immediately obvious.

    + +

    Portable Makefile Construction

    + +

    CUPS uses a common subset of make program syntax to ensure +that the software can be compiled "out of the box" on as many +systems as possible. The following is a list of assumptions we +follow when constructing makefiles:

    + +
      + +
    • Targets; we assume that the make program + supports the notion of simple targets of the form + "name:" that perform tab-indented commands that follow + the target, e.g.: + 
      +target:
+→ target commands
      • + +
    • Dependencies; we assume that the make program + supports recursive dependencies on targets, e.g.: + 
      +target: foo bar
+→ target commands
+
+foo: bla
+→ foo commands
+
+bar:
+→ bar commands
+
+bla:
+→ bla commands
      • + +
    • Variable Definition; we assume that the make program + supports variable definition on the command-line or in the makefile + using the following form: + 
      +name=value
      + +
    • Variable Substitution; we assume that the make program + supports variable substitution using the following forms: +
        +
      • $(name); substitutes the value of "name",
        • +
      • ($name:.old=.new); substitutes the value of "name" + with the filename extensions ".old" changed to ".new",
        • +
      • $(MAKEFLAGS); substitutes the + command-line options passed to the program + without the leading hyphen (-),
        • +
      • $$; substitutes a single $ character,
        • +
      • $<; substitutes the current source file or dependency, and
        • +
      • $@; substitutes the current target name.
        • +
      • + +
    • Suffixes; we assume that the make program + supports filename suffixes with assumed dependencies, e.g.: + 
      +.SUFFIXES: .c .o
+.c.o:
+→ $(CC) $(CFLAGS) -o $@ -c $<
      • + +
    • Include Files; we assume that the make program + supports the include directive, e.g.: + 
      +include ../Makedefs
+include Dependencies
      • + +
    • Comments; we assume that comments begin with + a # character and proceed to the end of the + current line.
      • + +
    • Line Length; we assume that there is no + practical limit to the length of lines.
      • + +
    • Continuation of long lines; we assume that + the \ character may be placed at the end of a + line to concatenate two or more lines in a + makefile to form a single long line.
      • + +
    • Shell; we assume a POSIX-compatible shell is + present on the build system.
      • + +
    + +

    Standard Variables

    + +

    The following variables are defined in the "Makedefs" file +generated by the autoconf software:

    + +
      + +
    • AR; the library archiver command,
      • + +
    • ARFLAGS; options for the library archiver command,
      • + +
    • BUILDROOT; optional installation prefix,
      • + +
    • MAN1EXT; extension for man pages in section 1,
      • + +
    • MAN3EXT; extension for man pages in section 3,
      • + +
    • MAN5EXT; extension for man pages in section 5,
      • + +
    • MAN7EXT; extension for man pages in section 7,
      • + +
    • MAN8DIR; subdirectory for man pages in section 8,
      • + +
    • MAN8EXT; extension for man pages in section 8,
      • + +
    • CC; the C compiler command,
      • + +
    • CFLAGS; options for the C compiler command,
      • + +
    • CXX; the C++ compiler command,
      • + +
    • CXXFLAGS; options for the C++ compiler command,
      • + +
    • DSOCOMMAND; the shared library building command,
      • + +
    • DSOFLAGS; options for the shared library building command,
      • + +
    • INSTALL; the install command,
      • + +
    • INSTALL_BIN; the program installation command,
      • + +
    • INSTALL_DATA; the data file installation command,
      • + +
    • INSTALL_DIR; the directory installation command,
      • + +
    • INSTALL_LIB; the library installation command,
      • + +
    • INSTALL_MAN; the documentation installation command,
      • + +
    • INSTALL_SCRIPT; the shell script installation command,
      • + +
    • LDFLAGS; options for the linker,
      • + +
    • LIBS; libraries for all programs,
      • + +
    • LN; the ln command,
      • + +
    • OPTIM; common compiler optimization options,
      • + +
    • RM; the rm command,
      • + +
    • SHELL; the sh (POSIX shell) command,
      • + +
    • STRIP; the strip command,
      • + +
    • bindir; the binary installation directory,
      • + +
    • datadir; the data file installation directory,
      • + +
    • exec_prefix; the installation prefix for executable files,
      • + +
    • libdir; the library installation directory,
      • + +
    • mandir; the man page installation directory,
      • + +
    • prefix; the installation prefix for non-executable files, and
      • + +
    • srcdir; the source directory.
      • + +
    + +

    Standard Targets

    + +

    The following standard targets must be defined in each +makefile:

    + +
      + +
    • all; creates all target programs, + libraries, and documentation files,
      • + +
    • clean; removes all target programs, + libraries, documentation files, and object files,
      • + +
    • depend; generates automatic dependencies + for any C or C++ source files (also see "Dependencies"),
      • + +
    • distclean; removes autoconf-generated files + in addition to those removed by the "clean" target,
      • + +
    • install; installs all distribution files in + their corresponding locations (also see "Install/Uninstall Support"),
      • + +
    • uninstall; removes all distribution files from + their corresponding locations (also see "Install/Uninstall Support"), and
      • + +
    + + +

    Object Files

    + +

    Object files (the result of compiling a C or C++ source file) +have the extension ".o".

    + +

    Programs

    + +

    Program files are the result of linking object files and +libraries together to form an executable file. A typical +program target looks like:

    + +
    +program: $(OBJS)
+→ echo Linking $@...
+→ $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
+
    + +

    Static Libraries

    + +

    Static libraries have a prefix of "lib" and the extension +".a". A typical static library target looks like:

    + +
    +libname.a: $(OBJECTS)
+→ echo Creating $@...
+→ $(RM) $@
+→ $(AR) $(ARFLAGS) $@ $(OBJECTS)
+→ $(RANLIB) $@
+
    + +

    Shared Libraries

    + +

    Shared libraries have a prefix of "lib" and the extension +".dylib", ".sl", ".so", or "_s.a" depending on the operating +system. A typical shared library is composed of several targets +that look like:

    + +
    +libname.so: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ...
+→ $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS)
+→ $(RM) libname.so libname.so.$(DSOMAJOR)
+→ $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR)
+→ $(LN) libname.so.$(DSOVERSION) libname.so
+
+libname.sl: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.sl.$(DSOVERSION) ...
+→ $(DSOCOMMAND) libname.sl.$(DSOVERSION) $(OBJECTS)
+→ $(RM) libname.sl libname.sl.$(DSOMAJOR)
+→ $(LN) libname.sl.$(DSOVERSION) libname.sl.$(DSOMAJOR)
+→ $(LN) libname.sl.$(DSOVERSION) libname.sl
+
+libname.dylib: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ...
+→ $(DSOCOMMAND) libname.$(DSOVERSION).dylib \
+→ → -install_name $(libdir)/libname.$(DSOMAJOR).dylib \
+→ → -current_version libname.$(DSOVERSION).dylib \
+→ → -compatibility_version $(DSOMAJOR).0 \
+→ → $(OBJECTS) $(LIBS)
+→ $(RM) libname.dylib
+→ $(RM) libname.$(DSOMAJOR).dylib
+→ $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib
+→ $(LN) libname.$(DSOVERSION).dylib libname.dylib
+
+libname_s.a: $(OBJECTS)
+→ echo $(DSOCOMMAND) libname_s.o ...
+→ $(DSOCOMMAND) libname_s.o $(OBJECTS) $(LIBS)
+→ echo $(LIBCOMMAND) libname_s.a libname_s.o
+→ $(RM) $@
+→ $(LIBCOMMAND) libname_s.a libname_s.o
+→ $(CHMOD) +x libname_s.a
+
    + + +

    Dependencies

    + +

    Static dependencies are expressed in each makefile following the +target, for example:

    + +
    +foo: bar
+
    + +

    Static dependencies shall only be used when it is not +possible to automatically generate them. Automatic dependencies +are stored in a file named "Dependencies" and included at the +end of the makefile. The following "depend" target rule shall be +used to create the automatic dependencies: + +

    +depend:
+→ $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c)
+
    + +

    We only regenerate the automatic dependencies on a Linux +system and express any non-Linux dependencies statically in the +makefile.

    + +

    Install/Uninstall Support

    + +

    All makefiles must contain install and uninstall rules which +install or remove the corresponding software. These rules must +use the $(BUILDROOT) variable as a prefix to any +installation directory so that CUPS can be installed in a +temporary location for packaging by programs like +rpmbuild.

    + +

    The $(INSTALL_BIN), $(INSTALL_DATA), +$(INSTALL_DIR), $(INSTALL_LIB), +$(INSTALL_MAN), and $(INSTALL_SCRIPT) +variables must be used when installing files so that the proper +ownership and permissions are set on the installed files.

    + +

    The $(RANLIB) command must be run on any static +libraries after installation since the symbol table is +invalidated when the library is copied on some platforms.

    + + + diff --git a/doc/help/spec-command.html b/doc/help/spec-command.html index a9f74f098d..8847203d27 100644 --- a/doc/help/spec-command.html +++ b/doc/help/spec-command.html @@ -1,6 +1,6 @@ - + CUPS Command File Format diff --git a/doc/help/spec-design.html b/doc/help/spec-design.html new file mode 100644 index 0000000000..cfec318824 --- /dev/null +++ b/doc/help/spec-design.html @@ -0,0 +1,170 @@ + + + + CUPS Design Description + + + +

    Like most printing systems, CUPS is designed around a central +print scheduling process that dispatches print jobs, processes +administrative commands, provides printer status information to +local and remote programs, and informs users as needed. Figure 1 +shows the basic organization of CUPS.

    + +

    Scheduler

    + +

    The scheduler is a HTTP/1.1 server application that handles +HTTP requests. Besides handling printer requests via IPP POST +requests, the scheduler also acts as a full-featured web server +for documentation, status monitoring, and administration.

    + +

    The scheduler also manages a list of available printers on +the LAN and dispatches print jobs as needed using the +appropriate filters and backends.

    + +

    Configuration Files

    + +

    The configuration files consist of:

    + +
      + +
    • The HTTP server configuration file.
      • + +
    • Printer and class definition files.
      • + +
    • MIME type and conversion rule files.
      • + +
    • PostScript Printer Description (PPD) files.
      • + +
    + +

    The HTTP server configuration file is purposely similar to +the Apache server configuration file and defines all of the +access control properties for the server.

    + +

    The printer and class definition files list the available +printer queues and classes. Printer classes are collections of +printers. Jobs sent to a class are forwarded to the first +available printer in the class, round-robin fashion.

    + +

    The MIME type files list the supported MIME types +(text/plain, application/postscript, etc.) and "magic' rules for +automatically detecting the format of a file. These are used by +the HTTP server to determine the Content-Type field for +GET and HEAD requests and by the IPP request +handler to determine the file type when a Print-Job or +Send-File request is received with a +document-format of +application/octet-stream.

    + +

    The MIME conversion rule files list the available filters. +The filters are used when a job is dispatched so that an +application can send a convenient file format to the printing +system which then converts the document into a printable format +as needed. Each filter has a relative cost associated with it, +and the filtering algorithm chooses the set of filters that will +convert the file to the needed format with the lowest total +"cost".

    + +

    The PPD files describe the capabilities of all printers, not +just PostScript printers. There is one PPD file for each +printer. PPD files for non-PostScript printers define additional +filters through cupsFilter attributes to support +printer drivers.

    + +

    CUPS Block Diagram
    +Figure 1 - CUPS Block Diagram

    + +

    CUPS API

    + +

    The CUPS API contains CUPS-specific convenience functions for +queuing print jobs, getting printer information, accessing +resources via HTTP and IPP, and manipulating PPD files. Unlike +the rest of CUPS, the CUPS API is provided under the terms of +the GNU LGPL so it may be used by non-GPL applications.

    + +

    Berkeley and System V Commands

    + +

    CUPS provides the System V and Berkeley command-line +interfaces for submitting jobs and checking the printer status. +The lpstat and lpc status commands +also show network printers ("printer@server") when printer +browsing is enabled.

    + +

    The System V administation commands are supplied for managing +printers and classes. The Berkeley printer administration tool +(lpc) is only supported in a "read-only' mode to +check the current status of the printer queues and +scheduler.

    + +

    Filters

    + +

    A filter program reads from the standard input or from a file +if a filename is supplied. All filters must support a common set +of options including printer name, job ID, username, job title, +number of copies, and job options. All output is sent to the +standard output.

    + +

    Filters are provided for many file formats and include image +file and PostScript raster filters that support non-PostScript +printers. Multiple filters are run in parallel to produce the +required output format.

    + +

    The PostScript raster filter is based on the ESP Ghostscript +core. Instead of using the Ghostscript printer drivers, the CUPS +filter uses a generic CUPS raster printer driver and +CUPS-compliant front-end to support any kind of raster printer. +This allows the same printer driver filter to be used for +printing raster data from any filter.

    + +
    Talk about Apple's use of CUPS...
    + +

    CUPS Imaging

    + +

    The CUPS Imaging library provides functions for managing +large images, doing colorspace conversion and color management, +scaling images for printing, and managing raster page streams. +It is used by the CUPS image file filters, the PostScript RIP, +and all raster printers drivers.

    + +

    Backends

    + +

    A backend program is a special filter that sends print data +to a device or network connection. Backends for parallel, +serial, USB, LPD, IPP, and AppSocket (JetDirect) connections are +provided in CUPS 1.2.

    + +

    SAMBA version 2.0.6 and higher includes a SMB backend +(smbspool(1)) that can be used for printing to +Windows.

    + +

    Network Printing

    + +

    Traditionally, network printing has been one of the hardest +things to get working under UNIX. One reason is because each +vendor added their own extensions to the LPD protocol (the +previous standard for network printing), making cross-platform +printing difficult if not impossible.

    + +

    Another reason is that you have to administer every network +printer on every client machine. In some cases you can "clone' +the printer configuration from a "master' client to each of the +others, but even that can be time-consuming and error-prone. +Something better is needed.

    + +

    CUPS provides "printer browsing", which allows clients to +automatically see and use printers from any server on a LAN. +This means that you only need to configure the server and the +clients will automatically see the printers and classes on +it.

    + +

    In addition, CUPS can automatically merge multiple identical +network printers into "implicit classes". This allows clients to +send jobs to the implicit class and have them print on the first +available printer or server. In addition, failsafe and +load-balancing functions are enabled simply by defining the same +printer on multiple servers!

    + + + diff --git a/doc/help/spec-ipp.html b/doc/help/spec-ipp.html index 24991a90d7..47a2a5ac50 100644 --- a/doc/help/spec-ipp.html +++ b/doc/help/spec-ipp.html @@ -1,6 +1,6 @@ - + CUPS Implementation of IPP diff --git a/doc/help/spec-ppd.html b/doc/help/spec-ppd.html index 51c35b925f..4ef176c098 100644 --- a/doc/help/spec-ppd.html +++ b/doc/help/spec-ppd.html @@ -1,6 +1,6 @@ - + CUPS PPD Extensions @@ -8,7 +8,7 @@ + + CUPS Raster Format + + + +

    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.

    + +

    CUPS 1.0 and 1.1 used a version 1 raster format. CUPS 1.2 +introduces a version 2 format that is a superset of the version 1 +format. Applications using the CUPS Imaging API (the cupsRaster* +functions) can read both formats without code changes.

    + +

    The registered MIME media type for CUPS raster files is +application/vnd.cups-raster.

    + + +

    Version 1 Raster File Format

    + +

    A version 1 raster file begins with a 32-bit 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 Imaging API 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 (uncompressed, raw) raster data +for that page.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 1: CUPS Version 1 Raster Page Device Dictionary
    BytesTypeDescriptionValues
    0-63C StringMediaClassMedia class string
    64-127C StringMediaColorMedia color string
    128-191C StringMediaTypeMedia type string
    192-255C StringOutputTypeOutput type string
    256-259Unsigned IntegerAdvanceDistance0 to 232 - 1 points
    260-263Unsigned IntegerAdvanceMedia0 = Never advance roll
    + 1 = Advance roll after file
    + 2 = Advance roll after job
    + 3 = Advance roll after set
    + 4 = Advance roll after page
    264-267Unsigned IntegerCollate0 = do not collate copies
    + 1 = collate copies
    268-271Unsigned IntegerCutMedia0 = Never cut media
    + 1 = Cut roll after file
    + 2 = Cut roll after job
    + 3 = Cut roll after set
    + 4 = Cut roll after page
    272-275Unsigned IntegerDuplex0 = Print single-sided
    + 1 = Print double-sided
    276-283Unsigned Integers (2)HWResolutionHorizontal and vertical resolution in dots-per-inch.
    284-299Unsigned Integers (4)ImagingBoundingBoxFour integers giving the left, bottom, right, and top positions + of the page bounding box in points
    300-303Unsigned IntegerInsertSheet0 = Do not insert separator sheets
    + 1 = Insert separator sheets
    304-307Unsigned IntegerJog0 = Do no jog pages
    + 1 = Jog pages after file
    + 2 = Jog pages after job
    + 3 = Jog pages after set
    308-311Unsigned IntegerLeadingEdge0 = Top edge is first
    + 1 = Right edge is first
    + 2 = Bottom edge is first
    + 3 = Left edge is first
    312-319Unsigned Integers (2)MarginsLeft and bottom origin of image in points
    320-323Unsigned IntegerManualFeed0 = Do not manually feed media
    + 1 = Manually feed media
    324-327Unsigned IntegerMediaPositionInput slot position from 0 to N
    328-331Unsigned IntegerMediaWeightMedia weight in grams per meter squared
    332-335Unsigned IntegerMirrorPrint0 = Do not mirror prints
    + 1 = Mirror prints
    336-339Unsigned IntegerNegativePrint0 = Do not invert prints
    + 1 = Invert prints
    340-343Unsigned IntegerNumCopies1 to 232 - 1
    344-347Unsigned IntegerOrientation0 = Do not rotate page
    + 1 = Rotate page counter-clockwise
    + 2 = Turn page upside down
    + 3 = Rotate page clockwise
    348-351Unsigned IntegerOutputFaceUp0 = Output face down
    + 1 = Output face up
    352-359Unsigned Integers (2)PageSizeWidth and length in points
    360-363Unsigned IntegerSeparations0 = Print composite image
    + 1 = Print color separations
    364-367Unsigned IntegerTraySwitch0 = Do not change trays if selected tray is empty
    + 1 = Change trays if selected tray is empty
    368-371Unsigned IntegerTumble0 = Do not rotate even pages when duplexing
    + 1 = Rotate even pages when duplexing
    372-375Unsigned IntegercupsWidthWidth of page image in pixels
    376-379Unsigned IntegercupsHeightHeight of page image in pixels
    380-383Unsigned IntegercupsMediaTypeDriver-specific 0 to 232 - 1
    384-387Unsigned IntegercupsBitsPerColor1, 2, 4, 8 bits for version 1 raster files
    + 1, 2, 4, 8, and 16 bits for version 2 raster files
    388-391Unsigned IntegercupsBitsPerPixel1 to 32 bits for version 1 raster files
    + 1 to 64 bits for version 2 raster files
    392-395Unsigned IntegercupsBytesPerLine1 to 232 - 1 bytes
    396-399Unsigned IntegercupsColorOrder0 = chunky pixels (CMYK CMYK CMYK)
    + 1 = banded pixels (CCC MMM YYY KKK)
    + 2 = planar pixels (CCC... MMM... YYY... KKK...)
    400-403Unsigned IntegercupsColorSpace0 = white
    + 1 = RGB
    + 2 = RGBA
    + 3 = black
    + 4 = CMY
    + 5 = YMC
    + 6 = CMYK
    + 7 = YMCK
    + 8 = KCMY
    + 9 = KCMYcm
    + 10 = GMCK
    + 11 = GMCS
    + 12 = WHITE
    + 13 = GOLD
    + 14 = SILVER
    + 15 = CIE XYZ
    + 16 = CIE Lab
    + 17 = RGBW
    + 32 = ICC1
    + 33 = ICC2
    + 34 = ICC3
    + 35 = ICC4
    + 36 = ICC5
    + 37 = ICC6
    + 38 = ICC7
    + 39 = ICC8
    + 40 = ICC9
    + 41 = ICCA (10)
    + 42 = ICCB (11)
    + 43 = ICCC (12)
    + 44 = ICCD (13)
    + 45 = ICCE (14)
    + 46 = ICCF (15)
    +
    404-407Unsigned IntegercupsCompressionDriver-specific 0 to 232 - 1
    408-411Unsigned IntegercupsRowCountDriver-specific 0 to 232 - 1
    412-415Unsigned IntegercupsRowFeedDriver-specific 0 to 232 - 1
    416-419Unsigned IntegercupsRowStepDriver-specific 0 to 232 - 1
    + + +

    Version 2 Raster File Format

    + +

    A version 2 raster file begins with a 32-bit synchronization +word: 0x52615332 ("RaS2") for big-endian architectures and +0x32536152 ("2SaR") 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 Imaging API raster functions +perform this function automatically.

    + +

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

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 2: CUPS Version 2 Raster Page Device Dictionary
    BytesTypeDescriptionValues
    0-419Version 1 header dataSee Table 1
    420-423Unsigned IntegercupsNumColors1 to 6 colors
    424-427IEEE Single PrecisioncupsBorderlessScalingFactor0.0 or 1.0 or greater
    428-435IEEE Single Precision (2)cupsPageSizeWidth and length in points
    436-451IEEE Single Precision (4)cupsImagingBBoxFour floating point numbers giving the left, bottom, + right, and top positions of the page bounding box in + points
    452-515Unsigned Integers (16)cupsInteger16 driver-defined integer values
    516-579IEEE Single Precision (16)cupsReal16 driver-defined floating point values
    580-1603C Strings (16x64)cupsString16 driver-defined strings
    1604-1667C StringcupsMarkerTypeInk/toner type string
    1668-1731C StringcupsRenderingIntentColor rendering intent string
    1732-1795C StringcupsPageSizeNamePage size name/keyword string from PPD
    + +

    Compressed Raster Data Format

    + +

    The version 2 raster data is compressed using a modified TIFF +packbits algorithm. Lines are grouped into an integral number of +color values based upon the cupsColorOrder +setting:

    + +
    + + + + + + + + + + + + + + + + +
    cupsColorOrderBytes per color value
    0 (chunky)(cupsBitsPerPixel + 7) / 8
    1 (banded)(cupsBitsPerColor + 7) / 8
    2 (planar)(cupsBitsPerColor + 7) / 8
    + +

    Each line of raster data begins with a repetition count from 1 +to 256 that is encoded using a single byte of "count - 1".

    + +

    After the repetition count, whole color values for that line +are run-length encoded using the TIFF packbits algorithm. 1 to +128 repeated colors are encoded using an initial byte of "count - +1" followed by the color value byte(s). 2 to 128 non-repeating +colors are encoded using an initial byte of "257 - count" +followed by the color value bytes.

    + + + +

    Change History

    + +

    Changes in CUPS 1.2

    + +
      + +
    • Bumped raster version to 2
      • + +
    • Added RGBW colorspace
      • + +
    • Added 16 bit per color support
      • + +
    • Added cupsNumColors, cupsBorderlessScalingFactor, + cupsPageSize, cupsImagingBBox, cupsInteger, cupsReal, + cupsString, cupsMarkerType, cupsRenderingIntent, and + cupsPageSizeName attributes to the page device + dictionary
      • + +
    • Added raster data compression
      • + +
    • Added data type column to device dictionary + documentation.
      • + +
    + +

    Changes in CUPS 1.1.19

    + +
      + +
    • Added ICC and CIE colorspaces.
      • + +
    + + + diff --git a/doc/help/spec-stp.html b/doc/help/spec-stp.html new file mode 100644 index 0000000000..5884690c2b --- /dev/null +++ b/doc/help/spec-stp.html @@ -0,0 +1,130 @@ + + + + CUPS Software Test Plan + + + +

    This software test plan provides detailed tests that are used +to evaluate the stability and compliance of the Common UNIX +Printing System ("CUPS") Version 1.2.

    + + +

    Test Procedure

    + +

    The test software and data files are located in the +test subdirectory of the source distribution. A script +is provided to compile the ipptest program and run +all of the tests that follow, producing a success/fail +report.

    + +

    The test target of the top-level makefile can be +used to run this script:

    + +
    +make test
+
    + +

    or you can run the test script directly:

    + +
    +cd test
+./run-stp-tests
+
    + +

    A Software Test Report is stored in a HTML file in the +test subdirectory at the conclusion of the test.

    + + +

    IPP Compliance Tests

    + +

    This section describes the tests used to validate the IPP +standards compliance of the CUPS server.

    + +

    Request Tests

    + +

    These tests verify that the CUPS scheduler only accepts valid +IPP requests that start with the attributes-charset +and attributes-natural-language attributes and also +contain a printer-uri or job-uri +attribute.

    + +

    It also verifies that the CUPS scheduler always responds with +attributes-charset and +attributes-natural-language attributes, using +default values if they are not provided by the client.

    + +

    CUPS Printer Operation Tests

    + +

    These tests verify that the CUPS printer operations are +supported and function properly. Two printers called +Test1 and Test2 are created, one as a +PostScript printer and one as a raster printer.

    + +

    Job Operation Tests

    + +

    These test verify that the CUPS scheduler accepts print jobs +for all supported file formats and that the +cancel-job, hold-job, and +resume-job operations work.

    + +

    Subscription Operation Tests

    + +

    These test verify that the CUPS scheduler accepts +subscriptions with print jobs and that all subscription +operations work as required by the IPP notification and mailto +specifications.

    + + +

    Command Tests

    + +

    This section describes the tests used to validate the Berkeley +and System V commands included with CUPS.

    + +

    lpadmin

    + +

    This test verifies that printers can be added, modified, and +defaulted using the lpadmin command.

    + +

    lpc

    + +

    This test verifies that the lpc command can show +the current status of all print queues.

    + +

    lpq

    + +

    This test verifies that the lpq command lists +any jobs in the queue.

    + +

    lpstat

    + +

    This test verifies that the lpstat command works +with all reports using the "-t" option.

    + +

    lp

    + +

    This test verifies that the lp command works with +both the default destination and a specific destination.

    + +

    lpr

    + +

    This test verifies that the lpr command works +with both the default destination and a specific destination.

    + +

    lprm

    + +

    This test verifies that the lprm command can +properly cancel a job.

    + +

    cancel

    + +

    This test verifies that the cancel command can +properly cancel a job or all jobs.

    + +

    lpinfo

    + +

    This test verifies that the lpinfo command +returns a list of available printer drivers and devices.

    + + + diff --git a/doc/help/standard.html.in b/doc/help/standard.html.in index 699239bc37..94b4473d17 100644 --- a/doc/help/standard.html.in +++ b/doc/help/standard.html.in @@ -39,39 +39,39 @@ Basic authentication with membership in the group Value - Browsing + Browsing @CUPS_BROWSING@ - BrowseLocalProtocols + BrowseLocalProtocols @CUPS_BROWSE_LOCAL_PROTOCOLS@ - BrowseRemoteProtocols + BrowseRemoteProtocols @CUPS_BROWSE_REMOTE_PROTOCOLS@ - BrowseShortNames + BrowseShortNames @CUPS_BROWSE_SHORT_NAMES@ - ConfigFilePerm + ConfigFilePerm @CUPS_CONFIG_FILE_PERM@ - DefaultShared + DefaultShared @CUPS_DEFAULT_SHARED@ - ImplicitClasses + ImplicitClasses @CUPS_IMPLICIT_CLASSES@ - LogFilePerm + LogFilePerm @CUPS_LOG_FILE_PERM@ - UseNetworkDefault + UseNetworkDefault @CUPS_USE_NETWORK_DEFAULT@ @@ -88,7 +88,7 @@ Basic authentication with membership in the group @CUPS_SERVERROOT@ The location of configuration files such as printers.conf. Overridden by the ServerRoot + HREF="ref-cupsd-conf.html#ServerRoot">ServerRoot directive in cupsd.conf. @@ -107,7 +107,7 @@ Basic authentication with membership in the group @CUPS_SERVERBIN@ The location of server programs such as backends and filters. Overridden by the ServerBin + HREF="ref-cupsd-conf.html#ServerBin">ServerBin directive in cupsd.conf. @@ -118,14 +118,14 @@ Basic authentication with membership in the group @CUPS_DATADIR@ The location of data files such as fonts. Overridden by the DataDir + HREF="ref-cupsd-conf.html#DataDir">DataDir directive in cupsd.conf. @CUPS_DOCROOT@ The location of documentation files. Overridden by the DocumentRoot + HREF="ref-cupsd-conf.html#DocumentRoot">DocumentRoot directive in cupsd.conf. @@ -137,7 +137,7 @@ Basic authentication with membership in the group The location of cache files such as ppds.dat and remote.cache. Overridden by the CacheDir + HREF="ref-cupsd-conf.html#CacheDir">CacheDir directive in cupsd.conf. @@ -145,25 +145,25 @@ Basic authentication with membership in the group The location of the access_log, error_log, and page_log files. Overridden by the AccessLog, + HREF="ref-cupsd-conf.html#AccessLog">AccessLog, ErrorLog, + HREF="ref-cupsd-conf.html#ErrorLog">ErrorLog, PageLog, + HREF="ref-cupsd-conf.html#PageLog">PageLog, directive in cupsd.conf. @CUPS_STATEDIR@ The location of the domain socket file and state data such as authentication certificates. Overridden by the StateDir + HREF="ref-cupsd-conf.html#StateDir">StateDir directive in cupsd.conf. @CUPS_REQUESTS@ The location of spooled print jobs. Overridden by the RequestRoot + HREF="ref-cupsd-conf.html#RequestRoot">RequestRoot directive in cupsd.conf. diff --git a/doc/help/translation.html b/doc/help/translation.html new file mode 100644 index 0000000000..3ffb2de61d --- /dev/null +++ b/doc/help/translation.html @@ -0,0 +1,1050 @@ + + + + Translating CUPS + + + +

    Thanks to its extensive use of templates, images, and message +catalogs, CUPS can be easily translated (or customized!) to suit +your needs. This help file will guide you through the CUPS +localization files so you can get the most out of it.

    + +

    Getting Started

    + +

    Start by downloading the CUPS source code from www.cups.org. After you extract the files +from the source archive, you will want to copy the following +files and directories:

    + +
      + +
    • doc/images/button-*.gif - the web + interface button images
      • + +
    • doc/images/button-*.scm - the Gimp scripts + we use to generate the web interface button images
      • + +
    • doc/index.html - the web interface home + page
      • + +
    • locale/cups.pot - the message catalog
      • + +
    • templates/*.tmpl - the web interface + template files
      • + +
    + +

    With the exception of the message catalogs, localization files +are placed in subdirectories under the doc and +templates using the locale name. Locale names are +either ll or ll_CC, where "ll" is the +2-letter language code and "CC" is the 2-letter country code.

    + +

    All non-image files must be encoded using the UTF-8 character +set.

    + + +

    Submitting a Translation for CUPS

    + +

    To submit a translation for inclusion in CUPS, translate all +of the button images, template files, the +index.html.in file, and the message catalog. Place +these files in the correct subdirectory in the CUPS source code +archive and run the following command to create an archive with +your files:

    + +
    +tar cvf ll_CC.tar.gz doc/ll_CC locale/ll_CC.po templates/ll_CC
+
    + +

    Replace "ll_CC" with the locale name for your translation. +Once you have created the archive, go to the CUPS Bugs +& Features page and submit a bug report, attaching the +translation to the report.

    + + +

    Button Images

    + +

    The web interface button images are used to activate functions +on the CUPS web pages. Table 1 lists the button images and the +English text labels for those buttons. Use the supplied Gimp +scripts to create button images that match the CUPS web interface +and save them in the doc/ll_CC/images subdirectory. +The Gimp button scripts can be installed using the following +command:

    + +
    +cp doc/images/button*.scm ~/.gimp-2.2/scripts
+
    + +

    If you have already started the Gimp application, choose +Refresh Scripts from the Xtns->Script-Fu +sub-menu. The button scripts will be available under a new +Btns + +

    When you have created all of the button images, edit the +doc/Makefile file and add the locale name to the +LANGUAGES variable. You can then run "make +install" in the doc subdirectory to test the +translated buttons.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 1: Web Interface Buttons
    FilenameText
    button-accept-jobs.gifAccept Jobs
    button-add-class.gifAdd Class
    button-add-printer.gifAdd Printer
    button-add-this-printer.gifAdd This Printer
    button-cancel-all-jobs.gifCancel All Jobs
    button-cancel-job.gifCancel Job
    button-change-settings.gifChange Settings
    button-clean-print-heads.gifClean Print Heads
    button-clear.gifClear
    button-continue.gifContinue
    button-delete-class.gifDelete Class
    button-delete-printer.gifDelete Printer
    button-edit-configuration-file.gifEdit Configuration File
    button-export-samba.gifExport Printers to Samba
    button-help.gifHelp
    button-hold-job.gifHold Job
    button-manage-classes.gifManage Classes
    button-manage-jobs.gifManage Jobs
    button-manage-printers.gifManage Printers
    button-manage-server.gifManage Server
    button-modify-class.gifModify Class
    button-modify-printer.gifModify Printer
    button-move-job.gifMove Job
    button-move-jobs.gifMove All Jobs
    button-print-self-test-page.gifPrint Self-Test Page
    button-print-test-page.gifPrint Test Page
    button-publish-printer.gifPublish Printer
    button-reject-jobs.gifReject Jobs
    button-release-job.gifRelease Job
    button-restart-job.gifReprint Job
    button-save-changes.gifSave Changes
    button-search.gifSearch
    button-set-allowed-users.gifSet Allowed Users
    button-set-as-default.gifSet As Default
    button-set-printer-options.gifSet Printer Options
    button-show-active.gifShow Active Jobs
    button-show-all.gifShow All Jobs
    button-show-completed.gifShow Completed Jobs
    button-show-next.gifShow Next
    button-show-previous.gifShow Previous
    button-sort-ascending.gifShow Ascending
    button-sort-descending.gifShow Descending
    button-start-class.gifStart Class
    button-start-printer.gifStart Printer
    button-stop-class.gifStop Class
    button-stop-printer.gifStop Printer
    button-unpublish-printer.gifUnpublish Printer
    button-use-default-config.gifUse Default Configuration File
    button-view-access-log.gifView Access Log
    button-view-error-log.gifView Error Log
    button-view-page-log.gifView Page Log
    button-view-printable-version.gifView Printable Version
    + + +

    The Home Page

    + +

    The index.html file is a complete HTML file that is +displayed when the user visits "http://localhost:631/". Edit the +existing doc/index.html and save it in the +doc/ll_CC subdirectory so that the makefile can +install it. Run "make install" in the doc subdirectory +to test the new home page.

    + + +

    Message Catalogs

    + +

    CUPS message catalogs are GNU gettext ".po" text files that +provide a list of localized message strings for the CUPS +software. Message catalogs are named cups_ll.po or +cups_ll_CC.po, where "ll" is the standard 2-letter +abbreviation for the language and "CC" is the standard 2-letter +abbreviation for the country.

    + +

    When translating a new message catalog, copy the +cups.pot message catalog file in the locale +subdirectory of the CUPS source code. For example, to start +translating the message catalog to Canadian French, you would +type the following commands:

    + +
    +cd locale
+cp cups.pot fr_CA.po
+
    + +

    Alternatively, you can copy the existing fr.po +message catalog and then make any necessary changes.

    + +

    Once you have make your copy of the file, edit it using your +favorite text editor or translation program to translate the text +to the desired language.

    + +

    Finally, add your locale to the LANGUAGES +variable in the locale/Makefile file and run the "make +install" command in the locale subdirectory to test +the translation.

    + + +

    Template Files

    + +

    The CUPS scheduler provides a web interface that can be used +to do many common printing and administration tasks. The built-in +web server supports localization of web pages through the use of +subdirectories for each locale, e.g. "fr" for French, "de" for +German, "fr_ca" for French in Canada, and so forth.

    + +

    Template files are HTML files with special formatting +characters in them that allow substition of variables and arrays. +The CUPS CGI programs (admin.cgi, +classes.cgi, help.cgi, +jobs.cgi, and printers.cgi) use these +template file to provide dynamic content for the web interface. +Template files are installed in the +/usr/share/cups/templates directory by default. Table +2 lists the various template files and their purpose.

    + +

    Translated versions of the template files should be saved in +the templates/ll_CC subdirectory. For example, +Canadian French template files should be saved in the +templates/fr_CA subdirectory. After you have +translated all of the templates, add the locale to the +LANGUAGES variable in the +templates/Makefile and run "make install" in the +templates subdirectory to test the translation.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 2: Web Interface Template Files
    FilenamePurpose
    add-class.tmplThis is the initial form that is shown to add a new + printer class.
    add-printer.tmplThis is the initial form that is shown to add a new + printer.
    admin.tmplThis is the main administration page.
    choose-device.tmplThis is the form that shows the list of available + devices.
    choose-make.tmplThis is the form that shows the list of available + manufacturers.
    choose-model.tmplThis is the form that shows the list of available + printer models/drivers.
    choose-serial.tmplThis is the form that allows the user to choose + a serial port and any options.
    choose-uri.tmplThis is the form that allows the user to enter + a device URI for network printers.
    class-added.tmplThis template shows the "class added" message.
    class-confirm.tmplThis is the template used to confirm the + deletion of a class.
    class-deleted.tmplThis template shows the "class deleted" message.
    class-jobs-header.tmplThis template shows the "jobs" header for jobs in a + class.
    class-modified.tmplThis template shows the "class modified" message.
    classes.tmplThis template shows one or more printer classes.
    classes-header.tmplThis template shows the "showing N of M classes" header in + the class list.
    edit-config.tmplThis is the cupsd.conf editor page.
    error.tmplThis template displays a generic error message.
    error-op.tmplThis is the "unknown operation" error page.
    header.tmplThis template is used as the standard header on all dynamic + content.
    help-header.tmplThis is the top part of the help page.
    help-printable.tmplThis is the standard page header for the printable + version of help files.
    job-cancel.tmplThis template shows "job cancelled".
    job-hold.tmplThis template shows "job held".
    job-move.tmplThis template shows the move-job form.
    job-moved.tmplThis template shows "job moved".
    job-release.tmplThis template shows "job released".
    job-restart.tmplThis template shows "job reprinted".
    jobs.tmplThis template is used to list the print jobs on a server, + class, or printer.
    jobs-header.tmplThis template shows the "showing N or M jobs" header in the + jobs list.
    maintenance.tmplThis template shows "maintenance commands sent".
    modify-class.tmplThis template is used as the first form when modifying a + class.
    modify-printer.tmplThis template is used as the first form when modifying a + printer.
    option-boolean.tmplThis template is used to select a boolean PPD option.
    option-conflict.tmplThis template shows the conflicting options.
    option-header.tmplThis template is used to start a PPD option group.
    option-pickmany.tmplThis template is used to select a multi-valued PPD option.
    option-pickone.tmplThis template is used to select a single-valued PPD option.
    option-trailer.tmplThis template is used to end a PPD option group.
    pager.tmplThis template shows the previous/next pager bar.
    printer-accept.tmplThis template shows "printer now accepting jobs".
    printer-added.tmplThis template shows "printer added".
    printer-configured.tmplThis template shows "printer configured".
    printer-confirm.tmplThis template asks the user to confirm the deletion + of a printer.
    printer-default.tmplThis template shows "default printer set".
    printer-deleted.tmplThis template shows "printer deleted".
    printer-jobs-header.tmplThis templates shows the "jobs" header for jobs on a + printer.
    printer-modified.tmplThis template shows "printer modified".
    printer-purge.tmplThis template shows "printer has been purged of all jobs".
    printer-reject.tmplThis template shows "printer now rejecting jobs".
    printer-start.tmplThis template shows "printer started".
    printer-stop.tmplThis template shows "printer stopped".
    printers.tmplThis template is used to list information on one or more + printers.
    printers-header.tmplThis template shows the "showing printer N of M" header in + the printers list.
    restart.tmplThis template shows "server restarting".
    samba-export.tmplThis template shows the export printers to Samba form.
    samba-exported.tmplThis template shows "printers exported to Samba".
    search.tmplThis template shows the search form.
    set-printer-options-header.tmplThis template shows the first part of the set printer options + form.
    set-printer-options-trailer.tmplThis template shows the last part of the set printer options + form.
    test-page.tmplThis template shows "test page printed".
    trailer.tmplThis template is used as the standard trailer on all dynamic + content.
    users.tmplThis template shows the set allowed users form.
    + +

    Inserting Attributes and Values

    + +

    Template files consist of HTML with variable substitutions for +named inside curley braces "{name}". Variable names are generally +the IPP attribute names with the hyphen ("-") replaced by the +underscore ("_") character. For example, the +job-printer-uri attribute is renamed to +job_printer_uri.

    + +

    Curley braces ("{" and "}") to indicate substitutions, and the +backslash ("\") character for quoting. To insert any of these +special characters as-is you need to use the HTML +&name; mechanism or prefix each special +character with the backslash ("\".)

    + +

    You substitute the value of a variable using +{NAME} in your template file. If the variable is +undefined then the {NAME} string is output +as-is.

    + +

    To substitute an empty string if the variable is undefined, +use {?NAME} instead.

    + +

    Array Substitutions

    + +

    The number of array elements can be inserted using +{#NAME}. If the array is undefined then 0 is output. +The current array element (starting at 1) is inserted with +{#}.

    + +

    Arrays are handled using {[NAME] at the beginning +of a section and } at the end. The information +between the closing bracket ("]") and closing brace ("}") is +repeated for as many elements as are in the named array. For +example, the following template will display a list of each job +in the job_id array:

    + +
    +<TABLE>
+<TR>
+	<TH>Job ID</TH>
+	<TH>Destination</TH>
+	<TH>Title</TH>
+</TR>
+
+{[job_id]
+<TR>
+	<TD>{?job_id}</TD>
+	<TD>{?job_printer_name}</TD>
+	<TD>{?job_name}</TD>
+</TR>
+}
+</TABLE>
+
    + +

    Arrays can be nested, however all elements within the curley +braces ("{" and "}") are indexed using the innermost array.

    + +

    Conditional Tests

    + +

    Templates can also test variables against specific values and +conditionally include text in the template. The format is:

    + +
    +{variable?true:false}
+{variable=value?true:false}
+{variable!value?true:false}
+{variable<value?true:false}
+{variable>value?true:false}
+
    + +

    where true is the text that is included if the +condition is true and false is the text that is +included if the condition is false. A value of # is +replaced with the current element number (starting at 1.) The +character after the variable name specifies the condition to +test. Table 3 shows the available test conditions.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 3: Template Substitution Conditions
    CharCondition
    ?True if variable exists.
    =True if variable is equal to value.
    !True if variable is not equal to value.
    <True if variable is less than value.
    >True if variable is greater than value.
    + +

    CGI Programs

    + +

    CUPS uses five CGI programs to manage the dynamic web +interfaces:

    + +
      + +
    • admin.cgi
      • +
    • classes.cgi
      • +
    • help.cgi
      • +
    • jobs.cgi
      • +
    • printers.cgi
      • + +
    + +

    Each CGI program accepts standard form variables such as +OP for the operation to perform, +PRINTER_NAME for the printer or class name to +operate on, QUERY for any search words, +FIRST for the first class, job, or printer to +display, and ORDER to control the order that +classes, jobs, or printers are displayed.

    + +

    In addition, the classes.cgi, +jobs.cgi, and printers.cgi programs +support a WHICH_JOBS variable to control which jobs +are displayed. Table 4 lists the supported values.

    + +
    + + + + + + + + + + + + + + + + + + + +
    Table 4: WHICH_JOBS Values
    OP ValueDescription
    allShow all jobs
    completedShow completed jobs
    not-completedShow active jobs
    + +

    admin.cgi

    + +

    The admin.cgi program handles all of the printer +and class administration functions and is run for all direct +accesses to the /admin resource. For most operations +it uses the PRINTER_NAME and OP form +variables to specify the action requested. Table 5 shows the +supported OP values.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 5: admin.cgi OP Values
    OP ValueDescription
    accept-jobsAccepts jobs on the named destination.
    add-classAdds a new printer class.
    add-printerAdds a new printer.
    config-serverConfigures the server.
    delete-classDeletes a printer class. The form variable CONFIRM + may be set to any value to bypass the confirmation page.
    delete-printerDeletes a printer. The form variable CONFIRM + may be set to any value to bypass the confirmation page.
    export-sambaExports printers to Samba.
    modify-classModifies a printer class.
    modify-printerModifies a printer.
    purge-jobsPurges all jobs on the named destination.
    redirectRedirects the web browser to the location referenced by + the URL form variable.
    reject-jobsRejects new jobs on the named destination.
    set-allowed-usersSets the allowed users for a destination.
    set-as-defaultSets the default destination.
    set-printer-optionsSets the default options for a printer.
    set-sharingSets the printer-is-shared attribute for a destination.
    start-classStarts the named class.
    start-printerStarts the named printer.
    stop-classStops the named class.
    stop-printerStops the named printer.
    + +

    classes.cgi

    + +

    The classes.cgi program is responsible for +listing class information, including jobs destined for that +class. It is for all direct accesses to the /classes +resource and supports the optional form variables OP +and WHICH_JOBS. If no form variables are supplied +then the CGI lists all or a specific class and the active jobs on +each class. Table 6 shows the supported OP +values.

    + +
    + + + + + + + + + + + + + + + + + +
    Table 6: classes.cgi OP Values
    OP ValueDescription
    move-jobsMoves the jobs on this class to another destination.
    print-test-pagePrints the standard PostScript test page.
    + + +

    help.cgi

    + +

    The help.cgi program handles all of the on-line +help functions and is run for all direct accesses to the +/help resource.

    + + +

    jobs.cgi

    + +

    The jobs.cgi program handles all of the job +functions and is run for all direct accesses to the +/jobs resource. For most operations it uses the +JOB_ID, OP, and WHICH_JOBS +form variables to specify the action requested. Table 7 shows the +supported OP values.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 7: jobs.cgi OP Values
    OP ValueDescription
    cancel-jobCancels a job.
    hold-jobHolds a job indefinitely.
    move-jobMoves a job to another destination.
    release-jobReleases a job for printing.
    restart-jobRestarts/reprints a stopped, cancelled, completed, or aborted + print job.
    + + +

    printers.cgi

    + +

    The printers.cgi program is responsible for +listing printer information, including jobs destined for that +printer. It is for all direct accesses to the +/printers resource and supports the optional form +variables OP and WHICH_JOBS. If no form +variables are supplied then the CGI lists all printers or a +specific printer and the active jobs on that printer. Table 8 +shows the supported OP values.

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 8: printers.cgi OP Values
    OP ValueDescription
    clean-print-headsClean the print heads.
    move-jobsMove all jobs to a different destination.
    print-self-test-pagePrint a printer self-test page.
    print-test-pagePrint a PostScript test page.
    + + + diff --git a/doc/idd.html b/doc/idd.html deleted file mode 100644 index dc52454ee0..0000000000 --- a/doc/idd.html +++ /dev/null @@ -1,1083 +0,0 @@ - - - -CUPS Interface Design Description - - - - - - - -

    -

    CUPS Interface Design Description


    -CUPS-IDD-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

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

    1 Scope

    -

    1.1 Identification

    -

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

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 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
      • -
    -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Internal Interfaces

    -

    3.1 Character Set Files

    -

    The character set files define a mapping between 8-bit characters and - the Unicode character set, or between Unicode and printer fonts. They - are named using the IETF charset names defined in RFCnnnn. These files - are ASCII text, the content of which is described below. Comments can - be included by using the # character in the first column of a - line.

    -

    3.1.1 8-Bit Character Set Files

    -

    8-bit character set files start with a line reading:

    -
      -
      -charset 8bit
-
      -
    -

    Following this are lines that define the font information:

    -
      -
      -first last direction width normal bold italic bold-italic
-
      -
    -

    First and last are the first and last glyphs in - the font mapping that correspond to that font; a maximum of 256 - characters can be mapped within each group, with a maximum of 256 - mappings (this is a PostScript limitation.) The glyph values are - hexadecimal.

    -

    Direction is the string "ltor", "rtol", or "rtola" - indicating left-to-right, right-to-left, or right-to-left Arabic text.

    -

    Width is the string "single" or "double"; double means - that the glyphs are twice as wide as ASCII characters in the Courier - typeface.

    -

    Normal, bold, italic, and bold-italic are the - typefaces to use for each presentation. If characters are only - available in a single style then only one typeface should be listed - (e.g. "Symbol".) Each font that is listed will be used (and downloaded - if needed) when printing.

    -

    The remaining lines define a character to Unicode glyph mapping for - the character set. The character and glyph values are hexadecimal:

    -
      -
      -xx yyyy
-
      -
    -

    3.1.2 Unicode Character Set Files

    -

    Unicode character set files start with a line reading:

    -
      -
      -charset encoding
-
      -
    -

    Encoding is the encoding to use for the text; currently - only the string "utf8" is supported.

    -

    Following this are lines defining the font information:

    -
      -
      -first last direction width normal bold italic bold-italic
-
      -
    -

    First and last are the first and last glyphs in - the font mapping that correspond to that font; a maximum of 256 - characters can be mapped within each group, with a maximum of 256 - mappings (this is a PostScript limitation.) The glyph values are - hexadecimal.

    -

    Direction is the string "ltor", "rtol", or "rtola" - indicating left-to-right, right-to-left, or right-to-left Arabic text.

    -

    Width is the string "single" or "double"; double means - that the glyphs are twice as wide as ASCII characters in the Courier - typeface.

    -

    Normal, bold, italic, and bold-italic are the - typefaces to use for each presentation. If characters are only - available in a single style then only one typeface should be listed - (e.g. "Symbol".) Each font that is listed will be used (and downloaded - if needed) when printing.

    -

    3.2 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:

    -
      -
    • 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-10
      • -
    • iso-8859-13
      • -
    • iso-8859-14
      • -
    • iso-8859-15
      • -
    • us-ascii
      • -
    • utf-8
      • -
    • windows-874
      • -
    • windows-1250
      • -
    • windows-1251
      • -
    • windows-1252
      • -
    • windows-1253
      • -
    • windows-1254
      • -
    • windows-1255
      • -
    • windows-1256
      • -
    • windows-1257
      • -
    • windows-1258
      • -
    • koi8-r
      • -
    • koi8-u
      • -
    -

    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.

    -

    3.3 MIME Files

    -

    CUPS uses two MIME files in its standard configuration.

    -

    3.3.1 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 ")" |
-	 "contains(" offset "," length "," 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.

    -

    3.3.2 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:

    -
      -
      -super/type SP super/type2 SP cost SP program
-
      -
    -

    3.4 Option Files

    -

    CUPS maintains user-defined printer and option files for each printer - and user on the system. The printers and options defined in the system - option file (/etc/cups/lpoptions) are loaded first, - followed by the user option file ($HOME/.lpoptions). - Options in the user file replace those defined in the system file for - the same destination. Each line in the files can be one of the - following:

    -
      -
      -Dest name option=value option=value ... option=value
-Dest name/instance option=value option=value ... option=value
-Default name option=value option=value ... option=value
-Default name/instance option=value option=value ... option=value
-
      -
    -

    The line beginning with "Default" indicates the default destination - for print jobs; a default line in the user option file overrides the - default defined in the system option file.

    -

    Name is the name of a printer known to the local server.

    -

    Instance can be any string of letters, numbers, and the - underscore up to 127 characters in length.

    -

    The remainder of the line contains a list of space-separated options - and their values.

    -

    3.5 PostScript Printer Description Files

    -

    PostScript Printer Description ("PPD") files describe the - capabilities of each printer and are used by CUPS to support - printer-specific features and intelligent filtering.

    -

    3.5.1 PPD Specification

    -

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

    -

    3.5.2 CUPS Extensions to PPD Files

    -

    CUPS adds several new attributes that are described below.

    -

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

    -

    3.5.2.2 cupsManualCopies

    -

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

    -

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

    -

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

    -

    3.5.2.5 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", "1.1", or "1.2".

    -

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

    3.6.1 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: -

    - - - - - - - - - - - - - - -
    DirectiveDescription
    <Class name> -
    </Class>    		Surrounds a class definition.
    <DefaultClass name> -
    </Class>    		Surrounds a class definition for the default - destination.
    AcceptingSpecifies whether the class is accepting new - jobs. May be the names "Yes" or "No".
    AllowUsersSpecifies a list of users that are allowed to - access the class.
    BannerStartSpecifies the banner that is printed before - other files in a job.
    BannerEndSpecifies the banner that is printed after - other files in a job.
    DenyUsersSpecifies a list of users that are not allowed - to access the class.
    InfoA textual description of the class.
    LocationA textual location of the class.
    PrinterSpecifies a printer that is a member of the - class.
    StateSpecifies the initial state of the class; can be - "Idle" or "Stopped".
    StateMessageSpecifies a textual message for the current - class state.
    -
    -

    -

    3.6.2 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: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    DirectiveDefaultDescription
    AccessLogaccess_logSpecifies the location of - the access log file. The special name "syslog" can be used to send - access log information to the system log.
    Allow-Allows connections from the specified - host, network, or domain.
    AuthClass-Specifies what level of - authentication is required; may be "User", "System", or "Group".
    AuthTypeNoneSpecifies the type of - authentication to perform; may be "None", "Basic", or "Digest".
    BrowseAddress255.255.255.255Specifies a - broadcast address to send CUPS browsing packets to.
    BrowseAllow-Specifies hosts or addresses from - which browsing information should be used.
    BrowseDeny-Specifies hosts or addresses from - which browsing information should not be used.
    BrowseInterval30Specifies the number of - seconds between browsing updates. A browse interval of 0 seconds - disables outgoing packets.
    BrowseOrderAllow,DenySpecifies the order of - BrowseAllow and BrowseDeny directive processing; can be "Deny,Allow" to - implicitly deny hosts unless they are allowed by a BrowseAllow line, or - "Allow,Deny" to implicitly allow hosts unless they are denied by a - BrowseDeny line.
    BrowsePoll-Specifies a server to poll for - available printers and classes.
    BrowsePort631Specifies the UDP port number to - use for browse packets.
    BrowseRelay-Specifies a source and destination - address for relaying browser information from one subnet to another.
    BrowseShortNamesyesSpecifies whether or not to - provide short names (without the "@server" part) for remote printers.
    BrowseTimeout300Specifies the number of - seconds to wait until remote destinations are removed from the local - destination list.
    BrowsingOnSpecifies whether or not printer and - class browsing is enabled; can be "On" or "Off".
    DataDir/usr/share/cupsSpecifies the directory - where CUPS data files are stored.
    DefaultCharsetiso-8859-1Specifies the default - character set.
    DefaultLanguagecurrent localeSpecifies the - default language.
    Deny-Refuses connections from the specified - host, network, or domain.
    DocumentRoot/usr/share/doc/cupsSpecifies the - document data root directory.
    ErrorLogerror_logSpecifies the error log file - location. The special name "syslog" can be used to send error log - information to the system log.
    Grouproot, sys, systemSpecifies the group name - or ID that is used when running external programs.
    HostNameLookupsOffSpecifies 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.
    ImplicitClassesOnSpecifies 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".
    KeepAliveOnSpecifies whether or not to use the - HTTP Keep-Alive feature; may be "On" or "Off".
    KeepAliveTimeout30Specifies the amount of time - to keep the HTTP connection alive before closing it.
    <Location path> -
    </Location>    		-Specifies a location to restrict - access to.
    LogLevelinfoControls 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.
    MaxClients100Specifies the maximum number of - simultaneous active clients. This value is internally limited to 1/3 of - the total number of available file descriptors.
    MaxLogSize0Specifies 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.
    MaxRequestSize0Specifies the maximum size of - HTTP requests in bytes. If set to 0 then there is no maximum.
    OrderAllow,DenySpecifies 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.
    PageLogpage_logSpecifies the location of the - page log file. The special name "syslog" can be used to send page log - information to the system log.
    Port631Specifies a port number to listen to - for HTTP connections.
    Printcap/etc/printcapSpecifies the location of - a Berkeley printcap file to update with a list of current printers and - classes. If no filename is supplied then this automatic generation is - disabled.
    RequestRoot/var/spool/cupsSpecifies the - location of request files.
    RIPCache8mSpecifies the size of the memory - cache in bytes that is used by RIP filters.
    ServerAdminroot@ServerNameSpecifies the person - to contact with problems.
    ServerNamehostnameSpecifies 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/etc/cupsSpecifies the root - directory for server configuration files.
    SystemGrouproot, sys, systemSpecifies the - group name used for System class authentication.
    TempDir/var/tmpSpecifies the temporary - directory to use.
    Timeout300The timeout in seconds before client - connections are closed in the middle of a request.
    UserlpSpecifies the user that is used when - running external programs.
    -
    -

    -

    3.6.3 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: -

    - - - - - - - - - - - - - - -
    DirectiveDescription
    AcceptingSpecifies 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.
    AllowUsersSpecifies a list of users that are allowed to - access the printer.
    BannerStartSpecifies the banner that is printed before - other files in a job.
    BannerEndSpecifies the banner that is printed after - other files in a job.
    DenyUsersSpecifies a list of users that are not allowed - to access the printer.
    DeviceURISpecifies the device-uri attribute for the - printer.
    InfoA textual description of the printer.
    LocationA textual location of the printer.
    <Printer name> -
    </Printer>    		Surrounds the printer definition.
    StateSpecifies the initial state of the printer; can be - "Idle" or "Stopped".
    StateMessageSpecifies a textual message for the current - printer state.
    -
    -

    -

    4 External Interfaces

    -

    4.1 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".

    -

    The AppSocket protocol is used by the Hewlett Packard JetDirect - network interfaces and print servers, as well as many other vendors' - products. See the CUPS Software Administrators Manual for a list of - supported products.

    -

    4.2 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 SP "location" SP "info" SP "make-and-model" NL
-
      -
    -

    State, uri, location, info, and make-and-model, - correspond to the IPP printer-state, -printer-uri-supported, printer-location, -printer-info, and printer-make-and-model attributes.

    -

    Type is a hexadecimal number string representing - capability/type bits: -

    - - - - - - - - - - - - - - - - - - -
    BitDescription
    00 = printer -
    1 = class
    10 = local -
    1 = remote -
    (always 1)
    21 = can print B
    31 = can print color
    41 = can duplex
    51 = can staple
    61 = can do fast copies
    71 = can do fast collating
    81 = can punch holes
    91 = can cover
    101 = can bind
    111 = can sort
    121 = can print up to 9x14 inches
    131 = can print up to 18x24 inches
    141 = can print up to 36x48 inches
    151 = can print variable sizes
    -
    -

    -

    4.3 CUPS Form File

    -

    CUPS Form files are XML files used by the CUPS formtops - filter to produce dynamic banner pages and support preprinted forms.

    -

    The MIME type for CUPS Form files is application/vnd.cups-form -.

    -

    4.3.1 CUPS Form DTD

    -

    The following DTD describes the available elements and attributes in - a CUPS Form file: -

    - - -
    -
    -<!ENTITY % Angle "CDATA" -- angle in degrees -->
-
-<!ENTITY % Color "CDATA" -- a color using sRGB: #RRGGBB as Hex values -->
-
-<!ENTITY % Length "CDATA" -- nn for pixels or nn% for percentage length -->
-
-<!ENTITY % Lengths "CDATA" -- comma-separated Length values -->
-
-<!ENTITY % Text "CDATA">
-
-<!ENTITY % heading "H1|H2|H3|H4|H5|H6">
-
-<!ENTITY % preformatted "PRE">
-
-<!ENTITY % i18n
- "lang        %LanguageCode; #IMPLIED  -- language code --
-  dir         (ltr|rtl)      #IMPLIED  -- direction for weak/neutral text --"
-  >
-
-<!ENTITY % attrs "%i18n;">
-
-<!ENTITY % fontstyle
- "B | FONT | I | TT">
-
-<!ENTITY % graphics
- "BOX | RECT | LINE | POLY | ARC | PIE | TEXT">
-
-<!ENTITY % insert
- "IMG | VAR">
-
-<!-- %inline; covers inline or "text-level" elements -->
-<!ENTITY % inline "#PCDATA | %fontstyle; | %graphics; | %insert;">
-
-<!ELEMENT (%fontstyle;) - - (%inline;)*>
-<!ATTLIST (%fontstyle;)
-  %attrs;                              -- %i18n --
-  >
-
-<!ELEMENT BR - O EMPTY                 -- forced line break -->
-<!ATTLIST BR
-  %attrs;                              -- %i18n --
-  >
-
-<!ENTITY % block
-     "P | %heading; | %preformatted;">
-
-<!ENTITY % flow "%block; | %inline;">
-
-<!ELEMENT PAGE O O (%flow;)+           -- document body -->
-<!ATTLIST PAGE
-  %attrs;                              -- %i18n --
-  align       (left|center|right) #IMPLIED -- horizontal alignment --
-  valign      (top|middle|center|bottom) #IMPLIED -- vertical alignment --
-  >
-
-<!ELEMENT P - O (%inline;)*            -- paragraph -->
-<!ATTLIST P
-  %attrs;                              -- %i18n --
-  align       (left|center|right) #IMPLIED -- horizontal alignment --
-  >
-
-<!ELEMENT (%heading;)  - - (%inline;)* -- heading -->
-<!ATTLIST (%heading;)
-  %attrs;                              -- %i18n --
-  align       (left|center|right) #IMPLIED -- horizontal alignment --
-  >
-
-<!ELEMENT PRE - - (%inline;)*          -- preformatted text -->
-<!ATTLIST PRE
-  %attrs;                              -- %i18n --
-  align       (left|center|right) #IMPLIED -- horizontal alignment --
-  >
-
-<!ELEMENT BOX - O EMPTY                -- unfilled box -->
-<!ATTLIST BOX
-  color       %Color;        #IMPLIED  -- override color --
-  height      %Length;       #REQUIRED -- height of box --
-  thickness   %Length;       #IMPLIED  -- override line thickness --
-  width       %Length;       #REQUIRED -- width of box --
-  x           %Length;       #REQUIRED -- horizontal position --
-  y           %Length;       #REQUIRED -- vertical position --
-  >
-
-<!ELEMENT RECT - O EMPTY               -- filled box -->
-<!ATTLIST RECT
-  color       %Color;        #IMPLIED  -- override color --
-  height      %Length;       #REQUIRED -- height of box --
-  width       %Length;       #REQUIRED -- width of box --
-  x           %Length;       #REQUIRED -- horizontal position --
-  y           %Length;       #REQUIRED -- vertical position --
-  >
-
-<!ELEMENT LINE - O EMPTY               -- polyline -->
-<!ATTLIST LINE
-  color       %Color;        #IMPLIED  -- override color --
-  thickness   %Length;       #IMPLIED  -- override line thickness --
-  x           %Lengths;      #REQUIRED -- horizontal positions --
-  y           %Lengths;      #REQUIRED -- vertical positions --
-  >
-
-<!ELEMENT POLY - O EMPTY               -- polygon (filled) -->
-<!ATTLIST POLY
-  color       %Color;        #IMPLIED  -- override color --
-  x           %Lengths;      #REQUIRED -- horizontal positions --
-  y           %Lengths;      #REQUIRED -- vertical positions --
-  >
-
-<!ELEMENT ARC - O EMPTY                -- unfilled arc -->
-<!ATTLIST ARC
-  color       %Color;        #IMPLIED  -- override color --
-  end         %Angle;        #IMPLIED  -- override end angle --
-  height      %Length;       #REQUIRED -- height of arc --
-  start       %Angle;        #IMPLIED  -- override start angle --
-  thickness   %Length;       #IMPLIED  -- override line thickness --
-  width       %Length;       #REQUIRED -- width of arc --
-  x           %Length;       #REQUIRED -- horizontal position --
-  y           %Length;       #REQUIRED -- vertical position --
-  >
-
-<!ELEMENT PIE - O EMPTY                -- filled arc -->
-<!ATTLIST PIE
-  color       %Color;        #IMPLIED  -- override color --
-  end         %Angle;        #IMPLIED  -- override end angle --
-  height      %Length;       #REQUIRED -- height of arc --
-  start       %Angle;        #IMPLIED  -- override start angle --
-  width       %Length;       #REQUIRED -- width of arc --
-  x           %Length;       #REQUIRED -- horizontal position --
-  y           %Length;       #REQUIRED -- vertical position --
-  >
-
-<!ELEMENT TEXT - - (%flow;)*           -- text box -->
-<!ATTLIST RECT
-  align       (left|center|right) #IMPLIED -- horizontal alignment --
-  height      %Length;       #REQUIRED -- height of box --
-  valign      (top|middle|center|bottom) #IMPLIED -- vertical alignment --
-  width       %Length;       #REQUIRED -- width of box --
-  x           %Length;       #REQUIRED -- horizontal position --
-  y           %Length;       #REQUIRED -- vertical position --
-  >
-
-
-<!ELEMENT IMG - O EMPTY                -- Embedded image -->
-<!ATTLIST IMG
-  %attrs;                              -- %coreattrs, %i18n, %events --
-  src         %URI;          #REQUIRED -- URI of image to embed --
-  height      %Length;       #IMPLIED  -- override height --
-  width       %Length;       #IMPLIED  -- override width --
-  >
-
-<!ELEMENT HEAD O O (DEFVAR)*           -- document head -->
-<!ATTLIST HEAD
-  %i18n;                               -- lang, dir --
-  >
-
-<!ELEMENT DEFVAR - O EMPTY             -- variable definition -->
-<!ATTLIST DEFVAR
-  name        CDATA          #REQUIRED -- name
-  value       CDATA          #REQUIRED -- value
-  >
-
-
-<!ENTITY % html.content "HEAD, PAGE">
-
-<!ELEMENT CUPSFORM - - (HEAD) (PAGE)+  -- document root element -->
-<!ATTLIST CUPSFORM
-  %i18n;                               -- lang, dir --
-  >
-
    -
    -
    -

    -

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

    -

    4.5 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 Image 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. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    BytesDescriptionValues
    0-63MediaClassNul-terminated ASCII string
    64-127MediaColorNul-terminated ASCII string
    128-191MediaTypeNul-terminated ASCII string
    192-255OutputTypeNul-terminated ASCII string
    256-259AdvanceDistance0 to 232 - 1 - points
    260-263AdvanceMedia0 = Never advance roll -
    1 = Advance roll after file -
    2 = Advance roll after job -
    3 = Advance roll after set -
    4 = Advance roll after page
    264-267Collate0 = do not collate copies -
    1 = collate copies
    268-271CutMedia0 = Never cut media -
    1 = Cut roll after file -
    2 = Cut roll after job -
    3 = Cut roll after set -
    4 = Cut roll after page
    272-275Duplex0 = Print single-sided -
    1 = Print double-sided
    276-283HWResolutionHorizontal and vertical - resolution in dots-per-inch.
    284-299ImagingBoundingBoxFour integers giving - the left, bottom, right, and top positions of the page bounding box in - points
    300-303InsertSheet0 = Do not insert separator - sheets -
    1 = Insert separator sheets
    304-307Jog0 = Do no jog pages -
    1 = Jog pages after file -
    2 = Jog pages after job -
    3 = Jog pages after set
    308-311LeadingEdge0 = Top edge is first -
    1 = Right edge is first -
    2 = Bottom edge is first -
    3 = Left edge is first
    312-319MarginsLeft and bottom origin of image - in points
    320-323ManualFeed0 = Do not manually feed - media -
    1 = Manually feed media
    324-327MediaPositionInput slot position from 0 - to N
    328-331MediaWeightMedia weight in grams per - meter squared
    332-335MirrorPrint0 = Do not mirror prints -
    1 = Mirror prints
    336-339NegativePrint0 = Do not invert prints -
    1 = Invert prints
    340-343NumCopies1 to 232 - 1
    344-347Orientation0 = Do not rotate page -
    1 = Rotate page counter-clockwise -
    2 = Turn page upside down -
    3 = Rotate page clockwise
    348-351OutputFaceUp0 = Output face down -
    1 = Output face up
    352-359PageSizeWidth and length in points
    360-363Separations0 = Print composite image -
    1 = Print color separations
    364-367TraySwitch0 = Do not change trays if - selected tray is empty -
    1 = Change trays if selected tray is empty
    368-371Tumble0 = Do not rotate even pages when - duplexing -
    1 = Rotate even pages when duplexing
    372-375cupsWidthWidth of page image in pixels
    376-379cupsHeightHeight of page image in - pixels
    380-383cupsMediaTypeDriver-specific 0 to 2 -32 - 1
    384-387cupsBitsPerColor1, 2, 4, 8 bits
    388-391cupsBitsPerPixel1 to 32 bits
    392-395cupsBytesPerLine1 to 232 - 1 - bytes
    396-399cupsColorOrder0 = chunky pixels (CMYK - CMYK CMYK) -
    1 = banded pixels (CCC MMM YYY KKK) -
    2 = planar pixels (CCC... MMM... YYY... KKK...)
    400-403cupsColorSpace0 = white -
    1 = RGB -
    2 = RGBA -
    3 = black -
    4 = CMY -
    5 = YMC -
    6 = CMYK -
    7 = YMCK -
    8 = KCMY -
    9 = KCMYcm
    404-407cupsCompressionDriver-specific 0 to 2 -32 - 1
    408-411cupsRowCountDriver-specific 0 to 2 -32 - 1
    412-415cupsRowFeedDriver-specific 0 to 2 -32 - 1
    416-419cupsRowStepDriver-specific 0 to 2 -32 - 1
    -
    -

    -

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

    -

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

    -

    4.7 Internet Printing Protocol

    -

    The Internet Printing Protocol and the CUPS extensions to it are - described in the CUPS Implementation of IPP document.

    -

    4.8 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".

    -

    4.9 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". Support for this protocol is - provided via the SAMBA smbspool(1) program provided with - SAMBA 2.0.6 and higher.

    -

    5 Directories

    -
    -
    /etc/cups
    -
    The scheduler configuration and MIME files reside here.
    -
    /etc/cups/certs
    -
    The authentication certificates reside here.
    -
    /etc/cups/interfaces
    -
    System V interface scripts reside here.
    -
    /etc/cups/ppd
    -
    This directory contains PPD files for each printer.
    -
    /usr/bin
    -
    The cancel, lp, lpq, -lpr, lprm, and lpstat commands reside - here.
    -
    /usr/lib, /usr/lib32
    -
    The shared libraries (DSOs) reside here.
    -
    /usr/lib/cups/backend
    -
    The backend filters reside here.
    -
    /usr/lib/cups/cgi-bin
    -
    The CGI programs reside here.
    -
    /usr/lib/cups/daemon
    -
    The polling and LPD daemons reside here.
    -
    /usr/lib/cups/filter
    -
    The file filters 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/charsets
    -
    The character set files reside here.
    -
    /usr/share/cups/data
    -
    The 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.
    -
    /usr/share/doc/cups
    -
    The scheduler documentation files reside here.
    -
    /var/log/cups
    -
    The access_log, error_log, and -page_log files reside here.
    -
    /var/spool/cups
    -
    This directory contains print job files.
    -
    -

    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
    -
    - - diff --git a/doc/idd.pdf b/doc/idd.pdf deleted file mode 100644 index ad1fc130be..0000000000 Binary files a/doc/idd.pdf and /dev/null differ diff --git a/doc/images/accept-jobs.gif b/doc/images/button-accept-jobs.gif similarity index 100% rename from doc/images/accept-jobs.gif rename to doc/images/button-accept-jobs.gif diff --git a/doc/images/add-class.gif b/doc/images/button-add-class.gif similarity index 100% rename from doc/images/add-class.gif rename to doc/images/button-add-class.gif diff --git a/doc/images/add-printer.gif b/doc/images/button-add-printer.gif similarity index 100% rename from doc/images/add-printer.gif rename to doc/images/button-add-printer.gif diff --git a/doc/images/add-this-printer.gif b/doc/images/button-add-this-printer.gif similarity index 100% rename from doc/images/add-this-printer.gif rename to doc/images/button-add-this-printer.gif diff --git a/doc/images/cancel-all-jobs.gif b/doc/images/button-cancel-all-jobs.gif similarity index 100% rename from doc/images/cancel-all-jobs.gif rename to doc/images/button-cancel-all-jobs.gif diff --git a/doc/images/cancel-job.gif b/doc/images/button-cancel-job.gif similarity index 100% rename from doc/images/cancel-job.gif rename to doc/images/button-cancel-job.gif diff --git a/doc/images/change-settings.gif b/doc/images/button-change-settings.gif similarity index 100% rename from doc/images/change-settings.gif rename to doc/images/button-change-settings.gif diff --git a/doc/images/clean-print-heads.gif b/doc/images/button-clean-print-heads.gif similarity index 100% rename from doc/images/clean-print-heads.gif rename to doc/images/button-clean-print-heads.gif diff --git a/doc/images/button-clear.gif b/doc/images/button-clear.gif new file mode 100644 index 0000000000..dcb9c44f1c Binary files /dev/null and b/doc/images/button-clear.gif differ diff --git a/doc/images/continue.gif b/doc/images/button-continue.gif similarity index 100% rename from doc/images/continue.gif rename to doc/images/button-continue.gif diff --git a/doc/images/delete-class.gif b/doc/images/button-delete-class.gif similarity index 100% rename from doc/images/delete-class.gif rename to doc/images/button-delete-class.gif diff --git a/doc/images/delete-printer.gif b/doc/images/button-delete-printer.gif similarity index 100% rename from doc/images/delete-printer.gif rename to doc/images/button-delete-printer.gif diff --git a/doc/images/edit-configuration-file.gif b/doc/images/button-edit-configuration-file.gif similarity index 100% rename from doc/images/edit-configuration-file.gif rename to doc/images/button-edit-configuration-file.gif diff --git a/doc/images/export-samba.gif b/doc/images/button-export-samba.gif similarity index 100% rename from doc/images/export-samba.gif rename to doc/images/button-export-samba.gif diff --git a/doc/images/help.gif b/doc/images/button-help.gif similarity index 100% rename from doc/images/help.gif rename to doc/images/button-help.gif diff --git a/doc/images/hold-job.gif b/doc/images/button-hold-job.gif similarity index 100% rename from doc/images/hold-job.gif rename to doc/images/button-hold-job.gif diff --git a/doc/images/manage-classes.gif b/doc/images/button-manage-classes.gif similarity index 100% rename from doc/images/manage-classes.gif rename to doc/images/button-manage-classes.gif diff --git a/doc/images/manage-jobs.gif b/doc/images/button-manage-jobs.gif similarity index 100% rename from doc/images/manage-jobs.gif rename to doc/images/button-manage-jobs.gif diff --git a/doc/images/manage-printers.gif b/doc/images/button-manage-printers.gif similarity index 100% rename from doc/images/manage-printers.gif rename to doc/images/button-manage-printers.gif diff --git a/doc/images/manage-server.gif b/doc/images/button-manage-server.gif similarity index 100% rename from doc/images/manage-server.gif rename to doc/images/button-manage-server.gif diff --git a/doc/images/modify-class.gif b/doc/images/button-modify-class.gif similarity index 100% rename from doc/images/modify-class.gif rename to doc/images/button-modify-class.gif diff --git a/doc/images/modify-printer.gif b/doc/images/button-modify-printer.gif similarity index 100% rename from doc/images/modify-printer.gif rename to doc/images/button-modify-printer.gif diff --git a/doc/images/move-job.gif b/doc/images/button-move-job.gif similarity index 100% rename from doc/images/move-job.gif rename to doc/images/button-move-job.gif diff --git a/doc/images/move-jobs.gif b/doc/images/button-move-jobs.gif similarity index 100% rename from doc/images/move-jobs.gif rename to doc/images/button-move-jobs.gif diff --git a/doc/images/print-self-test-page.gif b/doc/images/button-print-self-test-page.gif similarity index 100% rename from doc/images/print-self-test-page.gif rename to doc/images/button-print-self-test-page.gif diff --git a/doc/images/print-test-page.gif b/doc/images/button-print-test-page.gif similarity index 100% rename from doc/images/print-test-page.gif rename to doc/images/button-print-test-page.gif diff --git a/doc/images/publish-printer.gif b/doc/images/button-publish-printer.gif similarity index 100% rename from doc/images/publish-printer.gif rename to doc/images/button-publish-printer.gif diff --git a/doc/images/reject-jobs.gif b/doc/images/button-reject-jobs.gif similarity index 100% rename from doc/images/reject-jobs.gif rename to doc/images/button-reject-jobs.gif diff --git a/doc/images/release-job.gif b/doc/images/button-release-job.gif similarity index 100% rename from doc/images/release-job.gif rename to doc/images/button-release-job.gif diff --git a/doc/images/restart-job.gif b/doc/images/button-restart-job.gif similarity index 100% rename from doc/images/restart-job.gif rename to doc/images/button-restart-job.gif diff --git a/doc/images/save-changes.gif b/doc/images/button-save-changes.gif similarity index 100% rename from doc/images/save-changes.gif rename to doc/images/button-save-changes.gif diff --git a/doc/images/search.gif b/doc/images/button-search.gif similarity index 100% rename from doc/images/search.gif rename to doc/images/button-search.gif diff --git a/doc/images/set-allowed-users.gif b/doc/images/button-set-allowed-users.gif similarity index 100% rename from doc/images/set-allowed-users.gif rename to doc/images/button-set-allowed-users.gif diff --git a/doc/images/set-as-default.gif b/doc/images/button-set-as-default.gif similarity index 100% rename from doc/images/set-as-default.gif rename to doc/images/button-set-as-default.gif diff --git a/doc/images/set-printer-options.gif b/doc/images/button-set-printer-options.gif similarity index 100% rename from doc/images/set-printer-options.gif rename to doc/images/button-set-printer-options.gif diff --git a/doc/images/show-active.gif b/doc/images/button-show-active.gif similarity index 100% rename from doc/images/show-active.gif rename to doc/images/button-show-active.gif diff --git a/doc/images/show-all.gif b/doc/images/button-show-all.gif similarity index 100% rename from doc/images/show-all.gif rename to doc/images/button-show-all.gif diff --git a/doc/images/show-completed.gif b/doc/images/button-show-completed.gif similarity index 100% rename from doc/images/show-completed.gif rename to doc/images/button-show-completed.gif diff --git a/doc/images/show-next.gif b/doc/images/button-show-next.gif similarity index 100% rename from doc/images/show-next.gif rename to doc/images/button-show-next.gif diff --git a/doc/images/show-previous.gif b/doc/images/button-show-previous.gif similarity index 100% rename from doc/images/show-previous.gif rename to doc/images/button-show-previous.gif diff --git a/doc/images/sort-ascending.gif b/doc/images/button-sort-ascending.gif similarity index 100% rename from doc/images/sort-ascending.gif rename to doc/images/button-sort-ascending.gif diff --git a/doc/images/sort-descending.gif b/doc/images/button-sort-descending.gif similarity index 100% rename from doc/images/sort-descending.gif rename to doc/images/button-sort-descending.gif diff --git a/doc/images/start-class.gif b/doc/images/button-start-class.gif similarity index 100% rename from doc/images/start-class.gif rename to doc/images/button-start-class.gif diff --git a/doc/images/start-printer.gif b/doc/images/button-start-printer.gif similarity index 100% rename from doc/images/start-printer.gif rename to doc/images/button-start-printer.gif diff --git a/doc/images/stop-class.gif b/doc/images/button-stop-class.gif similarity index 100% rename from doc/images/stop-class.gif rename to doc/images/button-stop-class.gif diff --git a/doc/images/stop-printer.gif b/doc/images/button-stop-printer.gif similarity index 100% rename from doc/images/stop-printer.gif rename to doc/images/button-stop-printer.gif diff --git a/doc/images/unpublish-printer.gif b/doc/images/button-unpublish-printer.gif similarity index 100% rename from doc/images/unpublish-printer.gif rename to doc/images/button-unpublish-printer.gif diff --git a/doc/images/use-default-config.gif b/doc/images/button-use-default-config.gif similarity index 100% rename from doc/images/use-default-config.gif rename to doc/images/button-use-default-config.gif diff --git a/doc/images/view-access-log.gif b/doc/images/button-view-access-log.gif similarity index 100% rename from doc/images/view-access-log.gif rename to doc/images/button-view-access-log.gif diff --git a/doc/images/view-error-log.gif b/doc/images/button-view-error-log.gif similarity index 100% rename from doc/images/view-error-log.gif rename to doc/images/button-view-error-log.gif diff --git a/doc/images/view-page-log.gif b/doc/images/button-view-page-log.gif similarity index 100% rename from doc/images/view-page-log.gif rename to doc/images/button-view-page-log.gif diff --git a/doc/images/button-view-printable-version.gif b/doc/images/button-view-printable-version.gif new file mode 100644 index 0000000000..693dd43a14 Binary files /dev/null and b/doc/images/button-view-printable-version.gif differ diff --git a/doc/images/cancel.gif b/doc/images/cancel.gif deleted file mode 100644 index f183b56794..0000000000 Binary files a/doc/images/cancel.gif and /dev/null differ diff --git a/doc/images/classes.gif b/doc/images/classes.gif index ace15df980..0ac11977e7 100644 Binary files a/doc/images/classes.gif and b/doc/images/classes.gif differ diff --git a/doc/images/classes.svg b/doc/images/classes.svg new file mode 100644 index 0000000000..227d1b06bb --- /dev/null +++ b/doc/images/classes.svg @@ -0,0 +1,121 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/images/cups-black-button.scm b/doc/images/cups-black-button.scm new file mode 100644 index 0000000000..23cf817de6 --- /dev/null +++ b/doc/images/cups-black-button.scm @@ -0,0 +1,80 @@ +; CUPS Black Button +; Create a flat rounded button + +(define (script-fu-cups-black-button text text-color button-height button-color bg-color) + (let* ( + (img (car (gimp-image-new 256 256 RGB))) + (old-fg (car (gimp-palette-get-foreground))) + (old-bg (car (gimp-palette-get-background))) + (font-size (+ (/ (* 3 button-height) 5) 1)) + (dummy (gimp-palette-set-foreground text-color)) + (text-layer (car (gimp-text-fontname img -1 0 0 text 0 + TRUE font-size PIXELS + "Sans L,"))) + (text-width (car (gimp-drawable-width text-layer))) + (text-height (car (gimp-drawable-height text-layer))) + (button-width (+ text-width button-height)) + (bg-layer (car (gimp-layer-new img button-width button-height + RGBA-IMAGE "Background" 100 + NORMAL-MODE))) + ) + + ; Disable undo while we do our work... + (gimp-image-undo-disable img) + + ; Resize the image as needed... + (gimp-image-resize img button-width button-height 0 0) + (gimp-image-add-layer img bg-layer 1) + (gimp-layer-set-preserve-trans text-layer TRUE) + + ; Clear the background... + (gimp-selection-clear img) + (gimp-palette-set-background bg-color) + (gimp-edit-fill bg-layer 1) + + ; Make selections as needed for a rounded box. + (gimp-rect-select img (* 0.5 button-height) 0 + (- button-width button-height) button-height + REPLACE 0 0) + (gimp-ellipse-select img (- button-width button-height) 0 + button-height button-height ADD 1 0 0) + (gimp-ellipse-select img 0 0 button-height button-height ADD 1 0 0) + + ; Fill in the background... + (gimp-palette-set-background button-color) + (gimp-edit-fill bg-layer 1) + + ; Clear the border around the button image... + (gimp-selection-invert img) + (gimp-edit-clear bg-layer) + (gimp-selection-clear img) + + ; Restore original colors... + (gimp-palette-set-foreground old-fg) + (gimp-palette-set-background old-bg) + + ; Translate the text later to center it... + (gimp-layer-translate text-layer (* 0.5 button-height) + (- (* 0.5 (- button-height text-height)) 1)) + + ; Then flatten the image... + (gimp-image-merge-visible-layers img CLIP-TO-IMAGE) + (gimp-convert-indexed img 0 0 16 0 1 "") + (gimp-image-undo-enable img) + (gimp-display-new img) + ) +) + +(script-fu-register "script-fu-cups-black-button" + "/Btns/CUPS Black Button" + "CUPS Black Button" + "Michael Sweet " + "Michael Sweet " + "2000" + "" + SF-VALUE "Text String" "\"Button\"" + SF-COLOR "Text Color" '(255 255 255) + SF-VALUE "Button Size (in pixels)" "20" + SF-COLOR "Button Color" '(0 0 0) + SF-COLOR "Background Color" '(212 212 164) +) diff --git a/doc/images/cups-block-diagram.gif b/doc/images/cups-block-diagram.gif index 2fe505e44b..59fee5b10a 100644 Binary files a/doc/images/cups-block-diagram.gif and b/doc/images/cups-block-diagram.gif differ diff --git a/doc/images/cups-block-diagram.svg b/doc/images/cups-block-diagram.svg new file mode 100644 index 0000000000..46677274db --- /dev/null +++ b/doc/images/cups-block-diagram.svg @@ -0,0 +1,820 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + Scheduler (cupsd) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Filter + Filter + Backend + PortMonitor + + + + + + + JobFiles + + Web Interface(CGI) + + + + + BerkeleyCommands + CUPSCommands + System VCommands + + + + + + + ConfigFiles + + + + + + + LogFiles + + Notifiers + EMail + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LPD Support(cups-lpd) + + diff --git a/doc/images/cups-green-button.scm b/doc/images/cups-green-button.scm new file mode 100644 index 0000000000..4993bdd79c --- /dev/null +++ b/doc/images/cups-green-button.scm @@ -0,0 +1,80 @@ +; CUPS Green Button +; Create a flat rounded button + +(define (script-fu-cups-green-button text text-color button-height button-color bg-color) + (let* ( + (img (car (gimp-image-new 256 256 RGB))) + (old-fg (car (gimp-palette-get-foreground))) + (old-bg (car (gimp-palette-get-background))) + (font-size (+ (/ (* 3 button-height) 5) 1)) + (dummy (gimp-palette-set-foreground text-color)) + (text-layer (car (gimp-text-fontname img -1 0 0 text 0 + TRUE font-size PIXELS + "Sans L,"))) + (text-width (car (gimp-drawable-width text-layer))) + (text-height (car (gimp-drawable-height text-layer))) + (button-width (+ text-width button-height)) + (bg-layer (car (gimp-layer-new img button-width button-height + RGBA-IMAGE "Background" 100 + NORMAL-MODE))) + ) + + ; Disable undo while we do our work... + (gimp-image-undo-disable img) + + ; Resize the image as needed... + (gimp-image-resize img button-width button-height 0 0) + (gimp-image-add-layer img bg-layer 1) + (gimp-layer-set-preserve-trans text-layer TRUE) + + ; Clear the background... + (gimp-selection-clear img) + (gimp-palette-set-background bg-color) + (gimp-edit-fill bg-layer 1) + + ; Make selections as needed for a rounded box. + (gimp-rect-select img (* 0.5 button-height) 0 + (- button-width button-height) button-height + REPLACE 0 0) + (gimp-ellipse-select img (- button-width button-height) 0 + button-height button-height ADD 1 0 0) + (gimp-ellipse-select img 0 0 button-height button-height ADD 1 0 0) + + ; Fill in the background... + (gimp-palette-set-background button-color) + (gimp-edit-fill bg-layer 1) + + ; Clear the border around the button image... + (gimp-selection-invert img) + (gimp-edit-clear bg-layer) + (gimp-selection-clear img) + + ; Restore original colors... + (gimp-palette-set-foreground old-fg) + (gimp-palette-set-background old-bg) + + ; Translate the text later to center it... + (gimp-layer-translate text-layer (* 0.5 button-height) + (- (* 0.5 (- button-height text-height)) 1)) + + ; Then flatten the image... + (gimp-image-merge-visible-layers img CLIP-TO-IMAGE) + (gimp-convert-indexed img 0 0 16 0 1 "") + (gimp-image-undo-enable img) + (gimp-display-new img) + ) +) + +(script-fu-register "script-fu-cups-green-button" + "/Btns/CUPS Green Button" + "CUPS Green Button" + "Michael Sweet " + "Michael Sweet " + "2000" + "" + SF-VALUE "Text String" "\"Button\"" + SF-COLOR "Text Color" '(255 255 255) + SF-VALUE "Button Size (in pixels)" "20" + SF-COLOR "Button Color" '(0 153 0) + SF-COLOR "Background Color" '(212 212 164) +) diff --git a/doc/images/cups-red-button.scm b/doc/images/cups-red-button.scm new file mode 100644 index 0000000000..e608db5f0b --- /dev/null +++ b/doc/images/cups-red-button.scm @@ -0,0 +1,80 @@ +; CUPS Red Button +; Create a flat rounded button + +(define (script-fu-cups-red-button text text-color button-height button-color bg-color) + (let* ( + (img (car (gimp-image-new 256 256 RGB))) + (old-fg (car (gimp-palette-get-foreground))) + (old-bg (car (gimp-palette-get-background))) + (font-size (+ (/ (* 3 button-height) 5) 1)) + (dummy (gimp-palette-set-foreground text-color)) + (text-layer (car (gimp-text-fontname img -1 0 0 text 0 + TRUE font-size PIXELS + "Sans L,"))) + (text-width (car (gimp-drawable-width text-layer))) + (text-height (car (gimp-drawable-height text-layer))) + (button-width (+ text-width button-height)) + (bg-layer (car (gimp-layer-new img button-width button-height + RGBA-IMAGE "Background" 100 + NORMAL-MODE))) + ) + + ; Disable undo while we do our work... + (gimp-image-undo-disable img) + + ; Resize the image as needed... + (gimp-image-resize img button-width button-height 0 0) + (gimp-image-add-layer img bg-layer 1) + (gimp-layer-set-preserve-trans text-layer TRUE) + + ; Clear the background... + (gimp-selection-clear img) + (gimp-palette-set-background bg-color) + (gimp-edit-fill bg-layer 1) + + ; Make selections as needed for a rounded box. + (gimp-rect-select img (* 0.5 button-height) 0 + (- button-width button-height) button-height + REPLACE 0 0) + (gimp-ellipse-select img (- button-width button-height) 0 + button-height button-height ADD 1 0 0) + (gimp-ellipse-select img 0 0 button-height button-height ADD 1 0 0) + + ; Fill in the background... + (gimp-palette-set-background button-color) + (gimp-edit-fill bg-layer 1) + + ; Clear the border around the button image... + (gimp-selection-invert img) + (gimp-edit-clear bg-layer) + (gimp-selection-clear img) + + ; Restore original colors... + (gimp-palette-set-foreground old-fg) + (gimp-palette-set-background old-bg) + + ; Translate the text later to center it... + (gimp-layer-translate text-layer (* 0.5 button-height) + (- (* 0.5 (- button-height text-height)) 1)) + + ; Then flatten the image... + (gimp-image-merge-visible-layers img CLIP-TO-IMAGE) + (gimp-convert-indexed img 0 0 16 0 1 "") + (gimp-image-undo-enable img) + (gimp-display-new img) + ) +) + +(script-fu-register "script-fu-cups-red-button" + "/Btns/CUPS Red Button" + "CUPS Red Button" + "Michael Sweet " + "Michael Sweet " + "2000" + "" + SF-VALUE "Text String" "\"Button\"" + SF-COLOR "Text Color" '(255 255 255) + SF-VALUE "Button Size (in pixels)" "20" + SF-COLOR "Button Color" '(204 0 0) + SF-COLOR "Background Color" '(212 212 164) +) diff --git a/doc/images/cups-standard-button.scm b/doc/images/cups-standard-button.scm new file mode 100644 index 0000000000..565c3221eb --- /dev/null +++ b/doc/images/cups-standard-button.scm @@ -0,0 +1,80 @@ +; CUPS Standard Button +; Create a flat rounded button + +(define (script-fu-cups-standard-button text text-color button-height button-color bg-color) + (let* ( + (img (car (gimp-image-new 256 256 RGB))) + (old-fg (car (gimp-palette-get-foreground))) + (old-bg (car (gimp-palette-get-background))) + (font-size (+ (/ (* 3 button-height) 5) 1)) + (dummy (gimp-palette-set-foreground text-color)) + (text-layer (car (gimp-text-fontname img -1 0 0 text 0 + TRUE font-size PIXELS + "Sans L,"))) + (text-width (car (gimp-drawable-width text-layer))) + (text-height (car (gimp-drawable-height text-layer))) + (button-width (+ text-width button-height)) + (bg-layer (car (gimp-layer-new img button-width button-height + RGBA-IMAGE "Background" 100 + NORMAL-MODE))) + ) + + ; Disable undo while we do our work... + (gimp-image-undo-disable img) + + ; Resize the image as needed... + (gimp-image-resize img button-width button-height 0 0) + (gimp-image-add-layer img bg-layer 1) + (gimp-layer-set-preserve-trans text-layer TRUE) + + ; Clear the background... + (gimp-selection-clear img) + (gimp-palette-set-background bg-color) + (gimp-edit-fill bg-layer 1) + + ; Make selections as needed for a rounded box. + (gimp-rect-select img (* 0.5 button-height) 0 + (- button-width button-height) button-height + REPLACE 0 0) + (gimp-ellipse-select img (- button-width button-height) 0 + button-height button-height ADD 1 0 0) + (gimp-ellipse-select img 0 0 button-height button-height ADD 1 0 0) + + ; Fill in the background... + (gimp-palette-set-background button-color) + (gimp-edit-fill bg-layer 1) + + ; Clear the border around the button image... + (gimp-selection-invert img) + (gimp-edit-clear bg-layer) + (gimp-selection-clear img) + + ; Restore original colors... + (gimp-palette-set-foreground old-fg) + (gimp-palette-set-background old-bg) + + ; Translate the text later to center it... + (gimp-layer-translate text-layer (* 0.5 button-height) + (- (* 0.5 (- button-height text-height)) 1)) + + ; Then flatten the image... + (gimp-image-merge-visible-layers img CLIP-TO-IMAGE) + (gimp-convert-indexed img 0 0 16 0 1 "") + (gimp-image-undo-enable img) + (gimp-display-new img) + ) +) + +(script-fu-register "script-fu-cups-standard-button" + "/Btns/CUPS Standard Button" + "CUPS Standard Button" + "Michael Sweet " + "Michael Sweet " + "2000" + "" + SF-VALUE "Text String" "\"Button\"" + SF-COLOR "Text Color" '(255 255 255) + SF-VALUE "Button Size (in pixels)" "20" + SF-COLOR "Button Color" '(102 102 51) + SF-COLOR "Background Color" '(212 212 164) +) diff --git a/doc/images/printer-idle.gif b/doc/images/printer-idle.gif index 68d990c628..61e6c5d5d2 100644 Binary files a/doc/images/printer-idle.gif and b/doc/images/printer-idle.gif differ diff --git a/doc/images/printer-idle.svg b/doc/images/printer-idle.svg new file mode 100644 index 0000000000..c653007847 --- /dev/null +++ b/doc/images/printer-idle.svg @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/images/printer-processing.gif b/doc/images/printer-processing.gif index a9a23f7951..073be26873 100644 Binary files a/doc/images/printer-processing.gif and b/doc/images/printer-processing.gif differ diff --git a/doc/images/printer-processing.svg b/doc/images/printer-processing.svg new file mode 100644 index 0000000000..e4e2e55941 --- /dev/null +++ b/doc/images/printer-processing.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/images/printer-stopped.gif b/doc/images/printer-stopped.gif index 76f45649b1..f29f5b1488 100644 Binary files a/doc/images/printer-stopped.gif and b/doc/images/printer-stopped.gif differ diff --git a/doc/images/printer-stopped.svg b/doc/images/printer-stopped.svg new file mode 100644 index 0000000000..07c03ce6a3 --- /dev/null +++ b/doc/images/printer-stopped.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/images/web-add-this-printer.gif b/doc/images/web-add-this-printer.gif new file mode 100644 index 0000000000..e4bd2f2ca8 Binary files /dev/null and b/doc/images/web-add-this-printer.gif differ diff --git a/doc/images/web-password.gif b/doc/images/web-password.gif new file mode 100644 index 0000000000..d59c3764c2 Binary files /dev/null and b/doc/images/web-password.gif differ diff --git a/doc/images/web-printer-driver.gif b/doc/images/web-printer-driver.gif new file mode 100644 index 0000000000..6244421fb4 Binary files /dev/null and b/doc/images/web-printer-driver.gif differ diff --git a/doc/images/web-printer-status.gif b/doc/images/web-printer-status.gif new file mode 100644 index 0000000000..9202291ed0 Binary files /dev/null and b/doc/images/web-printer-status.gif differ diff --git a/doc/images/web-set-printer-options.gif b/doc/images/web-set-printer-options.gif new file mode 100644 index 0000000000..e1b9bcf08d Binary files /dev/null and b/doc/images/web-set-printer-options.gif differ diff --git a/doc/images/web-test-page.gif b/doc/images/web-test-page.gif new file mode 100644 index 0000000000..8d33e61149 Binary files /dev/null and b/doc/images/web-test-page.gif differ diff --git a/doc/index.html.in b/doc/index.html.in index d6186fb5fe..d082fa8acc 100644 --- a/doc/index.html.in +++ b/doc/index.html.in @@ -8,14 +8,14 @@ - + - - +

    Common UNIX Printing System @CUPS_VERSION@@CUPS_REVISION@
    +
    - - -CUPS Implementation of IPP - - - - - - - -

    -

    CUPS Implementation of IPP


    -CUPS-IPP-1.2
    -Easy Software Products
    -Copyright 1997-2003 All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Overview - -4 Operations - -5 Attributes - -A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    -

    This document provides an overview of the Internet Printing Protocol - ("IPP") version 1.1 as implemented in the Common UNIX Printing System - ("CUPS") version 1.2.

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This document is organized into the following sections:

    - -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Overview

    -

    CUPS 1.1 implements IPP/1.1 and the operations and attributes defined - in the "IPP: Job and Printer Set Operations", "IPP/1.1: Output-bin - Attribute Extension", and "IPP/1.1: finishings 'fold',' trim', and - 'bale' attribute values extension" specifications.

    -

    CUPS also provides 13 new operations and many new attributes to - support multiple IPP printers and printer classes on a single host.

    -

    3.1 IPP URIs

    -

    CUPS supports both the "http" and "ipp" methods. The following - resource names are used:

    -
    -
    method://hostname:port/
    -
    Can be used for all "get" operations.
    -
    method://hostname:port/admin
    -
    Used for all administrative operations.
    -
    method://hostname:port/classes/name
    -
    Specifies a printer class.
    -
    method://hostname:port/jobs/id
    -
    Specifies a job.
    -
    method://hostname:port/printers/name
    -
    Specifies a printer.
    -
    -

    So a typical printer URI would be - "ipp://foo.bar.com/printers/LaserJet".

    -

    In addition, the CUPS server also supports normal browser access to - "method://hostname:port/admin/", "method://hostname:port/classes/", - "method://hostname:port/jobs/", and "method://hostname:port/printers/" - to view and manage resources on the server dynamically.

    -

    3.2 CUPS IPP Operations

    -

    CUPS provides 13 extension operations in addition to most of the - standard IPP and registered extension operations: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Operation NameCUPS -CodeBrief Description
    Print-Job1.0 -0x0002Print a file.
    Validate-Job1.0 -0x0004Validate job attributes.
    Create-Job1.2 -0x0005Create a print job.
    Send-Document1.2 -0x0006Send a file for a print job.
    Cancel-Job1.0 -0x0008Cancel a print job.
    Get-Job-Attributes1.0 -0x0009Get job attributes.
    Get-Jobs1.0 -0x000AGet all jobs.
    Get-Printer-Attributes1.00x000BGet printer attributes.
    Hold-Job1.2 -0x000CHold a job for printing.
    Release-Job1.2 -0x000DRelease a job for printing.
    Pause-Printer1.0 -0x0010Pause printing on a printer.
    Resume-Printer1.0 -0x0011Resume printing on a printer.
    Purge-Jobs1.0 -0x0012Purge all jobs.
    Set-Job-Attributes1.2 -0x0014Set attributes for a pending or held job.
    CUPS-Get-Default1.0 -0x4001Get the default destination.
    CUPS-Get-Printers1.0 -0x4002Get all of the available printers.
    CUPS-Add-Modify-Printer1.00x4003Add or modify a printer.
    CUPS-Delete-Printer1.00x4004Delete a printer.
    CUPS-Get-Classes1.0 -0x4005Get all of the available printer classes.
    CUPS-Add-Modify-Class1.00x4006Add or modify a printer class.
    CUPS-Delete-Class1.0 -0x4007Delete a printer class.
    CUPS-Accept-Jobs1.0 -0x4008Accept jobs on a printer or printer class.
    CUPS-Reject-Jobs1.0 -0x4009Reject jobs on a printer or printer class.
    CUPS-Set-Default1.0 -0x400ASet the default destination.
    CUPS-Get-Devices1.2 -0x400BGet all of the available devices.
    CUPS-Get-PPDs1.2 -0x400CGet all of the available PPDs.
    CUPS-Move-Job1.2 -0x400DMove a job to a different printer.
    -
    -

    -

    4 Operations

    -

    The following sections describe the operations supported by CUPS. In - the interest of brevity, operations which use only the standard IPP - attributes are not described.

    -

    4.1 Print-Job Operation

    -

    The Print-Job operation (0x0002) prints a file.

    -

    4.1.1 Print-Job Request

    -

    The following groups of attributes are supplied as part of the - Print-Job request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer.

      -
    -

    Group 2: Job Template Attributes

    -
      -

      "job-billing" (text(MAX)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a billing string that is logged with - the page accounting information.

      -

      "job-sheets" (1setof type3 keyword | name(MAX)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies one or two banner pages that are - printed before and after any files in the print job. The name of "none" - is reserved to indicate that no banner page should be printed. If the - client does not specify this attribute then the value of the - "job-sheets-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value.

      -

      "media" (1setof type3 keyword | name(MAX)):

      -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output media. If - the client does not specify this attribute then the value of the - "media-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single media - attribute value.

      -

      Other Job Template Attributes

      -
    -

    The Print-Job request is followed by a file to be printed.

    -

    4.1.2 Print-Job Response

    -

    The following groups of attributes are send as part of the Print-Job - Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Job Attributes

    -
      -

      Standard Job Attributes

      -
    -

    4.2 Create-Job Operation

    -

    The Create-Job operation (0x0005) creates a new, empty print job.

    -

    4.2.1 Create-Job Request

    -

    The following groups of attributes are supplied as part of the - Create-Job request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer.

      -
    -

    Group 2: Job Template Attributes

    -
      -

      "job-billing" (text(MAX)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a billing string that is logged with - the page accounting information.

      -

      "job-sheets" (1setof type3 keyword | name(MAX)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies one or two banner pages that are - printed before and after any files in the print job. The name of "none" - is reserved to indicate that no banner page should be printed. If the - client does not specify this attribute then the value of the - "job-sheets-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value.

      -

      "media" (1setof type3 keyword | name(MAX)):

      -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output media. If - the client does not specify this attribute then the value of the - "media-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single media - attribute value.

      -

      Standard Job Template Attributes

      -
    -

    4.2.2 Create-Job Response

    -

    The following groups of attributes are send as part of the Create-Job - Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Job Attributes

    -
      -

      Standard Job Attributes

      -
    -

    4.3 Set-Job-Attributes Operation

    -

    The Set-Job-Attributes operation (0x0014) changes the attributes of - an active (not completed) job.

    -

    4.3.1 Set-Job-Attributes Request

    -

    The following groups of attributes are supplied as part of the - Set-Job-Attributes request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri) and "job-id" (integer)

      -

      OR

      -

      "job-uri":

      -

      The client MUST supply a URI for the specified printer and a job ID - number, or the job URI.

      -
    -

    Group 2: Job Template Attributes

    -
      -

      "job-sheets" (1setof type3 keyword | name(MAX)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies one or two banner pages that are - printed before and after any files in the print job. The name of "none" - is reserved to indicate that no banner page should be printed. If the - client does not specify this attribute then the value of the - "job-sheets-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value.

      -

      "media" (1setof type3 keyword | name(MAX)):

      -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output media. If - the client does not specify this attribute then the value of the - "media-default" printer object attribute is used.

      -

      Note: Standard IPP only allows specification of a single media - attribute value.

      -

      Other Job Template Attributes

      -
    -

    4.3.2 Set-Job-Attributes Response

    -

    The following groups of attributes are send as part of the - Set-Job-Attributes Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.4 CUPS-Get-Default Operation

    -

    The CUPS-Get-Default operation (0x4001) returns the default printer - URI and attributes.

    -

    4.4.1 CUPS-Get-Default Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Get-Default request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "requested-attributes" (1setOf keyword) :

      -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'.

      -
    -

    4.4.2 CUPS-Get-Default Response

    -

    The following groups of attributes are send as part of the - CUPS-Get-Default Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Printer Object Attributes

    -
      -

      The set of requested attributes and their current values.

      -
    -

    4.5 CUPS-Get-Printers Operation

    -

    The CUPS-Get-Printers operation (0x4002) returns the printer - attributes for every printer known to the system. This may include - printers that are not served directly by the server.

    -

    4.5.1 CUPS-Get-Printers Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Get-Printers request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "limit" (integer (1:MAX)):

      -

      The client OPTIONALLY supplies this attribute limiting the number of - printers that are returned.

      -

      "printer-info" (text(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies this attribute to select which - printers are returned.

      -

      "printer-location" (text(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies this attribute to select which - printers are returned.

      -

      "printer-type" (type2 enum):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a printer type enumeration to select - which printers are returned.

      -

      "printer-type-mask" (type2 enum):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a printer type mask enumeration to - select which bits are used in the "printer-type" attribute.

      -

      "requested-attributes" (1setOf keyword) :

      -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'.

      -
    -

    4.5.2 CUPS-Get-Printers Response

    -

    The following groups of attributes are send as part of the - CUPS-Get-Printers Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Printer Object Attributes

    -
      -

      The set of requested attributes and their current values for each - printer.

      -
    -

    4.6 CUPS-Add-Modify-Printer Operation

    -

    The CUPS-Add-Modify-Printer operation (0x4003) adds a new printer or - modifies an existing printer on the system.

    -

    4.6.1 CUPS-Add-Modify-Printer Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Add-Modify-Printer request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer.

      -
    -

    Group 2: Printer Object Attributes

    -
      -

      "banner-end-default" (name(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a banner page name that is printed - after files in a job. The reserved name "none" is used to specify that - no banner page should be printed.

      -

      "banner-start-default" (name(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a banner page name that is printed - before files in a job. The reserved name "none" is used to specify that - no banner page should be printed.

      -

      "device-uri" (uri):

      -

      The client OPTIONALLY supplies a device URI for the specified - printer.

      -

      "ppd-name" (name(127)):

      -

      The client OPTIONALLY supplies a PPD name for the specified printer.

      -

      "printer-is-accepting-jobs" (boolean):

      -

      The client OPTIONALLY supplies this boolean attribute indicating - whether or not the printer object should accept new jobs.

      -

      "printer-info" (text(127)):

      -

      The client OPTIONALLY supplies this attribute indicating the printer - information string.

      -

      "printer-location" (text(127)):

      -

      The client OPTIONALLY supplies this attribute indicating a textual - location of the printer.

      -

      "printer-more-info" (uri):

      -

      The client OPTIONALLY supplies this attribute indicating a URI for - additional printer information.

      -

      "printer-state" (type2 enum):

      -

      The client OPTIONALLY supplies this attribute indicating the - initial/current state of the printer. Only the "idle" and "stopped" - enumerations are recognized.

      -

      "printer-state-message" (text(MAX)):

      -

      The client OPTIONALLY supplies this attribute indicating a textual - reason for the current printer state.

      -

      "requesting-user-name-allowed" (1setof name(127) | delete)

      -

      OR

      -

      "requesting-user-name-denied" (1setof name(127) | delete):

      -

      The client OPTIONALLY supplies one of these attributes to specify an - access control list for incoming print jobs. To allow all users access - to a printer, use the delete tag for the attribute value.

      -
    -

    The CUPS-Add-Modify-Printer request can optionally be followed by a - PPD file or System V interface script to be used for the printer. The - "ppd-name" attribute overrides any file that is attached to the end of - the request with a local CUPS PPD file.

    -

    4.6.2 CUPS-Add-Modify-Printer Response

    -

    The following groups of attributes are send as part of the - CUPS-Add-Modify-Printer Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.7 CUPS-Delete-Printer Operation

    -

    The CUPS-Delete-Printer operation (0x4004) removes an existing - printer from the system.

    -

    4.7.1 CUPS-Delete-Printer Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Delete-Printer request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer.

      -
    -

    4.7.2 CUPS-Delete-Printer Response

    -

    The following groups of attributes are send as part of the - CUPS-Delete-Printer Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.8 CUPS-Get-Classes Operation

    -

    The CUPS-Get-Classes operation (0x4005) returns the printer - attributes for every printer class known to the system. This may - include printer classes that are not served directly by the server.

    -

    4.8.1 CUPS-Get-Classes Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Get-Classes request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "limit" (integer (1:MAX)):

      -

      The client OPTIONALLY supplies this attribute limiting the number of - printer classes that are returned.

      -

      "printer-info" (text(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies this attribute to select which printer - classes are returned.

      -

      "printer-location" (text(127)):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies this attribute to select which printer - classes are returned.

      -

      "printer-type" (type2 enum):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a printer type enumeration to select - which printer classes are returned.

      -

      "printer-type-mask" (type2 enum):

      -

      (CUPS 1.1 and higher)

      -

      The client OPTIONALLY supplies a printer type mask enumeration to - select which bits are used in the "printer-type" attribute.

      -

      "requested-attributes" (1setOf keyword) :

      -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'.

      -
    -

    4.8.2 CUPS-Get-Classes Response

    -

    The following groups of attributes are send as part of the - CUPS-Get-Classes Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Printer Class Object Attributes

    -
      -

      The set of requested attributes and their current values for each - printer class.

      -
    -

    4.9 CUPS-Add-Modify-Class Operation

    -

    The CUPS-Add-Modify-Class operation (0x4006) adds a new printer class - or modifies and existing printer class on the system.

    -

    4.9.1 CUPS-Add-Modify-Class Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Add-Modify-Class request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer class.

      -
    -

    Group 2: Printer Object Attributes

    -
      -

      "member-uris" (1setof uri):

      -

      The client OPTIONALLY supplies the "member-uris" set specifying the - printers and printer classes that are part of the class.

      -

      "printer-is-accepting-jobs" (boolean):

      -

      The client OPTIONALLY supplies this boolean attribute indicating - whether or not the class object should accept new jobs.

      -

      "printer-info" (text(127)):

      -

      The client OPTIONALLY supplies this attribute indicating the printer - information string.

      -

      "printer-location" (text(127)):

      -

      The client OPTIONALLY supplies this attribute indicating a textual - location of the class.

      -

      "printer-more-info" (uri):

      -

      The client OPTIONALLY supplies this attribute indicating a URI for - additional class information.

      -

      "printer-state" (type2 enum):

      -

      The client OPTIONALLY supplies this attribute indicating the - initial/current state of the class. Only the "idle" and "stopped" - enumerations are recognized.

      -

      "printer-state-message" (text(MAX)):

      -

      The client OPTIONALLY supplies this attribute indicating a textual - reason for the current class state.

      -

      "requesting-user-name-allowed" (1setof name(127))

      -

      OR

      -

      "requesting-user-name-denied" (1setof name(127)):

      -

      The client OPTIONALLY supplies one of these attributes to specify an - access control list for incoming print jobs. To allow all users access - to a class, use the delete tag for the attribute value.

      -
    -

    4.9.2 CUPS-Add-Modify-Class Response

    -

    The following groups of attributes are send as part of the - CUPS-Add-Modify-Class Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.10 CUPS-Delete-Class Operation

    -

    The CUPS-Delete-Class operation (0x4007) removes an existing printer - class from the system.

    -

    4.10.1 CUPS-Delete-Class Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Delete-Class request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer class.

      -
    -

    4.10.2 CUPS-Delete-Class Response

    -

    The following groups of attributes are send as part of the - CUPS-Delete-Class Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.11 CUPS-Accept-Jobs Operation

    -

    The CUPS-Accept-Jobs operation (0x4008) sets the - "printer-is-accepting-jobs" attribute to true for the specified printer - or printer class.

    -

    4.11.1 CUPS-Accept-Jobs Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Accept-Jobs request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer or printer - class.

      -
    -

    4.11.2 CUPS-Accept-Jobs Response

    -

    The following groups of attributes are send as part of the - CUPS-Accept-Jobs Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.12 CUPS-Reject-Jobs Operation

    -

    The CUPS-Reject-Jobs operation (0x4009) sets - the"printer-is-accepting-jobs" attribute to false for the specified - printer or printer class.

    -

    4.12.1 CUPS-Reject-Jobs Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Reject-Jobs request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer or printer - class.

      -
    -

    Group 2: Printer Object Attributes

    -
      -

      "printer-state-message" (text(MAX)):

      -

      The client OPTIONALLY supplies this attribute indicating a textual - reason for the current printer state.

      -
    -

    4.12.2 CUPS-Reject-Jobs Response

    -

    The following groups of attributes are send as part of the - CUPS-Reject-Jobs Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.13 CUPS-Set-Default Operation

    -

    The CUPS-Set-Default operation (0x400A) sets the default printer - destination for all clients when a resource name of "/printers" is - specified.

    -

    4.13.1 CUPS-Set-Default Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Set-Default request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri):

      -

      The client MUST supply a URI for the specified printer or printer - class.

      -
    -

    4.13.2 CUPS-Set-Default Response

    -

    The following groups of attributes are send as part of the - CUPS-Set-Default Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    4.14 CUPS-Get-Devices Operation

    -

    The CUPS-Get-Devices operation (0x400B) returns all of the supported - device-uri's for the server (CUPS 1.1 and higher).

    -

    4.14.1 CUPS-Get-Devices Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Get-Devices request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "device-class" (type1 keyword):

      -

      The client OPTIONALLY supplies a device class keyword to select which - devices are returned.

      -

      "limit" (integer (1:MAX)):

      -

      The client OPTIONALLY supplies this attribute limiting the number of - devices that are returned.

      -

      "requested-attributes" (1setOf keyword) :

      -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'.

      -
    -

    4.14.2 CUPS-Get-Devices Response

    -

    The following groups of attributes are send as part of the - CUPS-Get-Devices Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: Device Object Attributes

    -
      -

      The set of requested attributes and their current values for each - device.

      -
    -

    4.15 CUPS-Get-PPDs Operation

    -

    The CUPS-Get-PPDs operation (0x400C) returns all of the locally - available PPD files on the system (CUPS 1.1 and higher).

    -

    4.15.1 CUPS-Get-PPDs Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Get-PPDs request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "limit" (integer (1:MAX)):

      -

      The client OPTIONALLY supplies this attribute limiting the number of - PPDs that are returned.

      -

      "ppd-make" (text(127)):

      -

      The client OPTIONALLY supplies a printer manufacturer to select which - PPDs are returned.

      -

      "requested-attributes" (1setOf keyword) :

      -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'.

      -
    -

    4.15.2 CUPS-Get-PPDs Response

    -

    The following groups of attributes are send as part of the - CUPS-Get-PPDs Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    Group 2: PPD Attributes

    -
      -

      The set of requested attributes and their current values for each PPD - file.

      -
    -

    4.16 CUPS-Move-Job Operation

    -

    The CUPS-Move-Job operation (0x400D) moves an active print job to a - different printer (CUPS 1.1 and higher).

    -

    4.16.1 CUPS-Move-Job Request

    -

    The following groups of attributes are supplied as part of the - CUPS-Move-Job request:

    -

    Group 1: Operation Attributes

    -
      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.1 of the IPP Model and Semantics - document.

      -

      "printer-uri" (uri) and "job-id" (integer)

      -

      OR

      -

      "job-uri":

      -

      The client MUST supply a URI for the specified printer and a job ID - number, or the job URI.

      -
    -

    Group 2: Job Template Attributes

    -
      -

      "job-printer-uri" (uri)

      -

      The client MUST supply a URI for a printer on the same server.

      -
    -

    4.16.2 CUPS-Move-Job Response

    -

    The following groups of attributes are send as part of the - CUPS-Move-Job Response:

    -

    Group 1: Operation Attributes

    -
      -

      Status Message:

      -

      The standard response status message.

      -

      Natural Language and Character Set:

      -

      The "attributes-charset" and "attributes-natural-language" attributes - as described in section 3.1.4.2 of the IPP Model and Semantics - document.

      -
    -

    5 Attributes

    -

    CUPS provides many extension attributes to support multiple devices, - PPD files, standard job filters, printers, and printer classes.

    -

    5.1 Device Attributes

    -

    Device attributes are returned by the CUPS-Get-Devices operation and - enumerate all of the available hardware devices and network protocols - that are supported by the server.

    -

    5.1.1 device-class (type2 keyword)

    -

    The device-class attribute specifies the class of device and can be - one of the following:

    -
      -
    • "file" - a disk file.
      • -
    • "direct" - a parallel or fixed-rate serial data port, currently used - for Centronics, IEEE-1284, and USB printer ports.
      • -
    • "serial" - a variable-rate serial port.
      • -
    • "network" - a network connection, typically via AppSocket, HTTP, - IPP, LPD, or SMB/CIFS protocols.
      • -
    -

    5.1.2 device-info (text(127))

    -

    The device-info attribute specifies a human-readable string - describing the device, e.g. "Parallel Port #1".

    -

    5.1.3 device-make-and-model (text(127))

    -

    The device-makr-and-model attribute specifies a device identification - string provided by the printer connected to the device. If the device - or printer does not support identification then this attribute contains - the string "unknown".

    -

    5.1.4 device-uri (uri)

    -

    The device-uri attribute specifies a unique identifier for the - device. The actual format of the device-uri string depends on the value - of the device-class attribute:

    -
      -
    • "file" - The device-uri will be of the form - "file:/path/to/filename".
      • -
    • "direct" - The device-uri will be of the form - "method:/dev/filename", where method may be "parallel" or "usb" in the - current implementation.
      • -
    • "serial" - The device-uri will be of the form - "serial:/dev/filename?baud=value+parity=value+flow=value". The baud - value is the data rate in bits per second; the supported values depend - on the underlying hardware. The parity value can be one of "none", - "even", or "odd". The flow value can be one of "none", "soft" (XON/XOFF - handshaking), "hard" or "rts/cts" (RTS/CTS handshaking), or "dtrdsr" - (DTR/DSR handshaking). -

      The URI returned by CUPS-Get-Devices will contain the maximum baud - rate supported by the device and the best type of flow control - available ("soft" or "hard").

      -
    • "network" - The device-uri will be of the form - "method://[username:password@]hostname[:port]/[resource]", where method - may be "http", "ipp", "lpd", "smb", or "socket" in the current - implementation. -

      The URI returned by CUPS-Get-Devices will only contain the method - name followed by two slashes ("method://"). It is up to the client - application to add the appropriate host and other information when - adding a new printer.

      -

      The URI returned by Get-Printer-Attributes and CUPS-Get-Printers has - any username and password information stripped; the information is - still stored and used by the server internally to perform any needed - authentication.

      -
      • - -
    -

    5.2 Job Template Attributes

    -

    5.2.1 blackplot (boolean)

    -

    The blackplot attribute specifies whether HP-GL/2 plot files should - be rendered entirely in black ink (blackplot=true) or using the colors - and shades specified in the file (blackplot=false). The default value - is false.

    -

    5.2.2 brightness (integer(0:200))

    -

    The brightness attribute specifies the overall brightness of the - printed output in percent. A brightness of 100 is normal, while 200 is - twice as bright and 50 is half as bright. The default value is 100.

    -

    Brightness is applied to the Cyan, Magenta, Yellow, and Black values - using the function "f(x) = brightness / 100 * x".

    -

    5.2.3 columns (integer(1:4))

    -

    The columns attribute specifies the number of columns to generate - when printing text files. The default value is 1.

    -

    5.2.4 cpi (type2 enum)

    -

    The cpi attribute specifies the number of characters per inch when - printing text files. Only the values 10, 12, and 17 are currently - supported. The default value is 10.

    -

    5.2.5 fitplot (boolean)

    -

    The fitplot attribute specifies whether to scale HP-GL/2 plot files - to fit on the selected media (fitplot=true) or use the physical scale - specified in the plot file (fitplot=false). The default value is false.

    -

    5.2.6 gamma (integer(1:10000))

    -

    The gamma attribute specifies the luminance correction for the - output. A value of 1000 specifies no correction, while values of 2000 - and 500 will generate lighter and darker output, respectively. The - default value is 1000.

    -

    Gamma is applied to the Red, Green, and Blue values (or luminance for - grayscale output) using the function "f(x) = x(1000/gamma)".

    -

    5.2.7 hue (integer(-180:180))

    -

    The hue attribute specifies a color hue rotation when printing image - files. The default value is 0.

    -

    5.2.8 job-billing (text(MAX))

    -

    (CUPS 1.1 and higher)

    -

    The job-billing attribute provides a text value to associate with a - job for billing purposes.

    -

    5.2.9 job-hold-until (keyword | name(MAX))

    -

    (CUPS 1.1 and higher)

    -

    The job-hold-until attribute specifies a hold time. In addition to - the standard IPP/1.1 keyword names, CUPS supports name values of the - form "HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is - in Greenwich Mean Time (GMT) and not in the local time zone. If - the specified time is less than the current time, the job is held until - the next day.

    -

    5.2.10 job-sheets (1setof type3 keyword | - name(MAX))

    -

    (CUPS 1.1 and higher)

    -

    The job-sheets attribute specifies one or two banner files that are - printed before and after a job. The reserved value of "none" disables - banner printing. The default value is stored in the job-sheets-default - attribute.

    -

    If only one value is supplied, the banner file is printed before the - job. If two values are supplied, the first value is used as the - starting banner file and the second as the ending banner file.

    -

    5.2.11 job-originating-host-name (name(MAX))

    -

    (CUPS 1.1.5 and higher)

    -

    The job-originating-host-name attribute specifies the host from which - the job was queued. The value will be the hostname or IP address of the - client depending on whether hostname resolution is enabled. The - localhost address (127.0.0.1) is always resolved to the name - "localhost".

    -

    This attribute is read-only.

    -

    5.2.12 lpi (type2 enum)

    -

    The lpi attribute specifies the number of lines per inch when - printing text files. Only the values 6 and 8 are currently supported. - The default value is 6.

    -

    5.2.13 natural-scaling (integer(1:1000))

    -

    (CUPS 1.1.9 and higher)

    -

    The natural-scaling attribute specifies the scaling of image files - with respect to the natural image size. A value of 100 specifies that - the image file should exactly the natural size, while 50 is half the - natural size and 200 is twice the natural size. The default value is - 100.

    -

    The ppi option can be used to override the natural resolution of the - image, which controls the natural size.

    -

    5.2.14 number-up-layout (type2 keyword)

    -

    (CUPS 1.1.15 and higher)

    -

    The number-up-layout attribute specifies the order each input page is - placed on each output page. The following keywords are presently - defined:

    -
      -
    • btlr - Bottom to top, left to right
      • -
    • btrl - Bottom to top, right to left
      • -
    • lrbt - Left to right, bottom to top
      • -
    • lrtb - Left to right, top to bottom (default)
      • -
    • rlbt - Right to left, bottom to top
      • -
    • rltb - Right to left, top to bottom
      • -
    • tblr - Top to bottom, left to right
      • -
    • tbrl - Top to bottom, right to left
      • -
    -

    5.2.15 page-border (type2 keyword)

    -

    (CUPS 1.1.15 and higher)

    -

    The page-border attribute specifies whether a border is draw around - each page. The following keywords are presently defined:

    -
      -
    • double - Two hairline borders are drawn
      • -
    • double-thick - Two 1pt borders are drawn
      • -
    • none - No border is drawn (default)
      • -
    • single - A single hairline border is drawn
      • -
    • single-thick - A single 1pt border is drawn
      • -
    -

    5.2.16 page-bottom (integer(0:MAX))

    -

    The page-bottom attribute specifies the bottom margin in points (72 - points equals 1 inch). The default value is the device physical margin.

    -

    5.2.17 page-label (text(MAX))

    -

    (CUPS 1.1.7 and higher)

    -

    The page-label attribute provides a text value to place in the header - and footer on each page. If a classification level is set on the - server, then this classification is printed before the page label.

    -

    5.2.18 page-left (integer(0:MAX))

    -

    The page-left attribute specifies the left margin in points (72 - points equals 1 inch). The default value is the device physical margin.

    -

    5.2.19 page-right (integer(0:MAX))

    -

    The page-right attribute specifies the right margin in points (72 - points equals 1 inch). The default value is the device physical margin.

    -

    5.2.20 page-set (type2 keyword)

    -

    The page-set attribute specifies which pages to print in a file. The - supported keywords are "all", "even", and "odd". The default value is - "all".

    -

    5.2.21 page-top (integer(0:MAX))

    -

    The page-top attribute specifies the top margin in points (72 points - equals 1 inch). The default value is the device physical margin.

    -

    5.2.22 penwidth (integer(0:MAX))

    -

    The penwidth attribute specifies the default pen width in micrometers - when printing HP-GL/2 plot files. The default value is 1000 (1 - millimeter).

    -

    5.2.23 position (type2 keyword)

    -

    The position attribute specifies the location of image files on the - media. The following keyword values are recognized:

    -
      -
    • center - Center the image on the page (default)
      • -
    • top - Print the image centered at the top of the page
      • -
    • left - Print the image centered on the left of page
      • -
    • right - Print the image centered on the right of the - page
      • -
    • top-left - Print the image at the top left corner of - the page
      • -
    • top-right - Print the image at the top right corner of - the page
      • -
    • bottom - Print the image centered at the bottom of the - page
      • -
    • bottom-left - Print the image at the bottom left corner - of the page
      • -
    • bottom-right - Print the image at the bottom right - corner of the page
      • -
    -

    5.2.24 ppi (integer(1:MAX))

    -

    The ppi attribute specifies the resolution of an image file in pixels - per inch. The default value is the resolution included with the file or - 128 if no resolution information is available.

    -

    5.2.25 prettyprint (boolean)

    -

    The prettyprint attribute specifies whether text files should be - printed with a shaded header and keyword highlighting - (prettyprint=true) or without additional formatting - (prettyprint=false). The default value is false.

    -

    5.2.26 saturation (integer(0:200))

    -

    The saturation attribute specifies the color saturation when printing - image files. A saturation of 100 is normal, while values of 50 and 200 - will be half and twice as colorful, respectively. The default value is - 100.

    -

    5.2.27 scaling (integer(1:1000))

    -

    The scaling attribute specifies the scaling of image files with - respect to the selected media. A value of 100 specifies that the image - file should fit 100% of the page, or as much as possible given the - image dimensions. The default value is unspecified.

    -

    The scaling attribute overrides the ppi attribute if specified.

    -

    5.2.28 wrap (boolean)

    -

    The wrap attribute specifies whether long lines should be wrapped - (wrap=true) or not (wrap=false) when printing text files. The default - value is true.

    -

    5.3 PPD Attributes

    -

    5.3.1 ppd-natural-language (naturalLanguage)

    -

    The ppd-natural-language attribute specifies the language encoding of - the PPD file (the LanguageVersion attribute in the PPD file). If the - language is unknown or undefined then "en" (English) is assumed.

    -

    5.3.2 ppd-make (text(127))

    -

    The ppd-make attribute specifies the manufacturer of the printer (the - Manufacturer attribute in the PPD file). If the manufacturer is not - specified in the PPD file then an educated guess is made using the - NickName attribute in the PPD file.

    -

    5.3.3 ppd-make-and-model (text(127))

    -

    The ppd-make-and-model attribute specifies the manufacturer and model - name of the PPD file (the NickName attribute in the PPD file). If the - make and model is not specified in the PPD file then the ModelName or - ShortNickName attributes are used instead.

    -

    5.3.4 ppd-name (name(255))

    -

    The ppd-name attribute specifies the PPD filename on the server - relative to the model directory. The forward slash (/) is used to - delineate directories.

    -

    5.4 Printer Attributes

    -

    5.4.1 job-k-limit (integer)

    -

    (CUPS 1.1 and higher)

    -

    The job-k-limit attribute specifies the maximum number of kilobytes - that may be printed by a user, including banner files. The default - value of 0 specifies that there is no limit.

    -

    5.4.2 job-page-limit (integer)

    -

    (CUPS 1.1 and higher)

    -

    The job-page-limit attribute specifies the maximum number of pages - that may be printed by a user, including banner files. The default - value of 0 specifies that there is no limit.

    -

    5.4.3 job-quota-period (integer)

    -

    (CUPS 1.1 and higher)

    -

    The job-quota-period attribute specifies the time period used for - quota calculations, in seconds. The default value of 0 specifies that - the limits apply to all jobs that have been printed by a user that are - still known to the system.

    -

    5.4.4 job-sheets-supported (1setof type3 keyword | - name(MAX))

    -

    (CUPS 1.1 and higher)

    -

    The job-sheets-supported attribute specifies the available banner - files. There will always be at least one banner file available called - "none".

    -

    5.4.5 printer-type (type2 enum)

    -

    The printer-type attribute specifies printer type and capability bits - for the printer or class. The default value is computed from internal - state information and the PPD file for the printer. The following bits - are defined: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    BitDescription
    0x00000001Is a printer class.
    0x00000002Is a remote - destination.
    0x00000004Can print in black.
    0x00000008Can print in color.
    0x00000010Can print on both - sides of the page in hardware.
    0x00000020Can staple output.
    0x00000040Can do fast copies - in hardware.
    0x00000080Can do fast copy - collation in hardware.
    0x00000100Can punch output.
    0x00000200Can cover output.
    0x00000400Can bind output.
    0x00000800Can sort output.
    0x00001000Can handle media up - to US-Legal/A4.
    0x00002000Can handle media - from US-Legal/A4 to ISO-C/A2.
    0x00004000Can handle media - larger than ISO-C/A2.
    0x00008000Can handle - user-defined media sizes.
    0x00010000Is an implicit - (server-generated) class.
    -
    -

    -

    5.4.6 printer-type-mask (type2 enum)

    -

    (CUPS 1.1 and higher)

    -

    The printer-type-mask attribute is used to choose printers or classes - with the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits - are defined identically to the printer-type attribute and default to - all 1's.

    -

    5.4.7 requesting-user-name-allowed (1setof - name(127))

    -

    (CUPS 1.1 and higher)

    -

    The requesting-user-name-allowed attribute lists all of the users - that are allowed to access a printer or class. Either this attribute or - the requesting-user-name-denied attribute will be defined, but not - both.

    -

    5.4.8 requesting-user-name-denied (1setof name(127)) -

    -

    (CUPS 1.1 and higher)

    -

    The requesting-user-name-denied attribute lists all of the users that - are not allowed to access a printer or class. Either this attribute or - the requesting-user-name-allowed attribute will be defined, but not - both.

    -

    5.5 Printer Class Attributes

    -

    5.5.1 member-names (1setof name(127))

    -

    The member-names attribute specifies each of the printer-name - attributes of the member printers and classes. Each name corresponds to - the same element of the member-uris attribute.

    -

    5.5.2 member-uris (1setof uri)

    -

    The member-uris attribute specifies each of the printer-uri - attributes of the member printers and classes. Each URI corresponds to - the same element of the member-names attribute.

    -

    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
    -
    - - diff --git a/doc/ipp.pdf b/doc/ipp.pdf deleted file mode 100644 index 84771cd3ff..0000000000 Binary files a/doc/ipp.pdf and /dev/null differ diff --git a/doc/ipp.shtml b/doc/ipp.shtml deleted file mode 100644 index 79d8316d5d..0000000000 --- a/doc/ipp.shtml +++ /dev/null @@ -1,1994 +0,0 @@ - - - - - - CUPS Implementation of IPP - - - -

    Scope

    - -

    Identification

    - -

    This document provides an overview of the Internet Printing Protocol -("IPP") version 1.1 as implemented in the Common UNIX Printing System -("CUPS") version 1.2. - - - -

    Document Overview

    - -

    This document is organized into the following sections: - -

    - - - -

    Overview

    - -

    CUPS 1.1 implements IPP/1.1 and the operations and attributes -defined in the "IPP: Job and Printer Set Operations", -"IPP/1.1: Output-bin Attribute Extension", and "IPP/1.1: finishings -'fold',' trim', and 'bale' attribute values extension" specifications. - -

    CUPS also provides 13 new operations and many new attributes to -support multiple IPP printers and printer classes on a single host. - -

    IPP URIs

    - -

    CUPS supports both the "http" and "ipp" methods. The following -resource names are used: - -

    - -
    method://hostname:port/ - -
    Can be used for all "get" operations. - -
    method://hostname:port/admin - -
    Used for all administrative operations. - -
    method://hostname:port/classes/name - -
    Specifies a printer class. - -
    method://hostname:port/jobs/id - -
    Specifies a job. - -
    method://hostname:port/printers/name - -
    Specifies a printer. - -
    - -

    So a typical printer URI would be "ipp://foo.bar.com/printers/LaserJet". - -

    In addition, the CUPS server also supports normal browser access to -"method://hostname:port/admin/", "method://hostname:port/classes/", -"method://hostname:port/jobs/", and "method://hostname:port/printers/" -to view and manage resources on the server dynamically. - -

    CUPS IPP Operations

    - -

    CUPS provides 13 extension operations in addition to most of the -standard IPP and registered extension operations: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Operation NameCUPSCodeBrief Description
    Print-Job1.00x0002Print a file.
    Validate-Job1.00x0004Validate job attributes.
    Create-Job1.20x0005Create a print job.
    Send-Document1.20x0006Send a file for a print job.
    Cancel-Job1.00x0008Cancel a print job.
    Get-Job-Attributes1.00x0009Get job attributes.
    Get-Jobs1.00x000AGet all jobs.
    Get-Printer-Attributes1.00x000BGet printer attributes.
    Hold-Job1.20x000CHold a job for printing.
    Release-Job1.20x000DRelease a job for printing.
    Pause-Printer1.00x0010Pause printing on a printer.
    Resume-Printer1.00x0011Resume printing on a printer.
    Purge-Jobs1.00x0012Purge all jobs.
    Set-Job-Attributes1.20x0014Set attributes for a pending or held job.
    CUPS-Get-Default1.00x4001Get the default destination.
    CUPS-Get-Printers1.00x4002Get all of the available printers.
    CUPS-Add-Modify-Printer1.00x4003Add or modify a printer.
    CUPS-Delete-Printer1.00x4004Delete a printer.
    CUPS-Get-Classes1.00x4005Get all of the available printer classes.
    CUPS-Add-Modify-Class1.00x4006Add or modify a printer class.
    CUPS-Delete-Class1.00x4007Delete a printer class.
    CUPS-Accept-Jobs1.00x4008Accept jobs on a printer or printer class.
    CUPS-Reject-Jobs1.00x4009Reject jobs on a printer or printer class.
    CUPS-Set-Default1.00x400ASet the default destination.
    CUPS-Get-Devices1.20x400BGet all of the available devices.
    CUPS-Get-PPDs1.20x400CGet all of the available PPDs.
    CUPS-Move-Job1.20x400DMove a job to a different printer.
    -
    - -

    Operations

    - -

    The following sections describe the operations supported by CUPS. -In the interest of brevity, operations which use only the standard -IPP attributes are not described. - -

    Print-Job Operation

    - -

    The Print-Job operation (0x0002) prints a file. - -

    Print-Job Request

    - -

    The following groups of attributes are supplied as part of the -Print-Job request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer. - -

    - -

    Group 2: Job Template Attributes - -

      - -

      "job-billing" (text(MAX)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a billing string that is logged - with the page accounting information. - -

      "job-sheets" (1setof type3 keyword | name(MAX)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies one or two banner pages that - are printed before and after any files in the print job. The - name of "none" is reserved to indicate that no banner page - should be printed. If the client does not specify this - attribute then the value of the "job-sheets-default" printer - object attribute is used. - -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value. - -

      "media" (1setof type3 keyword | name(MAX)): - -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output - media. If the client does not specify this attribute then the - value of the "media-default" printer object attribute is used. - -

      Note: Standard IPP only allows specification of a single - media attribute value. - -

      Other Job Template Attributes - -

    - -

    The Print-Job request is followed by a file to be printed. - -

    Print-Job Response

    - -

    The following groups of attributes are send as part of the Print-Job -Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Job Attributes - -

      - -

      Standard Job Attributes - -

    - -

    Create-Job Operation

    - -

    The Create-Job operation (0x0005) creates a new, empty print job. - -

    Create-Job Request

    - -

    The following groups of attributes are supplied as part of the -Create-Job request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer. - -

    - -

    Group 2: Job Template Attributes - -

      - -

      "job-billing" (text(MAX)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a billing string that is logged - with the page accounting information. - -

      "job-sheets" (1setof type3 keyword | name(MAX)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies one or two banner pages that - are printed before and after any files in the print job. The - name of "none" is reserved to indicate that no banner page - should be printed. If the client does not specify this - attribute then the value of the "job-sheets-default" printer - object attribute is used. - -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value. - -

      "media" (1setof type3 keyword | name(MAX)): - -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output - media. If the client does not specify this attribute then the - value of the "media-default" printer object attribute is used. - -

      Note: Standard IPP only allows specification of a single - media attribute value. - -

      Standard Job Template Attributes - -

    - -

    Create-Job Response

    - -

    The following groups of attributes are send as part of the -Create-Job Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Job Attributes - -

      - -

      Standard Job Attributes - -

    - -

    Set-Job-Attributes Operation

    - -

    The Set-Job-Attributes operation (0x0014) changes the attributes of -an active (not completed) job. - -

    Set-Job-Attributes Request

    - -

    The following groups of attributes are supplied as part of the -Set-Job-Attributes request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri) and "job-id" (integer) -

      OR -

      "job-uri": - -

      The client MUST supply a URI for the specified printer and - a job ID number, or the job URI. - -

    - -

    Group 2: Job Template Attributes - -

      - -

      "job-sheets" (1setof type3 keyword | name(MAX)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies one or two banner pages that - are printed before and after any files in the print job. The - name of "none" is reserved to indicate that no banner page - should be printed. If the client does not specify this - attribute then the value of the "job-sheets-default" printer - object attribute is used. - -

      Note: Standard IPP only allows specification of a single - job-sheets attribute value. - -

      "media" (1setof type3 keyword | name(MAX)): - -

      The client OPTIONALLY supplies one or more media attributes - specifying the size, type, source, and color of the output - media. If the client does not specify this attribute then the - value of the "media-default" printer object attribute is used. - -

      Note: Standard IPP only allows specification of a single - media attribute value. - -

      Other Job Template Attributes - -

    - -

    Set-Job-Attributes Response

    - -

    The following groups of attributes are send as part of the Set-Job-Attributes -Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Get-Default Operation

    - -

    The CUPS-Get-Default operation (0x4001) returns the default printer -URI and attributes. - -

    CUPS-Get-Default Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Get-Default request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "requested-attributes" (1setOf keyword) : - -

      The client OPTIONALLY supplies a set of attribute names - and/or attribute group names in whose values the requester is - interested. If the client omits this attribute, the server - responds as if this attribute had been supplied with a value of - 'all'. - -

    - -

    CUPS-Get-Default Response

    - -

    The following groups of attributes are send as part of the -CUPS-Get-Default Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Printer Object Attributes - -

      - -

      The set of requested attributes and their current values. - -

    - -

    CUPS-Get-Printers Operation

    - -

    The CUPS-Get-Printers operation (0x4002) returns the printer -attributes for every printer known to the system. This may include -printers that are not served directly by the server. - -

    CUPS-Get-Printers Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Get-Printers request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "limit" (integer (1:MAX)): - -

      The client OPTIONALLY supplies this attribute limiting the - number of printers that are returned. - -

      "printer-info" (text(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies this attribute to - select which printers are returned. - -

      "printer-location" (text(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies this attribute to - select which printers are returned. - -

      "printer-type" (type2 enum): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a printer type enumeration to - select which printers are returned. - -

      "printer-type-mask" (type2 enum): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a printer type mask - enumeration to select which bits are used in the "printer-type" - attribute. - -

      "requested-attributes" (1setOf keyword) : - -

      The client OPTIONALLY supplies a set of attribute names - and/or attribute group names in whose values the requester is - interested. If the client omits this attribute, the server - responds as if this attribute had been supplied with a value of - 'all'. - -

    - -

    CUPS-Get-Printers Response

    - -

    The following groups of attributes are send as part of the -CUPS-Get-Printers Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Printer Object Attributes - -

      - -

      The set of requested attributes and their current values for - each printer. - -

    - -

    CUPS-Add-Modify-Printer Operation

    - -

    The CUPS-Add-Modify-Printer operation (0x4003) adds a new printer or -modifies an existing printer on the system. - -

    CUPS-Add-Modify-Printer Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Add-Modify-Printer request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer. - -

    - -

    Group 2: Printer Object Attributes - -

      - -

      "banner-end-default" (name(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a banner page name that is - printed after files in a job. The reserved name "none" is used to - specify that no banner page should be printed. - -

      "banner-start-default" (name(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a banner page name that is - printed before files in a job. The reserved name "none" is used to - specify that no banner page should be printed. - -

      "device-uri" (uri): - -

      The client OPTIONALLY supplies a device URI for the - specified printer. - -

      "ppd-name" (name(127)): - -

      The client OPTIONALLY supplies a PPD name for the specified - printer. - -

      "printer-is-accepting-jobs" (boolean): - -

      The client OPTIONALLY supplies this boolean attribute - indicating whether or not the printer object should accept new jobs. - -

      "printer-info" (text(127)): - -

      The client OPTIONALLY supplies this attribute indicating the - printer information string. - -

      "printer-location" (text(127)): - -

      The client OPTIONALLY supplies this attribute indicating a - textual location of the printer. - -

      "printer-more-info" (uri): - -

      The client OPTIONALLY supplies this attribute indicating a - URI for additional printer information. - -

      "printer-state" (type2 enum): - -

      The client OPTIONALLY supplies this attribute indicating the - initial/current state of the printer. Only the "idle" and "stopped" - enumerations are recognized. - -

      "printer-state-message" (text(MAX)): - -

      The client OPTIONALLY supplies this attribute indicating a - textual reason for the current printer state. - -

      "requesting-user-name-allowed" (1setof name(127) | delete) -

      OR -

      "requesting-user-name-denied" (1setof name(127) | delete): - -

      The client OPTIONALLY supplies one of these attributes to - specify an access control list for incoming print jobs. To allow - all users access to a printer, use the delete tag for the - attribute value. - -

    - -

    The CUPS-Add-Modify-Printer request can optionally be followed by a PPD -file or System V interface script to be used for the printer. The -"ppd-name" attribute overrides any file that is attached to the end of -the request with a local CUPS PPD file. - -

    CUPS-Add-Modify-Printer Response

    - -

    The following groups of attributes are send as part of the -CUPS-Add-Modify-Printer Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Delete-Printer Operation

    - -

    The CUPS-Delete-Printer operation (0x4004) removes an existing -printer from the system. - -

    CUPS-Delete-Printer Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Delete-Printer request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer. - -

    - -

    CUPS-Delete-Printer Response

    - -

    The following groups of attributes are send as part of the -CUPS-Delete-Printer Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Get-Classes Operation

    - -

    The CUPS-Get-Classes operation (0x4005) returns the printer -attributes for every printer class known to the system. This may -include printer classes that are not served directly by the server. - -

    CUPS-Get-Classes Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Get-Classes request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "limit" (integer (1:MAX)): - -

      The client OPTIONALLY supplies this attribute limiting the - number of printer classes that are returned. - -

      "printer-info" (text(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies this attribute to - select which printer classes are returned. - -

      "printer-location" (text(127)): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies this attribute to - select which printer classes are returned. - -

      "printer-type" (type2 enum): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a printer type enumeration to - select which printer classes are returned. - -

      "printer-type-mask" (type2 enum): - -

      (CUPS 1.1 and higher) - -

      The client OPTIONALLY supplies a printer type mask - enumeration to select which bits are used in the "printer-type" - attribute. - -

      "requested-attributes" (1setOf keyword) : - -

      The client OPTIONALLY supplies a set of attribute names - and/or attribute group names in whose values the requester is - interested. If the client omits this attribute, the server responds as - if this attribute had been supplied with a value of 'all'. - -

    - -

    CUPS-Get-Classes Response

    - -

    The following groups of attributes are send as part of the -CUPS-Get-Classes Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Printer Class Object Attributes - -

      - -

      The set of requested attributes and their current values for - each printer class. - -

    - -

    CUPS-Add-Modify-Class Operation

    - -

    The CUPS-Add-Modify-Class operation (0x4006) adds a new printer class or -modifies and existing printer class on the system. - -

    CUPS-Add-Modify-Class Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Add-Modify-Class request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer class. - -

    - -

    Group 2: Printer Object Attributes - -

      - -

      "member-uris" (1setof uri): - -

      The client OPTIONALLY supplies the "member-uris" set - specifying the printers and printer classes that are part of the class. - -

      "printer-is-accepting-jobs" (boolean): - -

      The client OPTIONALLY supplies this boolean attribute - indicating whether or not the class object should accept new jobs. - -

      "printer-info" (text(127)): - -

      The client OPTIONALLY supplies this attribute indicating the - printer information string. - -

      "printer-location" (text(127)): - -

      The client OPTIONALLY supplies this attribute indicating a - textual location of the class. - -

      "printer-more-info" (uri): - -

      The client OPTIONALLY supplies this attribute indicating a - URI for additional class information. - -

      "printer-state" (type2 enum): - -

      The client OPTIONALLY supplies this attribute indicating the - initial/current state of the class. Only the "idle" and "stopped" - enumerations are recognized. - -

      "printer-state-message" (text(MAX)): - -

      The client OPTIONALLY supplies this attribute indicating a - textual reason for the current class state. - -

      "requesting-user-name-allowed" (1setof name(127)) -

      OR -

      "requesting-user-name-denied" (1setof name(127)): - -

      The client OPTIONALLY supplies one of these attributes to - specify an access control list for incoming print jobs. To allow - all users access to a class, use the delete tag for the - attribute value. - -

    - -

    CUPS-Add-Modify-Class Response

    - -

    The following groups of attributes are send as part of the CUPS-Add-Modify-Class Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Delete-Class Operation

    - -

    The CUPS-Delete-Class operation (0x4007) removes an existing printer -class from the system. - -

    CUPS-Delete-Class Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Delete-Class request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer class. - -

    - -

    CUPS-Delete-Class Response

    - -

    The following groups of attributes are send as part of the -CUPS-Delete-Class Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Accept-Jobs Operation

    - -

    The CUPS-Accept-Jobs operation (0x4008) sets the -"printer-is-accepting-jobs" attribute to true for the specified printer -or printer class. - -

    CUPS-Accept-Jobs Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Accept-Jobs request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer or printer class. - -

    - -

    CUPS-Accept-Jobs Response

    - -

    The following groups of attributes are send as part of the -CUPS-Accept-Jobs Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Reject-Jobs Operation

    - -

    The CUPS-Reject-Jobs operation (0x4009) sets -the"printer-is-accepting-jobs" attribute to false for the specified -printer or printer class. - -

    CUPS-Reject-Jobs Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Reject-Jobs request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer or printer class. - -

    - -

    Group 2: Printer Object Attributes - -

      - -

      "printer-state-message" (text(MAX)): - -

      The client OPTIONALLY supplies this attribute indicating a - textual reason for the current printer state. - -

    - -

    CUPS-Reject-Jobs Response

    - -

    The following groups of attributes are send as part of the -CUPS-Reject-Jobs Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Set-Default Operation

    - -

    The CUPS-Set-Default operation (0x400A) sets the default printer -destination for all clients when a resource name of "/printers" is -specified. - -

    CUPS-Set-Default Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Set-Default request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri): - -

      The client MUST supply a URI for the specified printer or - printer class. - -

    - -

    CUPS-Set-Default Response

    - -

    The following groups of attributes are send as part of the -CUPS-Set-Default Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    CUPS-Get-Devices Operation

    - -

    The CUPS-Get-Devices operation (0x400B) returns all of the supported -device-uri's for the server (CUPS 1.1 and higher). - -

    CUPS-Get-Devices Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Get-Devices request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "device-class" (type1 keyword): - -

      The client OPTIONALLY supplies a device class keyword to select - which devices are returned. - -

      "limit" (integer (1:MAX)): - -

      The client OPTIONALLY supplies this attribute limiting the number of - devices that are returned. - -

      "requested-attributes" (1setOf keyword) : - -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'. - -

    - -

    CUPS-Get-Devices Response

    - -

    The following groups of attributes are send as part of the -CUPS-Get-Devices Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: Device Object Attributes - -

      - -

      The set of requested attributes and their current values for - each device. - -

    - -

    CUPS-Get-PPDs Operation

    - -

    The CUPS-Get-PPDs operation (0x400C) returns all of the locally -available PPD files on the system (CUPS 1.1 and higher). - -

    CUPS-Get-PPDs Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Get-PPDs request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "limit" (integer (1:MAX)): - -

      The client OPTIONALLY supplies this attribute limiting the number of - PPDs that are returned. - -

      "ppd-make" (text(127)): - -

      The client OPTIONALLY supplies a printer manufacturer to select - which PPDs are returned. - -

      "requested-attributes" (1setOf keyword) : - -

      The client OPTIONALLY supplies a set of attribute names and/or - attribute group names in whose values the requester is interested. If - the client omits this attribute, the server responds as if this - attribute had been supplied with a value of 'all'. - -

    - -

    CUPS-Get-PPDs Response

    - -

    The following groups of attributes are send as part of the -CUPS-Get-PPDs Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Group 2: PPD Attributes - -

      - -

      The set of requested attributes and their current values for each - PPD file. - -

    - -

    CUPS-Move-Job Operation

    - -

    The CUPS-Move-Job operation (0x400D) moves an active print job to a -different printer (CUPS 1.1 and higher). - -

    CUPS-Move-Job Request

    - -

    The following groups of attributes are supplied as part of the -CUPS-Move-Job request: - -

    Group 1: Operation Attributes - -

      - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.1 of the IPP Model and - Semantics document. - -

      "printer-uri" (uri) and "job-id" (integer) -

      OR -

      "job-uri": - -

      The client MUST supply a URI for the specified printer and - a job ID number, or the job URI. - -

    - -

    Group 2: Job Template Attributes - -

      - -

      "job-printer-uri" (uri) - -

      The client MUST supply a URI for a printer on the same server. - -

    - -

    CUPS-Move-Job Response

    - -

    The following groups of attributes are send as part of the -CUPS-Move-Job Response: - -

    Group 1: Operation Attributes - -

      - -

      Status Message: - -

      The standard response status message. - -

      Natural Language and Character Set: - -

      The "attributes-charset" and "attributes-natural-language" - attributes as described in section 3.1.4.2 of the IPP Model and - Semantics document. - -

    - -

    Attributes

    - -

    CUPS provides many extension attributes to support multiple devices, -PPD files, standard job filters, printers, and printer classes. - -

    Device Attributes

    - -

    Device attributes are returned by the CUPS-Get-Devices operation and -enumerate all of the available hardware devices and network protocols -that are supported by the server. - -

    device-class (type2 keyword)

    - -

    The device-class attribute specifies the class of device and can be -one of the following: - -

      - -
    • "file" - a disk file. - -
    • "direct" - a parallel or fixed-rate serial data port, - currently used for Centronics, IEEE-1284, and USB printer - ports. - -
    • "serial" - a variable-rate serial port. - -
    • "network" - a network connection, typically via AppSocket, - HTTP, IPP, LPD, or SMB/CIFS protocols. - -
    - -

    device-info (text(127))

    - -

    The device-info attribute specifies a human-readable string describing -the device, e.g. "Parallel Port #1". - -

    device-make-and-model (text(127))

    - -

    The device-makr-and-model attribute specifies a device -identification string provided by the printer connected to the device. -If the device or printer does not support identification then this -attribute contains the string "unknown". - -

    device-uri (uri)

    - -

    The device-uri attribute specifies a unique identifier for the -device. The actual format of the device-uri string depends on the value -of the device-class attribute: - -

      - -
    • "file" - The device-uri will be of the form - "file:/path/to/filename". - -
    • "direct" - The device-uri will be of the form - "method:/dev/filename", where method may be "parallel" or "usb" - in the current implementation. - -
    • "serial" - The device-uri will be of the form - "serial:/dev/filename?baud=value+parity=value+flow=value". - The baud value is the data rate in bits per second; the - supported values depend on the underlying hardware. - The parity value can be one of "none", "even", or "odd". - The flow value can be one of "none", "soft" (XON/XOFF - handshaking), "hard" or "rts/cts" (RTS/CTS handshaking), - or "dtrdsr" (DTR/DSR handshaking). - -

      The URI returned by CUPS-Get-Devices will contain the - maximum baud rate supported by the device and the best - type of flow control available ("soft" or "hard"). - -

    • "network" - The device-uri will be of the form - "method://[username:password@]hostname[:port]/[resource]", - where method may be "http", "ipp", "lpd", "smb", or - "socket" in the current implementation. - -

      The URI returned by CUPS-Get-Devices will only contain - the method name followed by two slashes ("method://"). - It is up to the client application to add the appropriate - host and other information when adding a new printer. - -

      The URI returned by Get-Printer-Attributes and - CUPS-Get-Printers has any username and password information - stripped; the information is still stored and used by the - server internally to perform any needed authentication. - -

    - -

    Job Template Attributes

    - -

    blackplot (boolean)

    - -

    The blackplot attribute specifies whether HP-GL/2 plot files should be -rendered entirely in black ink (blackplot=true) or using the colors and shades -specified in the file (blackplot=false). The default value is false. - -

    brightness (integer(0:200))

    - -

    The brightness attribute specifies the overall brightness of the printed -output in percent. A brightness of 100 is normal, while 200 is twice as -bright and 50 is half as bright. The default value is 100. - -

    Brightness is applied to the Cyan, Magenta, Yellow, and Black values using -the function "f(x) = brightness / 100 * x". - -

    columns (integer(1:4))

    - -

    The columns attribute specifies the number of columns to generate when -printing text files. The default value is 1. - -

    cpi (type2 enum)

    - -

    The cpi attribute specifies the number of characters per inch when -printing text files. Only the values 10, 12, and 17 are currently -supported. The default value is 10. - -

    fitplot (boolean)

    - -

    The fitplot attribute specifies whether to scale HP-GL/2 plot files to -fit on the selected media (fitplot=true) or use the physical scale specified -in the plot file (fitplot=false). The default value is false. - -

    gamma (integer(1:10000))

    - -

    The gamma attribute specifies the luminance correction for the output. -A value of 1000 specifies no correction, while values of 2000 and 500 will -generate lighter and darker output, respectively. The default value is -1000. - -

    Gamma is applied to the Red, Green, and Blue values (or luminance for -grayscale output) using the function "f(x) = x(1000/gamma)". - -

    hue (integer(-180:180))

    - -

    The hue attribute specifies a color hue rotation when printing image -files. The default value is 0. - -

    job-billing (text(MAX))

    - -

    (CUPS 1.1 and higher) - -

    The job-billing attribute provides a text value to associate with a job -for billing purposes. - -

    job-hold-until (keyword | name(MAX))

    - -

    (CUPS 1.1 and higher) - -

    The job-hold-until attribute specifies a hold time. In addition to the -standard IPP/1.1 keyword names, CUPS supports name values of the form -"HH:MM" and "HH:MM:SS" that specify a hold time. The hold time is in -Greenwich Mean Time (GMT) and not in the local time zone. If the -specified time is less than the current time, the job is held until the -next day. - -

    job-sheets (1setof type3 keyword | name(MAX))

    - -

    (CUPS 1.1 and higher) - -

    The job-sheets attribute specifies one or two banner files that are printed -before and after a job. The reserved value of "none" disables banner printing. -The default value is stored in the job-sheets-default attribute. - -

    If only one value is supplied, the banner file is printed before the job. -If two values are supplied, the first value is used as the starting banner -file and the second as the ending banner file. - -

    job-originating-host-name (name(MAX))

    - -

    (CUPS 1.1.5 and higher) - -

    The job-originating-host-name attribute specifies the host -from which the job was queued. The value will be the hostname or -IP address of the client depending on whether hostname -resolution is enabled. The localhost address (127.0.0.1) is -always resolved to the name "localhost". - -

    This attribute is read-only. - -

    lpi (type2 enum)

    - -

    The lpi attribute specifies the number of lines per inch when -printing text files. Only the values 6 and 8 are currently supported. -The default value is 6. - -

    mirror (boolean)

    - -

    The mirror attribute specifies whether pages are mirrored on -their X axis, which is useful for printing transfer images on -special media. The default value is false. - -

    natural-scaling (integer(1:1000))

    - -

    (CUPS 1.1.9 and higher) - -

    The natural-scaling attribute specifies the scaling of image files with -respect to the natural image size. A value of 100 specifies that the image -file should exactly the natural size, while 50 is half the natural size -and 200 is twice the natural size. The default value is 100. - -

    The ppi option can be used to override the natural resolution of the -image, which controls the natural size. - -

    number-up-layout (type2 keyword)

    - -

    (CUPS 1.1.15 and higher) - -

    The number-up-layout attribute specifies the order each input -page is placed on each output page. The following keywords are -presently defined: - -

      - -
    • btlr - Bottom to top, left to right
      • - -
    • btrl - Bottom to top, right to left
      • - -
    • lrbt - Left to right, bottom to top
      • - -
    • lrtb - Left to right, top to bottom (default)
      • - -
    • rlbt - Right to left, bottom to top
      • - -
    • rltb - Right to left, top to bottom
      • - -
    • tblr - Top to bottom, left to right
      • - -
    • tbrl - Top to bottom, right to left
      • - -
    - -

    page-border (type2 keyword)

    - -

    (CUPS 1.1.15 and higher) - -

    The page-border attribute specifies whether a border is -draw around each page. The following keywords are presently -defined: - -

      - -
    • double - Two hairline borders are drawn
      • - -
    • double-thick - Two 1pt borders are drawn
      • - -
    • none - No border is drawn (default)
      • - -
    • single - A single hairline border is drawn
      • - -
    • single-thick - A single 1pt border is drawn
      • - -
    - -

    page-bottom (integer(0:MAX))

    - -

    The page-bottom attribute specifies the bottom margin in points (72 points -equals 1 inch). The default value is the device physical margin. - -

    page-label (text(MAX))

    - -

    (CUPS 1.1.7 and higher) - -

    The page-label attribute provides a text value to place in -the header and footer on each page. If a classification level is -set on the server, then this classification is printed before -the page label. - -

    page-left (integer(0:MAX))

    - -

    The page-left attribute specifies the left margin in points (72 points -equals 1 inch). The default value is the device physical margin. - -

    page-right (integer(0:MAX))

    - -

    The page-right attribute specifies the right margin in points (72 points -equals 1 inch). The default value is the device physical margin. - -

    page-set (type2 keyword)

    - -

    The page-set attribute specifies which pages to print in a file. The -supported keywords are "all", "even", and "odd". The default value is -"all". - -

    page-top (integer(0:MAX))

    - -

    The page-top attribute specifies the top margin in points (72 points -equals 1 inch). The default value is the device physical margin. - -

    penwidth (integer(0:MAX))

    - -

    The penwidth attribute specifies the default pen width in micrometers -when printing HP-GL/2 plot files. The default value is 1000 (1 millimeter). - -

    position (type2 keyword)

    - -

    The position attribute specifies the location of image files on the -media. The following keyword values are recognized: - -

      - -
    • center - Center the image on the page (default) - -
    • top - Print the image centered at the top of the page - -
    • left - Print the image centered on the left of page - -
    • right - Print the image centered on the right of the page - -
    • top-left - Print the image at the top left corner of - the page - -
    • top-right - Print the image at the top right corner of - the page - -
    • bottom - Print the image centered at the bottom of - the page - -
    • bottom-left - Print the image at the bottom left - corner of the page - -
    • bottom-right - Print the image at the bottom right - corner of the page - -
    - -

    ppi (integer(1:MAX))

    - -

    The ppi attribute specifies the resolution of an image file in pixels -per inch. The default value is the resolution included with the file or -128 if no resolution information is available. - -

    prettyprint (boolean)

    - -

    The prettyprint attribute specifies whether text files should be printed -with a shaded header and keyword highlighting (prettyprint=true) or without -additional formatting (prettyprint=false). The default value is false. - -

    saturation (integer(0:200))

    - -

    The saturation attribute specifies the color saturation when -printing image files. A saturation of 100 is normal, while values of 50 -and 200 will be half and twice as colorful, respectively. The default -value is 100. - -

    scaling (integer(1:1000))

    - -

    The scaling attribute specifies the scaling of image files with -respect to the selected media. A value of 100 specifies that the image -file should fit 100% of the page, or as much as possible given the -image dimensions. The default value is unspecified. - -

    The scaling attribute overrides the ppi attribute if specified. - -

    wrap (boolean)

    - -

    The wrap attribute specifies whether long lines should be wrapped -(wrap=true) or not (wrap=false) when printing text files. The default -value is true. - -

    PPD Attributes

    - -

    ppd-natural-language (naturalLanguage)

    - -

    The ppd-natural-language attribute specifies the language encoding -of the PPD file (the LanguageVersion attribute in the PPD file). If the -language is unknown or undefined then "en" (English) is assumed. - -

    ppd-make (text(127))

    - -

    The ppd-make attribute specifies the manufacturer of the printer -(the Manufacturer attribute in the PPD file). If the manufacturer -is not specified in the PPD file then an educated guess is made using -the NickName attribute in the PPD file. - -

    ppd-make-and-model (text(127))

    - -

    The ppd-make-and-model attribute specifies the manufacturer and model -name of the PPD file (the NickName attribute in the PPD file). If the -make and model is not specified in the PPD file then the ModelName or -ShortNickName attributes are used instead. - -

    ppd-name (name(255))

    - -

    The ppd-name attribute specifies the PPD filename on the server -relative to the model directory. The forward slash (/) is used to -delineate directories. - -

    Printer Attributes

    - -

    job-k-limit (integer)

    - -

    (CUPS 1.1 and higher) - -

    The job-k-limit attribute specifies the maximum number of kilobytes that -may be printed by a user, including banner files. The default value of 0 -specifies that there is no limit. - -

    job-page-limit (integer)

    - -

    (CUPS 1.1 and higher) - -

    The job-page-limit attribute specifies the maximum number of pages that -may be printed by a user, including banner files. The default value of 0 -specifies that there is no limit. - -

    job-quota-period (integer)

    - -

    (CUPS 1.1 and higher) - -

    The job-quota-period attribute specifies the time period used for quota -calculations, in seconds. The default value of 0 specifies that the limits -apply to all jobs that have been printed by a user that are still known to -the system. - -

    job-sheets-supported (1setof type3 keyword | name(MAX))

    - -

    (CUPS 1.1 and higher) - -

    The job-sheets-supported attribute specifies the available banner files. -There will always be at least one banner file available called "none". - -

    printer-type (type2 enum)

    - -

    The printer-type attribute specifies printer type and capability bits for -the printer or class. The default value is computed from internal state -information and the PPD file for the printer. The following bits are defined: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    BitDescription
    0x00000001Is a printer class.
    0x00000002Is a remote destination.
    0x00000004Can print in black.
    0x00000008Can print in color.
    0x00000010Can print on both sides of the page in hardware.
    0x00000020Can staple output.
    0x00000040Can do fast copies in hardware.
    0x00000080Can do fast copy collation in hardware.
    0x00000100Can punch output.
    0x00000200Can cover output.
    0x00000400Can bind output.
    0x00000800Can sort output.
    0x00001000Can handle media up to US-Legal/A4.
    0x00002000Can handle media from US-Legal/A4 to ISO-C/A2.
    0x00004000Can handle media larger than ISO-C/A2.
    0x00008000Can handle user-defined media sizes.
    0x00010000Is an implicit (server-generated) class.
    - -

    printer-type-mask (type2 enum)

    - -

    (CUPS 1.1 and higher) - -

    The printer-type-mask attribute is used to choose printers or classes with -the CUPS-Get-Printers and CUPS-Get-Classes operations. The bits are defined -identically to the printer-type attribute and default to all 1's. - -

    requesting-user-name-allowed (1setof name(127))

    - -

    (CUPS 1.1 and higher) - -

    The requesting-user-name-allowed attribute lists all of the users that are -allowed to access a printer or class. Either this attribute or the -requesting-user-name-denied attribute will be defined, but not both. - -

    requesting-user-name-denied (1setof name(127))

    - -

    (CUPS 1.1 and higher) - -

    The requesting-user-name-denied attribute lists all of the users that are -not allowed to access a printer or class. Either this attribute or the -requesting-user-name-allowed attribute will be defined, but not both. - -

    Printer Class Attributes

    - -

    member-names (1setof name(127))

    - -

    The member-names attribute specifies each of the printer-name attributes of -the member printers and classes. Each name corresponds to the same element of -the member-uris attribute. - -

    member-uris (1setof uri)

    - -

    The member-uris attribute specifies each of the printer-uri attributes of -the member printers and classes. Each URI corresponds to the same element of -the member-names attribute. - - - - - diff --git a/doc/ja/images/accept-jobs.gif b/doc/ja/images/button-accept-jobs.gif similarity index 100% rename from doc/ja/images/accept-jobs.gif rename to doc/ja/images/button-accept-jobs.gif diff --git a/doc/ja/images/add-class.gif b/doc/ja/images/button-add-class.gif similarity index 100% rename from doc/ja/images/add-class.gif rename to doc/ja/images/button-add-class.gif diff --git a/doc/ja/images/add-printer.gif b/doc/ja/images/button-add-printer.gif similarity index 100% rename from doc/ja/images/add-printer.gif rename to doc/ja/images/button-add-printer.gif diff --git a/doc/ja/images/add-this-printer.gif b/doc/ja/images/button-add-this-printer.gif similarity index 100% rename from doc/ja/images/add-this-printer.gif rename to doc/ja/images/button-add-this-printer.gif diff --git a/doc/ja/images/cancel-all-jobs.gif b/doc/ja/images/button-cancel-all-jobs.gif similarity index 100% rename from doc/ja/images/cancel-all-jobs.gif rename to doc/ja/images/button-cancel-all-jobs.gif diff --git a/doc/ja/images/cancel-job.gif b/doc/ja/images/button-cancel-job.gif similarity index 100% rename from doc/ja/images/cancel-job.gif rename to doc/ja/images/button-cancel-job.gif diff --git a/doc/ja/images/change-settings.gif b/doc/ja/images/button-change-settings.gif similarity index 100% rename from doc/ja/images/change-settings.gif rename to doc/ja/images/button-change-settings.gif diff --git a/doc/ja/images/continue.gif b/doc/ja/images/button-continue.gif similarity index 100% rename from doc/ja/images/continue.gif rename to doc/ja/images/button-continue.gif diff --git a/doc/ja/images/delete-class.gif b/doc/ja/images/button-delete-class.gif similarity index 100% rename from doc/ja/images/delete-class.gif rename to doc/ja/images/button-delete-class.gif diff --git a/doc/ja/images/delete-printer.gif b/doc/ja/images/button-delete-printer.gif similarity index 100% rename from doc/ja/images/delete-printer.gif rename to doc/ja/images/button-delete-printer.gif diff --git a/doc/ja/images/edit-configuration-file.gif b/doc/ja/images/button-edit-configuration-file.gif similarity index 100% rename from doc/ja/images/edit-configuration-file.gif rename to doc/ja/images/button-edit-configuration-file.gif diff --git a/doc/ja/images/export-samba.gif b/doc/ja/images/button-export-samba.gif similarity index 100% rename from doc/ja/images/export-samba.gif rename to doc/ja/images/button-export-samba.gif diff --git a/doc/ja/images/help.gif b/doc/ja/images/button-help.gif similarity index 100% rename from doc/ja/images/help.gif rename to doc/ja/images/button-help.gif diff --git a/doc/ja/images/hold-job.gif b/doc/ja/images/button-hold-job.gif similarity index 100% rename from doc/ja/images/hold-job.gif rename to doc/ja/images/button-hold-job.gif diff --git a/doc/ja/images/manage-classes.gif b/doc/ja/images/button-manage-classes.gif similarity index 100% rename from doc/ja/images/manage-classes.gif rename to doc/ja/images/button-manage-classes.gif diff --git a/doc/ja/images/manage-jobs.gif b/doc/ja/images/button-manage-jobs.gif similarity index 100% rename from doc/ja/images/manage-jobs.gif rename to doc/ja/images/button-manage-jobs.gif diff --git a/doc/ja/images/manage-printers.gif b/doc/ja/images/button-manage-printers.gif similarity index 100% rename from doc/ja/images/manage-printers.gif rename to doc/ja/images/button-manage-printers.gif diff --git a/doc/ja/images/manage-server.gif b/doc/ja/images/button-manage-server.gif similarity index 100% rename from doc/ja/images/manage-server.gif rename to doc/ja/images/button-manage-server.gif diff --git a/doc/ja/images/modify-class.gif b/doc/ja/images/button-modify-class.gif similarity index 100% rename from doc/ja/images/modify-class.gif rename to doc/ja/images/button-modify-class.gif diff --git a/doc/ja/images/modify-printer.gif b/doc/ja/images/button-modify-printer.gif similarity index 100% rename from doc/ja/images/modify-printer.gif rename to doc/ja/images/button-modify-printer.gif diff --git a/doc/ja/images/move-job.gif b/doc/ja/images/button-move-job.gif similarity index 100% rename from doc/ja/images/move-job.gif rename to doc/ja/images/button-move-job.gif diff --git a/doc/ja/images/move-jobs.gif b/doc/ja/images/button-move-jobs.gif similarity index 100% rename from doc/ja/images/move-jobs.gif rename to doc/ja/images/button-move-jobs.gif diff --git a/doc/ja/images/print-test-page.gif b/doc/ja/images/button-print-test-page.gif similarity index 100% rename from doc/ja/images/print-test-page.gif rename to doc/ja/images/button-print-test-page.gif diff --git a/doc/ja/images/publish-printer.gif b/doc/ja/images/button-publish-printer.gif similarity index 100% rename from doc/ja/images/publish-printer.gif rename to doc/ja/images/button-publish-printer.gif diff --git a/doc/ja/images/reject-jobs.gif b/doc/ja/images/button-reject-jobs.gif similarity index 100% rename from doc/ja/images/reject-jobs.gif rename to doc/ja/images/button-reject-jobs.gif diff --git a/doc/ja/images/release-job.gif b/doc/ja/images/button-release-job.gif similarity index 100% rename from doc/ja/images/release-job.gif rename to doc/ja/images/button-release-job.gif diff --git a/doc/ja/images/restart-job.gif b/doc/ja/images/button-restart-job.gif similarity index 100% rename from doc/ja/images/restart-job.gif rename to doc/ja/images/button-restart-job.gif diff --git a/doc/ja/images/save-changes.gif b/doc/ja/images/button-save-changes.gif similarity index 100% rename from doc/ja/images/save-changes.gif rename to doc/ja/images/button-save-changes.gif diff --git a/doc/ja/images/search.gif b/doc/ja/images/button-search.gif similarity index 100% rename from doc/ja/images/search.gif rename to doc/ja/images/button-search.gif diff --git a/doc/ja/images/set-allowed-users.gif b/doc/ja/images/button-set-allowed-users.gif similarity index 100% rename from doc/ja/images/set-allowed-users.gif rename to doc/ja/images/button-set-allowed-users.gif diff --git a/doc/ja/images/set-as-default.gif b/doc/ja/images/button-set-as-default.gif similarity index 100% rename from doc/ja/images/set-as-default.gif rename to doc/ja/images/button-set-as-default.gif diff --git a/doc/ja/images/set-printer-options.gif b/doc/ja/images/button-set-printer-options.gif similarity index 100% rename from doc/ja/images/set-printer-options.gif rename to doc/ja/images/button-set-printer-options.gif diff --git a/doc/ja/images/show-active.gif b/doc/ja/images/button-show-active.gif similarity index 100% rename from doc/ja/images/show-active.gif rename to doc/ja/images/button-show-active.gif diff --git a/doc/ja/images/show-all.gif b/doc/ja/images/button-show-all.gif similarity index 100% rename from doc/ja/images/show-all.gif rename to doc/ja/images/button-show-all.gif diff --git a/doc/ja/images/show-completed.gif b/doc/ja/images/button-show-completed.gif similarity index 100% rename from doc/ja/images/show-completed.gif rename to doc/ja/images/button-show-completed.gif diff --git a/doc/ja/images/show-next.gif b/doc/ja/images/button-show-next.gif similarity index 100% rename from doc/ja/images/show-next.gif rename to doc/ja/images/button-show-next.gif diff --git a/doc/ja/images/show-previous.gif b/doc/ja/images/button-show-previous.gif similarity index 100% rename from doc/ja/images/show-previous.gif rename to doc/ja/images/button-show-previous.gif diff --git a/doc/ja/images/sort-ascending.gif b/doc/ja/images/button-sort-ascending.gif similarity index 100% rename from doc/ja/images/sort-ascending.gif rename to doc/ja/images/button-sort-ascending.gif diff --git a/doc/ja/images/sort-descending.gif b/doc/ja/images/button-sort-descending.gif similarity index 100% rename from doc/ja/images/sort-descending.gif rename to doc/ja/images/button-sort-descending.gif diff --git a/doc/ja/images/start-class.gif b/doc/ja/images/button-start-class.gif similarity index 100% rename from doc/ja/images/start-class.gif rename to doc/ja/images/button-start-class.gif diff --git a/doc/ja/images/start-printer.gif b/doc/ja/images/button-start-printer.gif similarity index 100% rename from doc/ja/images/start-printer.gif rename to doc/ja/images/button-start-printer.gif diff --git a/doc/ja/images/stop-class.gif b/doc/ja/images/button-stop-class.gif similarity index 100% rename from doc/ja/images/stop-class.gif rename to doc/ja/images/button-stop-class.gif diff --git a/doc/ja/images/stop-printer.gif b/doc/ja/images/button-stop-printer.gif similarity index 100% rename from doc/ja/images/stop-printer.gif rename to doc/ja/images/button-stop-printer.gif diff --git a/doc/ja/images/unpublish-printer.gif b/doc/ja/images/button-unpublish-printer.gif similarity index 100% rename from doc/ja/images/unpublish-printer.gif rename to doc/ja/images/button-unpublish-printer.gif diff --git a/doc/ja/images/use-default-config.gif b/doc/ja/images/button-use-default-config.gif similarity index 100% rename from doc/ja/images/use-default-config.gif rename to doc/ja/images/button-use-default-config.gif diff --git a/doc/ja/images/view-access-log.gif b/doc/ja/images/button-view-access-log.gif similarity index 100% rename from doc/ja/images/view-access-log.gif rename to doc/ja/images/button-view-access-log.gif diff --git a/doc/ja/images/view-error-log.gif b/doc/ja/images/button-view-error-log.gif similarity index 100% rename from doc/ja/images/view-error-log.gif rename to doc/ja/images/button-view-error-log.gif diff --git a/doc/ja/images/view-page-log.gif b/doc/ja/images/button-view-page-log.gif similarity index 100% rename from doc/ja/images/view-page-log.gif rename to doc/ja/images/button-view-page-log.gif diff --git a/doc/ja/images/cancel.gif b/doc/ja/images/cancel.gif deleted file mode 100644 index b182a5d87a..0000000000 Binary files a/doc/ja/images/cancel.gif and /dev/null differ diff --git a/doc/ja/index.html.in b/doc/ja/index.html.in index 02c50a892e..5b348005ae 100644 --- a/doc/ja/index.html.in +++ b/doc/ja/index.html.in @@ -8,14 +8,14 @@ - + - - +

    Common UNIX Printing System @CUPS_VERSION@@CUPS_REVISION@
    +
    - - - An Overview of the Common UNIX Printing System - - - - - - - - - -
    CUPS Logo

    An Overview of the
    - Common UNIX Printing System,
    - Version 1.2

    - -

    July 3, 2004
    - Michael Sweet, Easy Software Products
    - Copyright 1998-2004, All Rights Reserved.

    -
    - -
    -New Outline:
-
-New Features:
-
-1. Networking
-   a. IPv6
-        i. Next-generation Internet support
-       ii. ????
-   b. Domain sockets
-        i. Enhanced performance under load for local clients.
-       ii. Authentication without passwords on platforms that support it.
-   c. CUPS browsing updates
-        i. "Delete" bit for printers
-       ii. "lease-time" for printers so that clients and servers don't need
-          the same browse timeout/interval settings
-      iii. Additional attributes/default options for network-wide defaults
-       iv. Network default printer
-        v. Ability to control send and receive protocols independently
-   d. Rendevous support
-   e. LDAP support
-   f. Per-printer sharing
-
-2. IPP Support
-   a. Notifications
-   b. Document object
-   c. Send-URI, Print-URI
-   d. Other stuff?
-   e. Add/delete device operations
-
-3. Scheduler
-   a. Backchannel support
-   b. Port monitor support
-   c. Device monitor
-      i. Dynamic device discovery/management
-   d. All errors include a localized message.
-   e. Fine-grain policies, server default + per-printer
-   f. UTF-8 throughout
-
-4. Web Interface
-   a. cupsd.conf interface
-   b. Move-Job
-   c. Export printers to windows
-   d. Per-printer sharing controls
-   e. Per-printer access control lists 
-   f. Policy stuff
-
-5. I18N
-   a. Support for ... character sets
-   b. All commands and messages are localized
-   c. Character set transcoding
-   d. ... , and Japanese localizations
-
-6. Drivers
-   a. New HP-RTL driver.
-
-
    - -

    This whitepaper describes the Common UNIX Printing -SystemTM (CUPSTM), a portable and -extensible printing system for Linux®, -MacOS® X, UNIX®. CUPS is developed -by Easy Software Products, a -software firm located in Hollywood, Maryland that has been -selling commercial software for UNIX since 1993 through more -than 40 distributors serving over 80 countries worldwide.

    - -

    CUPS is used by Apple to provide printing on MacOS X and is -the defacto-standard for Linux. Additional information on CUPS -is available on the World Wide Web at the following URL:

    - -
    -    http://www.cups.org/
-
    - - -

    Background

    - -

    Printing within UNIX has historically been done using one of -two printing systems - the Berkeley Line Printer Daemon (LPD) -[RFC1179] and the AT&T Line Printer system. These printing -systems were designed in the 70's for printing text to line -printers; vendors have since added varying levels of support for -other types of printers.

    - -

    Replacements for these printing systems have emerged [LPRng, -Palladin, PLP], however none of the replacements change the -fundamental capabilities of these systems.

    - -

    Over the years several attempts at developing a standard -printing interface have been made, including the draft POSIX -Printing standard developed by the Institute of Electrical and -Electronics Engineers, Inc. (IEEE) [IEEE-1387.4] and Internet -Printing Protocol (IPP) developed by the Internet Engineering -Task Force (IETF) through the Printer Working Group (PWG) -[IETF-IPP]. The POSIX printing standard defines a common set of -command-line tools as well as a C interface for printer -administration and print jobs, but has been shelved by the -IEEE.

    - -

    The Internet Printing Protocol defines extensions to the -HyperText Transport Protocol 1.1 [RFC2616] to provide support -for remote printing services. IPP/1.1 was accepted by the IETF -as a proposed standard in ??? of ???. Unlike POSIX Printing, IPP -enjoys widespread industry support and has become the standard -network printing solution for all operating systems.

    - -

    CUPS uses IPP/1.1 to provide a complete, modern printing -system for UNIX that can be extended to support new printers, -devices, and protocols while providing compatibility with -existing UNIX applications. CUPS is free software provided under -the terms of the GNU General Public License and GNU Library -General Public License.

    - -

    History

    - -

    The first production release of CUPS (based on IPP/1.0) was -released in October of 1999. Version 1.1 of CUPS was released in -August of 2002 ???? and added support for IPP/1.1.

    - -

    CUPS 1.2 is based on IPP/1.1 and adds many of the functional -enhancements that have been requested by our users. As with CUPS -1.1, CUPS 1.2 will be followed by patch releases that address -any problems found with the software. New features will be put -in the 1.3 release to follow.

    - -

    Design Overview

    - -

    Like most printing systems, CUPS is designed around a central -print scheduling process that dispatches print jobs, processes -administrative commands, provides printer status information to -local and remote programs, and informs users as needed. Figure 1 -shows the basic organization of CUPS.

    - -

    CUPS Block Diagram
    -Figure 1 - CUPS Block Diagram

    - -

    Scheduler

    - -

    The scheduler is a HTTP/1.1 server application that handles -HTTP requests. Besides handling printer requests via IPP POST -requests, the scheduler also acts as a full-featured web server -for documentation, status monitoring, and administration.

    - -

    The scheduler also manages a list of available printers on -the LAN and dispatches print jobs as needed using the -appropriate filters and backends.

    - -

    Configuration Files

    - -

    The configuration files consist of:

    - -
      - -
    • The HTTP server configuration file.
      • - -
    • Printer and class definition files.
      • - -
    • MIME type and conversion rule files.
      • - -
    • PostScript Printer Description (PPD) files.
      • - -
    - -

    The HTTP server configuration file is purposely similar to -the Apache server configuration file and defines all of the -access control properties for the server.

    - -

    The printer and class definition files list the available -printer queues and classes. Printer classes are collections of -printers. Jobs sent to a class are forwarded to the first -available printer in the class, round-robin fashion.

    - -

    The MIME type files list the supported MIME types -(text/plain, application/postscript, etc.) and "magic' rules for -automatically detecting the format of a file. These are used by -the HTTP server to determine the Content-Type field for -GET and HEAD requests and by the IPP request -handler to determine the file type when a Print-Job or -Send-File request is received with a -document-format of -application/octet-stream.

    - -

    The MIME conversion rule files list the available filters. -The filters are used when a job is dispatched so that an -application can send a convenient file format to the printing -system which then converts the document into a printable format -as needed. Each filter has a relative cost associated with it, -and the filtering algorithm chooses the set of filters that will -convert the file to the needed format with the lowest total -"cost".

    - -

    The PPD files describe the capabilities of all printers, not -just PostScript printers. There is one PPD file for each -printer. PPD files for non-PostScript printers define additional -filters through cupsFilter attributes to support -printer drivers.

    - -

    CUPS API

    - -

    The CUPS API contains CUPS-specific convenience functions for -queuing print jobs, getting printer information, accessing -resources via HTTP and IPP, and manipulating PPD files. Unlike -the rest of CUPS, the CUPS API is provided under the terms of -the GNU LGPL so it may be used by non-GPL applications.

    - -

    Berkeley and System V Commands

    - -

    CUPS provides the System V and Berkeley command-line -interfaces for submitting jobs and checking the printer status. -The lpstat and lpc status commands -also show network printers ("printer@server") when printer -browsing is enabled.

    - -

    The System V administation commands are supplied for managing -printers and classes. The Berkeley printer administration tool -(lpc) is only supported in a "read-only' mode to -check the current status of the printer queues and -scheduler.

    - -

    Filters

    - -

    A filter program reads from the standard input or from a file -if a filename is supplied. All filters must support a common set -of options including printer name, job ID, username, job title, -number of copies, and job options. All output is sent to the -standard output.

    - -

    Filters are provided for many file formats and include image -file and PostScript raster filters that support non-PostScript -printers. Multiple filters are run in parallel to produce the -required output format.

    - -

    The PostScript raster filter is based on the ESP Ghostscript -core. Instead of using the Ghostscript printer drivers, the CUPS -filter uses a generic CUPS raster printer driver and -CUPS-compliant front-end to support any kind of raster printer. -This allows the same printer driver filter to be used for -printing raster data from any filter.

    - -
    Talk about Apple's use of CUPS...
    - -

    CUPS Imaging

    - -

    The CUPS Imaging library provides functions for managing -large images, doing colorspace conversion and color management, -scaling images for printing, and managing raster page streams. -It is used by the CUPS image file filters, the PostScript RIP, -and all raster printers drivers.

    - -

    Backends

    - -

    A backend program is a special filter that sends print data -to a device or network connection. Backends for parallel, -serial, USB, LPD, IPP, and AppSocket (JetDirect) connections are -provided in CUPS 1.2.

    - -

    SAMBA version 2.0.6 and higher includes a SMB backend -(smbspool(1)) that can be used for printing to -Windows.

    - -

    Network Printing

    - -

    Traditionally, network printing has been one of the hardest -things to get working under UNIX. One reason is because each -vendor added their own extensions to the LPD protocol (the -previous standard for network printing), making cross-platform -printing difficult if not impossible.

    - -

    Another reason is that you have to administer every network -printer on every client machine. In some cases you can "clone' -the printer configuration from a "master' client to each of the -others, but even that can be time-consuming and error-prone. -Something better is needed.

    - -

    CUPS provides "printer browsing", which allows clients to -automatically see and use printers from any server on a LAN. -This means that you only need to configure the server and the -clients will automatically see the printers and classes on -it.

    - -

    In addition, CUPS can automatically merge multiple identical -network printers into "implicit classes". This allows clients to -send jobs to the implicit class and have them print on the first -available printer or server. In addition, failsafe and -load-balancing functions are enabled simply by defining the same -printer on multiple servers!

    - -

    New Features in CUPS 1.2

    - -

    CUPS 1.2 includes many new features and capabilities: - -

      - -
    1. Backends - -
    2. Banner Page Support - -
    3. Digest Authentication - -
    4. Directory Services - -
    5. Directory Structure Changes - -
    6. Documentation - -
    7. Drivers - -
    8. Filters - -
    9. IPP Support - -
    10. Job Persistence - -
    11. LPD Client Support - -
    12. User-Defined Printers and Options - -
    13. Web Administration Interface - -
    - -

    1. Backends

    - -

    CUPS 1.2 implements a new backend interface for retrieving a -list of available devices for CUPS clients. This allows -administration interfaces to query the CUPS scheduler for a list -of available devices, automatically configure printers if the -device identification information is available, and present the -user with a list of available devices rather than relying on the -user to know what devices are configured on the system.

    - -

    The new release also includes a backend for USB printers -under *BSD and Linux. Support for USB under Solaris 8 will be -provided in a subsequent patch release.

    - -

    2. Banner Page Support

    - -

    CUPS 1.2 includes support for banner pages at the beginning -and end of a job. Banner pages may be of any file format and -support variable substitution for job titles, usernames, etc. -Default banner pages are associated with each printer and can be -overridden with command-line options by the user.

    - -

    3. Digest Authentication

    - -

    Digest authentication provides a more secure method of -authenticating access to the printing system. Unlike Basic -authentication, Digest authentication does not send passwords -"in the clear' so it is more difficult to gain unauthorized -access to your system.

    - -

    CUPS 1.2 implements Digest authentication using a special MD5 -password file instead of the UNIX password file. This file is -managed using the new lppasswd command.

    - -

    4. Directory Services

    - -

    CUPS 1.2 adds new directory service ("printer browsing") -features to make using CUPS on large LANs and WANs easier. You -can now poll a remote server for printer information and relay -it to the LAN as well as restrict what printer information is -processed (e.g. to "hide" servers, domains, or networks that you -don't want to see.)

    - -

    5. Directory Structure Changes

    - -

    CUPS 1.2 now uses a directory structure that complies with -the Filesystem Hierarchy Standard (FHS), version 2.0. This -should make integration into existing Linux and *BSD -distributions a lot easier.

    - -

    6. Documentation

    - -

    The CUPS 1.2 documentation has gone through many revisions, -including a completely rewritten administrators manual, a new -programmers manual, and an IPP implementation reference -manual.

    - -

    7. Drivers

    - -

    CUPS 1.2 includes drivers for EPSON dot-matrix and inkjet -printers. As with the HP PCL drivers, the EPSON drivers don't -necessarily provide the best possible output for each printer -but should provide adequate printing quality for general -day-to-day printing.

    - -

    8. Filters

    - -

    CUPS 1.2 includes new image, PostScript, PDF, and text -filters. The image filters have been upgraded to support Windows -BMP and Alias PIX files.

    - -

    The PostScript filter is now based off ESP Ghostscript. The -new filter provides much better performance with -higher-resolution printers and supports all Level 3 PostScript -language features.

    - -

    The new PDF filter is based off the excellent Xpdf software -from Derek Noonburg and supports automatic page scaling. The new -filter is a faster, smaller, more reliable replacement for the -GNU Ghostscript PDF filtering that was used in CUPS 1.0.

    - -

    The new text filter now supports bidirectional text and can -embed fonts as needed.

    - -

    9. IPP Support

    - -

    Probably the least visible portion of CUPS is the IPP -support. CUPS 1.1 implements all of the required IPP/1.1 -operations and attributes and most of the optional ones. The -optional Create-Job and Send-File operations are now -implemented, allowing for better System V printing system -compatibility (one job ID per lp command) and support -for banner pages.

    - -

    10. Job Persistence

    - -

    CUPS 1.2 supports job persistence. This means that jobs are -preserved even after a reboot, a feature that was sorely missing -from CUPS 1.0.

    - -

    In addition, CUPS 1.2 allows you to keep job information -after the job has printed. The basic post-job persistence mode -provides a job history (number of pages printed, time job was -printed, etc.) but does not preserve the actual job files. This -can be changed to discard all information after a job is printed -or keep the job files after printing so you can reprint a job at -some later time.

    - -

    11. LPD Client Support

    - -

    By popular request, CUPS 1.2 supports LPD-based clients using -a new mini-daemon that handles LPD requests and passes them on -to the main server.

    - -

    12. User-Defined Printers and Options

    - -

    CUPS 1.2 includes support for user-defined printers and -options via a new lpoptions command. User-defined -printers are special instances of the available printers (e.g. -"printer/instance" or "printer@server/instance") that can have -their own default options such as media size, resolution, and so -forth. The lpoptions command can also be used to set a -different default printer queue.

    - -

    13. Web Administration Interface

    - -

    CUPS 1.0 provided a simple class, job, and printer monitoring -interface for web browsers. CUPS 1.2 replaces this interface -with an enhanced administration interface that allows you to -add, modify, delete, configure, and control classes, jobs, and -printers.

    - -

    Software Using CUPS

    - -

    A lot has happened since CUPS 1.0 came out, and many software -packages are supporting CUPS. We have contributed code to the -SAMBA team to support CUPS, and parts of that are already -available in SAMBA 2.0.6 and 2.0.7. With any luck the final -pieces that provide a complete integration with SAMBA will be -available in the next release of SAMBA.

    - -

    Two graphical interfaces have appeared on the scene that use -CUPS as well. The KUPS project provides a KDE-based interface -for CUPS and can be found at:

    - -
    -    http://kups.sourceforge.net
-
    - -

    The X Printing Panel (XPP) project provides a graphical -printing panel for CUPS and can be found at:

    - -
    -    http://www.phy.uni-bayreuth.de/till/xpp/
-
    - -

    Numerous other filters, drivers, tutorials, etc. have been -made available on the CUPS Links web page, available at:

    - -
    -    http://www.cups.org/links.php
-
    - -

    Finally, our own ESP Print Pro software uses CUPS to provide -drivers for thousands of printers and can be found at:

    - -
    -    http://www.easysw.com/printpro
-
    - -

    Operating Systems Using CUPS

    - -

    One of our goals has always been to get as many UNIX/Linux -distributions using CUPS as possible. Debian is currently -providing CUPS as part of its stable distribution, and many -other distributions are considering it in their next -releases.

    - -

    Summary

    - -

    The Common UNIX Printing System provides a modern printing -interface for UNIX applications that is both flexible and -user-friendly. The software provides System V and Berkeley -compatible command-line interfaces to ensure compatibility with -existing applications. CUPS 1.2 adds many new features that make -it an even better choice for printing under UNIX.

    - -

    Who to Contact

    - -

    For more information on CUPS please contact us at: - -

    -    Attn: CUPS Information
-    Easy Software Products
-    44141 Airport View Drive Suite 204
-    Hollywood, Maryland 20636-3142 USA
-
-    +1.301.373.9600
-
-    cups-info@cups.org
-
    - -

    References

    - -
    - -
    IEEE-1387.4
    - -
    System Administration - Part 4: Printing Interfaces - (draft)
    - -
    IETF-IPP
    - -
    Internet Printing Protocol/1.1
    - -
    LPRng
    - -
    An enhanced, extended, and portable implementation - of the Berkeley LPR print spooler functionality
    - -
    Palladin
    - -
    A printing system developed at the Massachussetts - Institute of Technology
    - -
    PLP
    - -
    The Portable Line Printer spooler system
    - -
    RFC1179
    - -
    Line Printer Daemon Protocol
    - -
    RFC2046
    - -
    Multipurpose Internet Mail Extensions (MIME) Part - Two: Media Types
    - -
    RFC2616
    - -
    Hypertext Transfer Protocol -- HTTP/1.1
    - -
    - -

    Trademarks

    - -

    The Common UNIX Printing System, CUPS, and the CUPS logo are -the trademark property of Easy Software Products. All other -trademarks are the property of their respective owners.

    - - - diff --git a/doc/overview.pdf b/doc/overview.pdf deleted file mode 100644 index ada9b01a55..0000000000 Binary files a/doc/overview.pdf and /dev/null differ diff --git a/doc/ppd.shtml b/doc/ppd.shtml deleted file mode 100644 index fb86322dbe..0000000000 --- a/doc/ppd.shtml +++ /dev/null @@ -1,334 +0,0 @@ - - - CUPS PostScript Printer Description (PPD) File Specification - - - - - - - -

    Scope

    - -

    Identification

    - -

    This document describes the PostScript Printer Description -(PPD) file format and the supported extensions for the Common -UNIX Printing System ("CUPS") Version 1.2. It should be used in -conjunction with the Adobe PostScript Printer Description File -Format Specification, Version 4.3 when creating PPD files for -CUPS.

    - - - -

    Document Overview

    - -

    This CUPS PostScript Printer Description File Specification -document is organized into the following sections:

    - -
      - -
    • 1 - Scope
      • - -
    • 2 - References
      • - -
    • 3 - PPD File Syntax
      • - -
    • 4 - General Attributes
      • - -
    • 5 - Custom Options
      • - -
    • 6 - Color Profiles
      • - -
    • 7 - I18N Support
      • - -
    • A - Glossary
      • - -
    • B - Change History
      • - -
    - - - -

    PPD File Syntax

    - -

    PostScript Printer Description ("PPD") files describe the -capabilities of each printer and are used by CUPS to support -printer-specific features and intelligent filtering.

    - -

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

    - -

    The format is text-based and uses lines of up to 255 -characters terminated by a carriage return, linefeed, or -combination of carriage return and line feed. The following ABNF -definition [RFC2234] defines the general format of lines in a -PPD file:

    - -
    -    PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
-
-    HEADER   = "*" 0x50.50.44.2D.41.64.6F.62.65 ":"   ; *PPD-Adobe:
-               *WSP DQUOTE "4.3" DQUOTE LINE-END
-
-    COMMENT  = "*%" *TCHAR LINE-END
-
-    DATA     = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
-               1*(*WSP VALUE) LINE-END
-
-    VALUE    = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
-
-    KCHAR    = ALPHA / DIGIT / "_" / "." / "-"
-
-    SCHAR    = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
-
-    TCHAR    = %x20-7E / %xA0-FF
-
-    LINE-END = CR / LF / CR LF
-
    - - -

    General Attributes

    - -

    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.

    - -

    cupsFlipDuplex

    - -

    This boolean attribute notifies the RIP filters that the -destination printer requires an upside-down image for the back -page. The default value is false.

    - -

    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.

    - -

    cupsProtocol

    - -

    This optional attribute describes which binary communication -protocol to use when printing binary PostScript data. The -strings "None", "BCP", and "TBCP" are recognized, corresponding -to no encoding, BCP, and TBCP respectively.

    - -

    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", "1.1", or "1.2".

    - - -

    Custom Options

    - - -

    Color Profiles

    - -

    cupsColorProfile

    - -

    This string attribute specifies a color profile of the -form:

    - -
    -    *cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
-
    - -

    The Resolution and MediaType 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:

    - -
    -    | m00 m01 m02 |
-    | m10 m11 m12 |
-    | m20 m21 m22 |
-
    - -

    cupsICCProfile

    - -

    This attribute specifies an ICC color profile of the -form:

    - -
    -    *cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
-
    - -

    The ColorModel, MediaType, and -Resolution keywords specify a selector for color -profiles. If omitted, the color profile will match any option -keyword for the corresponding main keyword.

    - -

    The Description specifies human-readable text that -is associated with the color profile. The filename -portion specifies the ICC color profile to use; if the filename -is not absolute, it is loaded relative to the -/usr/share/cups/profiles directory.

    - -

    Customizing the Profile Selection Keywords

    - -

    The ColorModel, MediaType, and -Resolution keywords can be reassigned to different main -keywords, allowing drivers to do color profile selection based -on different parameters. The cupsICCQualifier1, -cupsICCQualifier2, and cupsICCQualifier3 -attributes define the mapping from selector to main keyword:

    - -
    -    *cupsICCQualifier1: MainKeyword
-    *cupsICCQualifier2: MainKeyword
-    *cupsICCQualifier3: MainKeyword
-
    - -

    The default mapping is as follows:

    - -
    -    *cupsICCQualifier1: ColorModel
-    *cupsICCQualifier2: MediaType
-    *cupsICCQualifier3: Resolution
-
    - -

    I18N Support

    - -

    CUPS 1.2 and higher adds support for PPD files containing multiple -languages by following the following rules:

    - -
      - -
    1. The LanguageVersion is English
      2. - -
    2. The LanguageEncoding is ISOLatin1
      3. - -
    3. Main and option keywords may not exceed 34 - characters, which is a subset of what the Adobe PPD spec - allows.
      4. - -
    4. Translations are specified using a locale prefix of - the form "ll" or "ll_CC." where "ll" is the 2-letter ISO - language code and "CC" is the 2-letter ISO country - code
      5. - -
    5. Translation strings are encoded using UTF-8.
      6. - -
    6. Main keywords are translated using any of the - following forms: -

      *ll.Translation MainKeyword/translation - text: ""
      - *ll_CC.Translation MainKeyword/translation - text: ""

      7. - -
    7. Option keywords are translated using any of the - following forms: -

      *ll.MainKeyword OptionKeyword/translation - text: ""
      - *ll_CC.MainKeyword OptionKeyword/translation - text: ""

      8. - -
    - -

    The following example shows how a fictional Foobar Laser 9999 -PPD file would be localized for English, French, and German:

    - -
    -    *LanguageVersion: English
-    *LanguageEncoding: ISOLatin1
-    *ModelName: "Foobar Laser 9999"
-    *fr_FR.Translation ModelName/La Foobar Laser 9999: ""
-    *de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
-    ...
-    *OpenUI *InputSlot/Paper Source: PickOne
-    *OrderDependency: 10 AnySetup *InputSlot
-    *DefaultInputSlot: Auto
-    *fr_FR.Translation InputSlot/Papier source: ""
-    *de_DE.Translation InputSlot/Papiereinzug: ""
-    *InputSlot Auto/Default: "<>setpagedevice"
-    *fr_FR.InputSlot Auto/Par Defaut: ""
-    *de_DE.InputSlot Auto/Standard: ""
-    *InputSlot Manual/Manual Feed: "<>setpagedevice"
-    *fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
-    *de_DE.InputSlot Manual/Manueller Einzug: ""
-    *CloseUI: *InputSlot
-
    - - - -

    Change History

    - -

    Changes in CUPS 1.2

    - -
      - -
    • cupsICCProfile
      • - -
    • New I18N support
      • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    - -

    Changes in CUPS 1.1

    - -
      - -
    • cupsProtocol
      • - -
    • cupsFlipDuplex
      • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    • - -
    - - - diff --git a/doc/references.shtml b/doc/references.shtml deleted file mode 100644 index 6a8dd82dfa..0000000000 --- a/doc/references.shtml +++ /dev/null @@ -1,42 +0,0 @@ -

    References

    - -

    CUPS Documentation

    - -

    The following CUPS documentation is referenced by this document: - -

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

    Other Documents

    - -

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

    diff --git a/doc/sam.html b/doc/sam.html deleted file mode 100644 index 85e9e4bcce..0000000000 --- a/doc/sam.html +++ /dev/null @@ -1,5281 +0,0 @@ - - - -CUPS Software Administrators Manual - - - - - - - -

    -

    CUPS Software Administrators Manual


    -CUPS-SAM-1.2.0
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    Preface - -1 - Printing System Overview - -2 - Building and Installing CUPS - -3 - Managing Printers - -4 - Printer Classes - -5 - Client Setup - -6 - Printing System Management - -7 - Printing with Other Systems - -A - Software License Agreement - -B - Common Network Settings - -C - Printer Drivers - -D - List of Files -
    -
    E - Troubleshooting Common Problems - -
    -

    Preface

    -

    This software administrators manual provides printer administration - information for the Common UNIX Printing SystemTM ("CUPS -TM"), version 1.2.0.

    -

    System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    - - -

    Document Overview

    -

    This software administrators manual is organized into the following - sections:

    - -

    Notation Conventions

    -

    Various font and syntax conventions are used in this guide. Examples - and their meanings and uses are explained below: -

    - - - - - - - - - - - - -
    Example   Description
     
    lpstat -
    lpstat(1)    		   The names of commands; - the first mention of a command or function in a chapter is followed by - a manual page section number.
     
    /var -
    /usr/share/cups/data/testprint.ps    		    -File and directory names.
     
    Request ID is Printer-123 -   Screen output.
     
    lp -d printer filename ENTER -   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are - written using the period (.) to indicate the decimal point.
    -
    - - -

    -

    Abbreviations

    - The following abbreviations are used throughout this manual: -
      -
      -
      kb
      -
      Kilobytes, or 1024 bytes -
       
      -
      Mb
      -
      Megabytes, or 1048576 bytes -
       
      -
      Gb
      -
      Gigabytes, or 1073741824 bytes -
       
      -
      -
    -

    Other References

    -
      -
      -
      CUPS Software Programmers Manual
      -
      A programmer guide for interfacing with and/or extending the CUPS - software. -
       
      -
      CUPS Software Users Manual
      -
      An end-user guide for using the CUPS software. -
       
      -
      -
    -

    1 - Printing System Overview

    -

    This chapter provides an overview of how the Common UNIX Printing - System works.

    -

    The Printing Problem

    -

    For years the printing problem has plagued UNIX. Unlike - Microsoft® Windows® or Mac OS, UNIX has no standard interface or system - in place for supporting printers. Among the solutions currently - available, the Berkeley and System V printing systems are the most - prevalent.

    -

    These printing systems support line printers (text only) or - PostScript printers (text and graphics), and with some coaxing they can - be made to support a full range of printers and file formats. However, - because each varient of the UNIX operating system uses a different - printing system than the next developing printer drivers for a wide - range of printers and operating systems is extremely difficult. That - combined with the limited volume of customers for each UNIX varient has - forced most printer vendors to give up supporting UNIX entirely.

    -

    CUPS is designed to eliminate the printing problem. One common - printing system can be used by all UNIX varients to support the - printing needs of users. Printer vendors can use its modular filter - interface to develop a single driver program that supports a wide range - of file formats with little or no effort. Since CUPS provides both the - System V and Berkeley printing commands, users (and applications) can - reap the benefits of this new technology with no changes.

    -

    The Technology

    -

    CUPS is based upon an emerging Internet standard called the Internet - Printing Protocol. IPP has been embraced by dozens of printer and - printer server manufacturers and is supported by Microsoft Windows - 2000.

    -

    IPP defines a standard protocol for printing as well as managing - print jobs and printer options like media size, resolution, and so - forth. Like all IP-based protocols, IPP can be used locally or over the - Internet to printers hundreds or thousands of miles away. Unlike other - protocols, however, IPP also supports access control, authentication, - and encryption, making it a much more capable and secure printing - solution than older ones.

    -

    IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") - which is the basis of web servers on the Internet. This allows users to - view documentation, check status information on a printer or server, - and manage their printers, classes, and jobs using their web browser.

    -

    CUPS provides a complete IPP/1.1 based printing system that provides - Basic, Digest, and local certificate authentication and user, domain, - or IP-based access control. TLS encryption will be available in future - versions of CUPS.

    -

    Jobs

    -

    Each file or set of files that is submitted for printing is called a - job. Jobs are identified by a unique number starting at 1 and are - assigned to a particular destination, usually a printer. Jobs can also - have options associated with them such as media size, number of copies, - and priority.

    -

    Classes

    -

    CUPS supports collections of printers known as classes. Jobs - sent to a class are forwarded to the first available printer in the - class.

    -

    Filters

    -

    Filters allow a user or application to print many types of files - without extra effort. Print jobs sent to a CUPS server are filtered - before sending them to a printer. Some filters convert job files to - different formats that the printer can understand. Others perform page - selection and ordering tasks.

    -

    CUPS provides filters for printing many types of image files, HP-GL/2 - files, PDF files, and text files. CUPS also supplies PostScript and - image file Raster Image Processor ("RIP") filters that convert - PostScript or image files into bitmaps that can be sent to a raster - printer.

    -

    Backends

    -

    Backends perform the most important task of all - they send the - filtered print data to the printer.

    -

    CUPS provides backends for printing over parallel, serial, and USB - ports, and over the network via the IPP, JetDirect (AppSocket), and - Line Printer Daemon ("LPD") protocols. Additional backends are - available in network service packages such as the SMB backend included - with the popular SAMBA software.

    -

    Backends are also used to determine the available devices. On startup - each backend is asked for a list of devices it supports, and any - information that is available. This allows the parallel backend to tell - CUPS that an EPSON Stylus Color 600 printer is attached to parallel - port 1, for example.

    -

    Printer Drivers

    -

    Printer drivers in CUPS consist of one of more filters specific to a - printer. CUPS includes sample printer drivers for Hewlett-Packard - LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, - and Stylus Photo printers. While these drivers do not generate optimal - output for the different printer models, they do provide basic printing - and demonstrate how you can write your own printer drivers and - incorporate them into CUPS.

    -

    Networking

    -

    Printers and classes on the local system are automatically shared - with other systems on the network. This allows you to setup one system - to print to a printer and use this system as a printer server or spool - host for all of the others. Users may then select a local printer by - name or a remote printer using "name@server".

    -

    CUPS also provides implicit classes, which are collections of - printers and/or classes with the same name. This allows you to setup - multiple servers pointing to the same physical network printer, for - example, so that you aren't relying on a single system for printing. - Because this also works with printer classes, you can setup multiple - servers and printers and never worry about a single point of failure - unless all of the printers and servers go down!

    -

    2 - Building and - Installing CUPS

    -

    This chapter shows how to build and install the Common UNIX Printing - System. If you are installing a binary distribution from the CUPS web - site, proceed to the section titled, Installing a - Binary Distribution.

    -

    Installing a Source Distribution

    -

    This section describes how to compile and install CUPS on your system - from the source code.

    -

    Requirements

    -

    You'll need ANSI-compliant C and C++ compilers to build CUPS on your - system. As its name implies, CUPS is designed to run on the UNIX - operating system, however the CUPS interface library and most of the - filters and backends supplied with CUPS should also compile and run - under Microsoft Windows.

    -

    For the image file filters and PostScript RIP, you'll need the JPEG, - PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with - significantly reduced functionality. Easy Software Products maintains a - mirror of the current versions of these libraries at:

    - -

    If you make changes to the man pages you'll need GNU groff or another - nroff-like package. GNU groff is available from:

    - -

    The documentation is formatted using the HTMLDOC software. If you - need to make changes you can get the HTMLDOC software from:

    - -

    Finally, you'll need a make program that understands the - include directive - FreeBSD, NetBSD, and OpenBSD - developers should use the gmake program.

    -

    Compiling CUPS

    -

    CUPS uses GNU autoconf to configure the makefiles and source code for - your system. Type the following command to configure CUPS for your - system:

    -
      -
      -./configure ENTER
-
      -
    -

    The default installation will put the CUPS software in the /etc -, /usr, and /var directories on your system, which - will overwrite any existing printing commands on your system. Use the ---prefix option to install the CUPS software in another location:

    -
      -
      -./configure --prefix=/some/directory ENTER
-
      -
    -

    If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a - system default location (typically /usr/include and - /usr/lib) you'll need to set the CFLAGS, -CXXFLAGS, and LDFLAGS environment variables prior to - running configure:

    -
      -
      -setenv CFLAGS "-I/some/directory" ENTER
-setenv CXXFLAGS "-I/some/directory" ENTER
-setenv LDFLAGS "-L/some/directory" ENTER
-setenv DSOFLAGS "-L/some/directory" ENTER
-./configure ... ENTER
-
      -
    -

    or:

    -
      -
      -CFLAGS="-I/some/directory"; export CFLAGS ENTER
-CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER
-LDFLAGS="-L/some/directory"; export LDFLAGS ENTER
-DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER
-./configure ... ENTER
-
      -
    -

    To enable support for encryption, you'll also want to add the - "--enable-ssl" option:

    -
      -
      -./configure --enable-ssl
-
      -
    -

    SSL and TLS support require the OpenSSL library, available at:

    - -

    If the OpenSSL headers and libraries are not installed in the - standard directories, use the --with-openssl-includes and ---with-openssl-libs options:

    -
      -
      -./configure --enable-ssl \
-    --with-openssl-includes=/foo/bar/include \
-    --with-openssl-libs=/foo/bar/lib
-
      -
    -

    Once you have configured things, just type:

    -
      -
      -make ENTER
-
      -
    -

    to build the software. - -

    -

    Installing the Software

    -

    Use the "install" target to install the software:

    -
      -
      -make install ENTER
-
      -
    -
    - - -
    WARNING: -

    Installing CUPS will overwrite your existing printing system. If you - experience difficulties with the CUPS software and need to go back to - your old printing system, you will need to reinstall the old printing - system from your operating system CDs.

    -
    -
    -

    Running the Software

    -

    Once you have installed the software you can start the CUPS server by - typing:

    -
      -
      -/usr/sbin/cupsd ENTER
-
      -
    - - -

    Installing a Binary Distribution

    -

    CUPS comes in a variety of binary distribution formats. Easy Software - Products provides binaries in TAR format with installation and removal - scripts ("portable" distributions), and in RPM and DPKG formats for Red - Hat and Debian-based distributions. Portable distributions are - available for all platforms, while the RPM and DPKG distributions are - only available for Linux. -

    - - -
    WARNING: -

    Installing CUPS will overwrite your existing printing system. If you - experience difficulties with the CUPS software and need to go back to - your old printing system, you will need to remove the CUPS software - with the provided script and/or reinstall the old printing system from - your operating system CDs.

    -
    -
    -

    -

    Installing a Portable Distribution

    -

    To install the CUPS software from a portable distribution you will - need to be logged in as root; doing an su is good enough. - Once you are the root user, run the installation script with:

    -
      -
      -./cups.install ENTER
-
      -
    -

    After asking you a few yes/no questions the CUPS software will be - installed and the scheduler will be started automatically. - -

    -

    Installing an RPM Distribution

    -

    To install the CUPS software from an RPM distribution you will need - to be logged in as root; doing an su is good enough. Once - you are the root user, run RPM with:

    -
      -
      -rpm -e lpr
-rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER
-
      -
    -

    After a short delay the CUPS software will be installed and the - scheduler will be started automatically.

    -

    Installing an Debian Distribution

    -

    To install the CUPS software from a Debian distribution you will need - to be logged in as root; doing an su is good enough. Once - you are the root user, run dpkg with:

    -
      -
      -dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER
-
      -
    -

    After a short delay the CUPS software will be installed and the - scheduler will be started automatically.

    -

    3 - Managing Printers

    -

    This chapter describes how to add your first printer and how to - manage your printers.

    -

    The Basics

    -

    Each printer queue has a name associated with it; the printer name - must start with a letter and can contain up to 127 letters, numbers, - and the underscore (_). Case is not significant, e.g. "PRINTER", - "Printer", and "printer" are considered to be the same name.

    -

    Printer queues also have a device associated with them. The device - can be a parallel port, a network interface, and so forth. Devices - within CUPS use Uniform Resource Identifiers ("URIs") which are a more - general form of Uniform Resource Locators ("URLs") that are used in - your web browser. For example, the first parallel port in Linux usually - uses a device URI of parallel:/dev/lp1. - -

    -

    You can see a complete list of supported devices by running the -lpinfo(8) command:

    -
      -
      -lpinfo -v ENTER
-network socket
-network http
-network ipp
-network lpd
-direct parallel:/dev/lp1
-serial serial:/dev/ttyS1?baud=115200
-serial serial:/dev/ttyS2?baud=115200
-direct usb:/dev/usb/lp0
-network smb
-
      -
    -

    The -v option specifies that you want a list of - available devices. The first word in each line is the type of device - (direct, file, network, or serial) and is followed by the device URI or - method name for that device. File devices have device URIs of the form -file:/directory/filename while network devices use the more - familiar method://server or method://server/path - format.

    -

    Finally, printer queues usually have a PostScript Printer Description - ("PPD") file associated with them. PPD files describe the capabilities - of each printer, the page sizes supported, etc., and are used for - PostScript and non-PostScript printers. CUPS includes PPD files for HP - LaserJet, HP DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus - printers.

    -

    Adding Your First Printer

    -

    CUPS provides two methods for adding printers: a command-line program - called lpadmin(8) and a Web interface. The lpadmin - command allows you to perform most printer administration tasks from - the command-line and is located in /usr/sbin. The Web - interface is located at:

    - -

    and steps you through printer configuration. If you don't like - command-line interfaces, try the Web interface - instead.

    -

    Adding Your First Printer from the Command-Line

    -

    Run the lpadmin command with the -p option - to add a printer to CUPS:

    -
      -
      -/usr/sbin/lpadmin -p printer -E -v device -m ppd ENTER
-
      -
    -

    For a HP DeskJet printer connected to the parallel port this would - look like:

    -
      -
      -/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER
-
      -
    -

    Similarly, a HP LaserJet printer using a JetDirect network interface - at IP address 11.22.33.44 would be added with the command:

    -
      -
      -/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER
-
      -
    -

    As you can see, deskjet.ppd and laserjet.ppd - are the PPD files for the HP DeskJet and HP LaserJet drivers included - with CUPS. You'll find a complete list of PPD files and the printers - they will work with in Appendix C, "Printer - Drivers".

    -

    For a dot matrix printer connected to the serial port this would - might look like:

    -
      -
      -/usr/sbin/lpadmin -p DotMatrix -E -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft deskjet.ppd ENTER
-
      -
    -

    Here you specify the serial port (e.g. S0,S1, d0, d1), baud rate - (e.g. 9600, 19200, 38400, 115200, etc.), number of bits, parity, and - flow control. If you do not need flow control, delete the "+flow=soft" - portion.

    -

    Adding Your First Printer from the Web

    -

    The CUPS web server provides a user-friendly "wizard" interface for - adding your printers. Rather than figuring out which device URI and PPD - file to use, you can instead click on the appropriate listings and fill - in some simple information. Enter the following URL in your web browser - to begin:

    - -

    Click on the Add Printer button to add a printer.

    -

    Managing Printers from the Command-Line

    -

    The lpadmin command enables you to perform most printer - administration tasks from the command-line. You'll find lpadmin - in the /usr/sbin directory.

    -

    Adding and Modifying Printers

    -

    Run the lpadmin command with the -p option - to add or modify a printer:

    -
      -
      -/usr/sbin/lpadmin -p printer options ENTER
-
      -
    -

    The options arguments can be any of the following:

    -
      -
      -
      -c class
      -
      Adds the named printer to printer class class. If the - class does not exist then it is created.
      -
      -i interface
      -
      Copies the named interface script to the printer. - Interface scripts are used by System V printer drivers. Since all - filtering is disabled when using an interface script, scripts generally - should not be used unless there is no other driver for a printer.
      -
      -m model
      -
      Specifies a standard printer driver which is usually a PPD file. A - list of all available models can be displayed using the lpinfo - command with the -m option. A list of printer drivers - included with CUPS can be found in Appendix - C, "Printer Drivers".
      -
      -r class
      -
      Removes the named printer from printer class class. If - the resulting class becomes empty then it is removed.
      -
      -v device-uri
      -
      Sets the device for communicating with the printer. If a job is - currently printing on the named printer then the job will be restarted - and sent to the new device.
      -
      -D info
      -
      Provides a textual description of the printer, e.g. "John's Personal - Printer".
      -
      -E
      -
      Enables the printer and accepts job. This option is equivalent to - running the enable(1) and accept(8) commands - on the printer.
      -
      -L location
      -
      Provides a textual location for the printer, e.g. "Computer Lab 5".
      -
      -P ppd-file
      -
      Specifies a local PPD file for the printer driver.
      -
      -
    -

    Deleting Printers

    -

    Run the lpadmin command with the -x option - to delete a printer:

    -
      -
      -/usr/sbin/lpadmin -x printer ENTER
-
      -
    -

    Setting the Default Printer

    -

    Run the lpadmin command with the -d option - to set a default printer:

    -
      -
      -/usr/sbin/lpadmin -d printer ENTER
-
      -
    -

    The default printer can be overridden by the user using the -lpoptions(1) command.

    -

    Starting and Stopping Printers

    -

    The enable and disable commands start and - stop printer queues, respectively:

    -
      -
      -/usr/bin/enable printer ENTER
-/usr/bin/disable printer ENTER
-
      -
    -

    Printers that are disabled may still accept jobs for printing, but - won't actually print any files until they are restarted. This is useful - if the printer malfunctions and you need time to correct the problem. - Any queued jobs are printed after the printer is enabled (started).

    -

    Accepting and Rejecting Print Jobs

    -

    The accept and reject commands accept and - reject print jobs for the named printer, respectively:

    -
      -
      -/usr/sbin/accept printer ENTER
-/usr/sbin/reject printer ENTER
-
      -
    -

    As noted above, a printer can be stopped but accepting new print - jobs. A printer can also be rejecting new print jobs while it finishes - those that have been queued. This is useful for when you must perform - maintenance on the printer and will not have it available to users for - a long period of time.

    -

    Setting Quotas on a Printer

    -

    CUPS supports page and size-based quotas for each printer. The quotas - are tracked individually for each user, but a single set of limits - applies to all users for a partiuclar printer. For example, you can - limit every user to 5 pages per day on an expensive printer, but you - cannot limit every user except Johnny.

    -

    The job-k-limit, job-page-limit, and job-quota-peiod - options determine whether and how quotas are enforced for a printer. - The job-quota-period option determines the time interval for - quota tracking. The interval is expressed in seconds, so a day is - 86,400, a week is 604,800 and a month is 2,592,000 seconds. The - job-k-limit option specifies the job size limit in killobytes. The - job-page-limit option specifies the number of pages limit.

    -

    For quotas to be enforced, the period and at least one of the limits - must be set to a non-zero value. The following options will enable - quotas:

    -
      -
      -/usr/sbin/lpadmin -p printer -o job-quota-period=604800 -o job-k-limit=1024 ENTER
-/usr/sbin/lpadmin -p printer -o job-quota-period=604800 -o job-page-limit=100 ENTER
-
      -
    -

    Or, you can combine all three options on the same line.

    -

    Restricting User Access to a Printer

    -

    The -u option of the lpadmin command - controls which users can print to a printer. The default configuration - allows all users to print to a printer:

    -
      -
      -/usr/sbin/lpadmin -p printer -u allow:all ENTER
-
      -
    -

    CUPS supports allow and deny lists so that you can specify a list of - users who are allowed to print or not allowed to print. Along with your - list of users, you can specify whether they are allowed or not allowed - to use the printer:

    -
      -
      -/usr/sbin/lpadmin -p printer -u allow:peter,paul,mary ENTER
-
      -
    -

    This command allows peter, paul, and mary to print to the named - printer, but all other users cannot print. The command:

    -
      -
      -/usr/sbin/lpadmin -p printer -u deny:peter,paul,mary ENTER
-
      -
    -

    has the opposite effect. All users except peter, paul, and mary will - be able to print to the named printer.

    -
    - - -
    NOTE: -

    The allow and deny options are not cummulative. That - is, you must provide the complete list of users to allow or deny each - time.

    -

    Also, CUPS only maintains one list of users - the list can allow or - deny users from printing. If you specify an allow list and then specify - a deny list, the deny list will replace the allow list - only one list - is active at any time.

    -
    -
    -

    Managing Printers from the Web

    -

    The Web interface is located at:

    - -

    From there you can perform all printer management tasks with a few - simple mouse clicks.

    -

    4 - Printer Classes

    -

    This chapter describes what printer classes are and how to manage - them.

    -

    The Basics

    -

    CUPS provides collections of printers called printer classes. - Jobs sent to a class are forwarded to the first available printer in - the class. Classes can themselves be members of other classes, so it is - possible for you to define very large, distributed printer classes for - high-availability printing.

    -

    CUPS also supports implicit classes. Implicit classes work - just like printer classes, but they are created automatically based - upon the available printers and classes on the network. This allows you - to setup multiple print servers with identical printer configurations - and have the client machines send their print jobs to the first - available server. If one or more servers go down, the jobs are - automatically redirected to the servers that are running, providing - fail-safe printing.

    -

    Managing Printer Classes from the Command-Line

    -

    Run the lpadmin command with the -p and --c options to add a printer to a class:

    -
      -
      -/usr/sbin/lpadmin -p printer -c class ENTER
-
      -
    -

    The class is created automatically if it doesn't exist. To - remove a printer from a class use the -r option:

    -
      -
      -/usr/sbin/lpadmin -p printer -r class ENTER
-
      -
    -

    To remove the entire class just use the -x option:

    -
      -
      -/usr/sbin/lpadmin -x class ENTER
-
      -
    -

    Managing Printer Classes from the Web Interface

    -

    The Web interface is located at:

    - -

    The Add Class and Modify Class interfaces - provide a list of available printers; click on the printers of interest - to add them to the class.

    -

    Implicit Classes

    -

    A noted earlier, implicit classes are created automatically from the - available network printers and classes. To disable this functionality, - set the ImplicitClasses - directive to Off in the cupsd.conf file. You - will find more information on doing this in - Chapter 6, "Printing System Management".

    -

    5 - Client Setup

    -

    This chapter discusses several ways to configure CUPS clients for - printing.

    -

    The Basics

    -

    A client is any machine that sends print jobs to another machine for - final printing. Clients can also be servers if they communicate - directly with any printers of their own.

    -

    CUPS supports several methods of configuring client machines:

    - -

    Manual Configuration of Print Queues

    -

    The most tedious method of configuring client machines is to - configure each remote queue by hand using the lpadmin - command:

    -
      -
      -lpadmin -p printer -E -v ipp://server/printers/printer ENTER
-
      -
    -

    The printer name is the name of the printer on the - server machine. The server name is the hostname or IP - address of the server machine. Repeat the lpadmin command - for each remote printer you wish to use.

    -
    - - -
    NOTE: -

    Manual configuration of print queues is not recommended for large - numbers of client machines because of the administration nightmare it - creates. For busy networks, consider subnetting groups of clients and - polling and relaying printer information instead.

    -
    -
    -

    Specifying a Single Server for Printing

    -

    CUPS can be configured to run without a local spooler and send all - jobs to a single server. However, if that server goes down then all - printing will be disabled. Use this configuration only as absolutely - needed.

    -

    The default server is normally "localhost". To override the default - server create a file named /etc/cups/client.conf and add a - line reading:

    -
      -
      -ServerName server
-
      -
    -

    to the file. The server name can be the hostname or IP - address of the default server.

    -

    The default server can also be customized on a per-user basis. To set - a user-specific server create a file named ~/.cupsrc and add - a line reading:

    -
      -
      -ServerName server
-
      -
    -

    to the file. The server name can be the hostname or IP - address of the default server.

    -

    Automatic Configuration of Print Queues

    -

    CUPS supports automatic client configuration of printers on the same - subnet. To configure printers on the same subnet, do nothing. - Each client should see the available printers within 30 seconds - automatically. The printer and class lists are updated automatically as - printers and servers are added or removed.

    -

    If you want to see printers on other subnets as well, use the - BrowsePoll directive as described next.

    -
    - - -
    NOTE: -

    The BrowseAddress directive - enables broadcast traffic from your server. The default configuration - braodcasts printer information every 30 seconds. Although this printer - information does not use much bandwidth, typically about 80 bytes per - printer, it can add up with large numbers of servers and printers.

    -

    Use the BrowseInterval and BrowseTimeout directives to tune - the amount of data that is added to your network load. In addition, - subnets can be used to minimize the amount of traffic that is carried - by the "backbone" of your large network.

    -
    -
    -

    Specifying Multiple Servers for Printing

    -

    If you have CUPS servers on different subnets, then you should - configure CUPS to poll those servers. Polling provides the benefits of - automatic configuration without significant configuration on the - clients, and multiple clients on the same subnet can share the same - configuration information.

    -

    Polling is enabled by specifying one or more -BrowsePoll directives in the /etc/cups/cupsd.conf - file. For information on making these changes, see - Chapter 6, "Printing System Management".

    -

    Multiple BrowsePoll lines can - be used to poll multiple CUPS servers. To limit the amount of polling - you do from client machines, you can have only one of the clients do - the polling and relay that information to the others on the same subnet - (described next).

    -

    Relaying Printers to Other Clients

    -

    When you have clients and servers spread across multiple subnets, the - polling method is inefficient. CUPS provides a -BrowseRelay directive that enables a single client to relay - (broadcast) the polled printer information to the local subnet.

    -

    For example, Server A and Server B are on subnet 1 and subnet 2, - while the clients are on subnet 3. To provide printers to all of the - clients in subnet 3, client C will be configured with the following - directives in /etc/cups/cupsd.conf:

    -
      -
      -# Poll the two servers
-
-BrowsePoll ServerA ENTER
-BrowsePoll ServerB ENTER
-
-
-# Relay the printers to the local subnet
-
-BrowseRelay 127.0.0.1 192.168.3.255 ENTER
-
      -
    -

    The BrowseRelay line - specifies a source address and mask. Any browse packets coming from a - matching address wil be sent to the given broadcast address. In this - case, we want the packets from the local machine (127.0.0.1) relayed to - the other clients.

    -

    As printers are found using polling, they are relayed from client C - to the rest of the clients through a broadcast on subnet 3. The rest of - the clients can use the standard cupsd.conf configuration.

    -

    The BrowseRelay directive can - also be used to relay browsing packets from one network interface to - another. For example, if client C in the previous example had network - interfaces attaches to both subnet 1 and subnet 2, it could use the - BrowseRelay directive exclusively:

    -
      -
      -# Relay the printers from subnet 1 and 2 to subnet 3
-
-BrowseRelay 192.168.1 192.168.3.255 ENTER
-BrowseRelay 192.168.2 192.168.3.255 ENTER
-
      -
    -

    Load Balancing and Failsafe Operation

    -

    When using server polling or broadcasting, CUPS clients can - automatically merge identical printers on multiple servers into a - single implicit class queue. Clients assume that printers with - the same name on multiple servers are in fact the same printer or type - of printer being served by multiple machines.

    -

    If you have two printers, LaserJet@ServerA and LaserJet@ServerB, a - third implicit class called LaserJet will be created - automatically on the client that refers to both printers. If the client - also has a local printer with the name LaserJet then an implicit class - named AnyLaserJet will be created instead.

    -

    The client will alternate between servers and automatically stop - sending jobs to a server if it goes down, providing a load-balancing - effect and fail-safe operation with automatic switchover.

    -
    - - -
    NOTE: -

    Note that implicit classes ( -ImplicitClasses) are enabled by default.

    -
    -
    -

    6 - Printing System - Management

    -

    This chapter shows how you can configure the CUPS server.

    -

    The Basics

    -

    Several text files are used to configure CUPS. All of the server - configuration files are located in the /etc/cups directory:

    -
      -
      - - -
      classes.conf
      -
      This file contains information on each printer class. Normally you - manipulate this file using the lpadmin command or the Web - interface. -
        - -
      -
      client.conf
      -
      This file provides the default server name for client machines. See Chapter 5, "Client Setup" for more - information. -
        - -
      -
      cupsd.conf
      -
      This file controls how the CUPS server (/usr/sbin/cupsd) - operates and is normally edited by hand. -
        - -
      -
      mime.convs
      -
      This file contains a list of standard file conversion filters and - their costs. You normally do not edit this file. -
        - -
      -
      mime.types
      -
      This file contains a list of standard file formats and how to - recognize them. You normally do not edit this file. -
        - -
      -
      printers.conf
      -
      This file contains information on each printer. Normally you - manipulate this file using the lpadmin command or the Web - Interface. -
       
      -
      -
    -

    Restarting the CUPS Server

    -

    Once you have made a change to a configuration file you need to - restart the CUPS server by sending it a HUP signal or - using the supplied initialization script. The CUPS distributions - install the script in the init.d directory with the name - cups. The location varies based upon the operating system:

    -
      -
      -/etc/software/init.d/cups restart ENTER
-/etc/rc.d/init.d/cups restart ENTER
-/etc/init.d/cups restart ENTER
-/sbin/init.d/cups restart ENTER
-
      -
    -

    Changing the Server Configuration

    -

    The /etc/cups/cupsd.conf file contains configuration - directives that control how the server functions. Each directive is - listed on a line by itself followed by its value. Comments are - introduced using the number sign ("#") character at the beginning of a - line. Since the server configuration file consists of plain text, you - can use your favorite text editor to make changes to it. - -

    -

    Server Directives

    -

    The cupsd.conf file contains many directives that - determine how the server operates:

    - - - -

    AccessLog

    -
    -

    Examples

    -
      -
      -AccessLog /var/log/cups/access_log
-AccessLog /var/log/cups/access_log-%s
-AccessLog syslog
-
      -
    -

    Description

    -

    The AccessLog directive sets the name of the access log - file. If the filename is not absolute then it is assumed to be relative - to the ServerRoot directory. The - access log file is stored in "common log format" and can be used by any - web access reporting tool to generate a report on CUPS server activity.

    -

    The server name can be included in the filename by using %s - in the name.

    -

    The special name "syslog" can be used to send the access information - to the system log instead of a plain file.

    -

    The default access log file is /var/log/cups/access_log. - -

    -

    Allow

    -
    -

    Examples

    -
      -
      -Allow from All
-Allow from None
-Allow from *.domain.com
-Allow from .domain.com
-Allow from host.domain.com
-Allow from nnn.*
-Allow from nnn.nnn.*
-Allow from nnn.nnn.nnn.*
-Allow from nnn.nnn.nnn.nnn
-Allow from nnn.nnn.nnn.nnn/mm
-Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
-Allow from @LOCAL
-Allow from @IF(name)
-
      -
    -

    Description

    -

    The Allow directive specifies a hostname, IP address, or - network that is allowed access to the server. Allow - directives are cummulative, so multiple Allow directives - can be used to allow access for multiple hosts or networks. The -/mm notation specifies a CIDR netmask: -

    - - - - - - -
    mmnetmask -mmnetmask
    00.0.0.0 -8255.0.0.0
    1128.0.0.0 -16255.255.0.0
    2192.0.0.0 -24255.255.255.0
    ...... -32255.255.255.255
    -
    -

    -

    The @LOCAL name will allow access from all local network - interfaces, but not remote point-to-point interfaces. The -@IF(name) name will allow access from the named interface.

    -

    The Allow directive must appear inside a - Location directive. - -

    -

    AuthClass

    -
    -

    Examples

    -
      -
      -AuthClass Anonymous
-AuthClass User
-AuthClass System
-AuthClass Group
-
      -
    -

    Description

    -

    The AuthClass directive defines what level of - authentication is required:

    -
      -
    • Anonymous - No authentication should be performed - (default.)
      • -
    • User - A valid username and password is required.
      • -
    • System - A valid username and password is required, and - the username must belong to the "sys" group; this can be changed using - the SystemGroup directive.
      • -
    • Group - A valid username and password is required, and - the username must belong to the group named by the AuthGroupName - directive.
      • -
    -

    The AuthClass directive must appear inside a - Location directive. - -

    -

    AuthGroupName

    -
    -

    Examples

    -
      -
      -AuthGroupName mygroup
-AuthGroupName lp
-
      -
    -

    Description

    -

    The AuthGroupName directive sets the group to use for -Group authentication.

    -

    The AuthGroupName directive must appear inside a - Location directive. - -

    -

    AuthType

    -
    -

    Examples

    -
      -
      -AuthType None
-AuthType Basic
-AuthType Digest
-AuthType BasicDigest
-
      -
    -

    Description

    -

    The AuthType directive defines the type of - authentication to perform:

    -
      -
    • None - No authentication should be performed (default.)
      • -
    • Basic - Basic authentication should be performed using - the UNIX password and group files.
      • -
    • Digest - Digest authentication should be performed - using the /etc/cups/passwd.md5 file.
      • -
    • BasicDigest - Basic authentication should be performed - using the /etc/cups/passwd.md5 file.
      • -
    -

    When using Basic, Digest, or -BasicDigest authentication, clients connecting through the -localhost interface can also authenticate using - certificates.

    -

    The AuthType directive must appear inside a - Location directive. - -

    -

    AutoPurgeJobs

    -
    -

    Examples

    -
      -
      -AutoPurgeJobs Yes
-AutoPurgeJobs No
-
      -
    -

    Description

    -

    The AutoPurgeJobs directive specifies whether or not to - purge completed jobs once they are no longer required for quotas. This - option has no effect if quotas are not enabled. The default setting is -No. - -

    -

    BrowseAddress

    -
    -

    Examples

    -
      -
      -BrowseAddress 255.255.255.255:631
-BrowseAddress 192.0.2.255:631
-BrowseAddress host.domain.com:631
-BrowseAddress @LOCAL
-BrowseAddress @IF(name)
-
      -
    -

    Description

    -

    The BrowseAddress directive specifies an address to send - browsing information to. Multiple BrowseAddress directives - can be specified to send browsing information to different networks or - systems.

    -

    The @LOCAL name will broadcast printer information to - all local interfaces. The @IF(name) name will broadcast to - the named interface.

    -

    No browse addresses are set by default.

    -
    - - -
    NOTE: -

    If you are using HP-UX 10.20 and a subnet that is not 24, 16, or 8 - bits, printer browsing (and in fact all broadcast reception) will not - work. This problem appears to be fixed in HP-UX 11.0.

    -
    -
    - - -

    BrowseAllow

    -
    -

    Examples

    -
      -
      -BrowseAllow from all
-BrowseAllow from none
-BrowseAllow from 192.0.2
-BrowseAllow from 192.0.2.0/24
-BrowseAllow from 192.0.2.0/255.255.255.0
-BrowseAllow from *.domain.com
-BrowseAllow from @LOCAL
-BrowseAllow from @IF(name)
-
      -
    -

    Description

    -

    The BrowseAllow directive specifies a system or network - to accept browse packets from. The default is to accept browse packets - from all hosts.

    -

    Host and domain name matching require that you enable the - HostNameLookups directive.

    -

    IP address matching supports exact matches, partial addresses that - match networks using netmasks of 255.0.0.0, 255.255.0.0, and - 255.255.255.0, or network addresses using the specified netmask or bit - count.

    -

    The @LOCAL name will allow browse data from all local - network interfaces, but not remote point-to-point interfaces. The -@IF(name) name will allow browse data from the named interface. - -

    -

    BrowseDeny

    -
    -

    Examples

    -
      -
      -BrowseDeny from all
-BrowseDeny from none
-BrowseDeny from 192.0.2
-BrowseDeny from 192.0.2.0/24
-BrowseDeny from 192.0.2.0/255.255.255.0
-BrowseDeny from *.domain.com
-BrowseDeny from @LOCAL
-BrowseDeny from @IF(name)
-
      -
    -

    Description

    -

    The BrowseDeny directive specifies a system or network - to reject browse packets from. The default is to deny browse packets - from no hosts.

    -

    Host and domain name matching require that you enable the - HostNameLookups directive.

    -

    IP address matching supports exact matches, partial addresses that - match networks using netmasks of 255.0.0.0, 255.255.0.0, and - 255.255.255.0, or network addresses using the specified netmask or bit - count.

    -

    The @LOCAL name will block browse data from all local - network interfaces, but not remote point-to-point interfaces. The -@IF(name) name will block browse data from the named interface. - -

    -

    BrowseOrder

    -
    -

    Examples

    -
      -
      -BrowseOrder allow,deny
-BrowseOrder deny,allow
-
      -
    -

    Description

    -

    The BrowseOrder directive specifies the order of - allow/deny processing. The default order is deny,allow:

    -
      -
    • allow,deny - Browse packets are accepted unless - specifically denied.
      • -
    • deny,allow - Browse packets are rejected unless - specifically allowed.
      • -
    - - -

    BrowseInterval

    -
    -

    Examples

    -
      -
      -BrowseInterval 0
-BrowseInterval 30
-
      -
    -

    Description

    -

    The BrowseInterval directive specifies the maximum - amount of time between browsing updates. Specifying a value of 0 - seconds disables outgoing browse updates but allows a server to receive - printer information from other hosts.

    -

    The BrowseInterval value should always be less than the BrowseTimeout value. Otherwise - printers and classes will disappear from client systems between - updates. - -

    -

    BrowsePoll

    -
    -

    Examples

    -
      -
      -BrowsePoll 192.0.2.2:631
-BrowsePoll host.domain.com:631
-
      -
    -

    Description

    -

    The BrowsePoll directive polls a server for available - printers once every BrowseInterval - seconds. Multiple BrowsePoll directives can be - specified to poll multiple servers.

    -

    If BrowseInterval is set to 0 then the server is polled - once every 30 seconds. - -

    -

    BrowsePort

    -
    -

    Examples

    -
      -
      -BrowsePort 631
-BrowsePort 9999
-
      -
    -

    Description

    -

    The BrowsePort directive specifies the UDP port number - used for browse packets. The default port number is 631.

    -
    - - -
    NOTE: -

    You must set the BrowsePort to the same value on all of - the systems that you want to see.

    -
    -
    - - -

    BrowseProtocols

    -
    -

    Examples

    -
      -
      -BrowseProtocols CUPS
-BrowseProtocols SLP
-BrowseProtocols CUPS SLP
-BrowseProtocols all
-
      -
    -

    Description

    -

    The BrowseProtocols directive specifies the protocols to - use when collecting and distributing shared printers on the local - network. The default protocol is CUPS, which is a - broadcast-based protocol.

    -
    - - -
    NOTE: -

    When using the SLP protocol, you must have at least one - Directory Agent (DA) server on your network. Otherwise the CUPS - scheduler (cupsd) will not respond to client requests for - several seconds while polling the network.

    -
    -
    - - -

    BrowseRelay

    -
    -

    Examples

    -
      -
      -BrowseRelay 193.0.2.1 192.0.2.255
-BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
-BrowseRelay 193.0.2.0/24 192.0.2.255
-BrowseRelay *.domain.com 192.0.2.255
-BrowseRelay host.domain.com 192.0.2.255
-
      -
    -

    Description

    -

    The BrowseRelay directive specifies source and - destination addresses for relaying browsing information from one host - or network to another. Multiple BrowseRelay directives can - be specified as needed.

    -

    BrowseRelay is typically used on systems that bridge - multiple subnets using one or more network interfaces. It can also be - used to relay printer information from polled servers with the line:

    -
      -
      -BrowseRelay 127.0.0.1 255.255.255.255
-
      -
    -

    This effectively provides access to printers on a WAN for all clients - on the LAN(s). - -

    -

    BrowseShortNames

    -
    -

    Examples

    -
      -
      -BrowseShortNames Yes
-BrowseShortNames No
-
      -
    -

    Description

    -

    The BrowseShortNames directive specifies whether or not - short names are used for remote printers when possible. Short names are - just the remote printer name, without the server ("printer"). If more - than one remote printer is detected with the same name, the printers - will have long names ("printer@server1", "printer@server2".)

    -

    The default value for this option is Yes. - -

    -

    BrowseTimeout

    -
    -

    Examples

    -
      -
      -BrowseTimeout 300
-BrowseTimeout 60
-
      -
    -

    Description

    -

    The BrowseTimeout directive sets the timeout for printer - or class information that is received in browse packets. Once a printer - or class times out it is removed from the list of available - destinations.

    -

    The BrowseTimeout value should always be greater than - the BrowseInterval value. - Otherwise printers and classes will disappear from client systems - between updates. - -

    -

    Browsing

    -
    -

    Examples

    -
      -
      -Browsing On
-Browsing Off
-
      -
    -

    Description

    -

    The Browsing directive controls whether or not network - printer browsing is enabled. The default setting is On.

    -
    - - -
    NOTE: -

    If you are using HP-UX 10.20 and a subnet that is not 24, 16, or 8 - bits, printer browsing (and in fact all broadcast reception) will not - work. This problem appears to be fixed in HP-UX 11.0.

    -
    -
    - - -

    Classification

    -
    -

    Examples

    -
      -
      -Classification
-Classification classified
-Classification confidential
-Classification secret
-Classification topsecret
-Classification unclassified
-
      -
    -

    Description

    -

    The Classification directive sets the classification - level on the server. When this option is set, at least one of the - banner pages is forced to the classification level, and the - classification is placed on each page of output. The default is no - classification level. - -

    -

    ClassifyOverride

    -
    -

    Examples

    -
      -
      -ClassifyOverride Yes
-ClassifyOverride No
-
      -
    -

    Description

    -

    The ClassifyOverride directive specifies whether users - can override the default classification level on the server. When the - server classification is set, users can change the classification using - the job-sheets option and can choose to only print one - security banner before or after the job. If the job-sheets - option is set to none then the server default - classification is used.

    -

    The default is to not allow classification overrides. - -

    -

    ConfigFilePerm

    -
    -

    Examples

    -
      -
      -ConfigFilePerm 0644
-ConfigFilePerm 0600
-
      -
    -

    Description

    -

    The ConfigFilePerm directive specifies the permissions - to use when writing configuration files. The default is 0600. - -

    -

    DataDir

    -
    -

    Examples

    -
      -
      -DataDir /usr/share/cups
-
      -
    -

    Description

    -

    The DataDir directive sets the directory to use for data - files. - -

    -

    DefaultCharset

    -
    -

    Examples

    -
      -
      -DefaultCharset utf-8
-DefaultCharset iso-8859-1
-DefaultCharset windows-1251
-
      -
    -

    Description

    -

    The DefaultCharset directive sets the default character - set to use for client connections. The default character set is -utf-8 but is overridden by the character set for the language - specified by the client or the DefaultLanguage directive. - -

    -

    DefaultLanguage

    -
    -

    Examples

    -
      -
      -DefaultLanguage de
-DefaultLanguage en
-DefaultLanguage es
-DefaultLanguage fr
-DefaultLanguage it
-
      -
    -

    Description

    -

    The DefaultLanguage directive specifies the default - language to use for client connections. Setting the default language - also sets the default character set if a language localization file - exists for it. The default language is "en" for English. - -

    -

    Deny

    -
    -

    Examples

    -
      -
      -Deny from All
-Deny from None
-Deny from *.domain.com
-Deny from .domain.com
-Deny from host.domain.com
-Deny from nnn.*
-Deny from nnn.nnn.*
-Deny from nnn.nnn.nnn.*
-Deny from nnn.nnn.nnn.nnn
-Deny from nnn.nnn.nnn.nnn/mm
-Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
-Deny from @LOCAL
-Deny from @IF(name)
-
      -
    -

    Description

    -

    The Deny directive specifies a hostname, IP address, or - network that is allowed access to the server. Deny - directives are cummulative, so multiple Deny directives - can be used to allow access for multiple hosts or networks. The -/mm notation specifies a CIDR netmask: -

    - - - - - - -
    mmnetmask -mmnetmask
    00.0.0.0 -8255.0.0.0
    1128.0.0.0 -16255.255.0.0
    2192.0.0.0 -24255.255.255.0
    ...... -32255.255.255.255
    -
    -

    -

    The @LOCAL name will deny access from all local network - interfaces, but not remote point-to-point interfaces. The -@IF(name) name will deny access from the named interface.

    -

    The Deny directive must appear inside a - Location directive. - -

    -

    DocumentRoot

    -
    -

    Examples

    -
      -
      -DocumentRoot /usr/share/doc/cups
-DocumentRoot /foo/bar/doc/cups
-
      -
    -

    Description

    -

    The DocumentRoot directive specifies the location of web - content for the HTTP server in CUPS. If an absolute path is not - specified then it is assumed to be relative to the - ServerRoot directory. The default directory is - /usr/share/doc/cups.

    -

    Documents are first looked up in a sub-directory for the primary - language requested by the client (e.g. /usr/share/doc/cups/fr/... -) and then directly under the DocumentRoot directory (e.g. - /usr/share/doc/cups/...), so it is possible to localize the web - content by providing subdirectories for each language needed. - -

    -

    Encryption

    -
    -

    Examples

    -
      -
      -Encryption Never
-Encryption IfRequested
-Encryption Required
-Encryption Always
-
      -
    -

    Description

    -

    The Encryption directive must appear instead a - Location section and specifies the encryption settings - for that location. The default setting is IfRequested for - all locations. - -

    -

    ErrorLog

    -
    -

    Examples

    -
      -
      -ErrorLog /var/log/cups/error_log
-ErrorLog /var/log/cups/error_log-%s
-ErrorLog syslog
-
      -
    -

    Description

    -

    The ErrorLog directive sets the name of the error log - file. If the filename is not absolute then it is assumed to be relative - to the ServerRoot directory. The - default error log file is /var/log/cups/error_log.

    -

    The server name can be included in the filename by using %s - in the name.

    -

    The special name "syslog" can be used to send the error information - to the system log instead of a plain file. - -

    -

    FilterLimit

    -
    -

    Examples

    -
      -
      -FilterLimit 0
-FilterLimit 200
-FilterLimit 1000
-
      -
    -

    Description

    -

    The FilterLimit directive sets the maximum cost of all - running job filters. It can be used to limit the number of filter - programs that are run on a server to minimize disk, memory, and CPU - resource problems. A limit of 0 disables filter limiting.

    -

    An average print to a non-PostScript printer needs a filter limit of - about 200. A PostScript printer needs about half that (100). Setting - the limit below these thresholds will effectively limit the scheduler - to printing a single job at any time.

    -

    The default limit is 0. - -

    -

    FilterNice

    -
    -

    Examples

    -
      -
      -FilterNice 0
-FilterNice 39
-FilterNice -10
-
      -
    -

    Description

    -

    The FilterNice directive sets the scheduling priority of - job filters. Values larger than 0 give filters a lower priority while - values smaller than 0 give filters a higher priority. The -FilterNice value does not affect the priority of job backends.

    -

    The default priority is 0. - -

    -

    FontPath

    -
    -

    Examples

    -
      -
      -FontPath /foo/bar/fonts
-FontPath /usr/share/cups/fonts:/foo/bar/fonts
-
      -
    -

    Description

    -

    The FontPath directive specifies the font path to use - when searching for fonts. The default font path is -/usr/share/cups/fonts. - -

    -

    Group

    -
    -

    Examples

    -
      -
      -Group sys
-Group system
-Group root
-
      -
    -

    Description

    -

    The Group directive specifies the UNIX group that filter - and CGI programs run as. The default group is sys, -system, or root depending on the operating system. - -

    -

    HideImplicitMembers

    -
    -

    Examples

    -
      -
      -HideImplicitMembers Yes
-HideImplicitMembers No
-
      -
    -

    Description

    -

    The HideImplicitMembers directive controls whether the - individual printers in an implicit class are shown to the user. The - default is No.

    -

    ImplicitClasses must be - enabled for this directive to have any effect.

    - - -

    HostNameLookups

    -
    -

    Examples

    -
      -
      -HostNameLookups On
-HostNameLookups Off
-HostNameLookups Double
-
      -
    -

    Description

    -

    The HostNameLookups directive controls whether or not - CUPS looks up the hostname for connecting clients. The Double - setting causes CUPS to verify that the hostname resolved from the - address matches one of the addresses returned for that hostname. -Double lookups also prevent clients with unregistered addresses - from connecting to your server. The default is Off to - avoid the potential server performance problems with hostname lookups. - Set this option to On or Double only if - absolutely required. - -

    -

    ImplicitClasses

    -
    -

    Examples

    -
      -
      -ImplicitClasses On
-ImplicitClasses Off
-
      -
    -

    Description

    -

    The ImplicitClasses directive controls whether implicit - classes are created based upon the available network printers and - classes. The default setting is On but is automatically - turned Off if Browsing - is turned Off. - -

    -

    ImplicitAnyClasses

    -
    -

    Examples

    -
      -
      -ImplicitAnyClasses On
-ImplicitAnyClasses Off
-
      -
    -

    Description

    -

    The ImplicitAnyClasses directive controls whether - implicit classes for local and remote printers are created with the - name AnyPrinter. The default setting is Off.

    -

    ImplicitClasses must be - enabled for this directive to have any effect.

    - - -

    Include

    -
    -

    Examples

    -
      -
      -Include filename
-Include /foo/bar/filename
-
      -
    -

    Description

    -

    The Include directive includes the named file in the -cupsd.conf file. If no leading path is provided, the file is - assumed to be relative to the ServerRoot - directory.

    - - -

    KeepAlive

    -
    -

    Examples

    -
      -
      -KeepAlive On
-KeepAlive Off
-
      -
    -

    Description

    -

    The KeepAlive directive controls whether or not to - support persistent HTTP connections. The default is On.

    -

    HTTP/1.1 clients automatically support persistent connections, while - HTTP/1.0 clients must specifically request them using the -Keep-Alive attribute in the Connection: field of - each request. - -

    -

    KeepAliveTimeout

    -
    -

    Examples

    -
      -
      -KeepAliveTimeout 60
-KeepAliveTimeout 30
-
      -
    -

    Description

    -

    The KeepAliveTimeout directive controls how long a - persistent HTTP connection will remain open after the last request. The - default is 60 seconds. - -

    -

    Limit

    -
    -

    Examples

    -
      -
      -<Limit GET POST>
-...
-</Limit>
-
-<Limit ALL>
-...
-</Limit>
-
      -
    -

    Description

    -

    The Limit directive groups access control directives for - specific types of HTTP requests and must appear inside a - Location section. Access can be limited for individual - request types (DELETE, GET, HEAD -, OPTIONS, POST, PUT, and -TRACE) or for all request types (ALL). The request - type names are case-sensitive for compatibility with Apache. - -

    -

    LimitExcept

    -
    -

    Examples

    -
      -
      -<LimitExcept GET POST>
-...
-</LimitExcept>
-
      -
    -

    Description

    -

    The LimitExcept directive groups access control - directives for specific types of HTTP requests and must appear inside a Location section. Unlike the - Limit directive, LimitExcept restricts - access for all requests except those listed on the -LimitExcept line. - -

    -

    LimitRequestBody

    -
    -

    Examples

    -
      -
      -LimitRequestBody 10485760
-LimitRequestBody 10m
-LimitRequestBody 0
-
      -
    -

    Description

    -

    The LimitRequestBody directive controls the maximum size - of print files, IPP requests, and HTML form data in HTTP POST requests. - The default limit is 0 which disables the limit check.

    -

    Also see the identical MaxRequestSize - directive. - -

    -

    Listen

    -
    -

    Examples

    -
      -
      -Listen 127.0.0.1:631
-Listen 192.0.2.1:631
-
      -
    -

    Description

    -

    The Listen directive specifies a network address and - port to listen for connections. Multiple Listen directives - can be provided to listen on multiple addresses.

    -

    The Listen directive is similar to the -Port directive but allows you to restrict access to specific - interfaces or networks. - -

    -

    Location

    -
    -

    Examples

    -
      -
      -<Location />
-...
-</Location>
-
-<Location /admin>
-...
-</Location>
-
-<Location /printers>
-...
-</Location>
-
-<Location /printers/name>
-...
-</Location>
-
-<Location /classes>
-...
-</Location>
-
-<Location /classes/name>
-...
-</Location>
-
      -
    -

    Description

    -

    The Location directive specifies access control and - authentication options for the specified HTTP resource or path. The - Allow, AuthClass -, AuthGroupName, - AuthType, Deny, - Encryption, Limit, - LimitExcept, Order, Require, and -Satisfy directives may all appear inside a location. -

    - - - - - - - - - - - - - - -
    Locations on the Server.
    LocationDescription
    /The path for all get operations (get-printers, - get-jobs, etc.)
    /adminThe path for all administration operations - (add-printer, delete-printer, start-printer, etc.)
    /admin/confThe path for access to the ESP Print Pro - configuration files (cupsd.conf, client.conf, etc.)
    /classesThe path for all classes
    /classes/nameThe resource for class name
    /jobsThe path for all jobs (hold-job, release-job, - etc.)
    /jobs/idThe resource for job id
    /printersThe path for all printers
    /printers/nameThe path for printer name
    /printers/name.ppdThe PPD file path for printer -name
    -
    -

    -

    Note that more specific resources override the less specific ones. So - the directives inside the /printers/name location will - override ones from /printers. Directives inside -/printers will override ones from /.   None of the - directives are inherited. More information can be found in section - "Printing System Security". - -

    -

    LogFilePerm

    -
    -

    Examples

    -
      -
      -LogFilePerm 0644
-LogFilePerm 0600
-
      -
    -

    Description

    -

    The LogFilePerm directive specifies the permissions to - use when writing configuration files. The default is 0644. - -

    -

    LogLevel

    -
    -

    Examples

    -
      -
      -LogLevel none
-LogLevel emerg
-LogLevel alert
-LogLevel crit
-LogLevel error
-LogLevel warn
-LogLevel notice
-LogLevel info
-LogLevel debug
-LogLevel debug2
-
      -
    -

    Description

    -

    The LogLevel directive specifies the level of logging - for the ErrorLog file. The - following values are recognized (each level logs everything under the - preceding levels):

    -
      -
    • none - Log nothing.
      • -
    • emerg - Log emergency conditions that prevent the - server from running.
      • -
    • alert - Log alerts that must be handled immediately.
      • -
    • crit - Log critical errors that don't prevent the - server from running.
      • -
    • error - Log general errors.
      • -
    • warn - Log errors and warnings.
      • -
    • notice - Log temporary error conditions.
      • -
    • info - Log all requests and state changes (default).
      • -
    • debug - Log basic debugging information.
      • -
    • debug2 - Log all debugging information.
      • -
    - - -

    MaxClients

    -
    -

    Examples

    -
      -
      -MaxClients 100
-MaxClients 1024
-
      -
    -

    Description

    -

    The MaxClients directive controls the maximum number of - simultaneous clients that will be allowed by the server. The default is - 100 clients.

    -
    - - -
    NOTE: -

    Since each print job requires a file descriptor for the status pipe, - the CUPS server internally limits the MaxClients value to - 1/3 of the available file descriptors to avoid possible problems when - printing large numbers of jobs.

    -
    -
    - - -

    MaxCopies

    -
    -

    Examples

    -
      -
      -MaxCopies 100
-MaxCopies 65535
-
      -
    -

    Description

    -

    The MaxCopies directive controls the maximum number of - copies that a user can print of a job. The default is 100 copies.

    -
    - - -
    NOTE: -

    Most HP PCL laser printers internally limit the number of copies to - 100.

    -
    -
    - - -

    MaxJobs

    -
    -

    Examples

    -
      -
      -MaxJobs 100
-MaxJobs 9999
-MaxJobs 0
-
      -
    -

    Description

    -

    The MaxJobs directive controls the maximum number of - jobs that are kept in memory. Once the number of jobs reaches the - limit, the oldest completed job is automatically purged from the system - to make room for the new one. If all of the known jobs are still - pending or active then the new job will be rejected.

    -

    Setting the maximum to 0 disables this functionality. The default - setting is 0. - -

    -

    MaxJobsPerPrinter

    -
    -

    Examples

    -
      -
      -MaxJobsPerPrinter 100
-MaxJobsPerPrinter 9999
-MaxJobsPerPrinter 0
-
      -
    -

    Description

    -

    The MaxJobsPerPrinter directive controls the maximum - number of active jobs that are allowed for each printer or class. Once - a printer or class reaches the limit, new jobs will be rejected until - one of the active jobs is completed, stopped, aborted, or cancelled.

    -

    Setting the maximum to 0 disables this functionality. The default - setting is 0. - -

    -

    MaxJobsPerUser

    -
    -

    Examples

    -
      -
      -MaxJobsPerUser 100
-MaxJobsPerUser 9999
-MaxJobsPerUser 0
-
      -
    -

    Description

    -

    The MaxJobsPerUser directive controls the maximum number - of active jobs that are allowed for each user. Once a user reaches the - limit, new jobs will be rejected until one of the active jobs is - completed, stopped, aborted, or cancelled.

    -

    Setting the maximum to 0 disables this functionality. The default - setting is 0. - -

    -

    MaxLogSize

    -
    -

    Examples

    -
      -
      -MaxLogSize 1048576
-MaxLogSize 1m
-MaxLogSize 0
-
      -
    -

    Description

    -

    The MaxLogSize directive controls the maximum size of - each log file. Once a log file reaches or exceeds the maximum size it - is closed and renamed to filename.O. This allows you to - rotate the logs automatically. The default size is 1048576 bytes (1MB).

    -

    Setting the maximum size to 0 disables log rotation. - -

    -

    MaxRequestSize

    -
    -

    Examples

    -
      -
      -MaxRequestSize 10485760
-MaxRequestSize 10m
-MaxRequestSize 0
-
      -
    -

    Description

    -

    The MaxRequestSize directive controls the maximum size - of print files, IPP requests, and HTML form data in HTTP POST requests. - The default limit is 0 which disables the limit check.

    -

    Also see the identical -LimitRequestBody directive. - -

    -

    Order

    -
    -

    Examples

    -
      -
      -Order Allow,Deny
-Order Deny,Allow
-
      -
    -

    Description

    -

    The Order directive defines the default access control. - The following values are supported:

    -
      -
    • Allow,Deny - Allow requests from all systems except - for those listed in a Deny directive.
      • -
    • Deny,Allow - Allow requests only from those listed in - an Allow directive.
      • -
    -

    The Order directive must appear inside a - Location directive. - -

    -

    PageLog

    -
    -

    Examples

    -
      -
      -PageLog /var/log/cups/page_log
-PageLog /var/log/cups/page_log-%s
-PageLog syslog
-
      -
    -

    Description

    -

    The PageLog directive sets the name of the page log - file. If the filename is not absolute then it is assumed to be relative - to the ServerRoot directory. The - default page log file is /var/log/cups/page_log.

    -

    The server name can be included in the filename by using %s - in the name.

    -

    The special name "syslog" can be used to send the page information to - the system log instead of a plain file. - -

    -

    Port

    -
    -

    Examples

    -
      -
      -Port 631
-Port 80
-
      -
    -

    Description

    -

    The Port directive specifies a port to listen on. - Multiple Port lines can be specified to listen on multiple - ports. The default port is 631. - -

    -

    PreserveJobHistory

    -
    -

    Examples

    -
      -
      -PreserveJobHistory On
-PreserveJobHistory Off
-
      -
    -

    Description

    -

    The PreserveJobHistory directive controls whether the - history of completed, cancelled, or aborted print jobs is stored on - disk.

    -

    A value of On (the default) preserves job information - until the administrator purges it with the cancel command.

    -

    A value of Off removes the job information as soon as - each job is completed, cancelled, or aborted. - -

    -

    PreserveJobFiles

    -
    -

    Examples

    -
      -
      -PreserveJobFiles On
-PreserveJobFiles Off
-
      -
    -

    Description

    -

    The PreserveJobFiles directive controls whether the - document files of completed, cancelled, or aborted print jobs are - stored on disk.

    -

    A value of On preserves job files until the - administrator purges them with the cancel command. Jobs - can be restarted (and reprinted) as desired until they are purged.

    -

    A value of Off (the default) removes the job files as - soon as each job is completed, cancelled, or aborted. - -

    -

    Printcap

    -
    -

    Examples

    -
      -
      -Printcap
-Printcap /etc/printcap
-Printcap /etc/printers.conf
-
      -
    -

    Description

    -

    The Printcap directive controls whether or not a - printcap file is automatically generated and updated with a list of - available printers. If specified with no value, then no printcap file - will be generated. The default is to generate a file named - /etc/printcap.

    -

    When a filename is specified (e.g. /etc/printcap), the - printcap file is written whenever a printer is added or removed. The - printcap file can then be used by applications that are hardcoded to - look at the printcap file for the available printers. - -

    -

    PrintcapFormat

    -
    -

    Examples

    -
      -
      -PrintcapFormat BSD
-PrintcapFormat Solaris
-
      -
    -

    Description

    -

    The PrintcapFormat directive controls the output format - of the printcap file. The default is to generate a BSD printcap file. - -

    -

    PrintcapGUI

    -
    -

    Example

    -
      -
      -PrintcapGUI /usr/bin/glpoptions
-
      -
    -

    Description

    -

    The PrintcapGUI directive sets the program to use when - displaying an option panel from an IRIX application that uses the - Impressario print API. The default program is the ESP Print Pro - "glpoptions" GUI.

    -

    The program must accept the -d option to specify a - printer and the -o option to specify one or more options. - After allowing the user to select/change options, the program must then - write the list of printing options without the -o to the - standard output. - -

    -

    RemoteRoot

    -
    -

    Examples

    -
      -
      -RemoteRoot remroot
-RemoteRoot root
-
      -
    -

    Description

    -

    The RemoteRoot directive sets the username for - unauthenticated root requests from remote hosts. The default username - is remroot. Setting RemoteRoot to root - effectively disables this security mechanism. - -

    -

    RequestRoot

    -
    -

    Examples

    -
      -
      -RequestRoot /var/spool/cups
-RequestRoot /foo/bar/spool/cups
-
      -
    -

    Description

    -

    The RequestRoot directive sets the directory for - incoming IPP requests and HTML forms. If an absolute path is not - provided then it is assumed to be relative to the - ServerRoot directory. The default request directory is - /var/spool/cups. - -

    -

    Require

    -
    -

    Examples

    -
      -
      -Require group foo bar
-Require user john mary
-Require valid-user
-
      -
    -

    Description

    -

    The Require directive specifies that authentication is - required for the resource. The group keyword specifies - that the authenticated user must be a member of one or more of the - named groups that follow.

    -

    The user keyboard specifies that the authenticated user - must be one of the named users that follow.

    -

    The valid-user keyword specifies that any authenticated - user may access the resource.

    -

    The default is to do no authentication. This directive must appear - inside a Location directive. - -

    -

    RIPCache

    -
    -

    Examples

    -
      -
      -RIPCache 8m
-RIPCache 1g
-RIPCache 2048k
-
      -
    -

    Description

    -

    The RIPCache directive sets the size of the memory cache - used by Raster Image Processor ("RIP") filters such as -imagetoraster and pstoraster. The size can be - suffixed with a "k" for kilobytes, "m" for megabytes, or "g" for - gigabytes. The default cache size is "8m", or 8 megabytes. - -

    -

    RootCertDuration

    -
    -

    Examples

    -
      -
      -RootCertDuration 300
-RootCertDuration 0
-
      -
    -

    Description

    -

    The RootCertDuration directive controls the interval - between updates of the root authentication certificate. The default is -300 seconds which updates the root certificate approximately once - every 5 minutes. Set the interval to 0 to disable certificate updates - entirely. - -

    -

    RunAsUser

    -
    -

    Examples

    -
      -
      -RunAsUser Yes
-RunAsUser No
-
      -
    -

    Description

    -

    The RunAsUser directive controls whether the scheduler - runs as the unpriviledged user account (usually lp). The - default is No which leaves the scheduler running as the -root user.

    -

    Note: Running as a non-priviledged user may prevent LPD and - locally connected printers from working due to permission problems. The - lpd backend will automatically use a non-priviledged mode - that is not 100% compliant with RFC 1179. The parallel, -serial, and usb backends will need write access to - the corresponding device files. - -

    -

    Satisfy

    -
    -

    Examples

    -
      -
      -Satisfy all
-Satisfy any
-
      -
    -

    Description

    -

    The Satisfy directive specifies whether all conditions - must be satisfied to allow access to the resource. If set to all -, then all authentication and access control conditions must be satified - to allow access.

    -

    Setting Satisfy to any allows a user to - gain access if the authentication or access control requirements are - satisfied. For example, you might require authentication for remote - access, but allow local access without authentication.

    -

    The default is all. This directive must appear inside a Location directive. - -

    -

    ServerAdmin

    -
    -

    Examples

    -
      -
      -ServerAdmin user@host
-ServerAdmin root@foo.bar.com
-
      -
    -

    Description

    -

    The ServerAdmin directive identifies the email address - for the administrator on the system. By default the administrator email - address is root@server, where server is the - server name. - -

    -

    ServerBin

    -
    -

    Examples

    -
      -
      -ServerBin /usr/lib/cups
-ServerBin /foo/bar/lib/cups
-
      -
    -

    Description

    -

    The ServerBin directive sets the directory for - server-run executables. If an absolute path is not provided then it is - assumed to be relative to the ServerRoot - directory. The default executable directory is /usr/lib/cups -. - -

    -

    ServerCertificate

    -
    -

    Examples

    -
      -
      -ServerCertificate /etc/cups/ssl/server.crt
-
      -
    -

    Description

    -

    The ServerCertificate directive specifies the location - of the SSL certificate file used by the server when negotiating - encrypted connections. The certificate must not be encrypted (password - protected) since the scheduler normally runs in the background and will - be unable to ask for a password. The default certificate file is - /etc/cups/ssl/server.crt. - -

    -

    ServerKey

    -
    -

    Examples

    -
      -
      -ServerKey /etc/cups/ssl/server.key
-
      -
    -

    Description

    -

    The ServerKey directive specifies the location of the - SSL private key file used by the server when negotiating encrypted - connections. The default key file is /etc/cups/ssl/server.crt -. - -

    -

    ServerName

    -
    -

    Examples

    -
      -
      -ServerName foo.domain.com
-ServerName myserver.domain.com
-
      -
    -

    Description

    -

    The ServerName directive specifies the hostname that is - reported to clients. By default the server name is the hostname. - -

    -

    ServerRoot

    -
    -

    Examples

    -
      -
      -ServerRoot /etc/cups
-ServerRoot /foo/bar/cups
-
      -
    -

    Description

    -

    The ServerRoot directive specifies the absolute path to - the server configuration and state files. It is also used to resolve - relative paths in the cupsd.conf file. The default server - directory is /etc/cups. - -

    -

    SSLListen

    -
    -

    Examples

    -
      -
      -SSLListen 127.0.0.1:443
-SSLListen 192.0.2.1:443
-
      -
    -

    Description

    -

    The SSLListen directive specifies a network address and - port to listen for secure connections. Multiple SSLListen - directives can be provided to listen on multiple addresses.

    -

    The SSLListen directive is similar to the - SSLPort directive but allows you to restrict access to - specific interfaces or networks. - -

    -

    SSLPort

    -
    -

    Examples

    -
      -
      -SSLPort 443
-
      -
    -

    Description

    -

    The SSLPort directive specifies a port to listen on for - secure connections. Multiple SSLPort lines can be - specified to listen on multiple ports. - -

    -

    SystemGroup

    -
    -

    Examples

    -
      -
      -SystemGroup sys
-SystemGroup system
-SystemGroup root
-
      -
    -

    Description

    -

    The SystemGroup directive specifies the system - administration group for System authentication. More - information can be found later in this chapter in - "Printing System Security". - -

    -

    TempDir

    -
    -

    Examples

    -
      -
      -TempDir /var/tmp
-TempDir /foo/bar/tmp
-
      -
    -

    Description

    -

    The TempDir directive specifies an absolute path for the - directory to use for temporary files. The default directory is - /var/tmp.

    -

    Temporary directories must be world-writable and should have the - "sticky" permission bit enabled so that other users cannot delete - filter temporary files. The following commands will create an - appropriate temporary directory called /foo/bar/tmp:

    -
      -
      -mkdir /foo/bar/tmp ENTER
-chmod a+rwxt /foo/bar/tmp ENTER
-
      -
    - - -

    Timeout

    -
    -

    Examples

    -
      -
      -Timeout 300
-Timeout 90
-
      -
    -

    Description

    -

    The Timeout directive controls the amount of time to - wait before an active HTTP or IPP request times out. The default - timeout is 300 seconds. - -

    -

    User

    -
    -

    Examples

    -
      -
      -User lp
-User guest
-
      -
    -

    Description

    -

    The User directive specifies the UNIX user that filter - and CGI programs run as. The default user is lp. - -

    -

    Printing System Security

    -

    CUPS provides support for address, certificate, and password (Basic - and Digest) based authentication and access control. Certificate and - password authentication provide ways to limit access to individual - people or groups.

    -

    Address based access control allows you to limit access to specific - systems, networks, or domains. While this does not provide - authentication, it does allow you to limit the potential users of your - system efficiently.

    -

    CUPS maintains a list of locations that have access control and/or - authentication enabled. Locations are specified using the - Location directive:

    - -

    Locations generally follow the directory structure of the - DocumentRoot directory, however CUPS does have several - virtual locations for administration, classes, jobs, and printers: -

    - - - - - - - - - - - - -
    LocationDescription
    /adminThe path for all administration operations.
    /classesThe path for all classes.
    /classes/nameThe resource for class name.
    /jobsThe path for all jobs.
    /jobs/idThe resource for job id.
    /printersThe path for all printers.
    /printers/nameThe path for printer name.
    /printers/name.ppdThe PPD file path for printer -name.
    -
    -

    -

    Authentication Using Certificates

    -

    CUPS supports a local certificate-based authentication scheme that - can be used in place of Basic or Digest - authentication by clients connecting through the localhost - interface. Certificate authentication is not supported or allowed from - clients on any other interface.

    -

    Certificates are 128-bit random numbers that refer to an internal - authentication record in the server. A client connecting via the -localhost interface sends a request with an authorization header - of:

    -
      -
      -Authorization: Local 0123456789ABCDEF0123456789ABCDEF
-
      -
    -

    The server then looks up the local certificate and authenticates - using the username associated with it.

    -

    Certificates are generated by the server automatically and stored in - the /etc/cups/certs directory using the process ID of the - CGI program started by the server. Certificate files are only readable - by the User and -Group defined in the cupsd.conf file. When the CGI - program ends the certificate is removed and invalidated automatically.

    -

    The special file /etc/cups/certs/0 defines the root - certificate which can be used by any client running as the - super-user or another user that is part of the group defined by the - SystemGroup directive. The root certificate is - automatically regenerated every 5 minutes.

    -

    Using Basic Authentication

    -

    Basic authentication uses UNIX users and passwords to authenticate - access to resources such as printers and classes, and to limit access - to administrative functions.

    -
    - - -
    NOTE: -

    Basic authentication sends the username and password Base64 encoded - from the client to the server, so it offers no protection against - eavesdropping. This means that a malicious user can monitor network - packets and discover valid users and passwords that could result in a - serious compromise in network security. Use Basic authentication with - extreme care.

    -
    -
    -

    The CUPS implementation of Basic authentication does not allow access - through user accounts without a password. If you try to authenticate - using an account without a password, your access will be immediately - blocked.

    -

    Once a valid username and password is authenticated by CUPS, any - additional group membership requirements are checked.

    -
    - - -
    NOTE: -

    The root user is considered by CUPS to be a member of every group.

    -
    -
    - - -

    Use the AuthType directive to enable Basic - authentication:

    -
      -
      -AuthType Basic
-
      -
    - - -

    Using Digest Authentication

    -

    Digest authentication uses users and passwords defined in the - /etc/cups/passwd.md5 file to authenticate access to resources - such as printers and classes, and to limit access to administrative - functions.

    -
    - - -
    NOTE: -

    Unlike Basic authentication, Digest passes the MD5 sum (basically a - complicated checksum) of the username and password instead of the - strings themselves. Also, Digest authentication does not use the UNIX - password file, so if an attacker does discover the original password it - is less likely to result in a serious security problem so long as you - use a different UNIX password than the corresponding Digest password.

    -

    The current CUPS implementation of Digest authentication uses the - client's hostname or IP address for the "nonce" value. The nonce value - is an additional string added to the username and password to make - guessing the password more difficult. The server checks that the nonce - value matches the client's hostname or address and rejects the MD5 sum - if it doesn't. Future versions of CUPS will support Digest "session" - authentication which adds the request data to the MD5 sum, providing - even better authentication and security.

    -

    Digest authentication does not guarantee that an attacker cannot gain - unauthorized access, but it is safer than Basic authentication and - should be used in place of Basic authentication whenever possible. - Support for Digest authentication in web browsers is not yet - universally available.

    -
    -
    - - -

    The lppasswd(1) command is used to add, change, or - remove accounts from the passwd.md5 file. To add a user to - the default system group, type:

    -
      -
      -lppasswd -a user ENTER
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
      -
    - - -

    Once added, a user can change his/her password by typing:

    -
      -
      -lppasswd ENTER
-Old password: (password) ENTER [password is not echoed]
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
      -
    - - -

    To remove a user from the password file, type:

    -
      -
      -lppasswd -x user ENTER
-
      -
    -

    Once a valid username and password is authenticated by CUPS, any - additional group membership requirements are checked.

    -
    - - -
    NOTE: -

    The root user is considered by CUPS to be a member of every group.

    -
    -
    -

    Use the AuthType directive to enable Digest - authentication:

    -
      -
      -AuthType Digest
-
      -
    -

    System and Group Authentication

    -

    The AuthClass directive - controls the level of authentication to perform. System - and Group authentication extend the normal user-based - authentication to require membership in a UNIX group. For System - authentication each user must belong to the sys, -system, or root group; the actual group depends on - the operating system.

    -

    For Group authentication each user must belong to the - group named by the AuthGroupName - directive:

    -
      -
      -<Location /path>
-AuthType Digest
-AuthClass Group
-AuthGroupName mygroup
-</Location>
-
      -
    -

    The named group must be a valid UNIX user group, usually defined in - the /etc/group or /etc/netgroup files. - Additionally, when using Digest authentication you need to create user - accounts with the named group:

    -
      -
      -lppasswd -g mygroup -a user ENTER
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
      -
    - - -

    Printer Accounting

    -

    CUPS maintains a log of all accesses, errors, and pages that are - printed. The log files are normally stored in the /var/log/cups - directory. You can change this by editing the /etc/cups/cupsd.conf - configuration file.

    -

    The access_log File

    -

    The access_log file lists each HTTP resource that is - accessed by a web browser or CUPS/IPP client. Each line is in the - so-called "Common Log Format" used by many web servers and web - reporting tools:

    -
      -
      -host group user date-time \"method resource version\" status bytes
-
-127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0
-127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0
-
      -
    -

    The host field will normally only be an IP address unless you - have enabled the HostNameLookups - directive in the cupsd.conf file.

    -

    The group field always contains "-" in CUPS.

    -

    The user field is the authenticated username of the requesting - user. If no username and password is supplied for the request then this - field contains "-".

    -

    The date-time field is the date and time of the request in - local time and is in the format:

    -
      -
      -[DD/MON/YYYY:HH:MM:SS +ZZZZ]
-
      -
    -

    where ZZZZ is the timezone offset in hours and minutes from - Greenwich Mean Time (a.k.a. GMT a.k.a. ZULU.)

    -

    The method field is the HTTP method used ("GET", "PUT", - "POST", etc.)

    -

    The resource field is the filename of the requested resource.

    -

    The version field is the HTTP specification version used by - the client. For CUPS clients this will always be "HTTP/1.1".

    -

    The status field contains the HTTP result status of the - request. Usually it is "200", but other HTTP status codes are possible. - For example, 401 is the "unauthorized access" status in the example - above.

    -

    The bytes field contains the number of bytes in the request. - For POST requests the bytes field contains the number of bytes - that was received from the client.

    -

    The error_log File

    -

    The error_log file lists messages from the scheduler - (errors, warnings, etc.):

    -
      -
      -level date-time message
-
-I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
-I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
-I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
-
      -
    -

    The level field contains the type of message:

    -
      -
    • E - An error occurred.
      • -
    • W - The server was unable to perform some action.
      • -
    • I - Informational message.
      • -
    • D - Debugging message.
      • -
    -

    The date-time field contains the date and time of when the - page started printing. The format of this field is identical to the - data-time field in the access_log file.

    -

    The message fields contains a free-form textual message.

    -

    The page_log File

    -

    The page_log file lists each page that is sent to a - printer. Each line contains the following information:

    -
      -
      -printer user job-id date-time page-number num-copies job-billing
-
-DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123
-
      -
    -

    The printer field contains the name of the printer that - printed the page. If you send a job to a printer class, this field will - contain the name of the printer that was assigned the job.

    -

    The user field contains the name of the user (the IPP -requesting-user-name attribute) that submitted this file for - printing.

    -

    The job-id field contains the job number of the page being - printed. Job numbers are reset to 1 whenever the CUPS server is - started, so don't depend on this number being unique!

    -

    The date-time field contains the date and time of when the - page started printing. The format of this field is identical to the - data-time field in the access_log file.

    -

    The page-number and num-pages fields contain the page - number and number of copies being printed of that page. For printer - that can not produce copies on their own, the num-pages field - will always be 1.

    -

    The job-billing field contains a copy of the job-billing - attribute provided with the IPP create-job or -print-job requests or "-" if none was provided. - -

    -

    File Typing and Filtering

    -

    CUPS provides a MIME-based file typing and filtering mechanism to - convert files to a printable format for each printer. On startup the - CUPS server reads MIME database files from the /etc/cups - directory (or a directory specified by the -ServerRoot directive) to build a file type and conversion - database in memory. These database files are plain ASCII text and can - be edited with your favorite text editor.

    -

    The mime.types and mime.convs files define the - standard file types and filters that are available on the system.

    -

    mime.types

    -

    The mime.types file defines the known file types. Each - line of the file starts with the MIME type and may be followed by one - or more file type recognition rules. For example, the text/html - file type is defined as:

    -
      -
      -text/html       html htm \
-                printable(0,1024) + \
-                (string(0,"<HTML>") string(0,"<!DOCTYPE"))
-
      -
    -

    The first two rules say that any file with an extension of .html - or .htm is a HTML file. The third rule says that any file - whose first 1024 characters are printable text and starts with the - strings <HTML> or <!DOCTYPE is a HTML file as - well.

    -

    The first two rules deal solely with the name of the file being - typed. This is useful when the original filename is known, however for - print files the server doesn't have a filename to work with. The third - rule takes care of this possibility and automatically figures out the - file type based upon the contents of the file instead.

    -

    The available tests are:

    -
      -
    • ( expr ) - Parenthesis for expression grouping
      • -
    • + - Logical AND
      • -
    • , or whitespace - Logical OR
      • -
    • ! - Logical NOT
      • -
    • match("pattern") - Pattern match on filename
      • -
    • extension - Pattern match on "*.extension"
      • -
    • ascii(offset,length) - True if bytes are valid - printable ASCII (CR, NL, TAB, BS, 32-126)
      • -
    • printable(offset,length) - True if bytes are printable - 8-bit chars (CR, NL, TAB, BS, 32-126, 160-254)
      • -
    • string(offset,"string") - True if bytes are identical - to string
      • -
    • contains(offset,range,"string") - True if the range of - bytes contains the string
      • -
    • char(offset,value) - True if byte is identical
      • -
    • short(offset,value) - True if 16-bit integer is - identical (network or "big-endian" byte order)
      • -
    • int(offset,value) - True if 32-bit integer is identical - (network or "big-endian" byte order)
      • -
    • locale("string") - True if current locale matches - string
      • -
    -

    All numeric values can be in decimal (123), octal (0123), or - hexadecimal (0x123) as desired. - -

    -

    Strings can be in quotes, all by themselves, as a string of - hexadecimal values, or some combination:

    -
      -
      -"string"
-'string'
-string
-<737472696e67>
-<7374>ring
-
      -
    -

    As shown in the text/html example, rules can continue on - multiple lines using the backslash (\) character. A more complex - example is the image/jpeg rules:

    -
      -
      -image/jpeg      jpeg jpg jpe string(0,<FFD8FF>) &&\
-                (char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
-                 char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
-                 char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
-                 char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
-
      -
    -

    This rule states that any file with an extension of .jpeg, - .jpg, or .jpe is a JPEG file. In addition, any file - starting with the hexadecimal string <FFD8FF> (JPEG - Start-Of-Image) followed by a character between and including -0xe0 and 0xef (JPEG APPn markers) is also a JPEG - file.

    -

    mime.convs

    -

    The mime.convs file defines all of the filter programs - that are known to the system. Each line consists of:

    -
      -
      -source destination cost program
-
-text/plain application/postscript 50 texttops
-application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
-image/* application/vnd.cups-postscript 50 imagetops
-image/* application/vnd.cups-raster 50 imagetoraster
-
      -
    -

    The source field is a MIME type, optionally using a wildcard - for the super-type or sub-type (e.g. "text/plain", "image/*", - "*/postscript").

    -

    The destination field is a MIME type defined in the - mime.types file.

    -

    The cost field defines a relative cost for the filtering - operation from 1 to 100. The cost is used to choose between two - different sets of filters when converting a file. For example, to - convert from image/jpeg to -application/vnd.cups-raster, you could use the imagetops - and pstoraster filters for a total cost of 100, or the -imagetoraster filter for a total cost of 50.

    -

    The program field defines the filter program to run; the - special program "-" can be used to make two file types equivalent. The - program must accept the standard filter arguments and environment - variables described in the CUPS Interface Design Description and CUPS - Software Programmers Manual:

    -
      -
      -program job user title options [filename]
-
      -
    -

    If specified, the filename argument defines a file to read - when filtering, otherwise the filter must read from the standard input. - All filtered output must go to the standard output. - -

    -

    Adding Filetypes and Filters

    -

    Adding a new file type or filter is fairly straight-forward. Rather - than adding the new type and filter to the mime.types and - mime.convs files which are overwritten when you upgrade to a new - version of CUPS, you simple need to create new files with .types - and .convs extensions in the /etc/cups directory. - We recommend that you use the product or format name, e.g.:

    -
      -
      -myproduct.types
-myproduct.convs
-
      -
    -

    If you are providing a filter for a common file format or printer, - add the company or author name:

    -
      -
      -acme-msword.types
-acme.msword.convs
-
      -
    -

    This will help to prevent name collisions if you install many - different file types and filters.

    -

    Once you choose the names for these files, create them using your - favorite text editor as described earlier in this chapter. Once you - have created the files, restart the cupsd process as - described earlier in "Restarting the CUPS Server" -.

    -

    Printer Drivers and PPD Files

    -

    Most CUPS printer drivers utilize one or more printer-specific - filters and a PPD file for each printer model. Printer driver filters - are registered via the PPD file using cupsFilter - attributes:

    -
      -
      -*cupsFilter: "application/vnd.cups-raster 0 rastertohp"
-
      -
    -

    The filter is specified using the source file type only; the - destination file type is assumed to be printer/name - - suitable for sending to the printer.

    -

    Writing Your Own Filter or Printer Driver

    -

    CUPS supports an unlimited number of file formats and filters, and - can handle any printer. If you'd like to write a filter or printer - driver for your favorite file format or printer, consult the CUPS - Software Programmers Manual for step-by-step instructions.

    -

    7 - Printing with Other - Systems

    -

    This chapter describes how to print from client systems that use the - LPD, Mac OS, or Windows printing protocols.

    -

    The Basics

    -

    CUPS is based on the IPP protocol, so any system that supports IPP - can send jobs to and receive jobs from CUPS automatically. However, not - all systems support IPP yet. This chapter will show you how to connect - these systems to your CUPS server, either to accept jobs from your - server for printing, or to send jobs to your server.

    -

    Printing from LPD Clients

    -

    CUPS supports limited functionality for LPD-based clients. With LPD - you can print files to specific printers, list the queue status, and so - forth. However, the automatic client configuration and printer options - are not supported by the LPD protocol, so you must manually configure - each client for the printers it needs to access.

    -

    The cups-lpd(8) program provides support for LPD clients - and can be used from either the inetd(8) or -xinetd(8) programs. Add the following line to the - /etc/inetd.conf file to enable LPD support on your server through - the inetd program:

    -
      -
      -printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
-
      -
    -

    The path to the cups-lpd may vary depending on your - installation.

    -

    Once you have added this line, send the inetd process a -HUP signal or reboot the system:

    -
      -
      -killall -HUP inetd ENTER [IRIX and some versions of Linux]
-kill -HUP pid ENTER [Others]
-reboot ENTER [For all systems if the HUP signal fails]
-
      -
    -

    If you are using the xinetd program, create a file named - /etc/xinetd.d/printer containing the following lines:

    -
      -
      -service printer
-{
-    socket_type = stream
-    protocol = tcp
-    wait = no
-    user = lp
-    server = /usr/lib/cups/daemon/cups-lpd
-}
-
      -
    -

    The xinetd program automatically reads the new - configuration file and enables LPD printing support. -

    - - -
    Warning: -

    cups-lpd currently does not perform any access control - based on the settings in cupsd.conf or in the - hosts.allow or hosts.deny files used by TCP wrappers. - Therefore, running cups-lpd on your server will allow any - computer on your network (and perhaps the entire Internet) to print to - your server.

    -

    While xinetd has built-in access control support, you - should use the TCP wrappers package with inetd to limit - access to only those computers that should be able to print through - your server.

    -
    -
    -

    -

    Printing to LPD Servers

    -

    CUPS provides the lpd backend for printing to LPD-based - servers and printers. Use a device URI of lpd://server/name - to print to a printer on an LPD server, where server is - the hostname or IP address of the server and name is the - queue name.

    -

    Microsoft Windows NT provides an LPD service under the name "TCP/IP - Printing Services". To enable LPD printing on NT, open the "Services" - control panel, select the "TCP/IP Printing Services" service, and click - on the "Start" button. Any shared printer will then be available via - the LPD protocol.

    -

    Printing from Mac OS Clients

    -

    CUPS does not provide Mac OS support directly. However, there are - several free and commercial software packages that do.

    -

    Columbia Appletalk Package (CAP)

    -

    Because the CAP LaserWriter server (lwsrv(8)) does not - support specification of PPD files, we do not recommend that you use - CAP with CUPS. However, you can run the lpsrv program for - limited printing with the command:

    -
      -
      -lwsrv -n "Name" -p printer -a /usr/lib/adicts -f /usr/lib/LW+Fonts
-
      -
    -

    where Name is the name you want to use when sharing the - printer, and printer is the name of the CUPS print queue. - -

    -

    XINET KA/Spool

    -

    To use your system as a print server for Mac OS clients, configure - each printer using a papserver(8) in the - /usr/adm/appletalk/services file, specifying the corresponding - PPD file in the /etc/cups/ppd directory for each printer. - For a printer named MyPrinter the entry would look like:

    -
      -
      -/usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
-"Printer Description" MyPrinter
-
      -
    -
    - - -
    NOTE: -

    Enter the text above on a single line without the backslash (\) - character.

    -
    -
    -

    NetATalk

    -

    To use your system as a print server for Mac OS clients, configure - each printer in the papd.conf file, specifying the - corresponding PPD file in the /etc/cups/ppd directory for - each printer. For a printer named MyPrinter the entry - would look like:

    -
      -
      -Printer Description:MyPrinter@MyServer:\
-        :pr=|/usr/bin/lp -d MyPrinter:\
-        :op=daemon:\
-        :pd=/etc/cups/ppd/MyPrinter.ppd:
-
      -
    - - -

    Printing to Mac OS Servers

    -

    CUPS currently does not provide a backend to communicate with a Mac - OS server. However, you can write and install a short shell script in - the /usr/lib/cups/backend directory that sends a print file - using the appropriate command. The following is a short script that - will run the papif command provided with CAP.

    -

    After copying this script to /usr/lib/cups/backend/cap, - specify a device URI of cap://server/printer to use this - backend with a print queue. - -

    -
      -
      -"/usr/lib/cups/backend/cap"
-#!/bin/sh
-#
-# Usage: cap job user title copies options [filename]
-#
-
-# No arguments means show available devices...
-
-if test ${#argv} = 0; then
-	echo "network cap \"Unknown\" \"Mac OS Printer via CAP\""
-	exit 0
-fi
-
-# Collect arguments...
-
-user=$2
-copies=$4
-
-if test ${#argv} = 5; then
-	# Get print file from stdin; copies have already been handled...
-	file=/var/tmp/$$.prn
-	copies=1
-	cat > $file
-else
-	# Print file is on command-line...
-	file=$6
-fi
-
-# Create a dummy cap.printers file for this printer based
-# upon a device URI of "cap://server/printer"...
-
-echo $PRINTER/$DEVICE_URI | \
-	awk -F/ '{print $1 "=" $5 ":LaserWriter@" $4}' > /var/tmp/$$.cap
-
-CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS
-
-# Send the file to the printer, once for each copy. This assumes that you
-# have properly initialized the cap.printers file...
-
-while [ $copies -gt 0 ]; do
-	papif -n $user < $file
-
-        copies=`expr $copies - 1`
-done
-
-# Remove any temporary files...
-if test ${#argv} = 5; then
-	/bin/rm -f $file
-fi
-
-/bin/rm -f /var/tmp/$$.cap
-
-exit 0
-
      -
    - - -

    Printing from Windows Clients

    -

    While CUPS does not provide Windows support directly, the free SAMBA - software package does. SAMBA version 2.0.6 is the first release of - SAMBA that supports CUPS. You can download SAMBA from:

    - -

    To configure SAMBA for CUPS, edit the smb.conf file and - replace the existing printing commands and options with the line:

    -
      -
      -printing = cups
-printcap name = cups
-
      -
    -

    That's all there is to it! Remote users will now be able to browse - and print to printers on your system.

    -

    Exporting Printer Drivers

    -

    You can optionally export printer drivers from your CUPS server using - the cupsaddsmb command and the SAMBA 2.2.0 or higher - software.

    -

    Before you can export the printers you must download the current - Adobe PostScript printer drivers from the Adobe web site ( -http://www.adobe.com/). Use the free unzip software to - extract the files from the self-extracting ZIP file containing the - drivers; you will need the following files:

    -
      -
      -ADFONTS.MFM
-ADOBEPS4.DRV
-ADOBEPS4.HLP
-ADOBEPS5.DLL
-ADOBEPSU.DLL
-ADOBEPSU.HLP
-DEFPRTR2.PPD
-ICONLIB.DLL
-PSMON.DLL
-
      -
    -

    Copy these files to the /usr/share/cups/drivers directory - - you may need to rename some of the files so the filenames are all - UPPERCASE.

    -

    Next, add a print$ share for the printer drivers to your - smb.conf file:

    -
      -
      -[print$]
-    comment = Printer Drivers
-    path = /etc/samba/drivers
-    browseable = yes
-    guest ok = no
-    read only = yes
-    write list = root
-
      -
    -

    The directory for your printer drivers can be anywhere on the system; - just make sure it is writable by the users specified by the write - list directive. Also, make sure that you have SAMBA passwords - defined for each user in the write list using the -smbpasswd(1) command. Otherwise you will not be able to - authenticate

    -

    Finally, run the cupsaddsmb command to export the - printer drivers for one or more queues:

    -
      -
      -cupsaddsmb -U root printer1 ... printerN ENTER
-
      -
    -

    Running cupsaddsmb with the -a option will - export all printers:

    -
      -
      -cupsaddsmb -U root -a ENTER
-
      -
    -

    Printing to Windows Servers

    -

    CUPS can print to Windows servers in one of two ways. The first way - uses the LPD protocol on the CUPS system and the "TCP/IP Printing - Services" on the Windows system. You can find out more about this - configuration in the LPD section earlier in this - chapter.

    -

    The second way is through the Microsoft Server Message Block ("SMB") - protocol. Support for this protocol is provided with the free SAMBA - software package. You can download SAMBA from:

    - -

    To configure CUPS for SAMBA, run the following command:

    -
      -
      -ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER
-
      -
    -

    The smbspool(1) program is provided with SAMBA starting - with SAMBA 2.0.6. Once you have made the link you can configure your - printers with one of the following device URIs:

    -
      -
      -smb://workgroup/server/sharename
-smb://server/sharename
-smb://user:pass@workgroup/server/sharename
-smb://user:pass@server/sharename
-
      -
    -

    The workgroup name need only be specified if your system - is using a different workgroup. The user:pass strings are - required when printing to Windows NT servers or to shares with - passwords enabled under Windows 95 and 98.

    -

    A - Software License Agreement

    -

    Common UNIX Printing System License - Agreement

    -

    Copyright 1997-2003 by Easy Software Products -
    44141 AIRPORT VIEW DR STE 204 -
    HOLLYWOOD, MARYLAND 20636-3111 USA -
    -
    Voice: +1.301.373.9600 -
    Email: cups-info@cups.org -
    WWW: http://www.cups.org

    -

    Introduction

    -

    The Common UNIX Printing SystemTM, ("CUPSTM"), - is provided under the GNU General Public License ("GPL") and GNU - Library General Public License ("LGPL"), Version 2, with exceptions for - Apple operating systems and the OpenSSL toolkit. A copy of the - exceptions and licenses follow this introduction.

    -

    The GNU LGPL applies to the CUPS API library, located in the "cups" - subdirectory of the CUPS source distribution and in the "cups" include - directory and library files in the binary distributions. The GNU GPL - applies to the remainder of the CUPS distribution, including the - "pdftops" filter which is based upon Xpdf and the CUPS imaging library.

    -

    For those not familiar with the GNU GPL, the license basically allows - you to:

    -
      -
    • Use the CUPS software at no charge.
      • -
    • Distribute verbatim copies of the software in source or binary form.
      • -
    • Sell verbatim copies of the software for a media fee, or sell - support for the software.
      • -
    • Distribute or sell printer drivers and filters that use CUPS so long - as source code is made available under the GPL.
      • -
    -

    What this license does not allow you to do is make changes or - add features to CUPS and then sell a binary distribution without source - code. You must provide source for any new drivers, changes, or - additions to the software, and all code must be provided under the GPL - or LGPL as appropriate. The only exceptions to this are the portions of - the CUPS software covered by the Apple operating system license - exceptions outlined later in this license agreement.

    -

    The GNU LGPL relaxes the "link-to" restriction, allowing you to - develop applications that use the CUPS API library under other licenses - and/or conditions as appropriate for your application.

    -

    License Exceptions

    -

    In addition, as the copyright holder of CUPS, Easy Software Products - grants the following special exceptions:

    -
      -
    1. Apple Operating System Development License Exception; -
        -
      1. Software that is developed by any person or entity for an Apple - Operating System ("Apple OS-Developed Software"), including but not - limited to Apple and third party printer drivers, filters, and backends - for an Apple Operating System, that is linked to the CUPS imaging - library or based on any sample filters or backends provided with CUPS - shall not be considered to be a derivative work or collective work - based on the CUPS program and is exempt from the mandatory source code - release clauses of the GNU GPL. You may therefore distribute linked - combinations of the CUPS imaging library with Apple OS-Developed - Software without releasing the source code of the Apple OS-Developed - Software. You may also use sample filters and backends provided with - CUPS to develop Apple OS-Developed Software without releasing the - source code of the Apple OS-Developed Software.
        2. -
      2. An Apple Operating System means any operating system software - developed and/or marketed by Apple Computer, Inc., including but not - limited to all existing releases and versions of Apple's Darwin, Mac OS - X, and Mac OS X Server products and all follow-on releases and future - versions thereof.
        3. -
      3. This exception is only available for Apple OS-Developed Software and - does not apply to software that is distributed for use on other - operating systems.
        4. -
      4. All CUPS software that falls under this license exception have the - following text at the top of each source file:
        This file is - subject to the Apple OS-Developed Software exception.
        5. -
      -
      2. -
    2. OpenSSL Toolkit License Exception; -
        -
      1. Easy Software Products explicitly allows the compilation and - distribution of the CUPS software with the OpenSSL Toolkit.
        2. -
      -
      3. -
    -

    No developer is required to provide these exceptions in a derived - work.

    -

    Trademarks

    -

    Easy Software Products has trademarked the Common UNIX Printing - System, CUPS, and CUPS logo. These names and logos may be used freely - in any direct port or binary distribution of CUPS. Please contract Easy - Software Products for written permission to use them in derivative - products. Our intention is to protect the value of these trademarks and - ensure that any derivative product meets the same high-quality - standards as the original.

    -

    Binary Distribution Rights

    -

    Easy Software Products also sells rights to the CUPS source code - under a binary distribution license for vendors that are unable to - release source code for their drivers, additions, and modifications to - CUPS under the GNU GPL and LGPL. For information please contact us at - the address shown above.

    -

    The Common UNIX Printing System provides a "pdftops" filter that is - based on the Xpdf software. For binary distribution licensing of this - software, please contact:

    Derek B. Noonburg -
    Email: derekn@foolabs.com -
    WWW: - http://www.foolabs.com/xpdf/

    -

    Support

    -

    Easy Software Products sells software support for CUPS as well as a - commercial printing product based on CUPS called ESP Print Pro. You can - find out more at our web site:

    - - - -

    GNU GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright 1989, 1991 Free Software Foundation, Inc.
-59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-Everyone is permitted to copy and distribute verbatim
-copies of this license document, but changing it is not allowed.
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public License is - intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users. This - General Public License applies to most of the Free Software - Foundation's software and to any other program whose authors commit to - using it. (Some other Free Software Foundation software is covered by - the GNU Library General Public License instead.) You can apply it to - your programs, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the software, or if you modify it.

    -

    For example, if you distribute copies of such a program, whether - gratis or for a fee, you must give the recipients all the rights that - you have. You must make sure that they, too, receive or can get the - source code. And you must show them these terms so they know their - rights.

    -

    We protect your rights with two steps: (1) copyright the software, - and (2) offer you this license which gives you legal permission to - copy, distribute and/or modify the software.

    -

    Also, for each author's protection and ours, we want to make certain - that everyone understands that there is no warranty for this free - software. If the software is modified by someone else and passed on, we - want its recipients to know that what they have is not the original, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that redistributors of a free - program will individually obtain patent licenses, in effect making the - program proprietary. To prevent this, we have made it clear that any - patent must be licensed for everyone's free use or not licensed at all.

    -

    The precise terms and conditions for copying, distribution and - modification follow.

    -

    GNU GENERAL PUBLIC LICENSE -
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -
      -
    1. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", below, - refers to any such program or work, and a "work based on the Program" - means either the Program or any derivative work under copyright law: - that is to say, a work containing the Program or a portion of it, - either verbatim or with modifications and/or translated into another - language. (Hereinafter, translation is included without limitation in - the term "modification".) Each licensee is addressed as "you". -

      Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - the Program is not restricted, and the output from the Program is - covered only if its contents constitute a work based on the Program - (independent of having been made by running the Program). Whether that - is true depends on what the Program does.

      -
    2. You may copy and distribute verbatim copies of the Program's source - code as you receive it, in any medium, provided that you conspicuously - and appropriately publish on each copy an appropriate copyright notice - and disclaimer of warranty; keep intact all the notices that refer to - this License and to the absence of any warranty; and give any other - recipients of the Program a copy of this License along with the - Program. -

      You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

      -
    3. You may modify your copy or copies of the Program or any portion of - it, thus forming a work based on the Program, and copy and distribute - such modifications or work under the terms of Section 1 above, provided - that you also meet all of these conditions: -
        -
      1. You must cause the modified files to carry prominent notices stating - that you changed the files and the date of any change.
        2. -
      2. You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any part - thereof, to be licensed as a whole at no charge to all third parties - under the terms of this License.
        3. -
      3. if the modified program normally reads commands interactively when - run, you must cause it, when started running for such interactive use - in the most ordinary way, to print or display an announcement including - an appropriate copyright notice and a notice that there is no warranty - (or else, saying that you provide a warranty) and that users may - redistribute the program under these conditions, and telling the user - how to view a copy of this License. (Exception: if the Program itself - is interactive but does not normally print such an announcement, your - work based on the Program is not required to print an announcement.)
        4. -
      -

      These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Program, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Program, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

      -

      Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Program.

      -

      In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

      -
    4. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms of - Sections 1 and 2 above provided that you also do one of the following: -
        -
      1. Accompany it with the complete corresponding machine-readable source - code, which must be distributed under the terms of Sections 1 and 2 - above on a medium customarily used for software interchange; or,
        2. -
      2. Accompany it with a written offer, valid for at least three years, - to give any third party, for a charge no more than your cost of - physically performing source distribution, a complete machine-readable - copy of the corresponding source code, to be distributed under the - terms of Sections 1 and 2 above on a medium customarily used for - software interchange; or,
        3. -
      3. Accompany it with the information you received as to the offer to - distribute corresponding source code. (This alternative is allowed only - for noncommercial distribution and only if you received the program in - object code or executable form with such an offer, in accord with - Subsection b above.)
        4. -
      -

      The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete source - code means all the source code for all modules it contains, plus any - associated interface definition files, plus the scripts used to control - compilation and installation of the executable. However, as a special - exception, the source code distributed need not include anything that - is normally distributed (in either source or binary form) with the - major components (compiler, kernel, and so on) of the operating system - on which the executable runs, unless that component itself accompanies - the executable.

      -

      If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent access - to copy the source code from the same place counts as distribution of - the source code, even though third parties are not compelled to copy - the source along with the object code.

      -
    5. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt otherwise - to copy, modify, sublicense or distribute the Program is void, and will - automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such parties - remain in full compliance.
      6. -
    6. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify or - distribute the Program or its derivative works. These actions are - prohibited by law if you do not accept this License. Therefore, by - modifying or distributing the Program (or any work based on the - Program), you indicate your acceptance of this License to do so, and - all its terms and conditions for copying, distributing or modifying the - Program or works based on it.
      7. -
    7. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program subject to - these terms and conditions. You may not impose any further restrictions - on the recipients' exercise of the rights granted herein. You are not - responsible for enforcing compliance by third parties to this License.
      8. -
    8. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent issues), - conditions are imposed on you (whether by court order, agreement or - otherwise) that contradict the conditions of this License, they do not - excuse you from the conditions of this License. If you cannot - distribute so as to satisfy simultaneously your obligations under this - License and any other pertinent obligations, then as a consequence you - may not distribute the Program at all. For example, if a patent license - would not permit royalty-free redistribution of the Program by all - those who receive copies directly or indirectly through you, then the - only way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. -

      If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply and the section as a whole is intended to apply in other - circumstances.

      -

      It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system, which is - implemented by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

      -

      This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

      -
    9. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, the - original copyright holder who places the Program under this License may - add an explicit geographical distribution limitation excluding those - countries, so that distribution is permitted only in or among countries - not thus excluded. In such case, this License incorporates the - limitation as if written in the body of this License.
      10. -
    10. The Free Software Foundation may publish revised and/or new versions - of the General Public License from time to time. Such new versions will - be similar in spirit to the present version, but may differ in detail - to address new problems or concerns. -

      Each version is given a distinguishing version number. If the Program - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Program does not specify a version - number of this License, you may choose any version ever published by - the Free Software Foundation.

      -
    11. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted by the - Free Software Foundation, write to the Free Software Foundation; we - sometimes make exceptions for this. Our decision will be guided by the - two goals of preserving the free status of all derivatives of our free - software and of promoting the sharing and reuse of software generally.
      12. - - - - - - -
    -

    NO WARRANTY

    -
      -
    1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY - FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN - OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES - PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER - EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE - ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH - YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL - NECESSARY SERVICING, REPAIR OR CORRECTION.
      2. -
    2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY - AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.
      3. -
    -

    END OF TERMS AND CONDITIONS

    - - -

    GNU LIBRARY GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright (C) 1991 Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-
-[This is the first released version of the library GPL.  It is
- numbered 2 because it goes with version 2 of the ordinary GPL.]
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public Licenses - are intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users.

    -

    This license, the Library General Public License, applies to some - specially designated Free Software Foundation software, and to any - other libraries whose authors decide to use it. You can use it for your - libraries, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the library, or if you modify it.

    -

    For example, if you distribute copies of the library, whether gratis - or for a fee, you must give the recipients all the rights that we gave - you. You must make sure that they, too, receive or can get the source - code. If you link a program with the library, you must provide complete - object files to the recipients so that they can relink them with the - library, after making changes to the library and recompiling it. And - you must show them these terms so they know their rights.

    -

    Our method of protecting your rights has two steps: (1) copyright the - library, and (2) offer you this license which gives you legal - permission to copy, distribute and/or modify the library.

    -

    Also, for each distributor's protection, we want to make certain that - everyone understands that there is no warranty for this free library. - If the library is modified by someone else and passed on, we want its - recipients to know that what they have is not the original version, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that companies distributing free - software will individually obtain patent licenses, thus in effect - transforming the program into proprietary software. To prevent this, we - have made it clear that any patent must be licensed for everyone's free - use or not licensed at all.

    -

    Most GNU software, including some libraries, is covered by the - ordinary GNU General Public License, which was designed for utility - programs. This license, the GNU Library General Public License, applies - to certain designated libraries. This license is quite different from - the ordinary one; be sure to read it in full, and don't assume that - anything in it is the same as in the ordinary license.

    -

    The reason we have a separate public license for some libraries is - that they blur the distinction we usually make between modifying or - adding to a program and simply using it. Linking a program with a - library, without changing the library, is in some sense simply using - the library, and is analogous to running a utility program or - application program. However, in a textual and legal sense, the linked - executable is a combined work, a derivative of the original library, - and the ordinary General Public License treats it as such.

    -

    Because of this blurred distinction, using the ordinary General - Public License for libraries did not effectively promote software - sharing, because most developers did not use the libraries. We - concluded that weaker conditions might promote sharing better.

    -

    However, unrestricted linking of non-free programs would deprive the - users of those programs of all benefit from the free status of the - libraries themselves. This Library General Public License is intended - to permit developers of non-free programs to use free libraries, while - preserving your freedom as a user of such programs to change the free - libraries that are incorporated in them. (We have not seen how to - achieve this as regards changes in header files, but we have achieved - it as regards changes in the actual functions of the Library.) The hope - is that this will lead to faster development of free libraries.

    -

    The precise terms and conditions for copying, distribution and - modification follow. Pay close attention to the difference between a - "work based on the library" and a "work that uses the library". The - former contains code derived from the library, while the latter only - works together with the library.

    -

    Note that it is possible for a library to be covered by the ordinary - General Public License rather than by this special one.

    -

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -

    0. This License Agreement applies to any software - library which contains a notice placed by the copyright holder or other - authorized party saying it may be distributed under the terms of this - Library General Public License (also called "this License"). Each - licensee is addressed as "you".

    -

    A "library" means a collection of software functions and/or data - prepared so as to be conveniently linked with application programs - (which use some of those functions and data) to form executables.

    -

    The "Library", below, refers to any such software library or work - which has been distributed under these terms. A "work based on the - Library" means either the Library or any derivative work under - copyright law: that is to say, a work containing the Library or a - portion of it, either verbatim or with modifications and/or translated - straightforwardly into another language. (Hereinafter, translation is - included without limitation in the term "modification".)

    -

    "Source code" for a work means the preferred form of the work for - making modifications to it. For a library, complete source code means - all the source code for all modules it contains, plus any associated - interface definition files, plus the scripts used to control - compilation and installation of the library.

    -

    Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - a program using the Library is not restricted, and output from such a - program is covered only if its contents constitute a work based on the - Library (independent of the use of the Library in a tool for writing - it). Whether that is true depends on what the Library does and what the - program that uses the Library does.

    -

    1. You may copy and distribute verbatim copies of - the Library's complete source code as you receive it, in any medium, - provided that you conspicuously and appropriately publish on each copy - an appropriate copyright notice and disclaimer of warranty; keep intact - all the notices that refer to this License and to the absence of any - warranty; and distribute a copy of this License along with the Library.

    -

    You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

    -

    2. You may modify your copy or copies of the Library - or any portion of it, thus forming a work based on the Library, and - copy and distribute such modifications or work under the terms of - Section 1 above, provided that you also meet all of these conditions:

    -
      -
    1. The modified work must itself be a software library. -

      -
    2. You must cause the files modified to carry prominent notices stating - that you changed the files and the date of any change. -

      -
    3. You must cause the whole of the work to be licensed at no charge to - all third parties under the terms of this License. -

      -
    4. If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses the - facility, other than as an argument passed when the facility is - invoked, then you must make a good faith effort to ensure that, in the - event an application does not supply such function or table, the - facility still operates, and performs whatever part of its purpose - remains meaningful. -

      (For example, a function in a library to compute square roots has a - purpose that is entirely well-defined independent of the application. - Therefore, Subsection 2d requires that any application-supplied - function or table used by this function must be optional: if the - application does not supply it, the square root function must still - compute square roots.)

      -
      5. - - - -
    -

    These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Library, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Library, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

    -

    Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Library.

    -

    In addition, mere aggregation of another work not based on the - Library with the Library (or with a work based on the Library) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

    -

    3. You may opt to apply the terms of the ordinary - GNU General Public License instead of this License to a given copy of - the Library. To do this, you must alter all the notices that refer to - this License, so that they refer to the ordinary GNU General Public - License, version 2, instead of to this License. (If a newer version - than version 2 of the ordinary GNU General Public License has appeared, - then you can specify that version instead if you wish.) Do not make any - other change in these notices.

    -

    Once this change is made in a given copy, it is irreversible for that - copy, so the ordinary GNU General Public License applies to all - subsequent copies and derivative works made from that copy.

    -

    This option is useful when you wish to copy part of the code of the - Library into a program that is not a library.

    -

    4. You may copy and distribute the Library (or a - portion or derivative of it, under Section 2) in object code or - executable form under the terms of Sections 1 and 2 above provided that - you accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections 1 - and 2 above on a medium customarily used for software interchange.

    -

    If distribution of object code is made by offering access to copy - from a designated place, then offering equivalent access to copy the - source code from the same place satisfies the requirement to distribute - the source code, even though third parties are not compelled to copy - the source along with the object code.

    -

    5. A program that contains no derivative of any - portion of the Library, but is designed to work with the Library by - being compiled or linked with it, is called a "work that uses the - Library". Such a work, in isolation, is not a derivative work of the - Library, and therefore falls outside the scope of this License.

    -

    However, linking a "work that uses the Library" with the Library - creates an executable that is a derivative of the Library (because it - contains portions of the Library), rather than a "work that uses the - library". The executable is therefore covered by this License. Section - 6 states terms for distribution of such executables.

    -

    When a "work that uses the Library" uses material from a header file - that is part of the Library, the object code for the work may be a - derivative work of the Library even though the source code is not. - Whether this is true is especially significant if the work can be - linked without the Library, or if the work is itself a library. The - threshold for this to be true is not precisely defined by law.

    -

    If such an object file uses only numerical parameters, data structure - layouts and accessors, and small macros and small inline functions (ten - lines or less in length), then the use of the object file is - unrestricted, regardless of whether it is legally a derivative work. - (Executables containing this object code plus portions of the Library - will still fall under Section 6.)

    -

    Otherwise, if the work is a derivative of the Library, you may - distribute the object code for the work under the terms of Section 6. - Any executables containing that work also fall under Section 6, whether - or not they are linked directly with the Library itself.

    -

    6. As an exception to the Sections above, you may - also compile or link a "work that uses the Library" with the Library to - produce a work containing portions of the Library, and distribute that - work under terms of your choice, provided that the terms permit - modification of the work for the customer's own use and reverse - engineering for debugging such modifications.

    -

    You must give prominent notice with each copy of the work that the - Library is used in it and that the Library and its use are covered by - this License. You must supply a copy of this License. If the work - during execution displays copyright notices, you must include the - copyright notice for the Library among them, as well as a reference - directing the user to the copy of this License. Also, you must do one - of these things:

    -
      -
    1. Accompany the work with the complete corresponding machine-readable - source code for the Library including whatever changes were used in the - work (which must be distributed under Sections 1 and 2 above); and, if - the work is an executable linked with the Library, with the complete - machine-readable "work that uses the Library", as object code and/or - source code, so that the user can modify the Library and then relink to - produce a modified executable containing the modified Library. (It is - understood that the user who changes the contents of definitions files - in the Library will not necessarily be able to recompile the - application to use the modified definitions.) -

      -
    2. Accompany the work with a written offer, valid for at least three - years, to give the same user the materials specified in Subsection 6a, - above, for a charge no more than the cost of performing this - distribution. -

      -
    3. If distribution of the work is made by offering access to copy from - a designated place, offer equivalent access to copy the above specified - materials from the same place. -

      -
    4. Verify that the user has already received a copy of these materials - or that you have already sent this user a copy.
      5. - - - -
    -

    For an executable, the required form of the "work that uses the - Library" must include any data and utility programs needed for - reproducing the executable from it. However, as a special exception, - the source code distributed need not include anything that is normally - distributed (in either source or binary form) with the major components - (compiler, kernel, and so on) of the operating system on which the - executable runs, unless that component itself accompanies the - executable.

    -

    It may happen that this requirement contradicts the license - restrictions of other proprietary libraries that do not normally - accompany the operating system. Such a contradiction means you cannot - use both them and the Library together in an executable that you - distribute.

    -

    7. You may place library facilities that are a work - based on the Library side-by-side in a single library together with - other library facilities not covered by this License, and distribute - such a combined library, provided that the separate distribution of the - work based on the Library and of the other library facilities is - otherwise permitted, and provided that you do these two things:

    -
      -
    1. Accompany the combined library with a copy of the same work based on - the Library, uncombined with any other library facilities. This must be - distributed under the terms of the Sections above. -

      -
    2. Give prominent notice with the combined library of the fact that - part of it is a work based on the Library, and explaining where to find - the accompanying uncombined form of the same work.
      3. - -
    -

    8. You may not copy, modify, sublicense, link with, - or distribute the Library except as expressly provided under this - License. Any attempt otherwise to copy, modify, sublicense, link with, - or distribute the Library is void, and will automatically terminate - your rights under this License. However, parties who have received - copies, or rights, from you under this License will not have their - licenses terminated so long as such parties remain in full compliance.

    -

    9. You are not required to accept this License, - since you have not signed it. However, nothing else grants you - permission to modify or distribute the Library or its derivative works. - These actions are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Library (or any work based - on the Library), you indicate your acceptance of this License to do so, - and all its terms and conditions for copying, distributing or modifying - the Library or works based on it.

    -

    10. Each time you redistribute the Library (or any - work based on the Library), the recipient automatically receives a - license from the original licensor to copy, distribute, link with or - modify the Library subject to these terms and conditions. You may not - impose any further restrictions on the recipients' exercise of the - rights granted herein. You are not responsible for enforcing compliance - by third parties to this License.

    -

    11. If, as a consequence of a court judgment or - allegation of patent infringement or for any other reason (not limited - to patent issues), conditions are imposed on you (whether by court - order, agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this License. If - you cannot distribute so as to satisfy simultaneously your obligations - under this License and any other pertinent obligations, then as a - consequence you may not distribute the Library at all. For example, if - a patent license would not permit royalty-free redistribution of the - Library by all those who receive copies directly or indirectly through - you, then the only way you could satisfy both it and this License would - be to refrain entirely from distribution of the Library.

    -

    If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply, and the section as a whole is intended to apply in other - circumstances.

    -

    It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system which is implemented - by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

    -

    This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

    -

    12. If the distribution and/or use of the Library is - restricted in certain countries either by patents or by copyrighted - interfaces, the original copyright holder who places the Library under - this License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only in or - among countries not thus excluded. In such case, this License - incorporates the limitation as if written in the body of this License.

    -

    13. The Free Software Foundation may publish revised - and/or new versions of the Library General Public License from time to - time. Such new versions will be similar in spirit to the present - version, but may differ in detail to address new problems or concerns.

    -

    Each version is given a distinguishing version number. If the Library - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Library does not specify a license - version number, you may choose any version ever published by the Free - Software Foundation.

    -

    14. If you wish to incorporate parts of the Library - into other free programs whose distribution conditions are incompatible - with these, write to the author to ask for permission. For software - which is copyrighted by the Free Software Foundation, write to the Free - Software Foundation; we sometimes make exceptions for this. Our - decision will be guided by the two goals of preserving the free status - of all derivatives of our free software and of promoting the sharing - and reuse of software generally.

    -

    NO WARRANTY

    -

    15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, - THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY - APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE - OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU - ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

    -

    16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR - AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO - MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL - OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.

    -

    END OF TERMS AND CONDITIONS

    -

    B - Common Network Settings -

    -

    This appendix covers many of the popular TCP/IP network interfaces - and printer servers available on the market today.

    -

    Configuring a Network Interface

    -

    When you first install a network printer or print server on your LAN, - you need to set the Internet Protocol ("IP") address. On most - higher-end "workgroup" printers, you can set the address through the - printer control panel. However, in most cases you will want to assign - the addresses remotely from your workstation. This makes administration - a bit easier and avoids assigning duplicate addresses accidentally.

    -

    To setup your printer or print server for remote address assignment, - you'll need the Ethernet Media Access Control ("MAC") address, also - sometimes called a node address, and the IP address you want to use for - the device. The Ethernet MAC address can often be found on the printer - test page or bottom of the print server. - -

    -

    Configuring the IP Address Using ARP

    -

    The easiest way to set the IP address of a network device is to use - the arp(8) command. The arp sends an Address - Resolution Protocol ("ARP") packet to the specified Ethernet MAC - address, setting the network device's IP address:

    -
      -
      -arp -s ip-address ethernet-address ENTER
-arp -s host.domain.com 08:00:69:00:12:34 ENTER
-arp -s 192.0.2.2 08:00:69:00:12:34 ENTER
-
      -
    -

    Configuring the IP Address Using RARP

    -

    The most flexible way to remotely assign IP addresses under UNIX is - through the Reverse Address Resolution Protocol ("RARP"). RARP allows a - network device to request an IP address using its Ethernet MAC address, - and one or more RARP servers on the network will respond with an ARP - packet with the IP address the device can use.

    -

    RARP should be used when you have to manage many printers or print - servers, or when you have a network device that does not remember its - IP address after a power cycle. If you just have a single printer or - print server, the arp command is the way to go.

    -

    Some UNIX operating systems use a program called rarpd(8) - to manage RARP. Others, like Linux, support this protocol in the - kernel. For systems that provide the rarpd program you - will need to start it before RARP lookups will work:

    -
      -
      -rarpd ENTER
-
      -
    -

    Under IRIX you can enable this functionality by default using:

    -
      -
      -chkconfig rarpd on ENTER
-
      -
    -

    Both the rarpd program and kernel RARP support read a - list of Ethernet and IP addresses from the file /etc/ethers. - Each line contains the Ethernet address (colon delimited) followed by - an IP address or hostname like:

    -
      -
      -08:00:69:00:12:34 myprinter.mydomain.com
-08:00:69:00:12:34 192.0.2.2
-
      -
    -

    Add a line to this file and cycle the power on the printer or print - server to set its address. - -

    -

    Configuring the IP Address Using BOOTP

    -

    The BOOTP protocol is used when you need to provide additional - information such as the location of a configuration file to the network - interface. Using the standard bootpd(8) program supplied - with UNIX you simply need to add a line to the /etc/bootptab - file; for IRIX:

    -
      -
      -myprinter 08:00:69:00:12:34 192.0.2.2 myprinter.boot
-
      -
    - - -

    Newer versions of bootpd use a different format:

    -
      -
      -myprinter:ha=080069001234:ip=192.0.2.2:t144=myprinter.boot
-
      -
    -

    The myprinter.boot file resides in the - /usr/local/boot directory by default. If you do not need to - provide a boot file you may leave the last part of the line blank.

    - - -
    - - -
    NOTE: -

    Some versions of UNIX do not enable the BOOTP service by default. The - /etc/inetd.conf usually contains a line for the BOOTP service - that can be uncommented if needed.

    -
    -
    -

    Verifying the Printer Connection

    -

    To test that the IP address has been successfully assigned and that - the printer is properly connected to your LAN, type:

    -
      -
      -ping ip-address ENTER
-
      -
    -

    If the connection is working properly you will see something like:

    -
      -
      -ping myprinter ENTER
-PING myprinter (192.0.2.2): 56 data bytes
-64 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
-64 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
-64 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
-64 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
-
      -
    -

    If not, verify that the printer or print server is connected to the - LAN, it is powered on, the LAN cabling is good, and the IP address is - set correctly. You can usually see the current IP address and network - status by printing a configuration or test page on the device. - -

    -

    Common Network Interface Settings

    -

    Once you have set the IP address you can access the printer or print - server using the ipp, lpd, or socket - backends. The following is a list of common network interfaces and - printer servers and the settings you should use with CUPS: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Model/ManufacturerDevice - URI(s)
    Apple LaserWriterlpd:// -address/PASSTHRU
    Axis w/o IPP -
    (see directions)    		socket://address -:9100 -
    socket://address:9101 -
    socket://address:9102
    Axis w/IPPipp://address -/LPT1 -
    ipp://address/LPT2 -
    ipp://address/COM1
    Castelle LANpressTM -lpd://address/pr1 -
    lpd://address/pr2 -
    lpd://address/pr3
    DPI NETPrintlpd://address -/pr1 -
    lpd://address/pr2 -
    lpd://address/pr3
    EFI® Fiery® RIPlpd:// -address/print
    EPSON® Multiprotocol Ethernet - Interface Boardsocket://address
    Extended System ExtendNET -lpd://address/pr1 -
    lpd://address/pr2 -
    lpd://address/pr3
    Hewlett Packard JetDirect w/o IPP -socket://address:9100 -
    socket://address:9101 -
    socket://address:9102
    Hewlett Packard JetDirect w/IPP -ipp://address/ipp -
    ipp://address/ipp/port1 -
    ipp://address/ipp/port2 -
    ipp://address/ipp/port3
    Intel® NetportExpress XL, PRO/100 -lpd://address/LPT1_PASSTHRU -
    lpd://address/LPT2_PASSTHRU -
    lpd://address/COM1_PASSTHRU
    LexmarkTM MarkNet -lpd://address/ps
    Linksys EtherFast® -
    (see directions)    		socket://address -:4010 -
    socket://address:4020 -
    socket://address:4030
    Kodak®lpd://address/ps
    QMS® CrownNetTM -lpd://address/ps
    Tektronix® PhaserShareTM -socket://address:9100
    XEROX® 4512 NIClpd:// -address/PORT1
    XEROX® XNIClpd://address -/PASSTHRU
    XEROX® (most others)socket:// -address:5503
    -
    -

    -

    Configuring Axis Print Servers

    -

    The Axis print servers can be configured using ARP, RARP, or BOOTP. - However, on models that do not provide IPP support an additional step - must be performed to configure the TCP/IP portion of the print server - for use with CUPS. - -

    -

    Each print server contains a configuration file named config - that contains a list of network parameters used by the server. To - modify this file you must first download it from the print server using - the ftp(1) program:

    -
      -
      -ftp ip-address ENTER
-Connected to ip-address.
-220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
-ftp> user root ENTER
-331 User name ok, need password
-Password: pass ENTER (this is not echoed)
-230 User logged in
-ftp> get config ENTER
-local: config remote: config
-200 PORT command successful.
-150 Opening data connection for config (192,0,2,2),
-(mode ascii).
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
      -
    - - -

    Next, edit the file with your favorite text editor and locate the - lines beginning with:

    -
      -
      -RTN_OPT.     : YES
-RTEL_PR1.    : 0
-RTEL_PR2.    : 0
-RTEL_PR3.    : 0
-RTEL_PR4.    : 0
-RTEL_PR5.    : 0
-RTEL_PR6.    : 0
-RTEL_PR7.    : 0
-RTEL_PR8.    : 0
-
      -
    - - - Change the RTN_OPT line to read: -
      -
      -RTN_OPT.     : NO
-
      -
    - - -

    This disables the Reverse TELNET protocol and enables the standard - TELNET protocol on the print server. Next, assign a port number for - each parallel and serial port on the server as follows:

    -
      -
      -RTEL_PR1.    : 9100
-RTEL_PR2.    : 9101
-RTEL_PR3.    : 9102
-RTEL_PR4.    : 9103
-RTEL_PR5.    : 9104
-RTEL_PR6.    : 9105
-RTEL_PR7.    : 9106
-RTEL_PR8.    : 9107
-
      -
    - - -

    This essentially makes the Axis print server look like a Hewlett - Packard JetDirect EX print server. Save the file and then upload the - new config file using the ftp command:

    -
      -
      -ftp ip-address ENTER
-Connected to ip-address.
-220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
-ftp> user root ENTER
-331 User name ok, need password
-Password: pass ENTER (this is not echoed)
-230 User logged in
-ftp> put config CONFIG ENTER
-local: config remote: CONFIG
-200 PORT command successful.
-150 Opening data connection for config (192,0,2,2), (mode ascii).
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> get hardreset ENTER
-local: hardreset remote: hardreset
-200 PORT command successful.
-421 Axis NPS ### hard reset, closing connection.
-ftp> quit ENTER
-221 Goodbye.
-
      -
    -

    Your Axis print server is now ready for use!

    -

    Configuring Linksys Print Servers

    -

    The Linksys print servers can be configured using ARP, RARP, or - BOOTP. Like older Axis print servers, an additional step must be - performed to configure the TCP/IP portion of the print server for use - with CUPS. - -

    -

    Each print server contains a configuration file named CONFIG - that contains a list of network parameters used by the server. To - modify this file you must first download it from the print server using - the ftp(1) program:

    -
      -
      -ftp -n ip-address ENTER
-Connected to ip-address.
-220 Print Server Ready.
-Remote system type is Print.
-ftp> get CONFIG ENTER
-local: CONFIG remote: CONFIG
-200 Command OK.
-150 Open ASCII Mode Connection.
-WARNING! 68 bare linefeeds received in ASCII mode
-File may not have transferred correctly.
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
      -
    - - -

    Next, edit the file with your favorite text editor and locate the - lines beginning with:

    -
      -
      -0100 L1_PROUT:P1
-0120 L2_PROUT:P1
-0140 L3_PROUT:P1
-
      -
    -

    Change the port number for each parallel and serial port on the - server as follows:

    -
      -
      -0100 L1_PROUT:P1
-0120 L2_PROUT:P2
-0140 L3_PROUT:P3
-
      -
    - - -

    This maps each virtual printer with a physical port. Save the file - and then upload the new CONFIG file using the ftp - command:

    -
      -
      -ftp -n ip-address ENTER
-Connected to ip-address.
-220 Print Server Ready.
-Remote system type is Print.
-ftp> put CONFIG ENTER
-local: CONFIG remote: CONFIG
-200 Command OK.
-150 Open ASCII Mode Connection.
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
      -
    -

    Your Linksys print server is now ready for use!

    -

    C - Printer Drivers

    -

    This appendix lists the printer drivers that are provided with CUPS.

    -

    Printer Drivers

    -

    CUPS includes the following printer drivers:

    - -

    EPSON 9-pin Dot Matrix

    -

    The EPSON 9-pin Dot Matrix driver (epson9.ppd) supports - 9-pin dot matrix printers that implement the ESC/P command set. It - provides 60x72, 120x72, and 240x72 DPI output in black only.

    -

    EPSON 24-pin Dot Matrix

    -

    The EPSON 24-pin Dot Matrix driver (epson9.ppd) supports - 24-pin dot matrix printers that implement the ESC/P command set. It - provides 120x180, 180x180, 360x180, and 360x360 DPI output in black - only.

    -

    EPSON Stylus Color

    -

    The EPSON Stylus Color driver (stcolor.ppd) supports EPSON - Stylus Color printers that implement the ESC/P2 command set. It - provides 180, 360, and 720 DPI output in black and color (CMYK).

    -

    EPSON Stylus Photo

    -

    The EPSON Stylus Photo driver (stphoto.ppd) supports EPSON - Stylus Photo printers that implement the ESC/P2 command set. It - provides 180, 360, and 720 DPI output in black and color (CMYKcm).

    -

    HP DeskJet

    -

    The HP DeskJet driver (deskjet.ppd) supports HP DeskJet - printers that implement the PCL command set. It provides 150, 300, and - 600 DPI output in black and color (CMYK).

    -

    The DeskJet printers that implement the HP-PPA command set (720C, - 722C, 820C, and 1100C) are not supported due to a complete lack - of documentation and support from Hewlett Packard.

    -

    The duplexer provided with the HP DeskJet 900 series printers is also - not supported for similar reasons.

    -

    HP LaserJet

    -

    The HP LaserJet driver (laserjet.ppd) supports HP LaserJet - printers that implement the PCL command set. It provides 150, 300, and - 600 DPI output in black only and supports the duplexer if installed.

    -

    LaserJet printers that do not implement PCL (3100, 3150) are not - supported due to a complete lack of documentation and support from - Hewlett Packard.

    -

    D - List of Files

    -

    This appendix lists the files and directories that are installed for - the Common UNIX Printing System. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    PathnameDescription
    /etc/cups/certs/The location of - authentication certificate files for local HTTP clients.
    /etc/cups/classes.confThe printer classes - configuration file for the scheduler.
    /etc/cups/cupsd.confThe scheduler - configuration file.
    /etc/cups/interfaces/The location of - System V interface scripts for printers.
    /etc/cups/mime.convsThe list of standard - file filters included with CUPS.
    /etc/cups/mime.typesThe list of recognized - file types for CUPS.
    /etc/cups/ppd/The location of PostScript - Printer Description ("PPD") files for printers.
    /etc/cups/printers.confThe printer - configuration file for the scheduler.
    /usr/bin/cancelThe System V cancel job(s) - command.
    /usr/bin/disableThe System V disable - printer command.
    /usr/bin/enableThe System V enable printer - command.
    /usr/bin/lpThe System V print command.
    /usr/bin/lpoptionsSets user-defined - printing options and defaults.
    /usr/bin/lppasswdAdds, changes, or removes - Digest password accounts.
    /usr/bin/lpqThe Berkeley status command.
    /usr/bin/lprThe Berkeley print command.
    /usr/bin/lprmThe Berkeley cancel job(s) - command.
    /usr/bin/lpstatThe System V status - command.
    /usr/include/cups/CUPS API header files.
    /usr/lib32/libcups.a -
    /usr/lib32/libcupsimage.a    		Static libraries (IRIX 6.5)
    /usr/lib/libcups.a -
    /usr/lib/libcupsimage.a    		Static libraries (all others)
    /usr/lib/libcups.sl.2 -
    /usr/lib/libcupsimage.sl.2    		Shared libraries (HP-UX)
    /usr/lib32/libcups.so.2 -
    /usr/lib32/libcupsimage.so.2    		Shared libraries (IRIX 6.5)
    /usr/lib/libcups.so.2 -
    /usr/lib/libcupsimage.so.2    		Shared libraries (all others)
    /usr/lib/cups/backend/Backends for various - types of printer connections.
    /usr/lib/cups/cgi-bin/CGI programs for the - scheduler.
    /usr/lib/cups/daemon/Daemons for polling - and LPD support.
    /usr/lib/cups/filter/Filters for various - types of files.
    /usr/lib/locale/The location of - language-specific message files. (System V)
    /usr/lib/nls/msg/The location of - language-specific message files. (Compaq Tru64 UNIX)
    /usr/share/locale/The location of - language-specific message files. (Linux, *BSD)
    /usr/sbin/acceptThe accept-jobs command.
    /usr/sbin/cupsdThe CUPS print scheduler.
    /usr/sbin/lpadminThe System V printer - administration tool.
    /usr/sbin/lpcThe Berkeley printer - administration tool.
    /usr/sbin/lpinfoThe get-devices and - get-ppds command.
    /usr/sbin/lpmoveThe move-jobs command.
    /usr/sbin/rejectThe reject-jobs command.
    /usr/share/catman/a_man/ -
    /usr/share/catman/u_man/    		Man pages (IRIX)
    /usr/share/man/Man pages (Compaq Tru64 - UNIX, HP-UX, Solaris)
    /usr/man/Man pages (all others)
    /usr/share/cups/data/The location of - filter data files.
    /usr/share/cups/data/testprint.psThe - PostScript test page file.
    /usr/share/cups/fonts/The location of - PostScript fonts for the PostScript RIP.
    /usr/share/cups/model/The location of - PostScript Printer Description ("PPD") files and interface scripts that - may be used to setup a printer queue.
    /usr/share/cups/pstoraster/Other - PostScript RIP initialization files.
    /usr/share/cups/pstoraster/FontmapThe font - mapping file (converts filenames to fontnames)
    /usr/share/cups/templates/The location of - HTML template files for the web interfaces.
    /usr/share/doc/cups/Documentation and web - page data for the scheduler.
    /var/log/cups/The location of scheduler - log files.
    /var/spool/cups/The location of print - files waiting to be printed.
    -
    -

    -

    E - Troubleshooting Common Problems

    -

    This appendix covers some of the common problems first-time users - encounter when installing and configuring CUPS.

    -

    Commercial support for CUPS is available from Easy Software Products. - For more information please contact us at:

    - -

    My Applications Don't See the Available Printers

    -

    Many applications read the /etc/printcap file to get a - list of available printers.

    -

    The default CUPS configuration creates the /etc/printcap - file automatically. To enable or disable automatic creation and - updating of this file, use the Printcap - directive described in Chapter 6, - "Printing System Management".

    -

    CUPS Doesn't Recognize My Username or Password!

    -

    CUPS will ask you for a UNIX username and password when you perform - printer administration tasks remotely or via a web browser. The default - configuration requires that you use the root username and - the corresponding password to authenticate the request.

    -

    CUPS does not allow you to authenticate an administration request - with an account that has no password for security reasons. If you do - not have a password on your root account then you won't be - able to add printers remotely or via the web interface! - -

    -

    To disable password authentication you need to edit the - /etc/cups/cupsd.conf file and comment out the lines reading:

    -
      -
      -AuthType Basic
-AuthClass System
-
      -
    -

    for the /admin location. Then restart the CUPS server as - described in Chapter 6, "Printing System - Management".

    -
    - - -
    NOTE: -

    Disabling password checks will allow any local user to change your - printer and class configuration, but remote administration from another - machine will still not be allowed.

    -
    -
    -

    I Can't Do Administration Tasks from Another - Machine!

    -

    The default CUPS configuration limits administration to the local - machine. To open up access, edit the /etc/cups/cupsd.conf - and comment out the lines reading:

    -
      -
      -Order deny,allow
-Deny from all
-Allow from 127.0.0.1
-
      -
    -

    for the /admin location. Then restart the CUPS server as - described in Chapter 6, "Printing System - Management".

    -
    - - -
    NOTE: -

    Allowing administration access from all hosts is a potential security - risk. Please read Chapter 6, "Printing - System Management" for a description of these risks and ways to - minimize them.

    -
    -
    - - -

    I Can't Do Administration Tasks from My Web Browser! -

    -

    This problem is usually caused by:

    -
      -
    1. not specifying the correct password for the root account.
      2. -
    2. accessing the CUPS server using the hostname or IP address of the - server without enabling remote access for administration functions. - This can be corrected by following the instructions in the - "I Can't Do Administration Tasks from Another Machine!" section - earlier in this appendix.
      3. -
    3. not setting a password on the root account. CUPS will not - authenticate a user account that does not have a password for security - reasons.
      4. -
    4. authenticating using an account other than root, but the account you - are using is not a member of the system group.
      5. -
    5. configuring CUPS to use Digest authentication, but your web browser - does not support Digest authentication.
      6. -
    -

    Connection Refused Messages

    -

    Under normal circumstances, "connection refused" messages for a - networked printer should be expected from time to time. Most network - interfaces only allow a single connection to be made at any given time - (one job at a time) and will refuse access to all other systems while - the first connection is active. CUPS automatically retries the - connection once every 30 seconds.

    -

    If the problem persists and you are unable to print any jobs to the - printer, verify that another machine is not maintaining a connection - with the printer, and that you have selected the proper port or printer - name for the printer.

    -

    Also, most external print servers will refuse connections if the - connected printer is turned off or is off-line. Verify that the - affected printer is turned on and is online.

    -

    Write Error Messages

    -

    If you get "write error" messages on a printer queue the printer - interface (usually a Hewlett Packard JetDirect interface) has timed out - and reset the network connection from your workstation.

    -

    The error is caused by that startup delay between the initial setup - of the printer or plotter and the first page of print data that is - sent. - -

    -

    To correct the problem, change the idle timeout on the interface to - at least 180 seconds or 3 minutes. To change the timeout on a Hewlett - Packard JetDirect interface, type:

    -
      -
      -telnet ip-address ENTER
-
-Trying ip-address...
-Connected to ip-address.
-Escape character is `^]'.
-
-Please type [Return] two times, to initialize telnet configuration
-For HELP type "?"
-> idle-timeout: 180 ENTER
-> quit ENTER
-
      -
    - - diff --git a/doc/sam.pdf b/doc/sam.pdf deleted file mode 100644 index ae1b148171..0000000000 Binary files a/doc/sam.pdf and /dev/null differ diff --git a/doc/sam.shtml b/doc/sam.shtml deleted file mode 100644 index 9452aa2764..0000000000 --- a/doc/sam.shtml +++ /dev/null @@ -1,5062 +0,0 @@ - - - - - - CUPS Software Administrators Manual - - - -

    Preface

    - -

    This software administrators manual provides printer administration -information for the Common UNIX Printing SystemTM -("CUPSTM"), version 1.2.0. - - - - -

    Document Overview

    - -

    This software administrators manual is organized into the following sections:

    - - - -

    Notation Conventions

    - -

    Various font and syntax conventions are used in this guide. Examples and -their meanings and uses are explained below: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Example   Description
     
    lpstat
    - lpstat(1)    		   The names of commands; the first mention of a command or - function in a chapter is followed by a manual page section - number.
     
    /var
    - /usr/share/cups/data/testprint.ps    		   File and directory names.
     
    Request ID is Printer-123   Screen output.
     
    lp -d printer filename ENTER   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are written using the period (.) to indicate - the decimal point.
    - - -

    Abbreviations

    - -The following abbreviations are used throughout this manual: - -
      -
      - -
      kb -
      Kilobytes, or 1024 bytes
        - -
      Mb -
      Megabytes, or 1048576 bytes
        - -
      Gb -
      Gigabytes, or 1073741824 bytes
        - -
      -
    - -

    Other References

    - -
      -
      - -
      CUPS Software Programmers Manual - -
      A programmer guide for interfacing with and/or extending the CUPS - software.
        - -
      CUPS Software Users Manual - -
      An end-user guide for using the CUPS software.
        - -
      -
    - - - - - -

    2 - Building and Installing CUPS

    - -

    This chapter shows how to build and install the Common UNIX Printing System. -If you are installing a binary distribution from the CUPS web site, proceed to -the section titled, Installing a Binary Distribution. - -

    Installing a Source Distribution

    - -

    This section describes how to compile and install CUPS on your system -from the source code. - -

    Requirements

    - -

    You'll need ANSI-compliant C and C++ compilers to build CUPS on your -system. As its name implies, CUPS is designed to run on the UNIX -operating system, however the CUPS interface library and most of the -filters and backends supplied with CUPS should also compile and run -under Microsoft Windows. - -

    For the image file filters and PostScript RIP, you'll need the JPEG, -PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with -significantly reduced functionality. Easy Software Products maintains a -mirror of the current versions of these libraries at: - -

    - -

    If you make changes to the man pages you'll need GNU groff or another -nroff-like package. GNU groff is available from: - -

    - -

    The documentation is formatted using the HTMLDOC software. If you need to -make changes you can get the HTMLDOC software from: - -

    - -

    Finally, you'll need a make program that -understands the include directive - FreeBSD, -NetBSD, and OpenBSD developers should use the gmake -program. - -

    Compiling CUPS

    - -

    CUPS uses GNU autoconf to configure the makefiles and source code -for your system. Type the following command to configure CUPS for your -system: - -

      -./configure ENTER
-
    - -

    The default installation will put the CUPS software in the -/etc, /usr, and /var directories on -your system, which will overwrite any existing printing commands on -your system. Use the --prefix option to install the CUPS -software in another location: - -

      -./configure --prefix=/some/directory ENTER
-
    - -

    If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a -system default location (typically /usr/include and -/usr/lib) you'll need to set the CFLAGS, -CXXFLAGS, and LDFLAGS environment variables -prior to running configure: - -

      -setenv CFLAGS "-I/some/directory" ENTER
-setenv CXXFLAGS "-I/some/directory" ENTER
-setenv LDFLAGS "-L/some/directory" ENTER
-setenv DSOFLAGS "-L/some/directory" ENTER
-./configure ... ENTER
-
    - -

    or: - -

      -CFLAGS="-I/some/directory"; export CFLAGS ENTER
-CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER
-LDFLAGS="-L/some/directory"; export LDFLAGS ENTER
-DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER
-./configure ... ENTER
-
    - -

    To enable support for encryption, you'll also want to add the -"--enable-ssl" option: - -

      -./configure --enable-ssl
-
    - -

    SSL and TLS support require the OpenSSL library, available at: - -

    - -

    If the OpenSSL headers and libraries are not installed in the -standard directories, use the --with-openssl-includes -and --with-openssl-libs options:

    - -
      -./configure --enable-ssl \
-    --with-openssl-includes=/foo/bar/include \
-    --with-openssl-libs=/foo/bar/lib
-
    - -

    Once you have configured things, just type: - -

      -make ENTER
-
    - -

    to build the software. - - -

    Installing the Software

    - -

    Use the "install" target to install the software: - -

      -make install ENTER
-
    - -
    - - - -
    - WARNING: - -

    Installing CUPS will overwrite your existing printing - system. If you experience difficulties with the CUPS software - and need to go back to your old printing system, you will need - to reinstall the old printing system from your operating system CDs. -

    - -

    Running the Software

    - -

    Once you have installed the software you can start the CUPS server by -typing: - -

      -/usr/sbin/cupsd ENTER
-
    - - -

    Installing a Binary Distribution

    - -

    CUPS comes in a variety of binary distribution formats. Easy -Software Products provides binaries in TAR format with installation and -removal scripts ("portable" distributions), and in RPM and DPKG formats -for Red Hat and Debian-based distributions. Portable distributions are -available for all platforms, while the RPM and DPKG distributions are -only available for Linux. - -

    - - - -
    - WARNING: - -

    Installing CUPS will overwrite your existing printing - system. If you experience difficulties with the CUPS software - and need to go back to your old printing system, you will need - to remove the CUPS software with the provided script and/or - reinstall the old printing system from your operating system CDs. -

    - - -

    Installing a Portable Distribution

    - -

    To install the CUPS software from a portable distribution you will -need to be logged in as root; doing an su is good enough. -Once you are the root user, run the installation script with: - -

      -./cups.install ENTER
-
    - -

    After asking you a few yes/no questions the CUPS software will be -installed and the scheduler will be started automatically. - - -

    Installing an RPM Distribution

    - -

    To install the CUPS software from an RPM distribution you will need -to be logged in as root; doing an su is good enough. Once -you are the root user, run RPM with: - -

      -rpm -e lpr
-rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER
-
    - -

    After a short delay the CUPS software will be -installed and the scheduler will be started automatically. - -

    Installing an Debian Distribution

    - -

    To install the CUPS software from a Debian distribution you will -need to be logged in as root; doing an su is good enough. -Once you are the root user, run dpkg with: - -

      -dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER
-
    - -

    After a short delay the CUPS software will be installed and the -scheduler will be started automatically. - - -

    3 - Managing Printers

    - -

    This chapter describes how to add your first printer and how to -manage your printers. - -

    The Basics

    - -

    Each printer queue has a name associated with it; the printer name -must start with a letter and can contain up to 127 letters, numbers, -and the underscore (_). Case is not significant, e.g. "PRINTER", "Printer", -and "printer" are considered to be the same name. - -

    Printer queues also have a device associated with them. The device can be -a parallel port, a network interface, and so forth. Devices within CUPS use -Uniform Resource Identifiers ("URIs") which are a more general form of -Uniform Resource Locators ("URLs") that are used in your web browser. For -example, the first parallel port in Linux usually uses a device URI of -parallel:/dev/lp1. - - -

    You can see a complete list of supported devices by running the -lpinfo(8) command: - -

      -lpinfo -v ENTER
-network socket
-network http
-network ipp
-network lpd
-direct parallel:/dev/lp1
-serial serial:/dev/ttyS1?baud=115200
-serial serial:/dev/ttyS2?baud=115200
-direct usb:/dev/usb/lp0
-network smb
-
    - -

    The -v option specifies that you want a list of available -devices. The first word in each line is the type of device (direct, file, -network, or serial) and is followed by the device URI or method name for -that device. File devices have device URIs of the form -file:/directory/filename while network devices use the more -familiar method://server or method://server/path -format. - -

    Finally, printer queues usually have a PostScript Printer Description -("PPD") file associated with them. PPD files describe the capabilities of -each printer, the page sizes supported, etc., and are used for PostScript -and non-PostScript printers. CUPS includes PPD files for HP LaserJet, HP -DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus printers. - -

    Adding Your First Printer

    - -

    CUPS provides two methods for adding printers: a command-line -program called lpadmin(8) and a Web interface. The -lpadmin command allows you to perform most printer -administration tasks from the command-line and is located in -/usr/sbin. The Web interface is located at: - -

    - -

    and steps you through printer configuration. If you don't like -command-line interfaces, try the Web interface instead. - -

    Adding Your First Printer from the Command-Line

    - -

    Run the lpadmin command with the -p option to add a -printer to CUPS: - -

      -/usr/sbin/lpadmin -p printer -E -v device -m ppd ENTER
-
    - -

    For a HP DeskJet printer connected to the parallel port this would look -like: - -

      -/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER
-
    - -

    Similarly, a HP LaserJet printer using a JetDirect network interface at -IP address 11.22.33.44 would be added with the command: - -

      -/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER
-
    - -

    As you can see, deskjet.ppd and laserjet.ppd are -the PPD files for the HP DeskJet and HP LaserJet drivers included with CUPS. -You'll find a complete list of PPD files and the printers they will work with -in Appendix C, "Printer Drivers". - - -

    For a dot matrix printer connected to the serial port this would might look like: - -

      -/usr/sbin/lpadmin -p DotMatrix -E -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft deskjet.ppd ENTER
-
    - -

    Here you specify the serial port (e.g. S0,S1, d0, d1), baud rate -(e.g. 9600, 19200, 38400, 115200, etc.), number of bits, parity, and flow control. -If you do not need flow control, delete the "+flow=soft" portion. - - -

    Adding Your First Printer from the Web

    - -

    The CUPS web server provides a user-friendly "wizard" interface for -adding your printers. Rather than figuring out which device URI and PPD file -to use, you can instead click on the appropriate listings and fill in some -simple information. Enter the following URL in your web browser to begin: - -

    - -

    Click on the Add Printer button to add a printer. - -

    Managing Printers from the Command-Line

    - -

    The lpadmin command enables you to perform most printer -administration tasks from the command-line. You'll find lpadmin -in the /usr/sbin directory. - -

    Adding and Modifying Printers

    - -

    Run the lpadmin command with the -p option -to add or modify a printer: - -

      -/usr/sbin/lpadmin -p printer options ENTER
-
    - -

    The options arguments can be any of the following: - -

      -
      - -
      -c class - -
      Adds the named printer to printer class class. - If the class does not exist then it is created. - -
      -i interface - -
      Copies the named interface script to the printer. - Interface scripts are used by System V printer drivers. Since - all filtering is disabled when using an interface script, scripts - generally should not be used unless there is no other driver for - a printer. - -
      -m model - -
      Specifies a standard printer driver which is usually a PPD - file. A list of all available models can be displayed using the - lpinfo command with the -m option. A - list of printer drivers included with CUPS can be found in - Appendix C, "Printer Drivers". - -
      -r class - -
      Removes the named printer from printer class class. - If the resulting class becomes empty then it is removed. - -
      -v device-uri - -
      Sets the device for communicating with the printer. If a - job is currently printing on the named printer then the job - will be restarted and sent to the new device. - -
      -D info - -
      Provides a textual description of the printer, e.g. - "John's Personal Printer". - -
      -E - -
      Enables the printer and accepts job. This option is - equivalent to running the enable(1) and - accept(8) commands on the printer. - -
      -L location - -
      Provides a textual location for the printer, e.g. - "Computer Lab 5". - -
      -P ppd-file - -
      Specifies a local PPD file for the printer driver. - -
      -
    - -

    Deleting Printers

    - -

    Run the lpadmin command with the -x option -to delete a printer: - -

      -/usr/sbin/lpadmin -x printer ENTER
-
    - -

    Setting the Default Printer

    - -

    Run the lpadmin command with the -d option -to set a default printer: - -

      -/usr/sbin/lpadmin -d printer ENTER
-
    - -

    The default printer can be overridden by the user using the -lpoptions(1) command. - -

    Starting and Stopping Printers

    - -

    The enable and disable commands start and stop -printer queues, respectively: - -

      -/usr/bin/enable printer ENTER
-/usr/bin/disable printer ENTER
-
    - -

    Printers that are disabled may still accept jobs for printing, but won't -actually print any files until they are restarted. This is useful if the -printer malfunctions and you need time to correct the problem. Any queued -jobs are printed after the printer is enabled (started). - -

    Accepting and Rejecting Print Jobs

    - -

    The accept and reject commands accept and reject -print jobs for the named printer, respectively: - -

      -/usr/sbin/accept printer ENTER
-/usr/sbin/reject printer ENTER
-
    - -

    As noted above, a printer can be stopped but accepting new print -jobs. A printer can also be rejecting new print jobs while it finishes -those that have been queued. This is useful for when you must perform -maintenance on the printer and will not have it available to users for -a long period of time. - -

    Setting Quotas on a Printer

    - -

    CUPS supports page and size-based quotas for each printer. -The quotas are tracked individually for each user, but a single set of -limits applies to all users for a partiuclar printer. For example, you -can limit every user to 5 pages per day on an expensive printer, but -you cannot limit every user except Johnny.

    - -

    The job-k-limit, job-page-limit, and job-quota-peiod -options determine whether and how quotas are enforced for a printer. -The job-quota-period option determines the time interval for -quota tracking. The interval is expressed in seconds, so a day is -86,400, a week is 604,800 and a month is 2,592,000 seconds. The -job-k-limit option specifies the job size limit in killobytes. The -job-page-limit option specifies the number of pages limit.

    - -

    For quotas to be enforced, the period and at least one of the limits -must be set to a non-zero value. The following options will enable -quotas:

    - -
      -
      -/usr/sbin/lpadmin -p printer -o job-quota-period=604800 -o job-k-limit=1024 ENTER
-/usr/sbin/lpadmin -p printer -o job-quota-period=604800 -o job-page-limit=100 ENTER
-
      -
    - -

    Or, you can combine all three options on the same line.

    - -

    Restricting User Access to a Printer

    - -

    The -u option of the lpadmin command controls which users can -print to a printer. The default configuration allows all users to print -to a printer:

    - -
      -
      -/usr/sbin/lpadmin -p printer -u allow:all ENTER
-
      -
    - -

    CUPS supports allow and deny lists so that you can specify a -list of users who are allowed to print or not allowed to print. Along -with your list of users, you can specify whether they are allowed or -not allowed to use the printer:

    - -
      -
      -/usr/sbin/lpadmin -p printer -u allow:peter,paul,mary ENTER
-
      -
    - -

    This command allows peter, paul, and mary to print to the named -printer, but all other users cannot print. The command:

    - -
      -
      -/usr/sbin/lpadmin -p printer -u deny:peter,paul,mary ENTER
-
      -
    - -

    has the opposite effect. All users except peter, paul, and mary will -be able to print to the named printer.

    - -

    You can control access by UNIX groups as well by placing an -"@" character before each group name. The command:

    - -
      -
      -/usr/sbin/lpadmin -p printer -u allow:peter,paul,mary,@printgods ENTER
-
      -
    - -

    allows the users peter, paul, and mary to print, as well as -any user in the printgods group to print. - -

    - - - - -
    NOTE: - -

    The allow and deny options are not cummulative. That - is, you must provide the complete list of users to allow or deny each - time.

    - -

    Also, CUPS only maintains one list of users - the list can - allow or deny users from printing. If you specify an allow list and - then specify a deny list, the deny list will replace the allow list - - only one list is active at any time.

    - -
    -
    - -

    Managing Printers from the Web

    - -

    The Web interface is located at: - -

    - -

    From there you can perform all printer management tasks with a few -simple mouse clicks. - - -

    4 - Printer Classes

    - -

    This chapter describes what printer classes are and how to manage them. - -

    The Basics

    - -

    CUPS provides collections of printers called printer classes. Jobs -sent to a class are forwarded to the first available printer in the class. -Classes can themselves be members of other classes, so it is possible for -you to define very large, distributed printer classes for high-availability -printing. - -

    CUPS also supports implicit classes. Implicit classes work just -like printer classes, but they are created automatically based upon the -available printers and classes on the network. This allows you to setup -multiple print servers with identical printer configurations and have the -client machines send their print jobs to the first available server. If -one or more servers go down, the jobs are automatically redirected to the -servers that are running, providing fail-safe printing. - -

    Managing Printer Classes from the Command-Line

    - -

    Run the lpadmin command with the -p and -c options -to add a printer to a class: - -

      -/usr/sbin/lpadmin -p printer -c class ENTER
-
    - -

    The class is created automatically if it doesn't exist. To remove a -printer from a class use the -r option: - -

      -/usr/sbin/lpadmin -p printer -r class ENTER
-
    - -

    To remove the entire class just use the -x option: - -

      -/usr/sbin/lpadmin -x class ENTER
-
    - -

    Managing Printer Classes from the Web Interface

    - -

    The Web interface is located at: - -

    - -

    The Add Class and Modify Class interfaces provide a -list of available printers; click on the printers of interest to add them to -the class. - -

    Implicit Classes

    - -

    A noted earlier, implicit classes are created automatically from the -available network printers and classes. To disable this functionality, -set the ImplicitClasses -directive to Off in the cupsd.conf file. You -will find more information on doing this in -Chapter 6, "Printing System -Management". - - -

    5 - Client Setup

    - -

    This chapter discusses several ways to configure CUPS clients for -printing. - -

    The Basics

    - -

    A client is any machine that sends print jobs to another machine for -final printing. Clients can also be servers if they communicate directly with -any printers of their own. - -

    CUPS supports several methods of configuring client machines: - -

    - -

    Manual Configuration of Print Queues

    - -

    The most tedious method of configuring client machines is to configure -each remote queue by hand using the lpadmin command: - -

      -lpadmin -p printer -E -v ipp://server/printers/printer ENTER
-
    - -

    The printer name is the name of the printer on the server -machine. The server name is the hostname or IP address of the -server machine. Repeat the lpadmin command for each remote -printer you wish to use.

    - -
    - - - - -
    NOTE: -

    Manual configuration of print queues is not recommended for large - numbers of client machines because of the administration nightmare it - creates. For busy networks, consider subnetting groups of clients and - polling and relaying printer information instead.

    -
    -
    - -

    Specifying a Single Server for Printing

    - -

    CUPS can be configured to run without a local spooler and send all -jobs to a single server. However, if that server goes down then all -printing will be disabled. Use this configuration only as absolutely needed. - -

    The default server is normally "localhost". To override the default -server create a file named /etc/cups/client.conf and add -a line reading: - -

      -ServerName server
-
    - -

    to the file. The server name can be the hostname or IP address -of the default server. - -

    The default server can also be customized on a per-user basis. To set a -user-specific server create a file named ~/.cupsrc and add a line -reading: - -

      -ServerName server
-
    - -

    to the file. The server name can be the hostname or IP -address of the default server. - -

    Automatic Configuration of Print Queues

    - -

    CUPS supports automatic client configuration of printers on the same -subnet. To configure printers on the same subnet, do nothing. -Each client should see the available printers within 30 seconds -automatically. The printer and class lists are updated automatically as -printers and servers are added or removed. - -

    If you want to see printers on other subnets as well, use the -BrowsePoll -directive as described next.

    - -
    - - - - -
    NOTE: -

    The BrowseAddress directive - enables broadcast traffic from your server. The default configuration - braodcasts printer information every 30 seconds. Although this printer - information does not use much bandwidth, typically about 80 bytes per - printer, it can add up with large numbers of servers and printers.

    -

    Use the BrowseInterval - and BrowseTimeout directives to tune - the amount of data that is added to your network load. In addition, - subnets can be used to minimize the amount of traffic that is carried - by the "backbone" of your large network.

    -
    -
    - -

    Specifying Multiple Servers for Printing

    - -

    If you have CUPS servers on different subnets, then you should configure -CUPS to poll those servers. Polling provides the benefits of automatic -configuration without significant configuration on the clients, and multiple -clients on the same subnet can share the same configuration information. - -

    Polling is enabled by specifying one or more -BrowsePoll -directives in the /etc/cups/cupsd.conf file. -For information on making these changes, see -Chapter 6, "Printing System Management". - -

    Multiple BrowsePoll lines can -be used to poll multiple CUPS servers. To limit the amount of -polling you do from client machines, you can have only one of the -clients do the polling and relay that information to the others on the -same subnet (described next).

    - -

    Relaying Printers to Other Clients

    - -

    When you have clients and servers spread across multiple subnets, the -polling method is inefficient. CUPS provides a -BrowseRelay directive that enables a -single client to relay (broadcast) the polled printer information to the local subnet.

    - -

    For example, Server A and Server B are on subnet 1 and subnet 2, -while the clients are on subnet 3. -To provide printers to all of the clients in subnet 3, -client C will be configured with the following directives in /etc/cups/cupsd.conf:

    - -
      -# Poll the two servers
-
-BrowsePoll ServerA ENTER
-BrowsePoll ServerB ENTER
-
-
-# Relay the printers to the local subnet
-
-BrowseRelay 127.0.0.1 192.168.3.255 ENTER
-
    - -

    The BrowseRelay line specifies a source address and mask. -Any browse packets coming from a matching address wil be sent to the given broadcast address. -In this case, we want the packets from the local machine (127.0.0.1) relayed to the other clients.

    - -

    As printers are found using polling, -they are relayed from client C to the rest of the clients through a broadcast on subnet 3. -The rest of the clients can use the standard cupsd.conf configuration.

    - -

    The BrowseRelay directive can also be used to relay -browsing packets from one network interface to another. -For example, if client C in the previous example had network interfaces attaches to both -subnet 1 and subnet 2, it could use the BrowseRelay directive exclusively: - -

      -# Relay the printers from subnet 1 and 2 to subnet 3
-
-BrowseRelay 192.168.1 192.168.3.255 ENTER
-BrowseRelay 192.168.2 192.168.3.255 ENTER
-
    - -

    Load Balancing and Failsafe Operation

    - -

    When using server polling or broadcasting, CUPS clients can -automatically merge identical printers on multiple servers into a -single implicit class queue. Clients assume that printers with -the same name on multiple servers are in fact the same printer or type -of printer being served by multiple machines.

    - -

    If you have two printers, LaserJet@ServerA and LaserJet@ServerB, a -third implicit class called LaserJet will be created -automatically on the client that refers to both printers. If the client -also has a local printer with the name LaserJet then an implicit class -named AnyLaserJet will be created instead.

    - -

    The client will alternate between servers and automatically stop -sending jobs to a server if it goes down, providing a load-balancing -effect and fail-safe operation with automatic switchover.

    - -
    - - - -
    NOTE: -

    Note that implicit classes (ImplicitClasses) - are enabled by default.

    -
    - -

    6 - Printing System Management

    - -

    This chapter shows how you can configure the CUPS server. - -

    The Basics

    - -

    Several text files are used to configure CUPS. All of the server -configuration files are located in the /etc/cups directory: - -

      -
      - - -
      classes.conf - -
      This file contains information on each printer class. - Normally you manipulate this file using the - lpadmin command or the Web interface.
        - - -
      client.conf - -
      This file provides the default server name for client - machines. See Chapter 5, "Client - Setup" for more information.
        - - -
      cupsd.conf - -
      This file controls how the CUPS server - (/usr/sbin/cupsd) operates and is normally edited by - hand.
        - - -
      mime.convs - -
      This file contains a list of standard file conversion filters - and their costs. You normally do not edit this file.
        - - -
      mime.types - -
      This file contains a list of standard file formats and how to - recognize them. You normally do not edit this file.
        - - -
      printers.conf - -
      This file contains information on each printer. Normally - you manipulate this file using the lpadmin command - or the Web Interface.
        - -
      -
    - -

    Restarting the CUPS Server

    - -

    Once you have made a change to a configuration file you need to -restart the CUPS server by sending it a HUP signal or using the -supplied initialization script. The CUPS distributions install the -script in the init.d directory with the name -cups. The location varies based upon the operating system: - -

      -/etc/software/init.d/cups restart ENTER
-/etc/rc.d/init.d/cups restart ENTER
-/etc/init.d/cups restart ENTER
-/sbin/init.d/cups restart ENTER
-
    - -

    Changing the Server Configuration

    - -

    The /etc/cups/cupsd.conf file contains configuration -directives that control how the server functions. Each directive -is listed on a line by itself followed by its value. Comments are -introduced using the number sign ("#") character at the beginning of a -line. Since the server configuration file consists of plain text, you -can use your favorite text editor to make changes to it. - - -

    Server Directives

    - -

    The cupsd.conf file contains many directives that -determine how the server operates: - -

    - - -

    AccessLog

    -
    - -

    Examples

    - -
      -AccessLog /var/log/cups/access_log
-AccessLog /var/log/cups/access_log-%s
-AccessLog syslog
-
    - -

    Description

    - -

    The AccessLog directive sets the name of the access log -file. If the filename is not absolute then it is assumed to be relative -to the ServerRoot directory. The -access log file is stored in "common log format" and can be used by any -web access reporting tool to generate a report on CUPS server activity. - -

    The server name can be included in the filename by using -%s in the name. - -

    The special name "syslog" can be used to send the access information -to the system log instead of a plain file. - -

    The default access log file is /var/log/cups/access_log. - - -

    Allow

    -
    - -

    Examples

    - -
      -Allow from All
-Allow from None
-Allow from *.domain.com
-Allow from .domain.com
-Allow from host.domain.com
-Allow from nnn.*
-Allow from nnn.nnn.*
-Allow from nnn.nnn.nnn.*
-Allow from nnn.nnn.nnn.nnn
-Allow from nnn.nnn.nnn.nnn/mm
-Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
-Allow from @LOCAL
-Allow from @IF(name)
-
    - -

    Description

    - -

    The Allow directive specifies a hostname, IP address, -or network that is allowed access to the server. Allow -directives are cummulative, so multiple Allow directives -can be used to allow access for multiple hosts or networks. The -/mm notation specifies a CIDR netmask: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    mmnetmaskmmnetmask
    00.0.0.08255.0.0.0
    1128.0.0.016255.255.0.0
    2192.0.0.024255.255.255.0
    ......32255.255.255.255
    - -

    The @LOCAL name will allow access from all local -network interfaces, but not remote point-to-point interfaces. The -@IF(name) name will allow access from the named -interface. - -

    The Allow directive must appear inside a -Location directive. - - -

    AuthClass

    -
    - -

    Examples

    - -
      -AuthClass Anonymous
-AuthClass User
-AuthClass System
-AuthClass Group
-
    - -

    Description

    - -

    The AuthClass directive defines what level of authentication -is required: - -

      - -
    • Anonymous - No authentication should be performed - (default.) - -
    • User - A valid username and password is required. - -
    • System - A valid username and password is - required, and the username must belong to the "sys" group; this - can be changed using the - SystemGroup directive. - -
    • Group - A valid username and password is - required, and the username must belong to the group named by - the AuthGroupName directive. - -
    - -

    The AuthClass directive must appear inside a -Location directive. - - -

    AuthGroupName

    -
    - -

    Examples

    - -
      -AuthGroupName mygroup
-AuthGroupName lp
-
    - -

    Description

    - -

    The AuthGroupName directive sets the group to use for -Group authentication. - -

    The AuthGroupName directive must appear inside a -Location directive. - - -

    AuthType

    -
    - -

    Examples

    - -
      -AuthType None
-AuthType Basic
-AuthType Digest
-AuthType BasicDigest
-
    - -

    Description

    - -

    The AuthType directive defines the type of authentication to -perform: - -

      - -
    • None - No authentication should be performed - (default.) - -
    • Basic - Basic authentication should be - performed using the UNIX password and group files. - -
    • Digest - Digest authentication should be - performed using the /etc/cups/passwd.md5 file. - -
    • BasicDigest - Basic authentication should be - performed using the /etc/cups/passwd.md5 file. - -
    - -

    When using Basic, Digest, or -BasicDigest authentication, clients connecting -through the localhost interface can also -authenticate using certificates. - -

    The AuthType directive must appear inside a -Location directive. - - -

    AutoPurgeJobs

    -
    - -

    Examples

    - -
      -AutoPurgeJobs Yes
-AutoPurgeJobs No
-
    - -

    Description

    - -

    The AutoPurgeJobs directive specifies whether or not to purge -completed jobs once they are no longer required for quotas. This option has -no effect if quotas are not enabled. The default setting is No. - - -

    BrowseAddress

    -
    - -

    Examples

    - -
      -BrowseAddress 255.255.255.255:631
-BrowseAddress 192.0.2.255:631
-BrowseAddress host.domain.com:631
-BrowseAddress @LOCAL
-BrowseAddress @IF(name)
-
    - -

    Description

    - -

    The BrowseAddress directive specifies an address to -send browsing information to. Multiple BrowseAddress -directives can be specified to send browsing information to different -networks or systems. - -

    The @LOCAL name will broadcast printer -information to all local interfaces. The @IF(name) -name will broadcast to the named interface. - -

    No browse addresses are set by default.

    - -
    - - - -
    - NOTE: - -

    If you are using HP-UX 10.20 and a subnet that is not 24, - 16, or 8 bits, printer browsing (and in fact all broadcast - reception) will not work. This problem appears to be fixed in - HP-UX 11.0. -

    - - -

    BrowseAllow

    -
    - -

    Examples

    - -
      -BrowseAllow from all
-BrowseAllow from none
-BrowseAllow from 192.0.2
-BrowseAllow from 192.0.2.0/24
-BrowseAllow from 192.0.2.0/255.255.255.0
-BrowseAllow from *.domain.com
-BrowseAllow from @LOCAL
-BrowseAllow from @IF(name)
-
    - -

    Description

    - -

    The BrowseAllow directive specifies a system or network -to accept browse packets from. The default is to accept browse packets -from all hosts. - -

    Host and domain name matching require that you enable the -HostNameLookups directive. - -

    IP address matching supports exact matches, partial addresses that -match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, -or network addresses using the specified netmask or bit count. - -

    The @LOCAL name will allow browse data from all -local network interfaces, but not remote point-to-point -interfaces. The @IF(name) name will allow browse -data from the named interface. - - - -

    BrowseDeny

    -
    - -

    Examples

    - -
      -BrowseDeny from all
-BrowseDeny from none
-BrowseDeny from 192.0.2
-BrowseDeny from 192.0.2.0/24
-BrowseDeny from 192.0.2.0/255.255.255.0
-BrowseDeny from *.domain.com
-BrowseDeny from @LOCAL
-BrowseDeny from @IF(name)
-
    - -

    Description

    - -

    The BrowseDeny directive specifies a system or network -to reject browse packets from. The default is to deny browse packets -from no hosts. - -

    Host and domain name matching require that you enable the -HostNameLookups directive. - -

    IP address matching supports exact matches, partial addresses that -match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, -or network addresses using the specified netmask or bit count. - -

    The @LOCAL name will block browse data from all -local network interfaces, but not remote point-to-point -interfaces. The @IF(name) name will block browse -data from the named interface. - - - -

    BrowseOrder

    -
    - -

    Examples

    - -
      -BrowseOrder allow,deny
-BrowseOrder deny,allow
-
    - -

    Description

    - -

    The BrowseOrder directive specifies the order of allow/deny -processing. The default order is deny,allow: - -

      - -
    • allow,deny - Browse packets are accepted unless - specifically denied. - -
    • deny,allow - Browse packets are rejected unless - specifically allowed. - -
    - - -

    BrowseInterval

    -
    - -

    Examples

    - -
      -BrowseInterval 0
-BrowseInterval 30
-
    - -

    Description

    - -

    The BrowseInterval directive specifies the maximum amount of -time between browsing updates. Specifying a value of 0 seconds disables -outgoing browse updates but allows a server to receive printer information -from other hosts. - -

    The BrowseInterval value should always be less than the -BrowseTimeout value. Otherwise -printers and classes will disappear from client systems between updates. - - -

    BrowsePoll

    -
    - -

    Examples

    - -
      -BrowsePoll 192.0.2.2:631
-BrowsePoll host.domain.com:631
-
    - -

    Description

    - -

    The BrowsePoll directive polls a server for available -printers once every -BrowseInterval seconds. -Multiple BrowsePoll directives can be specified to poll -multiple servers. - -

    If BrowseInterval is set to 0 then the server is polled -once every 30 seconds. - - -

    BrowsePort

    -
    - -

    Examples

    - -
      -BrowsePort 631
-BrowsePort 9999
-
    - -

    Description

    - -

    The BrowsePort directive specifies the UDP port number -used for browse packets. The default port number is 631.

    - -
    - - - -
    - NOTE: - -

    You must set the BrowsePort to the same value - on all of the systems that you want to see. -

    - - -

    BrowseProtocols

    -
    - -

    Examples

    - -
      -BrowseProtocols CUPS
-BrowseProtocols SLP
-BrowseProtocols CUPS SLP
-BrowseProtocols all
-
    - -

    Description

    - -

    The BrowseProtocols directive specifies the protocols to -use when collecting and distributing shared printers on the local network. -The default protocol is CUPS, which is a broadcast-based -protocol.

    - -
    - - - -
    - NOTE: - -

    When using the SLP protocol, you must have at least - one Directory Agent (DA) server on your network. Otherwise the - CUPS scheduler (cupsd) will not respond to client - requests for several seconds while polling the network. -

    - - -

    BrowseRelay

    -
    - -

    Examples

    - -
      -BrowseRelay 193.0.2.1 192.0.2.255
-BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
-BrowseRelay 193.0.2.0/24 192.0.2.255
-BrowseRelay *.domain.com 192.0.2.255
-BrowseRelay host.domain.com 192.0.2.255
-
    - -

    Description

    - -

    The BrowseRelay directive specifies source and destination -addresses for relaying browsing information from one host or network to -another. Multiple BrowseRelay directives can be specified -as needed. - -

    BrowseRelay is typically used on systems that bridge -multiple subnets using one or more network interfaces. It can also be -used to relay printer information from polled servers with the line: - -

      -BrowseRelay 127.0.0.1 255.255.255.255
-
    - -

    This effectively provides access to printers on a WAN for all clients -on the LAN(s). - - -

    BrowseShortNames

    -
    - -

    Examples

    - -
      -BrowseShortNames Yes
-BrowseShortNames No
-
    - -

    Description

    - -

    The BrowseShortNames directive specifies whether or not -short names are used for remote printers when possible. Short names are -just the remote printer name, without the server ("printer"). If more than -one remote printer is detected with the same name, the printers will have -long names ("printer@server1", "printer@server2".) - -

    The default value for this option is Yes. - - -

    BrowseTimeout

    -
    - -

    Examples

    - -
      -BrowseTimeout 300
-BrowseTimeout 60
-
    - -

    Description

    - -

    The BrowseTimeout directive sets the timeout for -printer or class information that is received in browse packets. Once a -printer or class times out it is removed from the list of available -destinations. - -

    The BrowseTimeout value should always be greater than the -BrowseInterval value. Otherwise -printers and classes will disappear from client systems between updates. - - -

    Browsing

    -
    - -

    Examples

    - -
      -Browsing On
-Browsing Off
-
    - -

    Description

    - -

    The Browsing directive controls whether or not network printer -browsing is enabled. The default setting is On.

    - -
    - - - -
    - NOTE: - -

    If you are using HP-UX 10.20 and a subnet that is not 24, - 16, or 8 bits, printer browsing (and in fact all broadcast - reception) will not work. This problem appears to be fixed in - HP-UX 11.0. -

    - - -

    Classification

    -
    - -

    Examples

    - -
      -Classification
-Classification classified
-Classification confidential
-Classification secret
-Classification topsecret
-Classification unclassified
-
    - -

    Description

    - -

    The Classification directive sets the classification level -on the server. When this option is set, at least one of the banner pages -is forced to the classification level, and the classification is placed -on each page of output. The default is no classification level. - - -

    ClassifyOverride

    -
    - -

    Examples

    - -
      -ClassifyOverride Yes
-ClassifyOverride No
-
    - -

    Description

    - -

    The ClassifyOverride directive specifies whether users -can override the default classification level on the server. When the -server classification is set, users can change the classification using -the job-sheets option and can choose to only print one -security banner before or after the job. If the job-sheets -option is set to none then the server default classification -is used. - -

    The default is to not allow classification overrides. - - -

    ConfigFilePerm

    -
    - -

    Examples

    - -
      -ConfigFilePerm 0644
-ConfigFilePerm 0600
-
    - -

    Description

    - -

    The ConfigFilePerm directive specifies the permissions -to use when writing configuration files. The default is 0600. - - -

    DataDir

    -
    - -

    Examples

    - -
      -DataDir /usr/share/cups
-
    - -

    Description

    - -

    The DataDir directive sets the directory to use for data -files. - - -

    DefaultCharset

    -
    - -

    Examples

    - -
      -DefaultCharset utf-8
-DefaultCharset iso-8859-1
-DefaultCharset windows-1251
-
    - -

    Description

    - -

    The DefaultCharset directive sets the default character set -to use for client connections. The default character set is -utf-8 but is overridden by the character set for the language -specified by the client or the DefaultLanguage directive. - - -

    DefaultLanguage

    -
    - -

    Examples

    - -
      -DefaultLanguage de
-DefaultLanguage en
-DefaultLanguage es
-DefaultLanguage fr
-DefaultLanguage it
-
    - -

    Description

    - -

    The DefaultLanguage directive specifies the default language -to use for client connections. Setting the default language also sets the -default character set if a language localization file exists for it. The -default language is "en" for English. - - -

    Deny

    -
    - -

    Examples

    - -
      -Deny from All
-Deny from None
-Deny from *.domain.com
-Deny from .domain.com
-Deny from host.domain.com
-Deny from nnn.*
-Deny from nnn.nnn.*
-Deny from nnn.nnn.nnn.*
-Deny from nnn.nnn.nnn.nnn
-Deny from nnn.nnn.nnn.nnn/mm
-Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
-Deny from @LOCAL
-Deny from @IF(name)
-
    - -

    Description

    - -

    The Deny directive specifies a hostname, IP address, or -network that is allowed access to the server. Deny -directives are cummulative, so multiple Deny directives -can be used to allow access for multiple hosts or networks. The -/mm notation specifies a CIDR netmask: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    mmnetmaskmmnetmask
    00.0.0.08255.0.0.0
    1128.0.0.016255.255.0.0
    2192.0.0.024255.255.255.0
    ......32255.255.255.255
    - -

    The @LOCAL name will deny access from all local -network interfaces, but not remote point-to-point interfaces. The -@IF(name) name will deny access from the named -interface. - -

    The Deny directive must appear inside a -Location directive. - - -

    DocumentRoot

    -
    - -

    Examples

    - -
      -DocumentRoot /usr/share/doc/cups
-DocumentRoot /foo/bar/doc/cups
-
    - -

    Description

    - -

    The DocumentRoot directive specifies the location of -web content for the HTTP server in CUPS. If an absolute path is not -specified then it is assumed to be relative to the -ServerRoot directory. The -default directory is /usr/share/doc/cups. - -

    Documents are first looked up in a sub-directory for the primary -language requested by the client (e.g. /usr/share/doc/cups/fr/...) -and then directly under the DocumentRoot directory -(e.g. /usr/share/doc/cups/...), so it is possible to localize -the web content by providing subdirectories for each language needed. - - -

    Encryption

    -
    - -

    Examples

    - -
      -Encryption Never
-Encryption IfRequested
-Encryption Required
-Encryption Always
-
    - -

    Description

    - -

    The Encryption directive must appear instead a -Location -section and specifies the encryption settings for that location. -The default setting is IfRequested for all locations. - - -

    ErrorLog

    -
    - -

    Examples

    - -
      -ErrorLog /var/log/cups/error_log
-ErrorLog /var/log/cups/error_log-%s
-ErrorLog syslog
-
    - -

    Description

    - -

    The ErrorLog directive sets the name of the error log -file. If the filename is not absolute then it is assumed to be relative -to the ServerRoot directory. The -default error log file is /var/log/cups/error_log. - -

    The server name can be included in the filename by using -%s in the name. - -

    The special name "syslog" can be used to send the error information -to the system log instead of a plain file. - - -

    FilterLimit

    -
    - -

    Examples

    - -
      -FilterLimit 0
-FilterLimit 200
-FilterLimit 1000
-
    - -

    Description

    - -

    The FilterLimit directive sets the maximum cost -of all running job filters. It can be used to limit the number -of filter programs that are run on a server to minimize disk, -memory, and CPU resource problems. A limit of 0 disables filter -limiting. - -

    An average print to a non-PostScript printer needs a filter -limit of about 200. A PostScript printer needs about half that -(100). Setting the limit below these thresholds will effectively -limit the scheduler to printing a single job at any time. - -

    The default limit is 0. - - -

    FilterNice

    -
    - -

    Examples

    - -
      -FilterNice 0
-FilterNice 39
-FilterNice -10
-
    - -

    Description

    - -

    The FilterNice directive sets the scheduling -priority of job filters. Values larger than 0 give filters a -lower priority while values smaller than 0 give filters a higher -priority. The FilterNice value does not affect the -priority of job backends. - -

    The default priority is 0. - - -

    FontPath

    -
    - -

    Examples

    - -
      -FontPath /foo/bar/fonts
-FontPath /usr/share/cups/fonts:/foo/bar/fonts
-
    - -

    Description

    - -

    The FontPath directive specifies the font path to use when -searching for fonts. The default font path is -/usr/share/cups/fonts. - - -

    Group

    -
    - -

    Examples

    - -
      -Group sys
-Group system
-Group root
-
    - -

    Description

    - -

    The Group directive specifies the UNIX group that -filter and CGI programs run as. The default group is sys, -system, or root depending on the operating -system. - - -

    HideImplicitMembers

    -
    - -

    Examples

    - -
      -HideImplicitMembers Yes
-HideImplicitMembers No
-
    - -

    Description

    - -

    The HideImplicitMembers directive controls -whether the individual printers in an implicit class are shown -to the user. The default is No.

    - -

    ImplicitClasses -must be enabled for this directive to have any effect.

    - - -

    HostNameLookups

    -
    - -

    Examples

    - -
      -HostNameLookups On
-HostNameLookups Off
-HostNameLookups Double
-
    - -

    Description

    - -

    The HostNameLookups directive controls whether -or not CUPS looks up the hostname for connecting clients. The -Double setting causes CUPS to verify that the -hostname resolved from the address matches one of the addresses -returned for that hostname. Double lookups also -prevent clients with unregistered addresses from connecting -to your server. - -The default is Off to avoid the potential server -performance problems with hostname lookups. Set this option to -On or Double only if absolutely -required. - - -

    ImplicitClasses

    -
    - -

    Examples

    - -
      -ImplicitClasses On
-ImplicitClasses Off
-
    - -

    Description

    - -

    The ImplicitClasses directive controls whether implicit -classes are created based upon the available network printers and classes. -The default setting is On but is automatically turned -Off if Browsing is -turned Off. - - -

    ImplicitAnyClasses

    -
    - -

    Examples

    - -
      -ImplicitAnyClasses On
-ImplicitAnyClasses Off
-
    - -

    Description

    - -

    The ImplicitAnyClasses directive controls -whether implicit classes for local and remote printers are -created with the name AnyPrinter. The default -setting is Off.

    - -

    ImplicitClasses -must be enabled for this directive to have any effect.

    - - -

    Include

    -
    - -

    Examples

    - -
      -Include filename
-Include /foo/bar/filename
-
    - -

    Description

    - -

    The Include directive includes the named file in -the cupsd.conf file. If no leading path is -provided, the file is assumed to be relative to the -ServerRoot directory.

    - - -

    KeepAlive

    -
    - -

    Examples

    - -
      -KeepAlive On
-KeepAlive Off
-
    - -

    Description

    - -

    The KeepAlive directive controls whether or not to support -persistent HTTP connections. The default is On. - -

    HTTP/1.1 clients automatically support persistent connections, while -HTTP/1.0 clients must specifically request them using the -Keep-Alive attribute in the Connection: -field of each request. - - -

    KeepAliveTimeout

    -
    - -

    Examples

    - -
      -KeepAliveTimeout 60
-KeepAliveTimeout 30
-
    - -

    Description

    - -

    The KeepAliveTimeout directive controls how long a -persistent HTTP connection will remain open after the last request. The -default is 60 seconds. - - -

    Limit

    -
    - -

    Examples

    - -
      -<Limit GET POST>
-...
-</Limit>
-
-<Limit ALL>
-...
-</Limit>
-
    - -

    Description

    - -

    The Limit directive groups access control directives for -specific types of HTTP requests and must appear inside a -Location section. Access can be limited -for individual request types (DELETE, GET, -HEAD, OPTIONS, POST, PUT, -and TRACE) or for all request types (ALL). The -request type names are case-sensitive for compatibility with Apache. - - -

    LimitExcept

    -
    - -

    Examples

    - -
      -<LimitExcept GET POST>
-...
-</LimitExcept>
-
    - -

    Description

    - -

    The LimitExcept directive groups access control directives for -specific types of HTTP requests and must appear inside a -Location section. Unlike the -Limit directive, LimitExcept -restricts access for all requests except those listed on the -LimitExcept line. - - -

    LimitRequestBody

    -
    - -

    Examples

    - -
      -LimitRequestBody 10485760
-LimitRequestBody 10m
-LimitRequestBody 0
-
    - -

    Description

    - -

    The LimitRequestBody directive controls the maximum size of -print files, IPP requests, and HTML form data in HTTP POST requests. The -default limit is 0 which disables the limit check. - -

    Also see the identical -MaxRequestSize directive. - - -

    Listen

    -
    - -

    Examples

    - -
      -Listen 127.0.0.1:631
-Listen 192.0.2.1:631
-
    - -

    Description

    - -

    The Listen directive specifies a network address and port -to listen for connections. Multiple Listen directives can be -provided to listen on multiple addresses. - -

    The Listen directive is similar to the -Port directive but allows you to restrict -access to specific interfaces or networks. - - -

    Location

    -
    - -

    Examples

    - -
      -<Location />
-...
-</Location>
-
-<Location /admin>
-...
-</Location>
-
-<Location /printers>
-...
-</Location>
-
-<Location /printers/name>
-...
-</Location>
-
-<Location /classes>
-...
-</Location>
-
-<Location /classes/name>
-...
-</Location>
-
    - -

    Description

    - -

    The Location directive specifies access control and -authentication options for the specified HTTP resource or path. -The -Allow, -AuthClass, -AuthGroupName, -AuthType, -Deny, -Encryption, -Limit, -LimitExcept, -Order, -Require, and -Satisfy -directives may all appear inside a location. - -

    - - - - - - - - - - - -
    Locations on the Server.
    LocationDescription
    /The path for all get operations (get-printers, get-jobs, etc.)
    /adminThe path for all administration operations (add-printer, delete-printer, start-printer, etc.)
    /admin/confThe path for access to the ESP Print Pro configuration files (cupsd.conf, client.conf, etc.)
    /classesThe path for all classes
    /classes/nameThe resource for class name
    /jobsThe path for all jobs (hold-job, release-job, etc.)
    /jobs/idThe resource for job id
    /printersThe path for all printers
    /printers/nameThe path for printer name
    /printers/name.ppdThe PPD file path for printer name
    - -

    Note that more specific resources override the less specific ones. -So the directives inside the /printers/name location will override ones from /printers. -Directives inside /printers will override ones from /.   -None of the directives are inherited. -More information can be found in section "Printing System Security". - - -

    LogFilePerm

    -
    - -

    Examples

    - -
      -LogFilePerm 0644
-LogFilePerm 0600
-
    - -

    Description

    - -

    The LogFilePerm directive specifies the permissions -to use when writing configuration files. The default is 0644. - - -

    LogLevel

    -
    - -

    Examples

    - -
      -LogLevel none
-LogLevel emerg
-LogLevel alert
-LogLevel crit
-LogLevel error
-LogLevel warn
-LogLevel notice
-LogLevel info
-LogLevel debug
-LogLevel debug2
-
    - -

    Description

    - -

    The LogLevel directive specifies the level of logging -for the ErrorLog file. The -following values are recognized (each level logs everything under the -preceding levels): - -

      - -
    • none - Log nothing. - -
    • emerg - Log emergency conditions that prevent the - server from running. - -
    • alert - Log alerts that must be handled immediately. - -
    • crit - Log critical errors that don't prevent - the server from running. - -
    • error - Log general errors. - -
    • warn - Log errors and warnings. - -
    • notice - Log temporary error conditions. - -
    • info - Log all requests and state changes (default). - -
    • debug - Log basic debugging information. - -
    • debug2 - Log all debugging information. - -
    - - -

    MaxClients

    -
    - -

    Examples

    - -
      -MaxClients 100
-MaxClients 1024
-
    - -

    Description

    - -

    The MaxClients directive controls the maximum number of -simultaneous clients that will be allowed by the server. The default is -100 clients.

    - -
    - - - -
    - NOTE: - -

    Since each print job requires a file descriptor for the - status pipe, the CUPS server internally limits the - MaxClients value to 1/3 of the available file descriptors - to avoid possible problems when printing large numbers of jobs. -

    - - -

    MaxCopies

    -
    - -

    Examples

    - -
      -MaxCopies 100
-MaxCopies 65535
-
    - -

    Description

    - -

    The MaxCopies directive controls the maximum -number of copies that a user can print of a job. The default is -100 copies.

    - -
    - - - -
    - NOTE: - -

    Most HP PCL laser printers internally limit the - number of copies to 100. - -

    - - -

    MaxJobs

    -
    - -

    Examples

    - -
      -MaxJobs 100
-MaxJobs 9999
-MaxJobs 0
-
    - -

    Description

    - -

    The MaxJobs directive controls the maximum number of jobs -that are kept in memory. Once the number of jobs reaches the limit, the -oldest completed job is automatically purged from the system to make room -for the new one. If all of the known jobs are still pending or active then -the new job will be rejected. - -

    Setting the maximum to 0 disables this functionality. The default -setting is 0. - - -

    MaxJobsPerPrinter

    -
    - -

    Examples

    - -
      -MaxJobsPerPrinter 100
-MaxJobsPerPrinter 9999
-MaxJobsPerPrinter 0
-
    - -

    Description

    - -

    The MaxJobsPerPrinter directive controls the maximum number of active jobs -that are allowed for each printer or class. Once a printer or class reaches the limit, new jobs will be -rejected until one of the active jobs is completed, stopped, aborted, or cancelled. - -

    Setting the maximum to 0 disables this functionality. The default -setting is 0. - - -

    MaxJobsPerUser

    -
    - -

    Examples

    - -
      -MaxJobsPerUser 100
-MaxJobsPerUser 9999
-MaxJobsPerUser 0
-
    - -

    Description

    - -

    The MaxJobsPerUser directive controls the maximum number of active jobs -that are allowed for each user. Once a user reaches the limit, new jobs will be -rejected until one of the active jobs is completed, stopped, aborted, or cancelled. - -

    Setting the maximum to 0 disables this functionality. The default -setting is 0. - - -

    MaxLogSize

    -
    - -

    Examples

    - -
      -MaxLogSize 1048576
-MaxLogSize 1m
-MaxLogSize 0
-
    - -

    Description

    - -

    The MaxLogSize directive controls the maximum size of each -log file. Once a log file reaches or exceeds the maximum size it is closed -and renamed to filename.O. This allows you to rotate the logs -automatically. The default size is 1048576 bytes (1MB). - -

    Setting the maximum size to 0 disables log rotation. - - -

    MaxRequestSize

    -
    - -

    Examples

    - -
      -MaxRequestSize 10485760
-MaxRequestSize 10m
-MaxRequestSize 0
-
    - -

    Description

    - -

    The MaxRequestSize directive controls the maximum size of -print files, IPP requests, and HTML form data in HTTP POST requests. The -default limit is 0 which disables the limit check. - -

    Also see the identical -LimitRequestBody directive. - - -

    Order

    -
    - -

    Examples

    - -
      -Order Allow,Deny
-Order Deny,Allow
-
    - -

    Description

    - -

    The Order directive defines the default access control. -The following values are supported: - -

      - -
    • Allow,Deny - Allow requests from all - systems except for those listed in a Deny - directive. - -
    • Deny,Allow - Allow requests only from - those listed in an Allow directive. - -
    - -

    The Order directive must appear inside a -Location directive. - - -

    PageLog

    -
    - -

    Examples

    - -
      -PageLog /var/log/cups/page_log
-PageLog /var/log/cups/page_log-%s
-PageLog syslog
-
    - -

    Description

    - -

    The PageLog directive sets the name of the page log -file. If the filename is not absolute then it is assumed to be relative -to the ServerRoot directory. The -default page log file is /var/log/cups/page_log. - -

    The server name can be included in the filename by using -%s in the name. - -

    The special name "syslog" can be used to send the page information -to the system log instead of a plain file. - - -

    Port

    -
    - -

    Examples

    - -
      -Port 631
-Port 80
-
    - -

    Description

    - -

    The Port directive specifies a port to listen on. -Multiple Port lines can be specified to listen on multiple -ports. The default port is 631. - - -

    PreserveJobHistory

    -
    - -

    Examples

    - -
      -PreserveJobHistory On
-PreserveJobHistory Off
-
    - -

    Description

    - -

    The PreserveJobHistory directive controls whether -the history of completed, cancelled, or aborted print jobs is stored -on disk. - -

    A value of On (the default) preserves job information -until the administrator purges it with the cancel -command. - -

    A value of Off removes the job information as soon as -each job is completed, cancelled, or aborted. - - -

    PreserveJobFiles

    -
    - -

    Examples

    - -
      -PreserveJobFiles On
-PreserveJobFiles Off
-
    - -

    Description

    - -

    The PreserveJobFiles directive controls whether the -document files of completed, cancelled, or aborted print jobs are -stored on disk. - -

    A value of On preserves job files until the -administrator purges them with the cancel command. Jobs -can be restarted (and reprinted) as desired until they are purged. - -

    A value of Off (the default) removes the job files as -soon as each job is completed, cancelled, or aborted. - - -

    Printcap

    -
    - -

    Examples

    - -
      -Printcap
-Printcap /etc/printcap
-Printcap /etc/printers.conf
-
    - -

    Description

    - -

    The Printcap directive controls whether or not a -printcap file is automatically generated and updated with a list -of available printers. If specified with no value, then no -printcap file will be generated. The default is to generate a -file named /etc/printcap. - -

    When a filename is specified (e.g. /etc/printcap), the -printcap file is written whenever a printer is added or removed. The -printcap file can then be used by applications that are hardcoded to -look at the printcap file for the available printers. - - -

    PrintcapFormat

    -
    - -

    Examples

    - -
      -PrintcapFormat BSD
-PrintcapFormat Solaris
-
    - -

    Description

    - -

    The PrintcapFormat directive controls the output -format of the printcap file. The default is to generate a BSD -printcap file. - - -

    PrintcapGUI

    -
    - -

    Example

    - -
      -PrintcapGUI /usr/bin/glpoptions
-
    - -

    Description

    - -

    The PrintcapGUI directive sets the program to -use when displaying an option panel from an IRIX application -that uses the Impressario print API. The default program is the -ESP Print Pro "glpoptions" GUI. - -

    The program must accept the -d option to specify -a printer and the -o option to specify one or more -options. After allowing the user to select/change options, the -program must then write the list of printing options without the --o to the standard output. - - -

    RemoteRoot

    -
    - -

    Examples

    - -
      -RemoteRoot remroot
-RemoteRoot root
-
    - -

    Description

    - -

    The RemoteRoot directive sets the username for -unauthenticated root requests from remote hosts. The default -username is remroot. Setting RemoteRoot -to root effectively disables this security mechanism. - - -

    RequestRoot

    -
    - -

    Examples

    - -
      -RequestRoot /var/spool/cups
-RequestRoot /foo/bar/spool/cups
-
    - -

    Description

    - -

    The RequestRoot directive sets the directory for -incoming IPP requests and HTML forms. If an absolute path is not -provided then it is assumed to be relative to the -ServerRoot directory. The -default request directory is /var/spool/cups. - - -

    Require

    -
    - -

    Examples

    - -
      -Require group foo bar
-Require user john mary
-Require valid-user
-
    - -

    Description

    - -

    The Require directive specifies that -authentication is required for the resource. The -group keyword specifies that the authenticated user -must be a member of one or more of the named groups that follow. - -

    The user keyboard specifies that the -authenticated user must be one of the named users that follow. - -

    The valid-user keyword specifies that any -authenticated user may access the resource. - -

    The default is to do no authentication. This directive must -appear inside a Location -directive. - - -

    RIPCache

    -
    - -

    Examples

    - -
      -RIPCache 8m
-RIPCache 1g
-RIPCache 2048k
-
    - -

    Description

    - -

    The RIPCache directive sets the size of the memory -cache used by Raster Image Processor ("RIP") filters such as -imagetoraster and pstoraster. The size can -be suffixed with a "k" for kilobytes, "m" for megabytes, or -"g" for gigabytes. The default cache size is "8m", or 8 megabytes. - - -

    RootCertDuration

    -
    - -

    Examples

    - -
      -RootCertDuration 300
-RootCertDuration 0
-
    - -

    Description

    - -

    The RootCertDuration directive controls the -interval between updates of the root authentication certificate. -The default is 300 seconds which updates the root -certificate approximately once every 5 minutes. Set the interval -to 0 to disable certificate updates entirely. - - - -

    RunAsUser

    -
    - -

    Examples

    - -
      -RunAsUser Yes
-RunAsUser No
-
    - -

    Description

    - -

    The RunAsUser directive controls whether the -scheduler runs as the unpriviledged user account (usually lp). -The default is No which leaves the scheduler running as -the root user. - -

    Note: Running as a non-priviledged user may prevent -LPD and locally connected printers from working due to -permission problems. The lpd backend will -automatically use a non-priviledged mode that is not 100% -compliant with RFC 1179. The parallel, -serial, and usb backends will need -write access to the corresponding device files. - - -

    Satisfy

    -
    - -

    Examples

    - -
      -Satisfy all
-Satisfy any
-
    - -

    Description

    - -

    The Satisfy directive specifies whether all -conditions must be satisfied to allow access to the resource. If -set to all, then all authentication and access -control conditions must be satified to allow access. - -

    Setting Satisfy to any allows a user to -gain access if the authentication or access control requirements are -satisfied. For example, you might require authentication for remote -access, but allow local access without authentication. - -

    The default is all. This directive must appear -inside a Location -directive. - - -

    ServerAdmin

    -
    - -

    Examples

    - -
      -ServerAdmin user@host
-ServerAdmin root@foo.bar.com
-
    - -

    Description

    - -

    The ServerAdmin directive identifies the email address for the -administrator on the system. By default the administrator email address is -root@server, where server is the server name. - - -

    ServerBin

    -
    - -

    Examples

    - -
      -ServerBin /usr/lib/cups
-ServerBin /foo/bar/lib/cups
-
    - -

    Description

    - -

    The ServerBin directive sets the directory for -server-run executables. If an absolute path is not provided then it is -assumed to be relative to the -ServerRoot directory. The -default executable directory is /usr/lib/cups. - - -

    ServerCertificate

    -
    - -

    Examples

    - -
      -ServerCertificate /etc/cups/ssl/server.crt
-
    - -

    Description

    - -

    The ServerCertificate directive specifies the -location of the SSL certificate file used by the server when -negotiating encrypted connections. The certificate must not be -encrypted (password protected) since the scheduler normally runs -in the background and will be unable to ask for a password. -The default certificate file is /etc/cups/ssl/server.crt. - - -

    ServerKey

    -
    - -

    Examples

    - -
      -ServerKey /etc/cups/ssl/server.key
-
    - -

    Description

    - -

    The ServerKey directive specifies the location -of the SSL private key file used by the server when negotiating -encrypted connections. The default key file is -/etc/cups/ssl/server.crt. - - -

    ServerName

    -
    - -

    Examples

    - -
      -ServerName foo.domain.com
-ServerName myserver.domain.com
-
    - -

    Description

    - -

    The ServerName directive specifies the hostname that is -reported to clients. By default the server name is the hostname. - - -

    ServerRoot

    -
    - -

    Examples

    - -
      -ServerRoot /etc/cups
-ServerRoot /foo/bar/cups
-
    - -

    Description

    - -

    The ServerRoot directive specifies the absolute path to -the server configuration and state files. It is also used to resolve -relative paths in the cupsd.conf file. The default server -directory is /etc/cups. - - -

    ServerTokens

    -
    - -

    Examples

    - -
      -ServerTokens None
-ServerTokens ProductOnly
-ServerTokens Major
-ServerTokens Minor
-ServerTokens Minimal
-ServerTokens OS
-ServerTokens Full
-
    - -

    Description

    - -

    The ServerTokens directive specifies the information -that is included in the Server header of HTTP responses. The default value -is Minor which generates "CUPS/1.1". - - -

    SSLListen

    -
    - -

    Examples

    - -
      -SSLListen 127.0.0.1:443
-SSLListen 192.0.2.1:443
-
    - -

    Description

    - -

    The SSLListen directive specifies a network -address and port to listen for secure connections. Multiple -SSLListen directives can be provided to listen on -multiple addresses. - -

    The SSLListen directive is similar to the -SSLPort directive but allows -you to restrict access to specific interfaces or networks. - - -

    SSLPort

    -
    - -

    Examples

    - -
      -SSLPort 443
-
    - -

    Description

    - -

    The SSLPort directive specifies a port to listen -on for secure connections. Multiple SSLPort lines -can be specified to listen on multiple ports. - - -

    SystemGroup

    -
    - -

    Examples

    - -
      -SystemGroup sys
-SystemGroup system
-SystemGroup root
-
    - -

    Description

    - -

    The SystemGroup directive specifies the system -administration group for System authentication. More -information can be found later in this chapter in -"Printing System Security". - - -

    TempDir

    -
    - -

    Examples

    - -
      -TempDir /var/tmp
-TempDir /foo/bar/tmp
-
    - -

    Description

    - -

    The TempDir directive specifies an absolute path for -the directory to use for temporary files. The default directory is -/var/tmp. - -

    Temporary directories must be world-writable and should have the -"sticky" permission bit enabled so that other users cannot delete -filter temporary files. The following commands will create an -appropriate temporary directory called /foo/bar/tmp: - -

      -mkdir /foo/bar/tmp ENTER
-chmod a+rwxt /foo/bar/tmp ENTER
-
    - - -

    Timeout

    -
    - -

    Examples

    - -
      -Timeout 300
-Timeout 90
-
    - -

    Description

    - -

    The Timeout directive controls the amount of time to -wait before an active HTTP or IPP request times out. The default -timeout is 300 seconds. - - -

    User

    -
    - -

    Examples

    - -
      -User lp
-User guest
-
    - -

    Description

    - -

    The User directive specifies the UNIX user that -filter and CGI programs run as. The default user is lp. - - -

    Printing System Security

    - -

    CUPS provides support for address, certificate, and password (Basic -and Digest) based authentication and access control. Certificate and -password authentication provide ways to limit access to individual -people or groups. - -

    Address based access control allows you to limit access to specific -systems, networks, or domains. While this does not provide authentication, -it does allow you to limit the potential users of your system efficiently. - -

    CUPS maintains a list of locations that have access control and/or -authentication enabled. Locations are specified using the -Location directive: - -

    - -

    Locations generally follow the directory structure of the -DocumentRoot directory, however -CUPS does have several virtual locations for administration, classes, jobs, -and printers: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    LocationDescription
    /adminThe path for all administration operations.
    /classesThe path for all classes.
    /classes/nameThe resource for class name.
    /jobsThe path for all jobs.
    /jobs/idThe resource for job id.
    /printersThe path for all printers.
    /printers/nameThe path for printer name.
    /printers/name.ppdThe PPD file path for printer name.
    - -

    Authentication Using Certificates

    - -

    CUPS supports a local certificate-based authentication scheme that -can be used in place of Basic or Digest -authentication by clients connecting through the localhost -interface. Certificate authentication is not supported or allowed from -clients on any other interface. - -

    Certificates are 128-bit random numbers that refer to an internal -authentication record in the server. A client connecting via the -localhost interface sends a request with an -authorization header of: - -

      -Authorization: Local 0123456789ABCDEF0123456789ABCDEF
-
    - -

    The server then looks up the local certificate and authenticates -using the username associated with it. - -

    Certificates are generated by the server automatically and stored in -the /etc/cups/certs directory using the process ID of the -CGI program started by the server. Certificate files are only readable -by the User and -Group defined in the -cupsd.conf file. When the CGI program ends the certificate -is removed and invalidated automatically. - -

    The special file /etc/cups/certs/0 defines the root -certificate which can be used by any client running as the super-user -or another user that is part of the group defined by the -SystemGroup directive. The -root certificate is automatically regenerated every 5 minutes. - -

    Using Basic Authentication

    - -

    Basic authentication uses UNIX users and passwords to authenticate -access to resources such as printers and classes, and to limit access -to administrative functions.

    - -
    - - - -
    - NOTE: - -

    Basic authentication sends the username and password Base64 - encoded from the client to the server, so it offers no - protection against eavesdropping. This means that a malicious - user can monitor network packets and discover valid users and - passwords that could result in a serious compromise in network - security. Use Basic authentication with extreme care. -

    - -

    The CUPS implementation of Basic authentication does not allow access -through user accounts without a password. If you try to authenticate -using an account without a password, your access will be immediately -blocked. - -

    Once a valid username and password is authenticated by CUPS, any -additional group membership requirements are checked.

    - -
    - - - -
    - NOTE: - -

    The root user is considered by CUPS to be a member of every - group. -

    - - -

    Use the AuthType directive to enable Basic authentication: - -

      -AuthType Basic
-
    - - -

    Using Digest Authentication

    - -

    Digest authentication uses users and passwords defined in the -/etc/cups/passwd.md5 file to authenticate access to -resources such as printers and classes, and to limit access to -administrative functions.

    - -
    - - - -
    - NOTE: - -

    Unlike Basic authentication, Digest passes the MD5 sum - (basically a complicated checksum) of the username and password - instead of the strings themselves. Also, Digest authentication - does not use the UNIX password file, so if an attacker does - discover the original password it is less likely to result in a - serious security problem so long as you use a different UNIX - password than the corresponding Digest password. - -

    The current CUPS implementation of Digest authentication - uses the client's hostname or IP address for the "nonce" value. - The nonce value is an additional string added to the username - and password to make guessing the password more difficult. The - server checks that the nonce value matches the client's hostname - or address and rejects the MD5 sum if it doesn't. Future versions - of CUPS will support Digest "session" authentication which adds - the request data to the MD5 sum, providing even better - authentication and security. - -

    Digest authentication does not guarantee that an attacker - cannot gain unauthorized access, but it is safer than Basic - authentication and should be used in place of Basic - authentication whenever possible. Support for Digest - authentication in web browsers is not yet universally - available. -

    - - -

    The lppasswd(1) command is used to add, change, or -remove accounts from the passwd.md5 file. To add a -user to the default system group, type: - -

      -lppasswd -a user ENTER
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
    - - -

    Once added, a user can change his/her password by typing: - -

      -lppasswd ENTER
-Old password: (password) ENTER [password is not echoed]
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
    - - -

    To remove a user from the password file, type: - -

      -lppasswd -x user ENTER
-
    - -

    Once a valid username and password is authenticated by CUPS, any -additional group membership requirements are checked.

    - -
    - - - -
    - NOTE: - -

    The root user is considered by CUPS to be a member of every - group. -

    - -

    Use the AuthType directive to enable Digest authentication: - -

      -AuthType Digest
-
    - -

    System and Group Authentication

    - -

    The AuthClass directive controls -the level of authentication to perform. System and -Group authentication extend the normal user-based authentication -to require membership in a UNIX group. For System authentication -each user must belong to the sys, system, or -root group; the actual group depends on the operating system. - -

    For Group authentication each user must belong to the -group named by the AuthGroupName -directive: - -

      -<Location /path>
-AuthType Digest
-AuthClass Group
-AuthGroupName mygroup
-</Location>
-
    - -

    The named group must be a valid UNIX user group, usually defined in the -/etc/group or /etc/netgroup files. Additionally, when -using Digest authentication you need to create user accounts with the named -group: - -

      -lppasswd -g mygroup -a user ENTER
-Password: (password) ENTER [password is not echoed]
-Password again: (password) ENTER [password is not echoed]
-
    - - -

    Printer Accounting

    - -

    CUPS maintains a log of all accesses, errors, and -pages that are printed. The log files are normally stored in the -/var/log/cups directory. You can change this by -editing the /etc/cups/cupsd.conf configuration file. - -

    The access_log File

    - -

    The access_log file lists each HTTP resource that is accessed -by a web browser or CUPS/IPP client. Each line is in the so-called "Common -Log Format" used by many web servers and web reporting tools: - -

      -host group user date-time \"method resource version\" status bytes
-
-127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0
-127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0
-
    - -

    The host field will normally only be an IP address unless you -have enabled the HostNameLookups -directive in the cupsd.conf file. - -

    The group field always contains "-" in CUPS. - -

    The user field is the authenticated username of the requesting user. -If no username and password is supplied for the request then this field -contains "-". - -

    The date-time field is the date and time of the request in local time -and is in the format: - -

      -[DD/MON/YYYY:HH:MM:SS +ZZZZ]
-
    - -

    where ZZZZ is the timezone offset in hours and minutes from Greenwich -Mean Time (a.k.a. GMT a.k.a. ZULU.) - -

    The method field is the HTTP method used ("GET", "PUT", "POST", etc.) - -

    The resource field is the filename of the requested resource. - -

    The version field is the HTTP specification version used by the -client. For CUPS clients this will always be "HTTP/1.1". - -

    The status field contains the HTTP result status of the -request. Usually it is "200", but other HTTP status codes are possible. -For example, 401 is the "unauthorized access" status in the example -above. - -

    The bytes field contains the number of bytes in the request. -For POST requests the bytes field contains the number of bytes -that was received from the client. - -

    The error_log File

    - -

    The error_log file lists messages from the scheduler (errors, -warnings, etc.): - -

      -level date-time message
-
-I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
-I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
-I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
-
    - -

    The level field contains the type of message: - -

      - -
    • E - An error occurred. - -
    • W - The server was unable to perform some action. - -
    • I - Informational message. - -
    • D - Debugging message. - -
    - -

    The date-time field contains the date and time of when the page -started printing. The format of this field is identical to the data-time -field in the access_log file. - -

    The message fields contains a free-form textual message. - -

    The page_log File

    - -

    The page_log file lists each page that is sent to a printer. -Each line contains the following information: - -

      -printer user job-id date-time page-number num-copies job-billing
-
-DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123
-
    - -

    The printer field contains the name of the printer that -printed the page. If you send a job to a printer class, this field will -contain the name of the printer that was assigned the job. - -

    The user field contains the name of the user (the IPP -requesting-user-name attribute) that submitted this file for -printing. - -

    The job-id field contains the job number of the page being printed. -Job numbers are reset to 1 whenever the CUPS server is started, so don't depend -on this number being unique! - -

    The date-time field contains the date and time of when the page -started printing. The format of this field is identical to the data-time -field in the access_log file. - -

    The page-number and num-pages fields contain the page number -and number of copies being printed of that page. For printer that can not -produce copies on their own, the num-pages field will always be 1. - -

    The job-billing field contains a copy of the -job-billing attribute provided with the IPP -create-job or print-job requests or "-" if none -was provided. - - -

    File Typing and Filtering

    - -

    CUPS provides a MIME-based file typing and filtering mechanism to -convert files to a printable format for each printer. On startup the -CUPS server reads MIME database files from the /etc/cups -directory (or a directory specified by the -ServerRoot directive) to build -a file type and conversion database in memory. These database files are -plain ASCII text and can be edited with your favorite text editor. - -

    The mime.types and mime.convs files define the -standard file types and filters that are available on the system. - -

    mime.types

    - -

    The mime.types file defines the known file types. Each line -of the file starts with the MIME type and may be followed by one or -more file type recognition rules. For example, the -text/html file type is defined as: - -

      -text/html       html htm \
-                printable(0,1024) + \
-                (string(0,"<HTML>") string(0,"<!DOCTYPE"))
-
    - -

    The first two rules say that any file with an extension of -.html or .htm is a HTML file. The third rule -says that any file whose first 1024 characters are printable text and -starts with the strings <HTML> or -<!DOCTYPE is a HTML file as well. - -

    The first two rules deal solely with the name of the file being -typed. This is useful when the original filename is known, however for -print files the server doesn't have a filename to work with. The third -rule takes care of this possibility and automatically figures out the -file type based upon the contents of the file instead. - -

    The available tests are: - -

      - -
    • ( expr ) - Parenthesis for expression grouping - -
    • + - Logical AND - -
    • , or whitespace - Logical OR - -
    • ! - Logical NOT - -
    • match("pattern") - Pattern match on filename - -
    • extension - Pattern match on "*.extension" - -
    • ascii(offset,length) - True if bytes are valid - printable ASCII (CR, NL, TAB, BS, 32-126) - -
    • printable(offset,length) - True if bytes are - printable 8-bit chars (CR, NL, TAB, BS, 32-126, 160-254) - -
    • string(offset,"string") - True if bytes are - identical to string - -
    • contains(offset,range,"string") - True if the - range of bytes contains the string - -
    • char(offset,value) - True if byte is identical - -
    • short(offset,value) - True if 16-bit integer - is identical (network or "big-endian" byte order) - -
    • int(offset,value) - True if 32-bit integer is - identical (network or "big-endian" byte order) - -
    • locale("string") - True if current locale - matches string - -
    - -

    All numeric values can be in decimal (123), octal (0123), or hexadecimal -(0x123) as desired. - - -

    Strings can be in quotes, all by themselves, as a string -of hexadecimal values, or some combination: - -

      -"string"
-'string'
-string
-<737472696e67>
-<7374>ring
-
    - -

    As shown in the text/html example, rules can continue on -multiple lines using the backslash (\) character. A more complex example is -the image/jpeg rules: - -

      -image/jpeg      jpeg jpg jpe string(0,<FFD8FF>) &&\
-                (char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
-                 char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
-                 char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
-                 char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
-
    - -

    This rule states that any file with an extension of -.jpeg, .jpg, or .jpe is a JPEG file. -In addition, any file starting with the hexadecimal string -<FFD8FF> (JPEG Start-Of-Image) followed by a -character between and including 0xe0 and 0xef -(JPEG APPn markers) is also a JPEG file. - -

    mime.convs

    - -

    The mime.convs file defines all of the filter programs that -are known to the system. Each line consists of: - -

      -source destination cost program
-
-text/plain application/postscript 50 texttops
-application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
-image/* application/vnd.cups-postscript 50 imagetops
-image/* application/vnd.cups-raster 50 imagetoraster
-
    - -

    The source field is a MIME type, optionally using a wildcard for -the super-type or sub-type (e.g. "text/plain", "image/*", "*/postscript"). - -

    The destination field is a MIME type defined in the -mime.types file. - -

    The cost field defines a relative cost for the filtering -operation from 1 to 100. The cost is used to choose between two -different sets of filters when converting a file. For example, to convert -from image/jpeg to application/vnd.cups-raster, -you could use the imagetops and pstoraster -filters for a total cost of 100, or the imagetoraster filter -for a total cost of 50. - -

    The program field defines the filter program to run; the -special program "-" can be used to make two file types equivalent. The -program must accept the standard filter arguments and environment -variables described in the CUPS Interface Design Description and CUPS -Software Programmers Manual: - -

      -program job user title options [filename]
-
    - -

    If specified, the filename argument defines a file to read -when filtering, otherwise the filter must read from the standard input. -All filtered output must go to the standard output. - - -

    Adding Filetypes and Filters

    - -

    Adding a new file type or filter is fairly straight-forward. Rather -than adding the new type and filter to the mime.types and -mime.convs files which are overwritten when you upgrade to a -new version of CUPS, you simple need to create new files with -.types and .convs extensions in the -/etc/cups directory. We recommend that you use the product -or format name, e.g.: - -

      -myproduct.types
-myproduct.convs
-
    - -

    If you are providing a filter for a common file format or printer, -add the company or author name: - -

      -acme-msword.types
-acme.msword.convs
-
    - -

    This will help to prevent name collisions if you install many -different file types and filters. - -

    Once you choose the names for these files, create them using your -favorite text editor as described earlier in this chapter. Once you -have created the files, restart the cupsd process as -described earlier in "Restarting the CUPS Server". - -

    Printer Drivers and PPD Files

    - -

    Most CUPS printer drivers utilize one or more printer-specific filters -and a PPD file for each printer model. Printer driver filters are registered -via the PPD file using cupsFilter attributes: - -

      -*cupsFilter: "application/vnd.cups-raster 0 rastertohp"
-
    - -

    The filter is specified using the source file type only; the destination -file type is assumed to be printer/name - suitable for sending -to the printer. - -

    Writing Your Own Filter or Printer Driver

    - -

    CUPS supports an unlimited number of file formats and filters, and can -handle any printer. If you'd like to write a filter or printer driver for -your favorite file format or printer, consult the CUPS Software Programmers -Manual for step-by-step instructions. - - -

    7 - Printing with Other Systems

    - -

    This chapter describes how to print from client systems that use the -LPD, Mac OS, or Windows printing protocols. - -

    The Basics

    - -

    CUPS is based on the IPP protocol, so any system that supports IPP -can send jobs to and receive jobs from CUPS automatically. However, not -all systems support IPP yet. This chapter will show you how to connect -these systems to your CUPS server, either to accept jobs from your -server for printing, or to send jobs to your server. - -

    Printing from LPD Clients

    - -

    CUPS supports limited functionality for LPD-based clients. With LPD you can -print files to specific printers, list the queue status, and so forth. However, -the automatic client configuration and printer options are not supported by -the LPD protocol, so you must manually configure each client for the printers -it needs to access. - -

    The cups-lpd(8) program provides support for LPD -clients and can be used from either the inetd(8) or -xinetd(8) programs. Add the following line to the -/etc/inetd.conf file to enable LPD support on your -server through the inetd program: - -

      -printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
-
    - -

    The path to the cups-lpd may vary depending on your -installation. - -

    Once you have added this line, send the inetd -process a HUP signal or reboot the system: - -

      -killall -HUP inetd ENTER [IRIX and some versions of Linux]
-kill -HUP pid ENTER [Others]
-reboot ENTER [For all systems if the HUP signal fails]
-
    - -

    If you are using the xinetd program, create a -file named /etc/xinetd.d/printer containing the -following lines: - -

      -service printer
-{
-    socket_type = stream
-    protocol = tcp
-    wait = no
-    user = lp
-    server = /usr/lib/cups/daemon/cups-lpd
-}
-
    - -

    The xinetd program automatically reads the new -configuration file and enables LPD printing support. - -

    - - - -
    Warning: - -

    cups-lpd currently does not perform any - access control based on the settings in - cupsd.conf or in the hosts.allow - or hosts.deny files used by TCP wrappers. - Therefore, running cups-lpd on your server - will allow any computer on your network (and perhaps the - entire Internet) to print to your server. - -

    While xinetd has built-in access control - support, you should use the TCP wrappers package with - inetd to limit access to only those - computers that should be able to print through your - server. - -

    - -

    Printing to LPD Servers

    - -

    CUPS provides the lpd backend for printing to LPD-based -servers and printers. Use a device URI of lpd://server/name -to print to a printer on an LPD server, where server -is the hostname or IP address of the server and name is -the queue name. - -

    Microsoft Windows NT provides an LPD service under the name "TCP/IP -Printing Services". To enable LPD printing on NT, open the "Services" -control panel, select the "TCP/IP Printing Services" service, and click -on the "Start" button. Any shared printer will then be available via -the LPD protocol. - -

    Printing from Mac OS Clients

    - -

    CUPS does not provide Mac OS support directly. However, there are several -free and commercial software packages that do. - -

    Columbia Appletalk Package (CAP)

    - -

    Because the CAP LaserWriter server (lwsrv(8)) does -not support specification of PPD files, we do not recommend that you -use CAP with CUPS. However, you can run the lpsrv program -for limited printing with the command: - -

      -lwsrv -n "Name" -p printer -a /usr/lib/adicts -f /usr/lib/LW+Fonts
-
    - -

    where Name is the name you want to use when sharing the -printer, and printer is the name of the CUPS print queue. - - -

    XINET KA/Spool

    - -

    To use your system as a print server for Mac OS clients, -configure each printer using a papserver(8) in the -/usr/adm/appletalk/services file, specifying the -corresponding PPD file in the /etc/cups/ppd directory for -each printer. For a printer named MyPrinter the entry -would look like: - -

      -/usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
-"Printer Description" MyPrinter
-
    - -
    - - - -
    - NOTE: - -

    Enter the text above on a single line without the backslash (\) - character. -

    - -

    NetATalk

    - -

    To use your system as a print server for Mac OS clients, -configure each printer in the papd.conf file, specifying the -corresponding PPD file in the /etc/cups/ppd directory for -each printer. For a printer named MyPrinter the entry -would look like: - -

      -Printer Description:MyPrinter@MyServer:\
-        :pr=|/usr/bin/lp -d MyPrinter:\
-        :op=daemon:\
-        :pd=/etc/cups/ppd/MyPrinter.ppd:
-
    - - - -

    Printing to Mac OS Servers

    - -

    CUPS currently does not provide a backend to communicate with a Mac OS -server. However, you can write and install a short shell script -in the /usr/lib/cups/backend directory that sends a print file -using the appropriate command. The following is a short script that will -run the papif command provided with CAP. - -

    After copying this script to /usr/lib/cups/backend/cap, -specify a device URI of cap://server/printer to use this -backend with a print queue. - - -

      -
      -"/usr/lib/cups/backend/cap"
-#!/bin/sh
-#
-# Usage: cap job user title copies options [filename]
-#
-
-# No arguments means show available devices...
-
-if test ${#argv} = 0; then
-	echo "network cap \"Unknown\" \"Mac OS Printer via CAP\""
-	exit 0
-fi
-
-# Collect arguments...
-
-user=$2
-copies=$4
-
-if test ${#argv} = 5; then
-	# Get print file from stdin; copies have already been handled...
-	file=/var/tmp/$$.prn
-	copies=1
-	cat > $file
-else
-	# Print file is on command-line...
-	file=$6
-fi
-
-# Create a dummy cap.printers file for this printer based
-# upon a device URI of "cap://server/printer"...
-
-echo $PRINTER/$DEVICE_URI | \
-	awk -F/ '{print $1 "=" $5 ":LaserWriter@" $4}' > /var/tmp/$$.cap
-
-CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS
-
-# Send the file to the printer, once for each copy. This assumes that you
-# have properly initialized the cap.printers file...
-
-while [ $copies -gt 0 ]; do
-	papif -n $user < $file
-
-        copies=`expr $copies - 1`
-done
-
-# Remove any temporary files...
-if test ${#argv} = 5; then
-	/bin/rm -f $file
-fi
-
-/bin/rm -f /var/tmp/$$.cap
-
-exit 0
-
    - - -

    Printing from Windows Clients

    - -

    While CUPS does not provide Windows support directly, the free -SAMBA software package does. SAMBA version 2.0.6 is the first release -of SAMBA that supports CUPS. You can download SAMBA from: - -

    - -

    To configure SAMBA for CUPS, edit the smb.conf file and -replace the existing printing commands and options with the line: - -

      -printing = cups
-printcap name = cups
-
    - -

    That's all there is to it! Remote users will now be able to browse and -print to printers on your system. - -

    Exporting Printer Drivers

    - -

    You can optionally export printer drivers from your CUPS -server using the cupsaddsmb command and the SAMBA -2.2.0 or higher software. - -

    Before you can export the printers you must download the -current Adobe PostScript printer drivers from the Adobe web -site (http://www.adobe.com/). -Use the free unzip software to extract the files -from the self-extracting ZIP file containing the drivers; you -will need the following files: - -

      -ADFONTS.MFM
-ADOBEPS4.DRV
-ADOBEPS4.HLP
-ADOBEPS5.DLL
-ADOBEPSU.DLL
-ADOBEPSU.HLP
-DEFPRTR2.PPD
-ICONLIB.DLL
-PSMON.DLL
-
    - -

    Copy these files to the /usr/share/cups/drivers -directory - you may need to rename some of the files so the -filenames are all UPPERCASE. - -

    Next, add a print$ share for the printer -drivers to your smb.conf file: - -

      -[print$]
-    comment = Printer Drivers
-    path = /etc/samba/drivers
-    browseable = yes
-    guest ok = no
-    read only = yes
-    write list = root
-
    - -

    The directory for your printer drivers can be anywhere on the -system; just make sure it is writable by the users specified by -the write list directive. Also, make sure that you -have SAMBA passwords defined for each user in the write -list using the smbpasswd(1) command. -Otherwise you will not be able to authenticate - -

    Finally, run the cupsaddsmb command to export -the printer drivers for one or more queues: - -

      -cupsaddsmb -U root printer1 ... printerN ENTER
-
    - -

    Running cupsaddsmb with the -a option -will export all printers: - -

      -cupsaddsmb -U root -a ENTER
-
    - -

    Printing to Windows Servers

    - -

    CUPS can print to Windows servers in one of two ways. The first way uses -the LPD protocol on the CUPS system and the "TCP/IP Printing Services" on -the Windows system. You can find out more about this configuration in the -LPD section earlier in this chapter. - -

    The second way is through the Microsoft Server Message Block ("SMB") -protocol. Support for this protocol is provided with the free SAMBA -software package. You can download SAMBA from: - -

    - -

    To configure CUPS for SAMBA, run the following command: - -

      -ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER
-
    - -

    The smbspool(1) program is provided with SAMBA starting -with SAMBA 2.0.6. Once you have made the link you can configure your -printers with one of the following device URIs: - -

      -smb://workgroup/server/sharename
-smb://server/sharename
-smb://user:pass@workgroup/server/sharename
-smb://user:pass@server/sharename
-
    - -

    The workgroup name need only be specified if your -system is using a different workgroup. The user:pass -strings are required when printing to Windows NT servers or to shares -with passwords enabled under Windows 95 and 98. - - -

    A - Software License Agreement

    - - - - -

    B - Common Network Settings

    - -

    This appendix covers many of the popular TCP/IP network interfaces -and printer servers available on the market today. - -

    Configuring a Network Interface

    - -

    When you first install a network printer or print server on your -LAN, you need to set the Internet Protocol ("IP") address. On most -higher-end "workgroup" printers, you can set the address through the -printer control panel. However, in most cases you will want to assign -the addresses remotely from your workstation. This makes administration -a bit easier and avoids assigning duplicate addresses accidentally. - -

    To setup your printer or print server for remote address assignment, -you'll need the Ethernet Media Access Control ("MAC") address, also -sometimes called a node address, and the IP address you want to use for -the device. The Ethernet MAC address can often be found on the printer -test page or bottom of the print server. - - -

    Configuring the IP Address Using ARP

    - -

    The easiest way to set the IP address of a network device is to use -the arp(8) command. The arp sends an Address -Resolution Protocol ("ARP") packet to the specified Ethernet MAC address, -setting the network device's IP address: - -

      -arp -s ip-address ethernet-address ENTER
-arp -s host.domain.com 08:00:69:00:12:34 ENTER
-arp -s 192.0.2.2 08:00:69:00:12:34 ENTER
-
    - -

    Configuring the IP Address Using RARP

    - -

    The most flexible way to remotely assign IP addresses under UNIX -is through the Reverse Address Resolution Protocol ("RARP"). RARP -allows a network device to request an IP address using its Ethernet -MAC address, and one or more RARP servers on the network will -respond with an ARP packet with the IP address the device can use. - -

    RARP should be used when you have to manage many printers or print -servers, or when you have a network device that does not remember its -IP address after a power cycle. If you just have a single printer or -print server, the arp command is the way to go. - -

    Some UNIX operating systems use a program called -rarpd(8) to manage RARP. Others, like Linux, support this -protocol in the kernel. For systems that provide the rarpd -program you will need to start it before RARP lookups will work: - -

      -rarpd ENTER
-
    - -

    Under IRIX you can enable this functionality by default using: - -

      -chkconfig rarpd on ENTER
-
    - -

    Both the rarpd program and kernel RARP support read a -list of Ethernet and IP addresses from the file /etc/ethers. -Each line contains the Ethernet address (colon delimited) followed by -an IP address or hostname like: - -

      -08:00:69:00:12:34 myprinter.mydomain.com
-08:00:69:00:12:34 192.0.2.2
-
    - -

    Add a line to this file and cycle the power on the printer or print -server to set its address. - - -

    Configuring the IP Address Using BOOTP

    - -

    The BOOTP protocol is used when you need to provide additional information -such as the location of a configuration file to the network interface. Using -the standard bootpd(8) program supplied with UNIX you simply need to -add a line to the /etc/bootptab file; for IRIX: - -

      -myprinter 08:00:69:00:12:34 192.0.2.2 myprinter.boot
-
    - - -

    Newer versions of bootpd use a different format: - -

      -myprinter:ha=080069001234:ip=192.0.2.2:t144=myprinter.boot
-
    - -

    The myprinter.boot file resides in the /usr/local/boot -directory by default. If you do not need to provide a boot file you may leave -the last part of the line blank.

    - - -
    - - - -
    - NOTE: - -

    Some versions of UNIX do not enable the BOOTP service by - default. The /etc/inetd.conf usually contains a - line for the BOOTP service that can be uncommented if - needed. -

    - -

    Verifying the Printer Connection

    - -

    To test that the IP address has been successfully assigned and that the -printer is properly connected to your LAN, type: - -

      -ping ip-address ENTER
-
    - -

    If the connection is working properly you will see something like: - -

      -ping myprinter ENTER
-PING myprinter (192.0.2.2): 56 data bytes
-64 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
-64 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
-64 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
-64 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
-
    - -

    If not, verify that the printer or print server is connected to the -LAN, it is powered on, the LAN cabling is good, and the IP address is -set correctly. You can usually see the current IP address and network -status by printing a configuration or test page on the device. - - -

    Common Network Interface Settings

    - -

    Once you have set the IP address you can access the printer or print -server using the ipp, lpd, or -socket backends. The following is a list of common network -interfaces and printer servers and the settings you should use with -CUPS: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Model/ManufacturerDevice URI(s)
    Apple LaserWriterlpd://address/PASSTHRU
    Axis w/o IPP
    - (see directions)    		socket://address:9100
    - socket://address:9101
    - socket://address:9102
    Axis w/IPPipp://address/LPT1
    - ipp://address/LPT2
    - ipp://address/COM1
    Castelle LANpressTMlpd://address/pr1
    - lpd://address/pr2
    - lpd://address/pr3
    DPI NETPrintlpd://address/pr1
    - lpd://address/pr2
    - lpd://address/pr3
    EFI® Fiery® RIPlpd://address/print
    EPSON® Multiprotocol Ethernet Interface Boardsocket://address
    Extended System ExtendNETlpd://address/pr1
    - lpd://address/pr2
    - lpd://address/pr3
    Hewlett Packard JetDirect w/o IPPsocket://address:9100
    - socket://address:9101
    - socket://address:9102
    Hewlett Packard JetDirect w/IPPipp://address/ipp
    - ipp://address/ipp/port1
    - ipp://address/ipp/port2
    - ipp://address/ipp/port3
    Intel® NetportExpress XL, PRO/100lpd://address/LPT1_PASSTHRU
    - lpd://address/LPT2_PASSTHRU
    - lpd://address/COM1_PASSTHRU
    LexmarkTM MarkNetlpd://address/ps
    Linksys EtherFast®
    - (see directions)    		socket://address:4010
    - socket://address:4020
    - socket://address:4030
    Kodak®lpd://address/ps
    QMS® CrownNetTMlpd://address/ps
    Tektronix® PhaserShareTMsocket://address:9100
    XEROX® 4512 NIClpd://address/PORT1
    XEROX® XNIClpd://address/PASSTHRU
    XEROX® (most others)socket://address:5503
    - -

    Configuring Axis Print Servers

    - -

    The Axis print servers can be configured using ARP, RARP, or BOOTP. -However, on models that do not provide IPP support an additional step -must be performed to configure the TCP/IP portion of the print server -for use with CUPS. - - -

    Each print server contains a configuration file named -config that contains a list of network parameters used by -the server. To modify this file you must first download it from the -print server using the ftp(1) program: - -

      -ftp ip-address ENTER
-Connected to ip-address.
-220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
-ftp> user root ENTER
-331 User name ok, need password
-Password: pass ENTER (this is not echoed)
-230 User logged in
-ftp> get config ENTER
-local: config remote: config
-200 PORT command successful.
-150 Opening data connection for config (192,0,2,2),
-(mode ascii).
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
    - - -

    Next, edit the file with your favorite text editor and locate the -lines beginning with: - -

      -RTN_OPT.     : YES
-RTEL_PR1.    : 0
-RTEL_PR2.    : 0
-RTEL_PR3.    : 0
-RTEL_PR4.    : 0
-RTEL_PR5.    : 0
-RTEL_PR6.    : 0
-RTEL_PR7.    : 0
-RTEL_PR8.    : 0
-
    - - -Change the RTN_OPT line to read: - -
      -RTN_OPT.     : NO
-
    - - -

    This disables the Reverse TELNET protocol and enables the standard -TELNET protocol on the print server. Next, assign a port number for -each parallel and serial port on the server as follows: - -

      -RTEL_PR1.    : 9100
-RTEL_PR2.    : 9101
-RTEL_PR3.    : 9102
-RTEL_PR4.    : 9103
-RTEL_PR5.    : 9104
-RTEL_PR6.    : 9105
-RTEL_PR7.    : 9106
-RTEL_PR8.    : 9107
-
    - - -

    This essentially makes the Axis print server look like a Hewlett -Packard JetDirect EX print server. Save the file and then upload the -new config file using the ftp command: - -

      -ftp ip-address ENTER
-Connected to ip-address.
-220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
-ftp> user root ENTER
-331 User name ok, need password
-Password: pass ENTER (this is not echoed)
-230 User logged in
-ftp> put config CONFIG ENTER
-local: config remote: CONFIG
-200 PORT command successful.
-150 Opening data connection for config (192,0,2,2), (mode ascii).
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> get hardreset ENTER
-local: hardreset remote: hardreset
-200 PORT command successful.
-421 Axis NPS ### hard reset, closing connection.
-ftp> quit ENTER
-221 Goodbye.
-
    - -

    Your Axis print server is now ready for use! - -

    Configuring Linksys Print Servers

    - -

    The Linksys print servers can be configured using ARP, RARP, or -BOOTP. Like older Axis print servers, an additional step must be -performed to configure the TCP/IP portion of the print server for use -with CUPS. - - -

    Each print server contains a configuration file named -CONFIG that contains a list of network parameters used by -the server. To modify this file you must first download it from the -print server using the ftp(1) program: - -

      -ftp -n ip-address ENTER
-Connected to ip-address.
-220 Print Server Ready.
-Remote system type is Print.
-ftp> get CONFIG ENTER
-local: CONFIG remote: CONFIG
-200 Command OK.
-150 Open ASCII Mode Connection.
-WARNING! 68 bare linefeeds received in ASCII mode
-File may not have transferred correctly.
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
    - - -

    Next, edit the file with your favorite text editor and locate the -lines beginning with: - -

      -0100 L1_PROUT:P1
-0120 L2_PROUT:P1
-0140 L3_PROUT:P1
-
    - -

    Change the port number for -each parallel and serial port on the server as follows: - -

      -0100 L1_PROUT:P1
-0120 L2_PROUT:P2
-0140 L3_PROUT:P3
-
    - - -

    This maps each virtual printer with a physical port. Save the file and then upload the -new CONFIG file using the ftp command: - -

      -ftp -n ip-address ENTER
-Connected to ip-address.
-220 Print Server Ready.
-Remote system type is Print.
-ftp> put CONFIG ENTER
-local: CONFIG remote: CONFIG
-200 Command OK.
-150 Open ASCII Mode Connection.
-226 Transfer complete.
-##### bytes received in #.## seconds (##### Kbytes/s)
-ftp> quit ENTER
-221 Goodbye.
-
    - -

    Your Linksys print server is now ready for use! - - -

    C - Printer Drivers

    - -

    This appendix lists the printer drivers that are provided with CUPS. - -

    Printer Drivers

    - -

    CUPS includes the following printer drivers: - -

    - -

    EPSON 9-pin Dot Matrix

    - -

    The EPSON 9-pin Dot Matrix driver (epson9.ppd) supports -9-pin dot matrix printers that implement the ESC/P command set. It -provides 60x72, 120x72, and 240x72 DPI output in black only. - -

    EPSON 24-pin Dot Matrix

    - -

    The EPSON 24-pin Dot Matrix driver (epson9.ppd) supports -24-pin dot matrix printers that implement the ESC/P command set. It -provides 120x180, 180x180, 360x180, and 360x360 DPI output in black -only. - -

    EPSON Stylus Color

    - -

    The EPSON Stylus Color driver (stcolor.ppd) supports -EPSON Stylus Color printers that implement the ESC/P2 command set. It -provides 180, 360, and 720 DPI output in black and color (CMYK). - -

    EPSON Stylus Photo

    - -

    The EPSON Stylus Photo driver (stphoto.ppd) supports -EPSON Stylus Photo printers that implement the ESC/P2 command set. It -provides 180, 360, and 720 DPI output in black and color (CMYKcm). - -

    HP DeskJet

    - -

    The HP DeskJet driver (deskjet.ppd) supports HP DeskJet -printers that implement the PCL command set. It provides 150, 300, and -600 DPI output in black and color (CMYK). - -

    The DeskJet printers that implement the HP-PPA command set (720C, -722C, 820C, and 1100C) are not supported due to a complete lack -of documentation and support from Hewlett Packard. - -

    The duplexer provided with the HP DeskJet 900 series printers is also -not supported for similar reasons. - -

    HP LaserJet

    - -

    The HP LaserJet driver (laserjet.ppd) supports HP -LaserJet printers that implement the PCL command set. It provides 150, -300, and 600 DPI output in black only and supports the duplexer if -installed. - -

    LaserJet printers that do not implement PCL (3100, 3150) are not -supported due to a complete lack of documentation and support from -Hewlett Packard. - - -

    D - List of Files

    - -

    This appendix lists the files and directories that are installed for -the Common UNIX Printing System. - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    PathnameDescription
    /etc/cups/certs/The location of authentication certificate files for local - HTTP clients.
    /etc/cups/classes.confThe printer classes configuration file for the scheduler.
    /etc/cups/cupsd.confThe scheduler configuration file.
    /etc/cups/interfaces/The location of System V interface scripts for printers.
    /etc/cups/mime.convsThe list of standard file filters included with CUPS.
    /etc/cups/mime.typesThe list of recognized file types for CUPS.
    /etc/cups/ppd/The location of PostScript Printer Description ("PPD") files for - printers.
    /etc/cups/printers.confThe printer configuration file for the scheduler.
    /usr/bin/cancelThe System V cancel job(s) command.
    /usr/bin/disableThe System V disable printer command.
    /usr/bin/enableThe System V enable printer command.
    /usr/bin/lpThe System V print command.
    /usr/bin/lpoptionsSets user-defined printing options and defaults.
    /usr/bin/lppasswdAdds, changes, or removes Digest password accounts.
    /usr/bin/lpqThe Berkeley status command.
    /usr/bin/lprThe Berkeley print command.
    /usr/bin/lprmThe Berkeley cancel job(s) command.
    /usr/bin/lpstatThe System V status command.
    /usr/include/cups/CUPS API header files.
    /usr/lib32/libcups.a
    - /usr/lib32/libcupsimage.a    		Static libraries (IRIX 6.5)
    /usr/lib/libcups.a
    - /usr/lib/libcupsimage.a    		Static libraries (all others)
    /usr/lib/libcups.sl.2
    - /usr/lib/libcupsimage.sl.2    		Shared libraries (HP-UX)
    /usr/lib32/libcups.so.2
    - /usr/lib32/libcupsimage.so.2    		Shared libraries (IRIX 6.5)
    /usr/lib/libcups.so.2
    - /usr/lib/libcupsimage.so.2    		Shared libraries (all others)
    /usr/lib/cups/backend/Backends for various types of printer connections.
    /usr/lib/cups/cgi-bin/CGI programs for the scheduler.
    /usr/lib/cups/daemon/Daemons for polling and LPD support.
    /usr/lib/cups/filter/Filters for various types of files.
    /usr/lib/locale/The location of language-specific message files. (System V)
    /usr/lib/nls/msg/The location of language-specific message files. (Compaq Tru64 UNIX)
    /usr/share/locale/The location of language-specific message files. (Linux, *BSD)
    /usr/sbin/acceptThe accept-jobs command.
    /usr/sbin/cupsdThe CUPS print scheduler.
    /usr/sbin/lpadminThe System V printer administration tool.
    /usr/sbin/lpcThe Berkeley printer administration tool.
    /usr/sbin/lpinfoThe get-devices and get-ppds command.
    /usr/sbin/lpmoveThe move-jobs command.
    /usr/sbin/rejectThe reject-jobs command.
    /usr/share/catman/a_man/
    - /usr/share/catman/u_man/    		Man pages (IRIX)
    /usr/share/man/Man pages (Compaq Tru64 UNIX, HP-UX, Solaris)
    /usr/man/Man pages (all others)
    /usr/share/cups/data/The location of filter data files.
    /usr/share/cups/data/testprint.psThe PostScript test page file.
    /usr/share/cups/fonts/The location of PostScript fonts for the PostScript RIP.
    /usr/share/cups/model/The location of PostScript Printer Description ("PPD") files and - interface scripts that may be used to setup a printer queue.
    /usr/share/cups/pstoraster/Other PostScript RIP initialization files.
    /usr/share/cups/pstoraster/FontmapThe font mapping file (converts filenames to fontnames)
    /usr/share/cups/templates/The location of HTML template files for the web interfaces.
    /usr/share/doc/cups/Documentation and web page data for the scheduler.
    /var/log/cups/The location of scheduler log files.
    /var/spool/cups/The location of print files waiting to be printed.
    - - -

    E - Troubleshooting Common Problems

    - -

    This appendix covers some of the common problems first-time users -encounter when installing and configuring CUPS. - -

    Commercial support for CUPS is available from Easy Software Products. -For more information please contact us at: - -

    - -

    My Applications Don't See the Available Printers

    - -

    Many applications read the /etc/printcap file to -get a list of available printers. - -

    The default CUPS configuration creates the -/etc/printcap file automatically. To enable or -disable automatic creation and updating of this file, use the Printcap directive described -in Chapter 6, "Printing System -Management". - -

    CUPS Doesn't Recognize My Username or Password!

    - -

    CUPS will ask you for a UNIX username and password when you perform -printer administration tasks remotely or via a web browser. The default -configuration requires that you use the root username and -the corresponding password to authenticate the request. - -

    CUPS does not allow you to authenticate an administration request -with an account that has no password for security reasons. If you do -not have a password on your root account then you won't be -able to add printers remotely or via the web interface! - - -

    To disable password authentication you need to edit the -/etc/cups/cupsd.conf file and comment out the -lines reading: - -

      -AuthType Basic
-AuthClass System
-
    - -

    for the /admin location. Then restart the CUPS server as -described in Chapter 6, "Printing System -Management".

    - -
    - - - -
    - NOTE: - -

    Disabling password checks will allow any local user to - change your printer and class configuration, but remote - administration from another machine will still not be allowed. -

    - -

    I Can't Do Administration Tasks from Another Machine!

    - -

    The default CUPS configuration limits administration to the local -machine. To open up access, edit the /etc/cups/cupsd.conf -and comment out the lines reading: - -

      -Order deny,allow
-Deny from all
-Allow from 127.0.0.1
-
    - -

    for the /admin location. Then restart the CUPS server as -described in Chapter 6, "Printing System -Management".

    - -
    - - - -
    - NOTE: - -

    Allowing administration access from all hosts is a potential - security risk. Please read Chapter - 6, "Printing System Management" for a description of these - risks and ways to minimize them. -

    - - -

    I Can't Do Administration Tasks from My Web Browser!

    - -

    This problem is usually caused by: - -

      - -
    1. not specifying the correct password for the - root account. - -
    2. accessing the CUPS server using the hostname or IP - address of the server without enabling remote access for - administration functions. This can be corrected by following - the instructions in the "I Can't Do - Administration Tasks from Another Machine!" section earlier - in this appendix. - -
    3. not setting a password on the root account. CUPS will not - authenticate a user account that does not have a password for - security reasons. - -
    4. authenticating using an account other than root, but the - account you are using is not a member of the system group. - -
    5. configuring CUPS to use Digest authentication, but - your web browser does not support Digest authentication. - -
    - -

    Connection Refused Messages

    - -

    Under normal circumstances, "connection refused" messages for a -networked printer should be expected from time to time. Most network -interfaces only allow a single connection to be made at any given time -(one job at a time) and will refuse access to all other systems while -the first connection is active. CUPS automatically retries the -connection once every 30 seconds. - -

    If the problem persists and you are unable to print any jobs to the printer, -verify that another machine is not maintaining a connection with the printer, -and that you have selected the proper port or printer name for the printer. - -

    Also, most external print servers will refuse connections if the connected -printer is turned off or is off-line. Verify that the affected printer is -turned on and is online. - -

    Write Error Messages

    - -

    If you get "write error" messages on a printer queue the printer -interface (usually a Hewlett Packard JetDirect interface) has timed out -and reset the network connection from your workstation. - -

    The error is caused by that startup delay between the initial setup -of the printer or plotter and the first page of print data that is -sent. - - -

    To correct the problem, change the idle timeout on the interface to at least -180 seconds or 3 minutes. To change the timeout on a Hewlett Packard -JetDirect interface, type: - -

      -telnet ip-address ENTER
-
-Trying ip-address...
-Connected to ip-address.
-Escape character is `^]'.
-
-Please type [Return] two times, to initialize telnet configuration
-For HELP type "?"
-> idle-timeout: 180 ENTER
-> quit ENTER
-
    - - - diff --git a/doc/sdd.html b/doc/sdd.html deleted file mode 100644 index 92172102ad..0000000000 --- a/doc/sdd.html +++ /dev/null @@ -1,591 +0,0 @@ - - - -CUPS Software Design Description - - - - - - - -

    -

    CUPS Software Design Description


    -CUPS-SDD-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Design Overview - -A Glossary - -
    -

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

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    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.2: CUPS Configuration Management Plan
      • -
    • CUPS-IDD-1.2: CUPS System Interface Design Description
      • -
    • CUPS-IPP-1.2: CUPS Implementation of IPP
      • -
    • CUPS-SAM-1.2.x: CUPS Software Administrators Manual
      • -
    • CUPS-SDD-1.2: CUPS Software Design Description
      • -
    • CUPS-SPM-1.2.x: CUPS Software Programming Manual
      • -
    • CUPS-SSR-1.2: CUPS Software Security Report
      • -
    • CUPS-STP-1.2: CUPS Software Test Plan
      • -
    • CUPS-SUM-1.2.x: CUPS Software Users Manual
      • -
    • CUPS-SVD-1.2: CUPS Software Version Description
      • -
    -

    2.2 Other Documents

    -

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

    - -

    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
    -
    - - diff --git a/doc/sdd.pdf b/doc/sdd.pdf deleted file mode 100644 index 15a684056e..0000000000 Binary files a/doc/sdd.pdf and /dev/null differ diff --git a/doc/spm.html b/doc/spm.html deleted file mode 100644 index 925b1c29e2..0000000000 --- a/doc/spm.html +++ /dev/null @@ -1,8919 +0,0 @@ - - - -CUPS Software Programmers Manual - - - - - - - -

    -

    CUPS Software Programmers Manual


    -CUPS-SPM-1.2.0
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    Preface - -1 - Printing System Overview - -2 - The CUPS API - -3 - Writing Filters - -4 - Writing Printer Drivers - -5 - Writing Backends - -A - Software License Agreement - -B - Constants - -C - Structures - -D - Functions - -
    -

    Preface

    -

    This software programmers manual provides software programming - information for the Common UNIX Printing System ("CUPS") Version 1.2.0.

    -

    System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    - - -

    Document Overview

    -

    This software programmers manual is organized into the following - sections:

    - -

    Notation Conventions

    -

    Various font and syntax conventions are used in this guide. Examples - and their meanings and uses are explained below: -

    - - - - - - - - - - - - -
    Example   Description
     
    lpstat -
    lpstat(1)    		   The names of commands; - the first mention of a command or function in a chapter is followed by - a manual page section number.
     
    /var -
    /usr/share/cups/data/testprint.ps    		    -File and directory names.
     
    Request ID is Printer-123 -   Screen output.
     
    lp -d printer filename ENTER -   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are - written using the period (.) to indicate the decimal point.
    -
    - - -

    -

    Abbreviations

    - The following abbreviations are used throughout this manual: -
      -
      -
      kb
      -
      Kilobytes, or 1024 bytes -
       
      -
      Mb
      -
      Megabytes, or 1048576 bytes -
       
      -
      Gb
      -
      Gigabytes, or 1073741824 bytes -
       
      -
      -
    -

    Other References

    -
      -
      -
      CUPS Software Administrators Manual
      -
      An administration guide for the CUPS software. -
       
      -
      CUPS Software Users Manual
      -
      An end-user guide for using the CUPS software. -
       
      -
      -
    -

    1 - Printing System Overview

    -

    This chapter provides an overview of how the Common UNIX Printing - System works.

    -

    The Printing Problem

    -

    For years the printing problem has plagued UNIX. Unlike - Microsoft® Windows® or Mac OS, UNIX has no standard interface or system - in place for supporting printers. Among the solutions currently - available, the Berkeley and System V printing systems are the most - prevalent.

    -

    These printing systems support line printers (text only) or - PostScript printers (text and graphics), and with some coaxing they can - be made to support a full range of printers and file formats. However, - because each varient of the UNIX operating system uses a different - printing system than the next developing printer drivers for a wide - range of printers and operating systems is extremely difficult. That - combined with the limited volume of customers for each UNIX varient has - forced most printer vendors to give up supporting UNIX entirely.

    -

    CUPS is designed to eliminate the printing problem. One common - printing system can be used by all UNIX varients to support the - printing needs of users. Printer vendors can use its modular filter - interface to develop a single driver program that supports a wide range - of file formats with little or no effort. Since CUPS provides both the - System V and Berkeley printing commands, users (and applications) can - reap the benefits of this new technology with no changes.

    -

    The Technology

    -

    CUPS is based upon an emerging Internet standard called the Internet - Printing Protocol. IPP has been embraced by dozens of printer and - printer server manufacturers and is supported by Microsoft Windows - 2000.

    -

    IPP defines a standard protocol for printing as well as managing - print jobs and printer options like media size, resolution, and so - forth. Like all IP-based protocols, IPP can be used locally or over the - Internet to printers hundreds or thousands of miles away. Unlike other - protocols, however, IPP also supports access control, authentication, - and encryption, making it a much more capable and secure printing - solution than older ones.

    -

    IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") - which is the basis of web servers on the Internet. This allows users to - view documentation, check status information on a printer or server, - and manage their printers, classes, and jobs using their web browser.

    -

    CUPS provides a complete IPP/1.1 based printing system that provides - Basic, Digest, and local certificate authentication and user, domain, - or IP-based access control. TLS encryption will be available in future - versions of CUPS.

    -

    Jobs

    -

    Each file or set of files that is submitted for printing is called a - job. Jobs are identified by a unique number starting at 1 and are - assigned to a particular destination, usually a printer. Jobs can also - have options associated with them such as media size, number of copies, - and priority.

    -

    Classes

    -

    CUPS supports collections of printers known as classes. Jobs - sent to a class are forwarded to the first available printer in the - class.

    -

    Filters

    -

    Filters allow a user or application to print many types of files - without extra effort. Print jobs sent to a CUPS server are filtered - before sending them to a printer. Some filters convert job files to - different formats that the printer can understand. Others perform page - selection and ordering tasks.

    -

    CUPS provides filters for printing many types of image files, HP-GL/2 - files, PDF files, and text files. CUPS also supplies PostScript and - image file Raster Image Processor ("RIP") filters that convert - PostScript or image files into bitmaps that can be sent to a raster - printer.

    -

    Backends

    -

    Backends perform the most important task of all - they send the - filtered print data to the printer.

    -

    CUPS provides backends for printing over parallel, serial, and USB - ports, and over the network via the IPP, JetDirect (AppSocket), and - Line Printer Daemon ("LPD") protocols. Additional backends are - available in network service packages such as the SMB backend included - with the popular SAMBA software.

    -

    Backends are also used to determine the available devices. On startup - each backend is asked for a list of devices it supports, and any - information that is available. This allows the parallel backend to tell - CUPS that an EPSON Stylus Color 600 printer is attached to parallel - port 1, for example.

    -

    Printer Drivers

    -

    Printer drivers in CUPS consist of one of more filters specific to a - printer. CUPS includes sample printer drivers for Hewlett-Packard - LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, - and Stylus Photo printers. While these drivers do not generate optimal - output for the different printer models, they do provide basic printing - and demonstrate how you can write your own printer drivers and - incorporate them into CUPS.

    -

    Networking

    -

    Printers and classes on the local system are automatically shared - with other systems on the network. This allows you to setup one system - to print to a printer and use this system as a printer server or spool - host for all of the others. Users may then select a local printer by - name or a remote printer using "name@server".

    -

    CUPS also provides implicit classes, which are collections of - printers and/or classes with the same name. This allows you to setup - multiple servers pointing to the same physical network printer, for - example, so that you aren't relying on a single system for printing. - Because this also works with printer classes, you can setup multiple - servers and printers and never worry about a single point of failure - unless all of the printers and servers go down!

    -

    2 - The CUPS API

    -

    This chapter describes the CUPS Application Programmers Interface - ("API").

    -

    The CUPS API Library

    -

    The CUPS library provides a whole collection of interfaces needed to - support the internal needs of the CUPS software as well as the needs of - applications, filters, printer drivers, and backends.

    -

    Unlike the rest of CUPS, the CUPS API library is provided under the - GNU Library General Public License. This means that you can use the - CUPS API library in both proprietary and open-source programs.

    -

    Programs that use the CUPS API library typically will include the -<cups/cups.h> header file:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-jobid = cupsPrintFile("myprinter", "filename.ps", "title",
-                      num_options, options);
-
      -
    -

    Use the -lcups compiler option when linking to the CUPS - API library:

    -
      -
      -cc -o program program.c -lcups ENTER
-
      -
    -

    Additional options and libraries may be required depending on the - operating system and the location of the CUPS API library.

    -

    Detecting the CUPS API Library in GNU Autoconf

    -

    GNU autoconf is a popular configuration tool used by many programs. - Add the following lines to your configure.in file to check - for the CUPS API library in your configuration script:

    -
      -
      -AC_CHECK_LIB(socket,socket,
-if test "$uname" != "IRIX"; then
-	LIBS="-lsocket $LIBS"
-else
-	echo "Not using -lsocket since you are running IRIX."
-fi)
-AC_CHECK_LIB(nsl,gethostbyaddr,
-if test "$uname" != "IRIX"; then
-	LIBS="-lnsl $LIBS"
-else
-	echo "Not using -lnsl since you are running IRIX."
-fi)
-
-AC_CHECK_LIB(cups,httpConnect)
-
      -
    -

    Printing Services

    -

    The CUPS API library provides some basic printing services for - applications that need to print files.

    -

    Include Files

    -

    The include file used by all of these functions is -<cups/cups.h>:

    -
      -
      -#include <cups/cups.h>
-
      -
    -

    Printing a File

    -

    The CUPS API provides two functions for printing files. The first is -cupsPrintFile which prints a single named file:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-jobid = cupsPrintFile("name", "filename", "title", 0, NULL);
-
      -
    -

    The name string is the name of the printer or class to - print to. The filename string is the name of the file to - print. The title string is the name of the print job, e.g. - "Acme Word Document".

    -

    The return value is a unique ID number for the print job or 0 if - there was an error.

    -

    Printing Multiple Files

    -

    The second printing function is cupsPrintFiles:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int        jobid;
-int        num_files;
-const char *files[100];
-...
-
-jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL);
-
      -
    -

    Instead of passing a filename string as with cupsPrintFile() - you pass a file count (num_files) and filename pointer - array (files) for each file that you want to print.

    -

    As with cupsPrintFile() the return value is a unique ID - for the print job.

    -

    Cancelling Jobs

    -

    The cupsCancelJob() function cancels a queued print job:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int jobid;
-int status;
-...
-
-status = cupsCancelJob("name", jobid);
-
      -
    -

    The name string specifies the destination and is used to - determine the server to send the request to. The jobid - value is the integer returned from a previous cupsPrintFile() - or cupsPrintFiles() call.

    -

    cupsCancelJob() returns 1 if the job was - successfully cancelled and 0 if there was an error.

    -

    Getting the Available Printers and Classes

    -

    The cupsGetDests() function can be used to get a list of - the available printers, classes, and instances that a user has defined:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int         num_dests;
-cups_dest_t *dests;
-
-...
-
-num_dests = cupsGetDests(&dests);
-
      -
    -

    Each destination is stored in a cups_dest_t structure - which defines the printer or class name, the instance name (if any), if - it is the default destination, and the default options the user has - defined for the destination:

    -
      -
      -typedef struct               /**** Destination ****/
-{
-  char          *name,       /* Printer or class name */
-                *instance;   /* Local instance name or NULL */
-  int           is_default;  /* Is this printer the default? */
-  int           num_options; /* Number of options */
-  cups_option_t *options;    /* Options */
-} cups_dest_t;
-
      -
    -

    The destinations are sorted by name and instance for your - convenience. Once you have the list of available destinations, you can - lookup a specific destination using the cupsGetDest() - function:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("name", "instance", num_dests, dests);
-
      -
    -

    The name string is the printer or class name. You can - pass a value of NULL to get the default destination.

    -

    The instance string is the user-defined instance name. - Pass NULL to select the default instance, e.g. "name" - instead of "name/instance".

    -

    Printing with Options

    -

    All of the previous printing examples have passed 0 and -NULL for the last two arguments to the cupsPrintFile() - and cupsPrintFiles() functions. These last two arguments - are the number of options and a pointer to the option array:

    -
      -
      -int cupsPrintFile(const char *name, const char *filename, const char *title,
-                  int num_options, cups_option_t *options);
-int cupsPrintFiles(const char *name, int num_files, const char **files,
-                   const char *title, int num_options,
-		   cups_option_t *options);
-
      -
    -

    The cups_option_t structure holds each option and its - value. These are converted as needed and passed to the CUPS server when - printing a file.

    -

    The simplest way of handling options is to use the num_options - and options members of the cups_dest_t - structure described earlier:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int         jobid;
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("name", "instance", num_dests, dests);
-
-jobid  = cupsPrintFile(mydest->name, "filename", "title",
-                       mydest->num_options, mydest->options);
-
      -
    -

    This effectively uses the options a user has previous selected - without a lot of code.

    -

    Setting Printer Options

    -

    Options can also be set by your program using the -cupsAddOption() function:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-num_options = 0;
-options     = NULL;
-
-...
-
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-
      -
    -

    The name string is the name of the option, and the -value string is the value for that option.

    -

    Each call to cupsAddOption() returns the new number of - options. Since adding two options with the same name overwrites the - first value with the second, do not assume that calling -cupsAddOptions() 20 times will result in 20 options.

    -

    Call cupsFreeOptions once you are done using the - options:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-
      -
    -

    Getting Errors

    -

    If any of the CUPS API printing functions returns an error, the - reason for that error can be found by calling cupsLastError() - and cupsErrorString(). cupsLastError() - returns the last IPP error code that was encountered. -cupsErrorString() converts the error code to a localized message - string suitable for presentation to the user:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-if (jobid == 0)
-  puts(cupsErrorString(cupsLastError()));
-
      -
    -

    Passwords and Authentication

    -

    CUPS supports authentication of any request, including submission of - print jobs. The default mechanism for getting the username and password - is to use the login user and a password from the console.

    -

    To support other types of applications, in particular Graphical User - Interfaces ("GUIs"), the CUPS API provides functions to set the default - username and to register a callback function that returns a password - string.

    -

    The cupsSetPasswordCB() - function is used to set a password callback in your program. Only one - function can be used at any time.

    -

    The cupsSetUser() function - sets the current username for authentication. This function can be - called by your password callback function to change the current - username as needed.

    -

    The following example shows a simple password callback that gets a - username and password from the user:

    -
      -
      -#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
-  char	user[65];
-
-
-  puts(prompt);
-
- /* Get a username from the user */
-  printf("Username: ");
-  if (fgets(user, sizeof(user), stdin) == NULL)
-    return (NULL);
-
- /* Strip the newline from the string and set the user */
-  user[strlen(user) - 1] = '\0';
-
-  cupsSetUser(user);
-
- /* Use getpass() to ask for the password... */
-  return (getpass("Password: "));
-}
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-
      -
    -

    Similarly, a GUI interface could display the prompt string in a - window with input fields for the username and password. The username - should probably default to the value of -cupsUser() to make things easier on the user.

    -

    PPD Services

    -

    CUPS includes functions to access and manipulate PostScript Printer - Description ("PPD") files that are used with the printer drivers in - CUPS.

    -

    Each PPD file enumerates the available features provided by a - printer, including conflict information for specific options (e.g. - can't duplex output on envelopes.)

    -

    Include Files

    -

    Include the <cups/ppd.h> header file to use the PPD - functions:

    -
      -
      -#include <cups/ppd.h>
-
      -
    -

    This header file is also included by the <cups/cups.h> - header file.

    -

    Getting a PPD File for a Printer

    -

    The cupsGetPPD() function retrieves the PPD file for the - named printer or class:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-const char *filename;
-
-filename = cupsGetPPD("name");
-
      -
    -

    The name string is the name of the printer or class, - including the remote server name as appropriate (e.g. - "printer@server".)

    -

    The return value is a pointer to a filename in static storage; this - value is overwritten with each call to cupsGetPPD(). If - the printer or class does not exist, a NULL pointer will - be returned.

    -

    Loading a PPD File

    -

    The ppdOpenFile() function "opens" a PPD file and loads - it into memory:

    -
      -
      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("filename");
-
      -
    -

    The filename string is the name of the file to load, - such as the value returned by the cupsGetPPD() function.

    -

    The return value is a pointer to a structure describing the contents - of the PPD file or NULL if the PPD file could not be read.

    -

    Freeing PPD File Information

    -

    Once you are done using a PPD file, call the ppdClose() - function to free all memory that has been used:

    -
      -
      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdClose(ppd);
-
      -
    -

    The PPD File Structure

    -

    Each PPD file contains a number of capability attributes, printer - options, and conflict definitions. The page size options also include - the physical margins for the printer and the minimum and maximum sizes - for the printer. All of this information is stored in the -ppd_file_t structure.

    -

    Capabilities

    -

    Each PPD file contains a number of informational attributes that - describe the capabilities of the printer. These are provided in the -ppd_file_t structure in the following members: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    accurate_screensint1 - = supports accurate screens
    color_deviceint1 = - color device
    colorspaceppd_cs_t -Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, - PPD_CS_RGBK, PPD_CS_N
    contone_onlyint1 = - printer is continuous tone only
    num_emulations -
    emulations    		int -
    ppd_emul_t *    		Emulations supported by the printer
    flip_duplexint1 = - need to flip odd pages when duplexing
    num_fonts -
    fonts    		int -
    char **    		The fonts available on the printer.
    jcl_begin -
    jcl_ps -
    jcl_end    		char *Job Control - Language commands for PostScript output
    landscapeint -Landscape orientation, -90 or 90 degrees
    lang_encodingchar * -The character used for the option strings
    lang_versionchar * -The language used for the options strings (English, French, etc.)
    language_levelint -PostScript language level, 1 to 3
    manual_copiesint1 = - Copies are done manually
    model_numberint -Driver-specific model number.
    patcheschar *Patch - commands to send to the printer
    manufacturerchar * -The Manufacturer attribute from the PPD file, if any
    modelnamechar *The - ModelName attribute from the PPD file
    nicknamechar *The - NickName attribute from the PPD file, if any
    productchar *The - Product attribute from the PPD file, if any
    shortnicknamechar * -The ShortNickName attribute from the PPD file, if any
    throughputintNumber - of pages per minute
    ttrasterizerchar * -The TruType font rasterizer (Type42)
    variable_sizesint1 = - supports variable sizes
    -
    -

    -

    Options and Groups

    -

    PPD files support multiple options, which are stored in -ppd_option_t and ppd_choice_t structures by the PPD - functions.

    -

    Each option in turn is associated with a group stored in the -ppd_group_t structure. Groups can be specified in the PPD file; - if an option is not associated with a group then it is put in a - "General" or "Extra" group depending on the option.

    -

    Groups can also have sub-groups; CUPS currently limits the depth of - sub-groups to 1 level to reduce programming complexity.

    -

    Conflicts

    -

    PPD files support specification of conflict conditions between - different options. Conflicts are stored in ppd_conflict_t - structures which specify the options that conflict with each other.

    -

    Page Sizes

    -

    PPD files specify all of the available pages sizes and the physical - margins associated with them. These sizes are stored in -ppd_size_t structures and are available in the num_sizes - and sizes members of the ppd_file_t - structure. You can lookup a particular page size with the -ppdPageWidth(), ppdPageLength(), and -ppdPageSize() functions:

    -
      -
      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-float      width;
-float      length;
-
-...
-
-size   = ppdPageSize(ppd, "size");
-width  = ppdPageWidth(ppd, "size");
-length = ppdPageLength(ppd, "size");
-
      -
    -

    The size string is the named page size option. The width - and length are in points; there are 72 points per inch. The -ppd_size_t structure contains the width, length, and margin - information:

    -
      -
      -typedef struct    /**** Page Sizes ****/
-{
-  int   marked;   /* Page size selected? */
-  char  name[41]; /* Media size option */
-  float width,    /* Width of media in points */
-        length,   /* Length of media in points */
-        left,     /* Left printable margin in points */
-        bottom,   /* Bottom printable margin in points */
-        right,    /* Right printable margin in points */
-        top;      /* Top printable margin in points */
-} ppd_size_t;
-
      -
    -

    Custom Page Sizes

    -

    Besides the standard page sizes listed in a PPD file, some printers - support variable or custom page sizes. If variables_sizes - is non-zero, the custom_min, custom_max, and -custom_margins members of the ppd_file_t structure - define the limits of the variable sizes.

    -

    To get the resulting media size, use a page size string of -Custom.widthxlength, where width and -length are integer values in points:

    -
      -
      -Custom.612x792   [8.5 inches wide, 11 inches long]
-Custom.1224x792  [17 inches wide, 11 inches long]
-
      -
    -

    Marking Options

    -

    Before marking any user-defined options, call the -ppdMarkDefaults() function to mark the default options from the - PPD file:

    -
      -
      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdMarkDefaults(ppd);
-
      -
    -

    Then call the ppdMarkOption() function to mark - individual options:

    -
      -
      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-int        conflicts;
-
-...
-
-conflicts = ppdMarkOption(ppd, "name", "value");
-
      -
    -

    The name and value strings choose a - particular option and choice, respectively. The return value is 0 if - there are not conflicts created by the selection.

    -

    CUPS also provides a convenience function for marking all options in - the cups_option_t structure:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-ppd_file_t    *ppd;
-int           num_options;
-cups_option_t *options;
-int           conflicts;
-
-...
-
-conflicts = cupsMarkOptions(ppd, num_options, options);
-
      -
    -

    The cupsMarkOptions() function also handles mapping the - IPP job template attributes to PPD options. The return value is the - number of conflicts present.

    -

    Checking for Conflicts

    -

    The ppdMarkOption() and cupsMarkOptions() - functions return the number of conflicts with the currently marked - options.

    -

    Call the ppdConflicts() function to get the number of - conflicts after you have marked all of the options:

    -
      -
      -#include <cups/cups.h>
-
-...
-
-ppd_file_t *ppd;
-int        conflicts;
-
-...
-
-conflicts = ppdConflicts(ppd);
-
      -
    -

    The return value is the number of conflicting options, or 0 if there - are no conflicts.

    -

    3 - Writing Filters

    -

    This chapter describes how to write a file filter for CUPS.

    -

    Overview

    -

    File filters are programs that convert from one or more MIME types to - another type. Filters use a common command-line and environment - interface that allows them to be joined as needed to print files to any - type of printer.

    -

    Security Considerations

    -

    Filters are normally run as a non-priviledged user, so the major - security consideration is resource utilization - filters should not - depend on unlimited amounts of memory and disk space.

    -

    Users and Groups

    -

    The default CUPS configuration runs filters as user "lp" and group - "other".

    -

    Temporary Files

    -

    Temporary files should be created in the directory specified by the - "TMPDIR" environment variable. The -cupsTempFile() function can be used to safely choose - temporary files in this directory.

    -

    Sending Messages to the User

    -

    The CUPS scheduler collects messages sent to the standard error file - by the filter. These messages are relayed to the user based upon the - scheduler LogLevel directive.

    -

    The type of message is determined by an initial prefix sent on each - line:

    -
      -
    • DEBUG: - a debug message
      • -
    • INFO: - an informational message
      • -
    • WARNING: - a warning message
      • -
    • ERROR: - an error message
      • -
    • PAGE: - a page accounting message
      • -
    -

    If the line of text does not begin with any of the above prefixes, it - is treated as a debug message. Text following the prefix is copied to - the printer-state-message attribute for the printer, and - also added to the error_log unless it is an informational or - page accounting message.

    -

    Page Accounting

    -

    Page accounting messages are used to inform the server when one or - more pages are printed. Each line has the form:

    -
      -
      -PAGE: page-number copy-count
-
      -
    -

    The page-number field is the current page number, starting at - 1. The copy-count field specifies the number of copies of that - page that was produced.

    -

    Page account messages are added to the page_log file and - cause the job-sheets-completed attribute to be updated for - the job.

    -

    Command-Line Arguments

    -

    Every filter accepts exactly 6 or 7 command-line arguments:

    -
      -
      -printer job user title copies options [filename]
-
      -
    • printer - The name of the printer queue (normally this - is the name of the program being run)
      • -
    • job - The numeric job ID for the job being printed
      • -
    • user - The string from the originating-user-name - attribute
      • -
    • title - The string from the job-name - attribute
      • -
    • copies - The numeric value from the number-copies - attribute
      • -
    • options - String representations of the job template - attributes, separated by spaces. Boolean attributes are provided as - "name" for true values and "noname" for false values. All other - attributes are provided as "name=value" for single-valued attributes - and "name=value1,value2,...,valueN" for set attributes
      • -
    • filename - The request file
      • -
    -

    The filename argument is only provided to the first filter in - the chain; all filters must be prepared to read the print file - from the standard input if the filename argument is omitted.

    -

    Copy Generation

    -

    The copies argument specifies the number of copies to produce - of the input file. In general, you should only generate copies if the - filename argument is supplied. The only exception to this are - filters that produce device-independent PostScript output (without any - printer commands from the printer's PPD file), since the PostScript - filter pstops is responsible for copy generation.

    -

    Environment Variables

    -

    Every filter receives a fixed set of environment variables that can - be used by the filter:

    -
      -
    • CHARSET - The character set used by the client for this - print file
      • -
    • CONTENT_TYPE - The original document type, such as - "application/postscript"
      • -
    • CUPS_DATADIR - The location of CUPS data files
      • -
    • CUPS_SERVERROOT - The location of CUPS configuration - files
      • -
    • DEVICE_URI - The output device URI
      • -
    • LANG - The language used by the client for this print - file
      • -
    • PATH - The execution path exported to the filter
      • -
    • PPD - The full filename of the printer's PPD file
      • -
    • PRINTER - The name of the printer queue
      • -
    • RIP_CACHE - The maximum amount of memory each filter - should use
      • -
    • SOFTWARE - The name of the CUPS software, typically - "CUPS/1.1"
      • -
    • TZ - The local timezone
      • -
    • USER - The name of the current user
      • -
    -

    Dissecting the HP-GL/2 Filter

    -

    The HP-GL/2 filter (hpgltops) provided with CUPS is a - complex program that converts HP-GL/2 files into device-independent - PostScript output. Since it produces device-independent PostScript - output, it does not need to handle copy generation or writing printer - options from the printer's PPD file.

    -

    Initializing the Filter

    -

    The first task of any filter is to ensure that the correct number of - command-line arguments are present:

    -
      -
      -if (argc < 6 || argc > 7)
-{
-  fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
-  return (1);
-}
-
      -
    -

    After this you open the print file or read from the standard input as - needed:

    -
      -
      -FILE *fp;
-
-/*
- * If we have 7 arguments, print the file named on the command-line.
- * Otherwise, send stdin instead...
- */
-
-if (argc == 6)
-  fp = stdin;
-else
-{
- /*
-  * Try to open the print file...
-  */
-
-  if ((fp = fopen(argv[6], "rb")) == NULL)
-  {
-    perror("ERROR: unable to open print file - ");
-    return (1);
-  }
-}
-
      -
    -

    Once the print file has been opened, options can be processed using - the cupsParseOptions() and cupsGetOption() functions:

    -
      -
      -int           num_options;
-cups_option_t *options;
-const char    *val;
-
-/*
- * Process command-line options and write the prolog...
- */
-
-options     = NULL;
-num_options = cupsParseOptions(argv[5], 0, 
-
-if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
-  shading = 0;
-
-if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
-  FitPlot = 1;
-
-if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
-  PenWidth = (float)atoi(val) * 0.001f;
-
      -
    -

    After the options have been processed, the filter writes PostScript - code to the standard output based on the print file, closes the print - file (as needed), and returns 0 to the scheduler.

    -

    PostScript Output

    -

    Filters that produce PostScript output must generate output - conforming to the Adobe Document Structuring Conventions, 3.0. In - general this means the beginning of each file must begin with:

    -
      -
      -%!PS-Adobe-3.0
-%%BoundingBox: left bottom right top
-%%Pages: (atend)
-%%EndComments
-
      -
    -

    The left, bottom, right, and top values - are integers in points from the lower-lefthand corner of the page.

    -

    Pages must be surrounded by:

    -
      -
      -%%Page: number number
-gsave
-...
-grestore
-showpage
-
      -
    -

    And the end of each file must contain:

    -
      -
      -%%Trailer
-%%Pages: number-pages
-%%EOF
-
      -
    -

    These comments allow the PostScript filter to correctly perform page - accounting, copy generation, N-up printing, and so forth.

    -

    4 - Writing Printer Drivers -

    -

    This chapter discusses how to write a printer driver, which is a - special filter program that converts CUPS raster data into the - appropriate commands and data required for a printer.

    -

    Overview

    -

    Raster printers utilitize PPD files that specify one or more - device-specific filters that handle converting print files for the - printer. The simplest raster printer drivers provide a single filter - that converts CUPS raster data to the printer's native format.

    -

    CUPS Raster Data

    -

    CUPS raster data (application/vnd.cups-raster) consists - of a stream of raster page descriptions produced by one of the RIP - filters, such as pstoraster or imagetoraster.

    -

    Each page of data begins with a page dictionary structure called - cups_raster_header_t. This structure contains the - colorspace, bits per color, media size, media type, hardware - resolution, and so forth.

    -

    After the page dictionary comes the page data which is a - full-resolution, uncompressed bitmap representing the page in the - printer's output colorspace.

    -

    Page Accounting

    -

    Printer drivers must handle all page accounting. This means they must - send "PAGE:" messages to the standard error file for each page (and in - many cases, copy) sent to the printer.

    -

    Color Management

    -

    Printer drivers can implement their color management via the -cupsColorProfile attributes in the PPD file or internally in the - driver from a device-independent colorspace. In general, color - management performed by the RIP filters is more efficient than that - performed inside printer drivers.

    -

    For example, the pstoraster filter often only has to - perform a color conversion once each time the color is used for - multiple output pixels, while the raster filter must convert every - pixel on the page.

    -

    Device and Bitmap Variables

    -

    Besides the standard PostScript page device dictionary variables - defined in the Adobe PostScript Level 3 reference manual, the CUPS - filters support additional variables that are passed in the page device - dictionary header for the page and in some cases control the type of - raster data that is generated: -

    - - - - - - - - - - - - - - -
    VariableTypeDescription
    cupsWidthread-only integerWidth of bitmap in - pixels
    cupsHeightread-only integerHeight of bitmap in - pixels
    cupsMediaTyperead-write integerDevice-specific - media type code
    cupsBitsPerColorread-write integerNumber of - bits per color; 1, 2, 4, and 8 are currently supported
    cupsBitsPerPixelread-only integerNumber of - bits per pixel; 1 to 32
    cupsBytesPerLineread-only integerNumber of - bytes per line of raster graphics
    cupsColorOrderread-write enumThe order of - color values in the bitmap: -
      -
    • CUPS_ORDER_CHUNKED - CMYK CMYK CMYK
      • -
    • CUPS_ORDER_BANDED - CCC MMM YYY KKK
      • -
    • CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ...
      • -
    -
    cupsColorSpaceread-write enumThe colorspace of - the bitmap: -
      -
    • CUPS_CSPACE_W - White (luminance)
      • -
    • CUPS_CSPACE_RGB - Red, green, blue
      • -
    • CUPS_CSPACE_RGBA - Red, green, blue, alpha
      • -
    • CUPS_CSPACE_K - Black
      • -
    • CUPS_CSPACE_CMY - Cyan, magenta, yellow
      • -
    • CUPS_CSPACE_YMC - Yellow, magenta, cyan
      • -
    • CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black
      • -
    • CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black
      • -
    • CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow
      • -
    • CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, - light cyan, light magenta
      • -
    • CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic - magenta, metallic cyan, black
      • -
    • CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic - magenta, metallic cyan, metallic grey (silver)
      • -
    • CUPS_CSPACE_WHITE - White pigment (black as white - pigment)
      • -
    • CUPS_CSPACE_GOLD - Gold foil (black as gold foil)
      • -
    • CUPS_CSPACE_SILVER - Silver foil (black as silver foil)
      • -
    -
    cupsCompressionread-write integer -Device-specific compression type code
    cupsRowCountread-write integerDevice-specific - row count value
    cupsRowFeedread-write integerDevice-specific - row feed value
    cupsRowStepread-write integerDevice-specific - row step value
    -
    -

    -

    Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit - per color are transmitted to the raster driver in KCMY colorspace; the - driver is responsible for producing the correct separation of normal - and light cyan and magenta inks.

    -

    Dissecting the HP-PCL Driver

    -

    The HP-PCL driver provided with CUPS (rastertohp) - converts bitmap data from the raster filters into HP-PCL commands for - most PCL-compatible printers. The actual format of the raster data is - controlled by the PPD file being used - deskjet.ppd or - laserjet.ppd.

    -

    PPD Files

    -

    PPD files play an important part of all raster printer drivers. - Options defined in the PPD file contain PostScript commands that - control the raster data that is sent to the printer driver.

    -

    A typical CUPS printer driver will include ColorModel, -InputSlot, PageSize, PageRegion, and -Resolution options. Each option is shown using the standard PPD - format:

    -
      -
      -*OpenUI *PageSize/Media Size: PickOne
-*OrderDependency: 10 AnySetup *PageSize
-*DefaultPageSize: Letter
-*PageSize Letter/US Letter: "<<
-/PageSize [612 792]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize Legal/US Legal: "<<
-/PageSize [612 1008]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-*CloseUI: *PageSize
-
      -
    -

    The OpenUI keyword specifies the new option. The first - name is the option with an asterisk (*) in front of it. The first name - is usually followed by a slash (/) and a human-readable version of the - option name.

    -

    Every option must have a default value, specified using the -DefaultOption keyword.

    -

    Each option begins with the option name followed by the computer and - human-readable values. The PostScript commands follow these inside - double quotes. PostScript commands can be provided on a single line:

    -
      -
      -*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
-
      -
    -

    or broken down on separate lines using the End keyword - to terminate them:

    -
      -
      -*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-
      -
    -

    The choice of the two formats is usually esthetic. However, each line - in a PPD file must not exceed 255 characters, so if your PostScript - commands are long you may need to break them up on separate lines.

    -

    Reading Raster Data

    -

    As with any filter, your printer driver should handle raster data - from a filename specified on the command-line or from the standard - input. The cupsRasterOpen() - function opens a raster stream for printing:

    -
      -
      -int           fd;   /* File descriptor */
-cups_raster_t *ras; /* Raster stream for printing */
-
-
-/*
- * Check for valid arguments...
- */
-
-if (argc < 6 || argc > 7)
-{
- /*
-  * We don't have the correct number of arguments; write an error message
-  * and return.
-  */
-
-  fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
-  return (1);
-}
-
-/*
- * Open the page stream...
- */
-
-if (argc == 7)
-{
-  if ((fd = open(argv[6], O_RDONLY)) == -1)
-  {
-    perror("ERROR: Unable to open raster file - ");
-    sleep(1);
-    return (1);
-  }
-}
-else
-  fd = 0;
-
-ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
-
      -
    -

    Once you have opened the raster stream you just need to read each - page and print it:

    -
      -
      -cups_raster_header_t header;
-int                  y;
-unsigned char        data[8192];
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ... initialize the printer ...
-  for (y = header.cupsHeight; y > 0; y ++)
-  {
-    cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
-    ... send raster line to printer ...
-  }
-}
-
      -
    -

    After you have processed all pages, close the raster stream and - return:

    -
      -
      -cupsRasterClose(ras);
-
-return (0);
-
      -
    -

    5 - Writing Backends

    -

    This chapter describes how to write a backend for CUPS. Backends - communicate directly with printers and allow printer drivers and - filters to send data using any type of connection transparently.

    -

    Overview

    -

    Backends are special filters that communicate with printers directly. - They are treated slightly differently than filters, however, and have - some unique requirements.

    -

    Security Considerations

    -

    Backends are run as the root user, so special care must be taken to - avoid potential security violations. In particular, remember that a - backend will be able to manipulate disk files, devices, and other - resources that potentially could damage a system or printer.

    -

    Command-Line Arguments

    -

    Besides the standard filter arguments, backends are also run with no - arguments to get a list of available devices. This discovery process is - described later in this chapter.

    -

    Copy Generation

    -

    Like filters, backends should send multiple copies of the print file - only if a filename is supplied on the command-line. Otherwise the - backend should assume that the upstream filter has already added the - necessary commands or data to produce the multiple copies.

    -

    Page Accounting

    -

    Backend filters generally do not do page accounting, however they - should at a minimum produce a single page message for each copy that is - produced when a filename is present on the command-line. This is - because the user selected "raw" printing and no other accounting - information is possible.

    -

    Exclusive Access

    -

    Backends that talk to local character or block devices should open - the device file in exclusive mode (O_EXCL) to cooperate - with other printers defined for the same device.

    -

    Retries

    -

    All backends must retry connections to the device. This - includes backends that talk to local character or block devices, as the - user may define more than one printer queue pointing at the same - physical device.

    -

    To prevent excess CPU utilitization, the backend should go to sleep - for an amount of time between retries; the CUPS-supplied backends retry - once every 30 seconds.

    -

    Dissecting the Serial Port Backend

    -

    The serial port backend provides support for serial printers. Since - it does everything a good backend needs to do, it provides an excellent - example of what to do.

    -

    Supporting Device Discovery

    -

    As previously noted, backends are special filter programs that talk - to printer devices. Another task a backend must perform is to list the - available devices it supports. The backend lists the available devices - when no additioanl arguments are supplied on the command-line (i.e. - just the command name...)

    -

    The serial backend lists devices by looking at serial port files in - the /dev directory, by consulting a hardware inventory - (IRIX), and in some cases by trying to open the ports to see if they - actually exist.

    -

    Once it finds a serial port it writes a single line for each port to - the standard error file. Each line looks like this:

    -
      -
      -serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
-
      -
    -

    The first word "serial" is the device class; this identifies - the class of device which can be used to categorize it in user - interfaces. CUPS currently recognizes the following classes:

    -
      -
    • "file" - a disk file.
      • -
    • "direct" - a parallel or fixed-rate serial data port, currently used - for Centronics, IEEE-1284, and USB printer ports.
      • -
    • "serial" - a variable-rate serial port.
      • -
    • "network" - a network connection, typically via AppSocket, HTTP, - IPP, LPD, or SMB/CIFS protocols.
      • -
    -

    After the device class is the device URI, in this case - "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by - the user to select this port. For serial ports, the "baud=115200" - specifies the maximum baud rate supported by the port - the actual - value will vary based on the speed the user selects for the printer.

    -

    The last two strings are the model and description for the port. The - "Unknown" string means that the printer model is unknown - some devices - are able to provide a make and model such as "HP DeskJet" that allows - users and software to choose an appropriate printer driver more easily. - Both the model and description must be enclosed inside double quotes.

    -

    Opening the Serial Port

    -

    As noted previously, all backends should open device files in - exclusive mode, and retry as needed until the port is available. The - serial port does this using a do-while loop:

    -
      -
      -do
-{
-  if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
-  {
-    if (errno == EBUSY)
-    {
-      fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
-      sleep(30);
-    }
-    else
-    {
-      perror("ERROR: Unable to open serial port device file");
-      return (1);
-    }
-  }
-}
-while (fd < 0);
-
      -
    -

    If the port is busy or in use by another process, the backend will go - to sleep for 30 seconds and try again. If another error is detected a - message is sent to the user and the backend aborts the print job until - the problem can be corrected.

    -

    Writing Data to the Port

    -

    Network and character devices pose an interesting problem when - writing data to the port - they may not be able to write all of the - bytes in your buffer before returning. To work around this problem you - must loop until all bytes have been written:

    -
      -
      -while (nbytes > 0)
-{
-  if ((wbytes = write(fd, bufptr, nbytes)) < 0)
-    if (errno == ENOTTY)
-      wbytes = write(fd, bufptr, nbytes);
-
-  if (wbytes < 0)
-  {
-    perror("ERROR: Unable to send print file to printer");
-    break;
-  }
-
-  nbytes -= wbytes;
-  bufptr += wbytes;
-}
-
      -
    -

    The check for the ENOTTY error is needed on some - platforms to clear an error from a previous ioctl() call.

    -

    Finishing Up

    -

    Once you have sent the print file, return 0 if the file printed - successfully or 1 if it did not. This will allow the scheduler to stop - the print job if there is a device error, preserving the print job for - later printing once the problem has been corrected.

    -

    A - Software License Agreement

    -

    Common UNIX Printing System License - Agreement

    -

    Copyright 1997-2003 by Easy Software Products -
    44141 AIRPORT VIEW DR STE 204 -
    HOLLYWOOD, MARYLAND 20636-3111 USA -
    -
    Voice: +1.301.373.9600 -
    Email: cups-info@cups.org -
    WWW: http://www.cups.org

    -

    Introduction

    -

    The Common UNIX Printing SystemTM, ("CUPSTM"), - is provided under the GNU General Public License ("GPL") and GNU - Library General Public License ("LGPL"), Version 2, with exceptions for - Apple operating systems and the OpenSSL toolkit. A copy of the - exceptions and licenses follow this introduction.

    -

    The GNU LGPL applies to the CUPS API library, located in the "cups" - subdirectory of the CUPS source distribution and in the "cups" include - directory and library files in the binary distributions. The GNU GPL - applies to the remainder of the CUPS distribution, including the - "pdftops" filter which is based upon Xpdf and the CUPS imaging library.

    -

    For those not familiar with the GNU GPL, the license basically allows - you to:

    -
      -
    • Use the CUPS software at no charge.
      • -
    • Distribute verbatim copies of the software in source or binary form.
      • -
    • Sell verbatim copies of the software for a media fee, or sell - support for the software.
      • -
    • Distribute or sell printer drivers and filters that use CUPS so long - as source code is made available under the GPL.
      • -
    -

    What this license does not allow you to do is make changes or - add features to CUPS and then sell a binary distribution without source - code. You must provide source for any new drivers, changes, or - additions to the software, and all code must be provided under the GPL - or LGPL as appropriate. The only exceptions to this are the portions of - the CUPS software covered by the Apple operating system license - exceptions outlined later in this license agreement.

    -

    The GNU LGPL relaxes the "link-to" restriction, allowing you to - develop applications that use the CUPS API library under other licenses - and/or conditions as appropriate for your application.

    -

    License Exceptions

    -

    In addition, as the copyright holder of CUPS, Easy Software Products - grants the following special exceptions:

    -
      -
    1. Apple Operating System Development License Exception; -
        -
      1. Software that is developed by any person or entity for an Apple - Operating System ("Apple OS-Developed Software"), including but not - limited to Apple and third party printer drivers, filters, and backends - for an Apple Operating System, that is linked to the CUPS imaging - library or based on any sample filters or backends provided with CUPS - shall not be considered to be a derivative work or collective work - based on the CUPS program and is exempt from the mandatory source code - release clauses of the GNU GPL. You may therefore distribute linked - combinations of the CUPS imaging library with Apple OS-Developed - Software without releasing the source code of the Apple OS-Developed - Software. You may also use sample filters and backends provided with - CUPS to develop Apple OS-Developed Software without releasing the - source code of the Apple OS-Developed Software.
        2. -
      2. An Apple Operating System means any operating system software - developed and/or marketed by Apple Computer, Inc., including but not - limited to all existing releases and versions of Apple's Darwin, Mac OS - X, and Mac OS X Server products and all follow-on releases and future - versions thereof.
        3. -
      3. This exception is only available for Apple OS-Developed Software and - does not apply to software that is distributed for use on other - operating systems.
        4. -
      4. All CUPS software that falls under this license exception have the - following text at the top of each source file:
        This file is - subject to the Apple OS-Developed Software exception.
        5. -
      -
      2. -
    2. OpenSSL Toolkit License Exception; -
        -
      1. Easy Software Products explicitly allows the compilation and - distribution of the CUPS software with the OpenSSL Toolkit.
        2. -
      -
      3. -
    -

    No developer is required to provide these exceptions in a derived - work.

    -

    Trademarks

    -

    Easy Software Products has trademarked the Common UNIX Printing - System, CUPS, and CUPS logo. These names and logos may be used freely - in any direct port or binary distribution of CUPS. Please contract Easy - Software Products for written permission to use them in derivative - products. Our intention is to protect the value of these trademarks and - ensure that any derivative product meets the same high-quality - standards as the original.

    -

    Binary Distribution Rights

    -

    Easy Software Products also sells rights to the CUPS source code - under a binary distribution license for vendors that are unable to - release source code for their drivers, additions, and modifications to - CUPS under the GNU GPL and LGPL. For information please contact us at - the address shown above.

    -

    The Common UNIX Printing System provides a "pdftops" filter that is - based on the Xpdf software. For binary distribution licensing of this - software, please contact:

    Derek B. Noonburg -
    Email: derekn@foolabs.com -
    WWW: - http://www.foolabs.com/xpdf/

    -

    Support

    -

    Easy Software Products sells software support for CUPS as well as a - commercial printing product based on CUPS called ESP Print Pro. You can - find out more at our web site:

    - - - -

    GNU GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright 1989, 1991 Free Software Foundation, Inc.
-59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-Everyone is permitted to copy and distribute verbatim
-copies of this license document, but changing it is not allowed.
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public License is - intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users. This - General Public License applies to most of the Free Software - Foundation's software and to any other program whose authors commit to - using it. (Some other Free Software Foundation software is covered by - the GNU Library General Public License instead.) You can apply it to - your programs, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the software, or if you modify it.

    -

    For example, if you distribute copies of such a program, whether - gratis or for a fee, you must give the recipients all the rights that - you have. You must make sure that they, too, receive or can get the - source code. And you must show them these terms so they know their - rights.

    -

    We protect your rights with two steps: (1) copyright the software, - and (2) offer you this license which gives you legal permission to - copy, distribute and/or modify the software.

    -

    Also, for each author's protection and ours, we want to make certain - that everyone understands that there is no warranty for this free - software. If the software is modified by someone else and passed on, we - want its recipients to know that what they have is not the original, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that redistributors of a free - program will individually obtain patent licenses, in effect making the - program proprietary. To prevent this, we have made it clear that any - patent must be licensed for everyone's free use or not licensed at all.

    -

    The precise terms and conditions for copying, distribution and - modification follow.

    -

    GNU GENERAL PUBLIC LICENSE -
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -
      -
    1. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", below, - refers to any such program or work, and a "work based on the Program" - means either the Program or any derivative work under copyright law: - that is to say, a work containing the Program or a portion of it, - either verbatim or with modifications and/or translated into another - language. (Hereinafter, translation is included without limitation in - the term "modification".) Each licensee is addressed as "you". -

      Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - the Program is not restricted, and the output from the Program is - covered only if its contents constitute a work based on the Program - (independent of having been made by running the Program). Whether that - is true depends on what the Program does.

      -
    2. You may copy and distribute verbatim copies of the Program's source - code as you receive it, in any medium, provided that you conspicuously - and appropriately publish on each copy an appropriate copyright notice - and disclaimer of warranty; keep intact all the notices that refer to - this License and to the absence of any warranty; and give any other - recipients of the Program a copy of this License along with the - Program. -

      You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

      -
    3. You may modify your copy or copies of the Program or any portion of - it, thus forming a work based on the Program, and copy and distribute - such modifications or work under the terms of Section 1 above, provided - that you also meet all of these conditions: -
        -
      1. You must cause the modified files to carry prominent notices stating - that you changed the files and the date of any change.
        2. -
      2. You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any part - thereof, to be licensed as a whole at no charge to all third parties - under the terms of this License.
        3. -
      3. if the modified program normally reads commands interactively when - run, you must cause it, when started running for such interactive use - in the most ordinary way, to print or display an announcement including - an appropriate copyright notice and a notice that there is no warranty - (or else, saying that you provide a warranty) and that users may - redistribute the program under these conditions, and telling the user - how to view a copy of this License. (Exception: if the Program itself - is interactive but does not normally print such an announcement, your - work based on the Program is not required to print an announcement.)
        4. -
      -

      These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Program, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Program, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

      -

      Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Program.

      -

      In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

      -
    4. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms of - Sections 1 and 2 above provided that you also do one of the following: -
        -
      1. Accompany it with the complete corresponding machine-readable source - code, which must be distributed under the terms of Sections 1 and 2 - above on a medium customarily used for software interchange; or,
        2. -
      2. Accompany it with a written offer, valid for at least three years, - to give any third party, for a charge no more than your cost of - physically performing source distribution, a complete machine-readable - copy of the corresponding source code, to be distributed under the - terms of Sections 1 and 2 above on a medium customarily used for - software interchange; or,
        3. -
      3. Accompany it with the information you received as to the offer to - distribute corresponding source code. (This alternative is allowed only - for noncommercial distribution and only if you received the program in - object code or executable form with such an offer, in accord with - Subsection b above.)
        4. -
      -

      The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete source - code means all the source code for all modules it contains, plus any - associated interface definition files, plus the scripts used to control - compilation and installation of the executable. However, as a special - exception, the source code distributed need not include anything that - is normally distributed (in either source or binary form) with the - major components (compiler, kernel, and so on) of the operating system - on which the executable runs, unless that component itself accompanies - the executable.

      -

      If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent access - to copy the source code from the same place counts as distribution of - the source code, even though third parties are not compelled to copy - the source along with the object code.

      -
    5. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt otherwise - to copy, modify, sublicense or distribute the Program is void, and will - automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such parties - remain in full compliance.
      6. -
    6. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify or - distribute the Program or its derivative works. These actions are - prohibited by law if you do not accept this License. Therefore, by - modifying or distributing the Program (or any work based on the - Program), you indicate your acceptance of this License to do so, and - all its terms and conditions for copying, distributing or modifying the - Program or works based on it.
      7. -
    7. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program subject to - these terms and conditions. You may not impose any further restrictions - on the recipients' exercise of the rights granted herein. You are not - responsible for enforcing compliance by third parties to this License.
      8. -
    8. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent issues), - conditions are imposed on you (whether by court order, agreement or - otherwise) that contradict the conditions of this License, they do not - excuse you from the conditions of this License. If you cannot - distribute so as to satisfy simultaneously your obligations under this - License and any other pertinent obligations, then as a consequence you - may not distribute the Program at all. For example, if a patent license - would not permit royalty-free redistribution of the Program by all - those who receive copies directly or indirectly through you, then the - only way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. -

      If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply and the section as a whole is intended to apply in other - circumstances.

      -

      It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system, which is - implemented by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

      -

      This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

      -
    9. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, the - original copyright holder who places the Program under this License may - add an explicit geographical distribution limitation excluding those - countries, so that distribution is permitted only in or among countries - not thus excluded. In such case, this License incorporates the - limitation as if written in the body of this License.
      10. -
    10. The Free Software Foundation may publish revised and/or new versions - of the General Public License from time to time. Such new versions will - be similar in spirit to the present version, but may differ in detail - to address new problems or concerns. -

      Each version is given a distinguishing version number. If the Program - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Program does not specify a version - number of this License, you may choose any version ever published by - the Free Software Foundation.

      -
    11. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted by the - Free Software Foundation, write to the Free Software Foundation; we - sometimes make exceptions for this. Our decision will be guided by the - two goals of preserving the free status of all derivatives of our free - software and of promoting the sharing and reuse of software generally.
      12. - - - - - - -
    -

    NO WARRANTY

    -
      -
    1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY - FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN - OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES - PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER - EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE - ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH - YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL - NECESSARY SERVICING, REPAIR OR CORRECTION.
      2. -
    2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY - AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.
      3. -
    -

    END OF TERMS AND CONDITIONS

    - - -

    GNU LIBRARY GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright (C) 1991 Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-
-[This is the first released version of the library GPL.  It is
- numbered 2 because it goes with version 2 of the ordinary GPL.]
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public Licenses - are intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users.

    -

    This license, the Library General Public License, applies to some - specially designated Free Software Foundation software, and to any - other libraries whose authors decide to use it. You can use it for your - libraries, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the library, or if you modify it.

    -

    For example, if you distribute copies of the library, whether gratis - or for a fee, you must give the recipients all the rights that we gave - you. You must make sure that they, too, receive or can get the source - code. If you link a program with the library, you must provide complete - object files to the recipients so that they can relink them with the - library, after making changes to the library and recompiling it. And - you must show them these terms so they know their rights.

    -

    Our method of protecting your rights has two steps: (1) copyright the - library, and (2) offer you this license which gives you legal - permission to copy, distribute and/or modify the library.

    -

    Also, for each distributor's protection, we want to make certain that - everyone understands that there is no warranty for this free library. - If the library is modified by someone else and passed on, we want its - recipients to know that what they have is not the original version, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that companies distributing free - software will individually obtain patent licenses, thus in effect - transforming the program into proprietary software. To prevent this, we - have made it clear that any patent must be licensed for everyone's free - use or not licensed at all.

    -

    Most GNU software, including some libraries, is covered by the - ordinary GNU General Public License, which was designed for utility - programs. This license, the GNU Library General Public License, applies - to certain designated libraries. This license is quite different from - the ordinary one; be sure to read it in full, and don't assume that - anything in it is the same as in the ordinary license.

    -

    The reason we have a separate public license for some libraries is - that they blur the distinction we usually make between modifying or - adding to a program and simply using it. Linking a program with a - library, without changing the library, is in some sense simply using - the library, and is analogous to running a utility program or - application program. However, in a textual and legal sense, the linked - executable is a combined work, a derivative of the original library, - and the ordinary General Public License treats it as such.

    -

    Because of this blurred distinction, using the ordinary General - Public License for libraries did not effectively promote software - sharing, because most developers did not use the libraries. We - concluded that weaker conditions might promote sharing better.

    -

    However, unrestricted linking of non-free programs would deprive the - users of those programs of all benefit from the free status of the - libraries themselves. This Library General Public License is intended - to permit developers of non-free programs to use free libraries, while - preserving your freedom as a user of such programs to change the free - libraries that are incorporated in them. (We have not seen how to - achieve this as regards changes in header files, but we have achieved - it as regards changes in the actual functions of the Library.) The hope - is that this will lead to faster development of free libraries.

    -

    The precise terms and conditions for copying, distribution and - modification follow. Pay close attention to the difference between a - "work based on the library" and a "work that uses the library". The - former contains code derived from the library, while the latter only - works together with the library.

    -

    Note that it is possible for a library to be covered by the ordinary - General Public License rather than by this special one.

    -

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -

    0. This License Agreement applies to any software - library which contains a notice placed by the copyright holder or other - authorized party saying it may be distributed under the terms of this - Library General Public License (also called "this License"). Each - licensee is addressed as "you".

    -

    A "library" means a collection of software functions and/or data - prepared so as to be conveniently linked with application programs - (which use some of those functions and data) to form executables.

    -

    The "Library", below, refers to any such software library or work - which has been distributed under these terms. A "work based on the - Library" means either the Library or any derivative work under - copyright law: that is to say, a work containing the Library or a - portion of it, either verbatim or with modifications and/or translated - straightforwardly into another language. (Hereinafter, translation is - included without limitation in the term "modification".)

    -

    "Source code" for a work means the preferred form of the work for - making modifications to it. For a library, complete source code means - all the source code for all modules it contains, plus any associated - interface definition files, plus the scripts used to control - compilation and installation of the library.

    -

    Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - a program using the Library is not restricted, and output from such a - program is covered only if its contents constitute a work based on the - Library (independent of the use of the Library in a tool for writing - it). Whether that is true depends on what the Library does and what the - program that uses the Library does.

    -

    1. You may copy and distribute verbatim copies of - the Library's complete source code as you receive it, in any medium, - provided that you conspicuously and appropriately publish on each copy - an appropriate copyright notice and disclaimer of warranty; keep intact - all the notices that refer to this License and to the absence of any - warranty; and distribute a copy of this License along with the Library.

    -

    You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

    -

    2. You may modify your copy or copies of the Library - or any portion of it, thus forming a work based on the Library, and - copy and distribute such modifications or work under the terms of - Section 1 above, provided that you also meet all of these conditions:

    -
      -
    1. The modified work must itself be a software library. -

      -
    2. You must cause the files modified to carry prominent notices stating - that you changed the files and the date of any change. -

      -
    3. You must cause the whole of the work to be licensed at no charge to - all third parties under the terms of this License. -

      -
    4. If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses the - facility, other than as an argument passed when the facility is - invoked, then you must make a good faith effort to ensure that, in the - event an application does not supply such function or table, the - facility still operates, and performs whatever part of its purpose - remains meaningful. -

      (For example, a function in a library to compute square roots has a - purpose that is entirely well-defined independent of the application. - Therefore, Subsection 2d requires that any application-supplied - function or table used by this function must be optional: if the - application does not supply it, the square root function must still - compute square roots.)

      -
      5. - - - -
    -

    These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Library, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Library, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

    -

    Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Library.

    -

    In addition, mere aggregation of another work not based on the - Library with the Library (or with a work based on the Library) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

    -

    3. You may opt to apply the terms of the ordinary - GNU General Public License instead of this License to a given copy of - the Library. To do this, you must alter all the notices that refer to - this License, so that they refer to the ordinary GNU General Public - License, version 2, instead of to this License. (If a newer version - than version 2 of the ordinary GNU General Public License has appeared, - then you can specify that version instead if you wish.) Do not make any - other change in these notices.

    -

    Once this change is made in a given copy, it is irreversible for that - copy, so the ordinary GNU General Public License applies to all - subsequent copies and derivative works made from that copy.

    -

    This option is useful when you wish to copy part of the code of the - Library into a program that is not a library.

    -

    4. You may copy and distribute the Library (or a - portion or derivative of it, under Section 2) in object code or - executable form under the terms of Sections 1 and 2 above provided that - you accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections 1 - and 2 above on a medium customarily used for software interchange.

    -

    If distribution of object code is made by offering access to copy - from a designated place, then offering equivalent access to copy the - source code from the same place satisfies the requirement to distribute - the source code, even though third parties are not compelled to copy - the source along with the object code.

    -

    5. A program that contains no derivative of any - portion of the Library, but is designed to work with the Library by - being compiled or linked with it, is called a "work that uses the - Library". Such a work, in isolation, is not a derivative work of the - Library, and therefore falls outside the scope of this License.

    -

    However, linking a "work that uses the Library" with the Library - creates an executable that is a derivative of the Library (because it - contains portions of the Library), rather than a "work that uses the - library". The executable is therefore covered by this License. Section - 6 states terms for distribution of such executables.

    -

    When a "work that uses the Library" uses material from a header file - that is part of the Library, the object code for the work may be a - derivative work of the Library even though the source code is not. - Whether this is true is especially significant if the work can be - linked without the Library, or if the work is itself a library. The - threshold for this to be true is not precisely defined by law.

    -

    If such an object file uses only numerical parameters, data structure - layouts and accessors, and small macros and small inline functions (ten - lines or less in length), then the use of the object file is - unrestricted, regardless of whether it is legally a derivative work. - (Executables containing this object code plus portions of the Library - will still fall under Section 6.)

    -

    Otherwise, if the work is a derivative of the Library, you may - distribute the object code for the work under the terms of Section 6. - Any executables containing that work also fall under Section 6, whether - or not they are linked directly with the Library itself.

    -

    6. As an exception to the Sections above, you may - also compile or link a "work that uses the Library" with the Library to - produce a work containing portions of the Library, and distribute that - work under terms of your choice, provided that the terms permit - modification of the work for the customer's own use and reverse - engineering for debugging such modifications.

    -

    You must give prominent notice with each copy of the work that the - Library is used in it and that the Library and its use are covered by - this License. You must supply a copy of this License. If the work - during execution displays copyright notices, you must include the - copyright notice for the Library among them, as well as a reference - directing the user to the copy of this License. Also, you must do one - of these things:

    -
      -
    1. Accompany the work with the complete corresponding machine-readable - source code for the Library including whatever changes were used in the - work (which must be distributed under Sections 1 and 2 above); and, if - the work is an executable linked with the Library, with the complete - machine-readable "work that uses the Library", as object code and/or - source code, so that the user can modify the Library and then relink to - produce a modified executable containing the modified Library. (It is - understood that the user who changes the contents of definitions files - in the Library will not necessarily be able to recompile the - application to use the modified definitions.) -

      -
    2. Accompany the work with a written offer, valid for at least three - years, to give the same user the materials specified in Subsection 6a, - above, for a charge no more than the cost of performing this - distribution. -

      -
    3. If distribution of the work is made by offering access to copy from - a designated place, offer equivalent access to copy the above specified - materials from the same place. -

      -
    4. Verify that the user has already received a copy of these materials - or that you have already sent this user a copy.
      5. - - - -
    -

    For an executable, the required form of the "work that uses the - Library" must include any data and utility programs needed for - reproducing the executable from it. However, as a special exception, - the source code distributed need not include anything that is normally - distributed (in either source or binary form) with the major components - (compiler, kernel, and so on) of the operating system on which the - executable runs, unless that component itself accompanies the - executable.

    -

    It may happen that this requirement contradicts the license - restrictions of other proprietary libraries that do not normally - accompany the operating system. Such a contradiction means you cannot - use both them and the Library together in an executable that you - distribute.

    -

    7. You may place library facilities that are a work - based on the Library side-by-side in a single library together with - other library facilities not covered by this License, and distribute - such a combined library, provided that the separate distribution of the - work based on the Library and of the other library facilities is - otherwise permitted, and provided that you do these two things:

    -
      -
    1. Accompany the combined library with a copy of the same work based on - the Library, uncombined with any other library facilities. This must be - distributed under the terms of the Sections above. -

      -
    2. Give prominent notice with the combined library of the fact that - part of it is a work based on the Library, and explaining where to find - the accompanying uncombined form of the same work.
      3. - -
    -

    8. You may not copy, modify, sublicense, link with, - or distribute the Library except as expressly provided under this - License. Any attempt otherwise to copy, modify, sublicense, link with, - or distribute the Library is void, and will automatically terminate - your rights under this License. However, parties who have received - copies, or rights, from you under this License will not have their - licenses terminated so long as such parties remain in full compliance.

    -

    9. You are not required to accept this License, - since you have not signed it. However, nothing else grants you - permission to modify or distribute the Library or its derivative works. - These actions are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Library (or any work based - on the Library), you indicate your acceptance of this License to do so, - and all its terms and conditions for copying, distributing or modifying - the Library or works based on it.

    -

    10. Each time you redistribute the Library (or any - work based on the Library), the recipient automatically receives a - license from the original licensor to copy, distribute, link with or - modify the Library subject to these terms and conditions. You may not - impose any further restrictions on the recipients' exercise of the - rights granted herein. You are not responsible for enforcing compliance - by third parties to this License.

    -

    11. If, as a consequence of a court judgment or - allegation of patent infringement or for any other reason (not limited - to patent issues), conditions are imposed on you (whether by court - order, agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this License. If - you cannot distribute so as to satisfy simultaneously your obligations - under this License and any other pertinent obligations, then as a - consequence you may not distribute the Library at all. For example, if - a patent license would not permit royalty-free redistribution of the - Library by all those who receive copies directly or indirectly through - you, then the only way you could satisfy both it and this License would - be to refrain entirely from distribution of the Library.

    -

    If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply, and the section as a whole is intended to apply in other - circumstances.

    -

    It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system which is implemented - by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

    -

    This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

    -

    12. If the distribution and/or use of the Library is - restricted in certain countries either by patents or by copyrighted - interfaces, the original copyright holder who places the Library under - this License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only in or - among countries not thus excluded. In such case, this License - incorporates the limitation as if written in the body of this License.

    -

    13. The Free Software Foundation may publish revised - and/or new versions of the Library General Public License from time to - time. Such new versions will be similar in spirit to the present - version, but may differ in detail to address new problems or concerns.

    -

    Each version is given a distinguishing version number. If the Library - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Library does not specify a license - version number, you may choose any version ever published by the Free - Software Foundation.

    -

    14. If you wish to incorporate parts of the Library - into other free programs whose distribution conditions are incompatible - with these, write to the author to ask for permission. For software - which is copyrighted by the Free Software Foundation, write to the Free - Software Foundation; we sometimes make exceptions for this. Our - decision will be guided by the two goals of preserving the free status - of all derivatives of our free software and of promoting the sharing - and reuse of software generally.

    -

    NO WARRANTY

    -

    15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, - THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY - APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE - OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU - ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

    -

    16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR - AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO - MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL - OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.

    -

    END OF TERMS AND CONDITIONS

    -

    B - Constants

    -

    This appendix lists all of the constants that are defined by the CUPS - API.

    -

    CUPS Constants

    -

    Version Number

    -

    The CUPS_VERSION constant is a floating-point number - representing the API version number. The current version number is - 1.0100 which represents CUPS version 1.1.0.

    -

    Printer Capabilities

    -

    The CUPS_PRINTER constants represent capability bits for - printers and classes:

    -
      -
    • CUPS_PRINTER_LOCAL - Is a local printer or class.
      • -
    • CUPS_PRINTER_REMOTE - Is a remote printer or class.
      • -
    • CUPS_PRINTER_CLASS - Is a class.
      • -
    • CUPS_PRINTER_BW - Printer prints in black and white.
      • -
    • CUPS_PRINTER_COLOR - Printer prints in color.
      • -
    • CUPS_PRINTER_DUPLEX - Printer can print double-sided.
      • -
    • CUPS_PRINTER_STAPLE - Printer can staple output.
      • -
    • CUPS_PRINTER_COPIES - Printer can produce multiple - copies on its own.
      • -
    • CUPS_PRINTER_COLLATE - Printer can collate copies.
      • -
    • CUPS_PRINTER_PUNCH - Printer can punch holes in output.
      • -
    • CUPS_PRINTER_COVER - Printer can put covers on output.
      • -
    • CUPS_PRINTER_BIND - Printer can bind output.
      • -
    • CUPS_PRINTER_SORT - Printer can sort output.
      • -
    • CUPS_PRINTER_SMALL - Printer can print on media up to - 9x14 inches.
      • -
    • CUPS_PRINTER_MEDIUM - Printer can print on media from - 9x14 to 18x24 inches.
      • -
    • CUPS_PRINTER_LARGE - Printer can print on media larger - than 18x24 inches.
      • -
    • CUPS_PRINTER_VARIABLE - Printer can print on variable - or custom media sizes.
      • -
    • CUPS_PRINTER_IMPLICIT - Is an implicit class.
      • -
    • CUPS_PRINTER_OPTIONS - All of the printer capability - and option bits.
      • -
    -

    Encodings

    -

    CUPS defines the following character set encoding constants:

    -
      -
    • CUPS_US_ASCII - US ASCII character set.
      • -
    • CUPS_UTF_8 - UTF-8 encoding of Unicode.
      • -
    • CUPS_ISO8859_1 - ISO-8859-1 character set.
      • -
    • CUPS_ISO8859_2 - ISO-8859-2 character set.
      • -
    • CUPS_ISO8859_3 - ISO-8859-3 character set.
      • -
    • CUPS_ISO8859_4 - ISO-8859-4 character set.
      • -
    • CUPS_ISO8859_5 - ISO-8859-5 character set.
      • -
    • CUPS_ISO8859_6 - ISO-8859-6 character set.
      • -
    • CUPS_ISO8859_7 - ISO-8859-7 character set.
      • -
    • CUPS_ISO8859_8 - ISO-8859-8 character set.
      • -
    • CUPS_ISO8859_9 - ISO-8859-9 character set.
      • -
    • CUPS_ISO8859_10 - ISO-8859-10 character set.
      • -
    • CUPS_ISO8859_13 - ISO-8859-13 character set.
      • -
    • CUPS_ISO8859_14 - ISO-8859-14 character set.
      • -
    • CUPS_ISO8859_15 - ISO-8859-15 character set.
      • -
    • CUPS_WINDOWS_874 - Windows code page 874.
      • -
    • CUPS_WINDOWS_1250 - Windows code page 1250.
      • -
    • CUPS_WINDOWS_1251 - Windows code page 1251.
      • -
    • CUPS_WINDOWS_1252 - Windows code page 1252.
      • -
    • CUPS_WINDOWS_1253 - Windows code page 1253.
      • -
    • CUPS_WINDOWS_1254 - Windows code page 1254.
      • -
    • CUPS_WINDOWS_1255 - Windows code page 1255.
      • -
    • CUPS_WINDOWS_1256 - Windows code page 1256.
      • -
    • CUPS_WINDOWS_1257 - Windows code page 1257.
      • -
    • CUPS_WINDOWS_1258 - Windows code page 1258.
      • -
    • CUPS_KOI8_R - Russian code page koi8-r.
      • -
    • CUPS_KOI8_U - Ukrainian code page koi8-r.
      • -
    -

    HTTP Constants

    -

    Limits

    -

    The following constants define the limits for strings:

    -
      -
    • HTTP_MAX_BUFFER - Size of socket buffer.
      • -
    • HTTP_MAX_HOST - Maximum length of hostname.
      • -
    • HTTP_MAX_URI - Maximum length of URI.
      • -
    • HTTP_MAX_VALUE - Maximum length of field values.
      • -
    -

    Status Codes

    -

    The following status codes can be returned by httpUpdate() -:

    -
      -
    • HTTP_ERROR - A network error occurred
      • -
    • HTTP_CONTINUE - Continue response from HTTP proxy
      • -
    • HTTP_OK - OPTIONS/GET/HEAD/POST/TRACE command was - successful
      • -
    • HTTP_CREATED - PUT command was successful
      • -
    • HTTP_ACCEPTED - DELETE command was successful
      • -
    • HTTP_NOT_AUTHORITATIVE - Information isn't - authoritative
      • -
    • HTTP_NO_CONTENT - Successful command
      • -
    • HTTP_RESET_CONTENT - Content was reset/recreated
      • -
    • HTTP_PARTIAL_CONTENT - Only a partial file was - recieved/sent
      • -
    • HTTP_MULTIPLE_CHOICES - Multiple files match request
      • -
    • HTTP_MOVED_PERMANENTLY - Document has moved permanently
      • -
    • HTTP_MOVED_TEMPORARILY - Document has moved temporarily
      • -
    • HTTP_SEE_OTHER - See this other link...
      • -
    • HTTP_NOT_MODIFIED - File not modified
      • -
    • HTTP_USE_PROXY - Must use a proxy to access this URI
      • -
    • HTTP_BAD_REQUEST - Bad request
      • -
    • HTTP_UNAUTHORIZED - Unauthorized to access host
      • -
    • HTTP_PAYMENT_REQUIRED - Payment required
      • -
    • HTTP_FORBIDDEN - Forbidden to access this URI
      • -
    • HTTP_NOT_FOUND - URI was not found
      • -
    • HTTP_METHOD_NOT_ALLOWED - Method is not allowed
      • -
    • HTTP_NOT_ACCEPTABLE - Not Acceptable
      • -
    • HTTP_PROXY_AUTHENTICATION - Proxy Authentication is - Required
      • -
    • HTTP_REQUEST_TIMEOUT - Request timed out
      • -
    • HTTP_CONFLICT - Request is self-conflicting
      • -
    • HTTP_GONE - Server has gone away
      • -
    • HTTP_LENGTH_REQUIRED - A content length or encoding is - required
      • -
    • HTTP_PRECONDITION - Precondition failed
      • -
    • HTTP_REQUEST_TOO_LARGE - Request entity too large
      • -
    • HTTP_URI_TOO_LONG - URI too long
      • -
    • HTTP_UNSUPPORTED_MEDIATYPE - The requested media type - is unsupported
      • -
    • HTTP_SERVER_ERROR - Internal server error
      • -
    • HTTP_NOT_IMPLEMENTED - Feature not implemented
      • -
    • HTTP_BAD_GATEWAY - Bad gateway
      • -
    • HTTP_SERVICE_UNAVAILABLE - Service is unavailable
      • -
    • HTTP_GATEWAY_TIMEOUT - Gateway connection timed out
      • -
    • HTTP_NOT_SUPPORTED - HTTP version not supported
      • -
    -

    Fields

    -

    The following fields are indices for each of the standard HTTP fields - in HTTP 1/1:

    -
      -
    • HTTP_FIELD_ACCEPT_LANGUAGE - Accept-Language
      • -
    • HTTP_FIELD_ACCEPT_RANGES - Accept-Ranges
      • -
    • HTTP_FIELD_AUTHORIZATION - Authorization
      • -
    • HTTP_FIELD_CONNECTION - Connection
      • -
    • HTTP_FIELD_CONTENT_ENCODING - Content-Encoding
      • -
    • HTTP_FIELD_CONTENT_LANGUAGE - Content-Language
      • -
    • HTTP_FIELD_CONTENT_LENGTH - Content-Length
      • -
    • HTTP_FIELD_CONTENT_LOCATION - Content-Location
      • -
    • HTTP_FIELD_CONTENT_MD5 - Content-MD5
      • -
    • HTTP_FIELD_CONTENT_RANGE - Content-Range
      • -
    • HTTP_FIELD_CONTENT_TYPE - Content-Type
      • -
    • HTTP_FIELD_CONTENT_VERSION - Content-Version
      • -
    • HTTP_FIELD_DATE - Date
      • -
    • HTTP_FIELD_HOST - Host
      • -
    • HTTP_FIELD_IF_MODIFIED_SINCE - If-Modified-Since
      • -
    • HTTP_FIELD_IF_UNMODIFIED_SINCE - If-Unmodified-Since
      • -
    • HTTP_FIELD_KEEP_ALIVE - Keep-Alive
      • -
    • HTTP_FIELD_LAST_MODIFIED - Last-Modified
      • -
    • HTTP_FIELD_LINK - Link
      • -
    • HTTP_FIELD_LOCATION - Location
      • -
    • HTTP_FIELD_RANGE - Range
      • -
    • HTTP_FIELD_REFERER - Referer
      • -
    • HTTP_FIELD_RETRY_AFTER - Retry-After
      • -
    • HTTP_FIELD_TRANSFER_ENCODING - Transfer-Encoding
      • -
    • HTTP_FIELD_UPGRADE - Upgrade
      • -
    • HTTP_FIELD_USER_AGENT - User-Agent
      • -
    • HTTP_FIELD_WWW_AUTHENTICATE - WWW-Authenticate
      • -
    -

    IPP Constants

    -

    Limits

    -

    The following constants define array limits for IPP data:

    -
      -
    • IPP_MAX_NAME - Maximum length of an attribute name
      • -
    • IPP_MAX_VALUES - Maximum number of set-of values that - can be read in a request.
      • -
    -

    Tags

    -
      -
    • IPP_TAG_ZERO - Wildcard tag value for searches; also - used to separate groups of attributes
      • -
    • IPP_TAG_OPERATION - Tag for values of type operation
      • -
    • IPP_TAG_JOB - Tag for values of type job
      • -
    • IPP_TAG_END - Tag for values of type end
      • -
    • IPP_TAG_PRINTER - Tag for values of type printer
      • -
    • IPP_TAG_UNSUPPORTED_GROUP - Tag for values of type - unsupported_group
      • -
    • IPP_TAG_UNSUPPORTED_VALUE - Tag for values of type - unsupported_value
      • -
    • IPP_TAG_DEFAULT - Tag for values of type default
      • -
    • IPP_TAG_UNKNOWN - Tag for values of type unknown
      • -
    • IPP_TAG_NOVALUE - Tag for values of type novalue
      • -
    • IPP_TAG_NOTSETTABLE - Tag for values of type - notsettable
      • -
    • IPP_TAG_DELETEATTR - Tag for values of type deleteattr
      • -
    • IPP_TAG_ANYVALUE - Tag for values of type anyvalue
      • -
    • IPP_TAG_INTEGER - Tag for values of type integer
      • -
    • IPP_TAG_BOOLEAN - Tag for values of type boolean
      • -
    • IPP_TAG_ENUM - Tag for values of type enum
      • -
    • IPP_TAG_STRING - Tag for values of type string
      • -
    • IPP_TAG_DATE - Tag for values of type date
      • -
    • IPP_TAG_RESOLUTION - Tag for values of type resolution
      • -
    • IPP_TAG_RANGE - Tag for values of type range
      • -
    • IPP_TAG_COLLECTION - Tag for values of type collection
      • -
    • IPP_TAG_TEXTLANG - Tag for values of type textlang
      • -
    • IPP_TAG_NAMELANG - Tag for values of type namelang
      • -
    • IPP_TAG_TEXT - Tag for values of type text
      • -
    • IPP_TAG_NAME - Tag for values of type name
      • -
    • IPP_TAG_KEYWORD - Tag for values of type keyword
      • -
    • IPP_TAG_URI - Tag for values of type uri
      • -
    • IPP_TAG_URISCHEME - Tag for values of type urischeme
      • -
    • IPP_TAG_CHARSET - Tag for values of type charset
      • -
    • IPP_TAG_LANGUAGE - Tag for values of type language
      • -
    • IPP_TAG_MIMETYPE - Tag for values of type mimetype
      • -
    -

    Resolution Units

    -

    The IPP_RES_PER_INCH and IPP_RES_PER_CM - constants specify dots per inch and dots per centimeter, respectively.

    -

    Finishings

    -

    The finishing values specify special finishing operations to be - performed on the job.

    -
      -
    • IPP_FINISH_NONE - Do no finishing
      • -
    • IPP_FINISH_STAPLE - Staple the job
      • -
    • IPP_FINISH_PUNCH - Punch the job
      • -
    • IPP_FINISH_COVER - Cover the job
      • -
    • IPP_FINISH_BIND - Bind the job
      • -
    -

    Orientations

    -

    The orientation values specify the orientation of the job.

    -
      -
    • IPP_PORTRAIT - No rotation
      • -
    • IPP_LANDSCAPE - 90 degrees counter-clockwise
      • -
    • IPP_REVERSE_LANDSCAPE - 90 degrees clockwise
      • -
    • IPP_REVERSE_PORTRAIT - 180 degrees
      • -
    -

    Qualities

    -

    The quality values specify the desired quality of the print.

    -
      -
    • IPP_QUALITY_DRAFT - Draft quality
      • -
    • IPP_QUALITY_NORMAL - Normal quality
      • -
    • IPP_QUALITY_HIGH - High quality
      • -
    -

    Job States

    -

    The job state values are used to represent the current job state.

    -
      -
    • IPP_JOB_PENDING - Job is pending
      • -
    • IPP_JOB_HELD - Job is held
      • -
    • IPP_JOB_PROCESSING - Job is processing
      • -
    • IPP_JOB_STOPPED - Job is stopped
      • -
    • IPP_JOB_CANCELLED - Job is cancelled
      • -
    • IPP_JOB_ABORTED - Job is aborted
      • -
    • IPP_JOB_COMPLETED - Job is completed
      • -
    -

    Printer States

    -

    The printer state values are used to represent the current printer - state.

    -
      -
    • IPP_PRINTER_IDLE - Printer is idle
      • -
    • IPP_PRINTER_PROCESSING - Printer is processing
      • -
    • IPP_PRINTER_STOPPED - Printer is stopped
      • -
    -

    Operations

    -

    The operation values represent the available IPP operations.

    -
      -
    • IPP_PRINT_JOB - Print a file
      • -
    • IPP_PRINT_URI - Print a URI
      • -
    • IPP_VALIDATE_JOB - Validate job attributes
      • -
    • IPP_CREATE_JOB - Create a new job
      • -
    • IPP_SEND_DOCUMENT - Send a document to a job
      • -
    • IPP_SEND_URI - Send a URI to a job
      • -
    • IPP_CANCEL_JOB - Cancel a job
      • -
    • IPP_GET_JOB_ATTRIBUTES - Get job attributes
      • -
    • IPP_GET_JOBS - Get a list of all jobs
      • -
    • IPP_GET_PRINTER_ATTRIBUTES - Get printer attributes
      • -
    • IPP_HOLD_JOB - Hold a pending job
      • -
    • IPP_RELEASE_JOB - Release a held job
      • -
    • IPP_RESTART_JOB - Restart a completed job
      • -
    • IPP_PAUSE_PRINTER - Pause a printer
      • -
    • IPP_RESUME_PRINTER - Restart a paused printer
      • -
    • IPP_PURGE_JOBS - Purge jobs from the queue
      • -
    • IPP_SET_PRINTER_ATTRIBUTES - Set printer attributes
      • -
    • IPP_SET_JOB_ATTRIBUTES - Set job attributes
      • -
    • IPP_GET_PRINTER_SUPPORTED_VALUES - Get printer - supported values
      • -
    • CUPS_GET_DEFAULT - Get the default destination
      • -
    • CUPS_GET_PRINTERS - Get a list of all printers
      • -
    • CUPS_ADD_PRINTER - Add or modify a printer
      • -
    • CUPS_DELETE_PRINTER - Delete a printer
      • -
    • CUPS_GET_CLASSES - Get a list of all classes
      • -
    • CUPS_ADD_CLASS - Add or modify a class
      • -
    • CUPS_DELETE_CLASS - Delete a class
      • -
    • CUPS_ACCEPT_JOBS - Accept jobs on a printer or class
      • -
    • CUPS_REJECT_JOBS - Reject jobs on a printer or class
      • -
    • CUPS_SET_DEFAULT - Set the default destination
      • -
    • CUPS_GET_DEVICES - Get a list of all devices
      • -
    • CUPS_GET_PPDS - Get a list of all PPDs
      • -
    • CUPS_MOVE_JOB - Move a job to a new destination
      • -
    -

    Status Codes

    -

    Status codes are returned by all IPP requests.

    -
      -
    • IPP_OK - Request completed with no errors
      • -
    • IPP_OK_SUBST - Request completed but some attribute - values were substituted
      • -
    • IPP_OK_CONFLICT - Request completed but some attributes - conflicted
      • -
    • IPP_BAD_REQUEST - The request was bad
      • -
    • IPP_FORBIDDEN - You don't have access to the resource
      • -
    • IPP_NOT_AUTHENTICATED - You are not authenticated for - the resource
      • -
    • IPP_NOT_AUTHORIZED - You not authorized to access the - resource
      • -
    • IPP_NOT_POSSIBLE - The requested operation cannot be - completed
      • -
    • IPP_TIMEOUT - A timeout occurred
      • -
    • IPP_NOT_FOUND - The resource was not found
      • -
    • IPP_GONE - The resource has gone away
      • -
    • IPP_REQUEST_ENTITY - The request was too large
      • -
    • IPP_REQUEST_VALUE - The request contained a value that - was unknown to the server
      • -
    • IPP_DOCUMENT_FORMAT - The document format is not - supported by the server
      • -
    • IPP_ATTRIBUTES - Required attributes are missing
      • -
    • IPP_URI_SCHEME - The URI scheme is not supported
      • -
    • IPP_CHARSET - The charset is not supported
      • -
    • IPP_CONFLICT - One or more attributes conflict
      • -
    • IPP_COMPRESSION_NOT_SUPPORTED - The specified - compression is not supported
      • -
    • IPP_COMPRESSION_ERROR - The compressed data contained - an error
      • -
    • IPP_DOCUMENT_FORMAT_ERROR - The document data contained - an error in it
      • -
    • IPP_DOCUMENT_ACCESS_ERROR - The remote document could - not be accessed
      • -
    • IPP_INTERNAL_ERROR - The server encountered an internal - error
      • -
    • IPP_OPERATION_NOT_SUPPORTED - The requested operation - is not supported
      • -
    • IPP_SERVICE_UNAVAILABLE - The requested service is - unavailable
      • -
    • IPP_VERSION_NOT_SUPPORTED - The IPP request version is - not supported
      • -
    • IPP_DEVICE_ERROR - The output device encountered an - error
      • -
    • IPP_TEMPORARY_ERROR - A temporary error occurred
      • -
    • IPP_NOT_ACCEPTING - The destination is not accepting - jobs
      • -
    • IPP_PRINTER_BUSY - The destination is busy
      • -
    • IPP_ERROR_JOB_CANCELLED - The requested job has been - cancelled
      • -
    • IPP_MULTIPLE_JOBS_NOT_SUPPORTED - The server does not - support multiple jobs
      • -
    -

    PPD Constants

    -

    PPD Format Version

    -

    The PPD_VERSION constant defines a floating point number - representing the newest format version that is supported by CUPS, - currently 4.3.

    -

    PPD User-Interface Types

    -

    Each printer option has a type associated with it:

    -
      -
    • PPD_UI_BOOLEAN - The user can turn this option on or - off
      • -
    • PPD_UI_PICKONE - The user can choose one option value - to use.
      • -
    • PPD_UI_PICKMANY - The user can choose zero or more - option values.
      • -
    -

    PPD Sections

    -

    Some options must be output before others, or in different sections - of the output document. The ppd_section_t enumeration - defines which section the option must be output in:

    -
      -
    • PPD_ORDER_ANY - The option can be output in any of the - document, page, or prolog sections of the document
      • -
    • PPD_ORDER_DOCUMENT - The option must be output in the - DocumentSetup section of the document
      • -
    • PPD_ORDER_EXIT - The option must be output before the - document
      • -
    • PPD_ORDER_JCL - The option must be output in the job - control section of the document
      • -
    • PPD_ORDER_PAGE - The option must be output in the - PageSetup section of the document
      • -
    • PPD_ORDER_PROLOG - The option must be output in the - Prolog section of the document
      • -
    -

    PPD Colorspaces

    -

    Each printer has a default colorspace:

    -
      -
    • PPD_CS_CMYK - The printer uses CMYK colors by default
      • -
    • PPD_CS_CMY - The printer uses CMY colors by default
      • -
    • PPD_CS_GRAY - The printer uses grayscale by default
      • -
    • PPD_CS_RGB - The printer uses RGB colors by default
      • -
    • PPD_CS_RGBK - The printer uses RGBK colors by default
      • -
    • PPD_CS_N - The printer uses a DeviceN colorspace by - default
      • -
    -

    Raster Constants

    -

    Raster Sync Words

    -

    The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC - constants define the standard sync words at the beginning of each CUPS - raster file.

    -

    Raster Stream Modes

    -

    The CUPS_RASTER_READ and CUPS_RASTER_WRITE - constants are used with the -cupsRasterOpen() function to specify a stream for reading or - writing.

    -

    Raster Boolean Constants

    -

    The CUPS_FALSE and CUPS_TRUE constants - represent boolean values in the page header.

    -

    Raster Jog Values

    -

    The cups_jog_t enumeration defines constants for the Jog - page device dictionary variable:

    -
      -
    • CUPS_JOG_NONE - Do no jogging
      • -
    • CUPS_JOG_FILE - Jog pages after each file
      • -
    • CUPS_JOG_JOB - Jog pages after each job
      • -
    • CUPS_JOG_SET - Jog pages after each set of jobs
      • -
    -

    Raster Orientation Values

    -

    The cups_orient_t enumeration defines constants for the - Orientation page device dictionary variable:

    -
      -
    • CUPS_ORIENT_0 - Portrait orientation
      • -
    • CUPS_ORIENT_90 - Landscape orientation
      • -
    • CUPS_ORIENT_180 - Reverse-portrait orientation
      • -
    • CUPS_ORIENT_270 - Reverse-landscape orientation
      • -
    -

    Raster CutMedia Values

    -

    The cups_cut_t enumeration defines constants for the - CutMedia page device dictionary variable:

    -
      -
    • CUPS_CUT_NONE - Do no jogging
      • -
    • CUPS_CUT_FILE - Cut pages after each file
      • -
    • CUPS_CUT_JOB - Cut pages after each job
      • -
    • CUPS_CUT_SET - Cut pages after each set of jobs
      • -
    • CUPS_CUT_PAGE - Cut each page
      • -
    -

    Raster AdvanceMedia Values

    -

    The cups_advance_t enumeration defines constants for the - AdvanceMedia page device dictionary variable:

    -
      -
    • CUPS_ADVANCE_NONE - Do no jogging
      • -
    • CUPS_ADVANCE_FILE - Advance media after each file
      • -
    • CUPS_ADVANCE_JOB - Advance media after each job
      • -
    • CUPS_ADVANCE_SET - Advance media after each set of jobs
      • -
    • CUPS_ADVANCE_PAGE - Advance media for each page
      • -
    -

    Raster LeadingEdge Values

    -

    The cups_edge_t enumeration defines constants for the - LeadingEdge page device dictionary variable:

    -
      -
    • CUPS_EDGE_TOP - The top of the media is the leading - edge
      • -
    • CUPS_EDGE_RIGHT - The right of the media is the leading - edge
      • -
    • CUPS_EDGE_BOTTOM - The bottom of the media is the - leading edge
      • -
    • CUPS_EDGE_LEFT - The left of the media is the leading - edge
      • -
    -

    Raster Color Order Values

    -

    The cups_order_t enumeration defines the possible color - value orderings:

    -
      -
    • CUPS_ORDER_CHUNKED - CMYK CMYK CMYK
      • -
    • CUPS_ORDER_BANDED - CCC MMM YYY KKK
      • -
    • CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ...
      • -
    -

    Raster Colorspace Values

    -

    The cups_cspace_t enumeration defines the possible - colorspaces:

    -
      -
    • CUPS_CSPACE_W - White (luminance)
      • -
    • CUPS_CSPACE_RGB - Red, green, blue
      • -
    • CUPS_CSPACE_RGBA - Red, green, blue, alpha
      • -
    • CUPS_CSPACE_K - Black
      • -
    • CUPS_CSPACE_CMY - Cyan, magenta, yellow
      • -
    • CUPS_CSPACE_YMC - Yellow, magenta, cyan
      • -
    • CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black
      • -
    • CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black
      • -
    • CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow
      • -
    • CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, - light cyan, light magenta
      • -
    • CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic - magenta, metallic cyan, black
      • -
    • CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic - magenta, metallic cyan, metallic grey (silver)
      • -
    • CUPS_CSPACE_WHITE - White pigment (black as white - pigment)
      • -
    • CUPS_CSPACE_GOLD - Gold foil (black as gold foil)
      • -
    • CUPS_CSPACE_SILVER - Silver foil (black as silver foil)
      • -
    -

    C - Structures

    -

    This appendix describes all of the structures that are defined by the - CUPS API.

    -

    CUPS Structures

    -

    CUPS Destinations

    -

    The CUPS destination structure (cups_dest_t) contains - information on a specific destination or instance: -

    - - - - - - - - -
    MemberTypeDescription
    namechar *The name of the printer or class.
    instancechar *The instance of the printer or - class; NULL for the primary instance.
    is_defaultint1 if the destination is set as - the default, 0 otherwise.
    num_optionsintThe number of options associated - with this destination.
    optionscups_option_t * -The options associated with this destination.
    -
    -

    -

    CUPS Jobs

    -

    The CUPS job structure (cups_job_t) contains information - on a specific job: -

    - - - - - - - - - - - - - - - -
    MemberTypeDescription
    idintThe job ID for this job.
    destchar *The destination for this job - (printer or class name).
    titlechar *The job-name for this job (title).
    userchar *The job-originating-user-name for - this job (username).
    formatchar *The document-format for this job - (MIME type string).
    stateipp_jstateThe current state of the job.
    sizeintThe size of this job in kilobytes.
    priorityintThe priority of this job from 1 to - 100 (50 is normal).
    completed_timetime_tThe time the job was - completed, or 0 if not yet completed.
    creation_timetime_tThe time the job was - queued.
    processing_timetime_tThe time the job started - printing.
    -
    -

    -

    CUPS Messages

    -

    The CUPS messages structure (cups_lang_t) contains the - character set, locale name, and messages array: -

    - - - - - - - - - -
    MemberTypeDescription
    nextcups_lang_t *Pointer to the next messages - structure in memory.
    usedintThe number of active users of this - messages structure.
    encodingcups_encoding_tThe character encoding - of the message strings.
    languagechar [16]The language/locale name.
    messageschar *[]The array of message strings.
    -
    -

    -

    CUPS Options

    -

    The CUPS option structure (cups_option_t) contains the - option name and string value: -

    - - - - - -
    MemberTypeDescription
    namechar *The name of the option.
    valuechar *The string value of the option.
    -
    -

    -

    Networking Structures

    -

    HTTP State

    -

    The HTTP state structure (http_t) contains the current - state of a HTTP request or response: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    fdintThe socket for the HTTP connection.
    blockingint1 if the HTTP functions should - block, 0 if not.
    errorintThe last OS error that occurred on the - socket.
    activitytime_tThe last time the HTTP - connection was used.
    statehttp_state_tThe current HTTP - request/response state.
    statusintThe last HTTP status seen.
    versionhttp_version_tThe HTTP protocol version - in use.
    keep_alivehttp_keep_alive_tWhether or not to - use Keep-Alive
    hostaddrstruct sockaddr_inThe IPv4 address of - the HTTP server.
    hostnamechar []The hostname of the HTTP - server.
    fieldschar [][]The string values of all HTTP - request/response fields.
    datachar *Current byte in data buffer.
    data_encodinghttp_encoding_tThe transfer - encoding for the request/response.
    data_remainingintThe number of bytes remaining - in the current request, response, or chunk.
    usedintThe number of bytes that are used in - the buffer.
    bufferchar []The read/write buffer.
    auth_typeintThe type of authentication in use.
    md5_statemd5_state_tThe current MD5 digest - state.
    noncechar []The nonce value for Digest - authentication.
    nonce_countintThe nonce count value.
    tlsvoid *A pointer to private encryption data.
    encryptionhttp_encryption_tThe current - encryption mode.
    -
    -

    -

    IPP State

    -

    The IPP state structure (ipp_t) contains the current - state of a IPP request or response: -

    - - - -
    MemberTypeDescription
    -
    -

    -

    Raster Structures

    -

    Raster Page Header

    -

    The raster page header (cups_raster_header_t) consists - of the PostScript page device dictionary for the page: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    MediaClasschar[64]The media class name
    MediaColorchar[64]The media color name
    MediaTypechar[64]The media type name
    OutputTypechar[64]The output type name
    AdvanceDistanceunsignedThe distance to advance - the media in points
    AdvanceMediacups_adv_tWhen to advance the - media
    Collatecups_bool_tWhether or not to produce - collated copies
    CutMediacups_cut_tWhen to cut the media
    Duplexcups_bool_tWhether or not to print on - both sides of the paper
    HWResolutionunsigned[2]The resolution of the - page image in pixels per inch; the HWResolution[0] represents the - horizontal resolution and HWResolution[1] represents the vertical - resolution
    ImagingBoundingBoxunsigned[4]The bounding box - for the page in points; the elements represent the left, bottom, right, - and top coordinates of the imaged area (if 0 then the whole page is - imaged)
    InsertSheetcups_bool_tWhether or not to insert - a sheet before this page
    Jogcups_jog_tWhen to jog copies of the page
    LeadingEdgecups_edge_tThe leading edge of the - page
    Marginsunsigned[2]The lower-lefthand margin of - the page in points
    ManualFeedcups_bool_tWhether or not to - manually feed the page
    MediaPositionunsignedThe input slot number to - use
    MediaWeightunsignedThe weight of the output - media in grams/m2
    MirrorPrintcups_bool_tWhether or not to mirror - the print
    NegativePrintcups_bool_tWhether or not to - invert the print
    NumCopiesunsignedThe number of copies to - produce
    Orientationcups_orient_tThe orientation of the - page image
    OutputFaceUpcups_bool_tWhether or not to - output the page face up
    PageSizeunsigned[2]The width and height of the - page in points
    Separationscups_bool_tWhether or not to output - separations
    TraySwitchcups_bool_tWhether or not to - automatically switch trays for the requested media size/type
    Tumblecups_bool_tWhether or not to rotate the - back side of the page
    cupsWidthunsignedThe width of the page image - in pixels
    cupsHeightunsignedThe height of the page image - in pixels
    cupsMediaTypeunsignedThe device-specific media - type code
    cupsBitsPerColorunsignedThe number of bits per - color
    cupsBitsPerPixelunsignedThe number of bits per - pixel
    cupsBytesPerLineunsignedThe number of bytes - per line of image data
    cupsColorOrdercups_order_tThe order of color - values
    cupsColorSpacecups_cspace_tThe type of color - values
    cupsCompressionunsignedThe device-specific - compression code
    cupsRowCountunsignedThe device-specific row - count
    cupsRowFeedunsignedThe device-specific row - feed
    cupsRowStepunsignedThe device-specific row - step
    -
    -

    -

    D - Functions

    -

    This appendix provides a reference for all of the CUPS API functions. - -

    -

    cupsAddDest()

    -

    Usage

    -
    -int
-cupsAddDest(const char  *name,
-            const char  *instance,
-            int         num_dests,
-	    cups_dest_t **dests);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    nameThe name of the destination.
    instanceThe instance of the destination, or NULL for - the primary instance.
    num_destsThe number of destinations in the array.
    destA pointer to the destination array pointer.
    -
    -

    Returns

    -

    The new number of destinations in the array.

    -

    Description

    -

    cupsAddDest() adds the named destination to the - destination array if it does not already exist.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-
-
-num_dests = cupsAddDests("foo", "bar", num_dests, &dests);
-
    -

    See Also

    -

    cupsFreeDests(), - cupsGetDest(), -cupsGetDests() - -

    -

    cupsAddOption()

    -

    Usage

    -
    -int
-cupsAddOption(const char    *name,
-              const char    *value,
-              int           num_options,
-	      cups_option_t **options);
-
    -

    Arguments

    -
    - - - - - - - -
    ArgumentDescription
    nameThe name of the option.
    valueThe value of the option.
    num_optionsNumber of options currently in the array.
    optionsPointer to the options array.
    -
    -

    Returns

    -

    The new number of options.

    -

    Description

    -

    cupsAddOption() adds an option to the specified array.

    -

    Example

    -
    -#include <cups.h>
-
-...
-
-/* Declare the options array */
-int           num_options;
-cups_option_t *options;
-
-/* Initialize the options array */
-num_options = 0;
-options     = (cups_option_t *)0;
-
-/* Add options using cupsAddOption() */
-num_options = cupsAddOption("media", "letter", num_options, &options);
-num_options = cupsAddOption("resolution", "300dpi", num_options, &options);
-
    -

    See Also

    - cupsEncodeOptions(), - cupsFreeOptions(), -cupsGetOption(), -cupsParseOptions() - - -

    cupsCancelJob()

    -

    Usage

    -
    -int
-cupsCancelJob(const char *dest,
-              int        job);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    destPrinter or class name
    jobJob ID
    -
    -

    Returns

    -

    1 on success, 0 on failure. On failure the error can be found by - calling cupsLastError().

    -

    Description

    -

    cupsCancelJob() cancels the specifies job.

    -

    Example

    -
    -#include <cups.h>
-
-cupsCancelJob("LaserJet", 1);
-
    -

    See Also

    -

    cupsLastError(), - cupsPrintFile(), -cupsPrintFiles() - -

    -

    cupsDoFileRequest()

    -

    Usage

    -
    -ipp_t *
-cupsDoFileRequest(http_t     *http,
-                  ipp_t      *request,
-                  const char *resource,
-		  const char *filename);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    httpHTTP connection to server.
    requestIPP request data.
    resourceHTTP resource name for POST.
    filenameFile to send with POST request (NULL - pointer if none.)
    -
    -

    Returns

    -

    IPP response data or NULL if the request fails. On - failure the error can be found by calling -cupsLastError().

    -

    Description

    -

    cupsDoFileRequest() does a HTTP POST request and - provides the IPP request and optionally the contents of a file to the - IPP server. It also handles resubmitting the request and performing - password authentication as needed.

    -

    Example

    -
    -#include <cups.h>
-
-http_t      *http;
-cups_lang_t *language;
-ipp_t       *request;
-ipp_t       *response;
-
-...
-
-/* Get the default language */
-language = cupsLangDefault();
-
-/* Create a new IPP request */
-request  = ippNew();
-
-request->request.op.operation_id = IPP_PRINT_FILE;
-request->request.op.request_id   = 1;
-
-/* Add required attributes */
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
-             "attributes-charset", NULL, cupsLangEncoding(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
-             "attributes-natural-language", NULL,
-             language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
-             NULL, "ipp://hostname/resource");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
-             NULL, cupsUser());
-
-/* Do the request... */
-response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsUser(), httpConnect() -, ippAddString(), - ippNew() - -

    -

    cupsDoRequest()

    -

    Usage

    -
    -ipp_t *
-cupsDoRequest(http_t *http,
-              ipp_t *request,
-              const char *resource);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    httpHTTP connection to server.
    requestIPP request data.
    resourceHTTP resource name for POST.
    -
    -

    Returns

    -

    IPP response data or NULL if the request fails. On - failure the error can be found by calling -cupsLastError().

    -

    Description

    -

    cupsDoRequest() does a HTTP POST request and provides - the IPP request to the IPP server. It also handles resubmitting the - request and performing password authentication as needed.

    -

    Example

    -
    -#include <cups.h>
-
-http_t      *http;
-cups_lang_t *language;
-ipp_t       *request;
-ipp_t       *response;
-
-...
-
-/* Get the default language */
-language = cupsLangDefault();
-
-/* Create a new IPP request */
-request  = ippNew();
-
-request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
-request->request.op.request_id   = 1;
-
-/* Add required attributes */
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
-             "attributes-charset", NULL, cupsLangEncoding(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
-             "attributes-natural-language", NULL,
-             language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
-             NULL, "ipp://hostname/resource");
-
-/* Do the request... */
-response = cupsDoRequest(http, request, "/resource");
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsUser(), httpConnect() -, ippAddString(), - ippNew() - -

    -

    cupsEncodeOptions()

    -

    Usage

    -
    -void
-cupsEncodeOptions(ipp_t         *ipp,
-                  int           num_options,
-		  cups_option_t *options);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ippThe IPP request.
    num_optionsThe number of options.
    optionsThe options.
    -
    -

    Description

    -

    cupsEncodeOptions() encodes all of the options in the - specified array as IPP attributes and adds them to the IPP request.

    -

    Example

    -
    -#include <cups/cups.h>
-
-ipp_t         *ipp;
-int           num_options;
-cups_option_t *options;
-
-
-cupsEncodeOptions(ipp, num_options, options);
-
    -

    See Also

    -

    cupsAddOption(), - cupsParseOptions(), ippNew() - - -

    -

    cupsEncryption()

    -

    Usage

    -
    -http_encryption_t
-cupsEncryption(void);
-
    -

    Returns

    -

    The current encryption setting.

    -

    Description

    -

    cupsEncryption() returns the current encryption setting - for IPP requests such as printing.

    -

    Example

    -
    -#include <cups/cups.h>
-
-http_t *http;
-
-printf("The current encryption setting is %d.\n", cupsEncryption());
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-
    -

    See Also

    -

    cupsServer(), - httpConnectEncrypt(), -ippPort() - -

    -

    cupsFreeDests()

    -

    Usage

    -
    -void
-cupsFreeDests(int         num_dests,
-              cups_dest_t *dests);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    num_destsThe number of destinations in the array.
    destsThe destination array.
    -
    -

    Description

    -

    cupsFreeDests() frees a destination array that was - created using cupsGetDests().

    -

    Example

    -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    -

    See Also

    -

    cupsGetDest(), - cupsGetDests() - -

    -

    cupsFreeJobs()

    -

    Usage

    -
    -void
-cupsFreeJobs(int        num_jobs,
-             cups_job_t *jobs);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    num_jobsThe number of jobs.
    jobsThe job array.
    -
    -

    Description

    -

    cupsFreeJobs() frees an array of print jobs created by - the cupsGetJobs() function.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int        i;
-int        num_jobs;
-cups_job_t *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
-  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
-         jobs[i].user, jobs[i].title,
-	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-
    -

    See Also

    -

    cupsGetJobs(), - cupsGetDests() - -

    -

    cupsFreeOptions()

    -

    Usage

    -
    -void
-cupsFreeOptions(int           num_options,
-                cups_option_t *options);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    num_optionsNumber of options in array.
    optionsPointer to options array.
    -
    -

    Description

    -

    cupsFreeOptions() frees all memory associated with the - option array specified.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-
    -

    See Also

    -

    cupsAddOption(), - cupsEncodeOptions(), -cupsGetOption(), -cupsMarkOptions(), -cupsParseOptions() - -

    -

    cupsGetClasses()

    -

    Usage

    -
    -int
-cupsGetClasses(char ***classes);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    classesPointer to character pointer array.
    -
    -

    Returns

    -

    The number of printer classes available.

    -

    Description

    -

    cupsGetClasses() gets a list of the available printer - classes. The returned array should be freed using the free() - when it is no longer needed.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int  i;
-int  num_classes;
-char **classes;
-
-...
-
-num_classes = cupsGetClasses(
-
-...
-
-if (num_classes > 0)
-{
-  for (i = 0; i < num_classes; i ++)
-    free(classes[i]);
-
-  free(classes);
-}
-
    -

    See Also

    -

    cupsGetDefault(), - cupsGetPrinters() - -

    -

    cupsGetDefault()

    -

    Usage

    -
    -const char *
-cupsGetDefault(void);
-
    -

    Returns

    -

    A pointer to the default destination.

    -

    Description

    -

    cupsGetDefault() gets the default destination printer or - class. The default destination is stored in a static string and will be - overwritten (usually with the same value) after each call.

    -

    Example

    -
    -#include <cups/cups.h>
-
-printf("The default destination is %s\n", cupsGetDefault());
-
    -

    See Also

    -

    cupsGetClasses(), - cupsGetPrinters() - -

    -

    cupsGetDest()

    -

    Usage

    -
    -cups_dest_t *
-cupsGetDest(const char  *name,
-            const char  *instance,
-            int         num_dests,
-            cups_dest_t *dests);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    nameThe name of the destination, or NULL for the - default destination.
    instanceThe instance of the destination, or NULL for - the primary instance.
    num_destsThe number of destinations.
    destsThe destination array.
    -
    -

    Returns

    -

    A pointer to the specified destination, or NULL if none exists.

    -

    Description

    -

    cupsGetDest() finds the specified destination in the - array of destinations created by the cupsGetDests() - function.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    -

    See Also

    -

    cupsGetDests(), - cupsGetJobs() - -

    -

    cupsGetDests()

    -

    Usage

    -
    -int
-cupsGetDests(cups_dest_t **dests);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    destsA pointer to a destination array pointer.
    -
    -

    Returns

    -

    The number of available destinations.

    -

    Description

    -

    cupsGetDests() creates an array of available - destinations that the user can print to. The array should be freed - using the cupsFreeDests() function.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    -

    See Also

    -

    cupsFreeDests(), - cupsGetDest(), -cupsGetJobs() - -

    -

    cupsGetJobs()

    -

    Usage

    -
    -int
-cupsGetJobs(cups_job_t **jobs,
-            const char *dest,
-            int        myjobs,
-            int        completed);
-
    -

    Arguments

    -
    - - - - - - - -
    ArgumentDescription
    jobsA pointer to the job array pointer.
    destThe destination name, or NULL if jobs for all - destinations are requested.
    myjobs1 if only those jobs submitted by the current -cupsUser() should be returned, 0 for jobs submitted by all users.
    completed1 if only completed jobs should be returned, 0 - if only pending/processing jobs should be returned.
    -
    -

    Returns

    -

    The number of jobs.

    -

    Description

    -

    cupsGetJobs() creates an array of print jobs based on - the arguments supplied in the function call. The returned array should - be freed using the cupsFreeJobs() function.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int        i;
-int        num_jobs;
-cups_job_t *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
-  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
-         jobs[i].user, jobs[i].title,
-	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-
    -

    See Also

    -

    cupsFreeJobs(), - cupsGetDests() - -

    -

    cupsGetOption()

    -

    Usage

    -
    -const char *
-cupsGetOption(const char    *name,
-              int           num_options,
-              cups_option_t *options);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    nameThe name of the option.
    num_optionsThe number of options in the array.
    optionsThe options array.
    -
    -

    Returns

    -

    A pointer to the option values or NULL if the option is - not defined.

    -

    Description

    -

    cupsGetOption() returns the first occurrence of the - named option. If the option is not included in the options array then a - NULL pointer is returned.

    -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-const char    *media;
-
-...
-
-media = cupsGetOption("media", num_options, options);
-
    -

    See Also

    -

    cupsAddOption(), - cupsEncodeOptions(), -cupsFreeOptions(), -cupsMarkOptions(), -cupsParseOptions() - -

    -

    cupsGetPassword()

    -

    Usage

    -
    -const char *
-cupsGetPassword(const char *prompt);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    promptThe prompt to display to the user.
    -
    -

    Returns

    -

    A pointer to the password that was entered or NULL if no - password was entered.

    -

    Description

    -

    cupsGetPassword() displays the prompt string and asks - the user for a password. The password text is not echoed to the user.

    -

    Example

    -
    -#include <cups/cups.h>
-
-char *password;
-
-...
-
-password = cupsGetPassword("Please enter a password:");
-
    -

    See Also

    -

    cupsServer(), - cupsSetPasswordCB(), -cupsSetServer(), cupsSetUser() -, cupsUser() - -

    -

    cupsGetPPD()

    -

    Usage

    -
    -const char *
-cupsGetPPD(const char *printer);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    printerThe name of the printer.
    -
    -

    Returns

    -

    The name of a temporary file containing the PPD file or NULL - if the printer cannot be located or does not have a PPD file.

    -

    Description

    -

    cupsGetPPD() gets a copy of the PPD file for the named - printer. The printer name can be of the form "printer" or - "printer@hostname".

    -

    You should remove (unlink) the PPD file after you are done using it. - The filename is stored in a static buffer and will be overwritten with - each call to cupsGetPPD().

    -

    Example

    -
    -#include <cups/cups.h>
-
-char *ppd;
-
-...
-
-ppd = cupsGetPPD("printer@hostname");
-
-...
-
-unlink(ppd);
-
    - - -

    cupsGetPrinters()

    -

    Usage

    -
    -int
-cupsGetPrinters(char ***printers);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    printersPointer to character pointer array.
    -
    -

    Returns

    -

    The number of printer printers available.

    -

    Description

    -

    cupsGetPrinters() gets a list of the available printers. - The returned array should be freed using the free() when - it is no longer needed.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int  i;
-int  num_printers;
-char **printers;
-
-...
-
-num_printers = cupsGetPrinters(
-
-...
-
-if (num_printers > 0)
-{
-  for (i = 0; i < num_printers; i ++)
-    free(printers[i]);
-
-  free(printers);
-}
-
    -

    See Also

    -

    cupsGetClasses() - cupsGetDefault() - -

    -

    cupsLangDefault()

    -

    Usage

    -
    -const char *
-cupsLangDefault(void);
-
    -

    Returns

    -

    A pointer to the default language structure.

    -

    Description

    -

    cupsLangDefault() returns a language structure for the - default language. The default language is defined by the LANG - environment variable. If the specified language cannot be located then - the POSIX (English) locale is used.

    -

    Call cupsLangFree() to free any memory associated with - the language structure when you are done.

    -

    Example

    -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-...
-
-language = cupsLangDefault();
-
-...
-
-cupsLangFree(language);
-
    -

    See Also

    -

    cupsLangEncoding(), - cupsLangFlush(), -cupsLangFree(), cupsLangGet() -, cupsLangString() - -

    -

    cupsLangEncoding()

    -

    Usage

    -
    -char *
-cupsLangEncoding(cups_lang_t *language);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    languageThe language structure.
    -
    -

    Returns

    -

    A pointer to the encoding string.

    -

    Description

    -

    cupsLangEncoding() returns the language encoding used - for the specified language, e.g. "iso-8859-1", "utf-8", etc.

    -

    Example

    -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-char        *encoding;
-...
-
-language = cupsLangDefault();
-encoding = cupsLangEncoding(language);
-...
-
-cupsLangFree(language);
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangFlush(), -cupsLangFree(), cupsLangGet() -, cupsLangString() - -

    -

    cupsLangFlush()

    -

    Usage

    -
    -void
-cupsLangFlush(void);
-
    -

    Description

    -

    cupsLangFlush() frees all language structures that have - been allocated.

    -

    Example

    -
    -#include <cups/language.h>
-
-...
-
-cupsLangFlush();
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsLangFree(), cupsLangGet() -, cupsLangString() - -

    -

    cupsLangFree()

    -

    Usage

    -
    -void
-cupsLangFree(cups_lang_t *language);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    languageThe language structure to free.
    -
    -

    Description

    -

    cupsLangFree() frees the specified language structure.

    -

    Example

    -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-...
-
-cupsLangFree(language);
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsLangFlush(), cupsLangGet() -, cupsLangString() - -

    -

    cupsLangGet()

    -

    Usage

    -
    -cups_lang_t *
-cupsLangGet(const char *name);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    nameThe name of the locale.
    -
    -

    Returns

    -

    A pointer to a language structure.

    -

    Description

    -

    cupsLangGet() returns a language structure for the - specified locale. If the locale is not defined then the POSIX (English) - locale is substituted.

    -

    Example

    -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-
-...
-
-language = cupsLangGet("fr");
-
-...
-
-cupsLangFree(language);
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsLangFlush(), cupsLangFree() -, cupsLangString() - -

    -

    cupsLangString()

    -

    Usage

    -
    -char *
-cupsLangString(cups_lang_t *language,
-               int         message);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    languageThe language to query.
    messageThe message number.
    -
    -

    Returns

    -

    A pointer to the message string or NULL if the message - is not defined.

    -

    Description

    -

    cupsLangString() returns a pointer to the specified - message string in the specified language.

    -

    Example

    -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-char        *s;
-...
-
-language = cupsLangGet("fr");
-
-s = cupsLangString(language, CUPS_MSG_YES);
-
-...
-
-cupsLangFree(language);
-
    -

    See Also

    -

    cupsLangDefault(), - cupsLangEncoding(), -cupsLangFlush(), cupsLangFree() -, cupsLangGet() - -

    -

    cupsLastError()

    -

    Usage

    -
    -ipp_status_t
-cupsLastError(void);
-
    -

    Returns

    -

    An enumeration containing the last IPP error.

    -

    Description

    -

    cupsLastError() returns the last IPP error that - occurred. If no error occurred then it will return IPP_OK - or IPP_OK_CONFLICT.

    -

    Example

    -
    -#include <cups/cups.h>
-
-ipp_status_t status;
-
-...
-
-status = cupsLastError();
-
    -

    See Also

    -

    cupsCancelJob(), - cupsPrintFile() - -

    -

    cupsMarkOptions()

    -

    Usage

    -
    -int
-cupsMarkOptions(ppd_file_t    *ppd,
-                int           num_options,
-                cups_option_t *options);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    ppdThe PPD file to mark.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    -
    -

    Returns

    -

    The number of conflicts found.

    -

    Description

    -

    cupsMarkOptions() marks options in the PPD file. It also - handles mapping of IPP option names and values to PPD option names.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-ppd_file_t    *ppd;
-
-...
-
-cupsMarkOptions(ppd, num_options, options);
-
    -

    See Also

    -

    cupsAddOption(), - cupsFreeOptions(), -cupsGetOption(), -cupsParseOptions() - -

    -

    cupsParseOptions()

    -

    Usage

    -
    -int
-cupsParseOptions(const char    *arg,
-                 int           num_options,
-                 cups_option_t **options);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    argThe string containing one or more options.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array pointer.
    -
    -

    Returns

    -

    The new number of options in the array.

    -

    Description

    -

    cupsParseOptions() parses the specifies string for one - or more options of the form "name=value", "name", or "noname". It can - be called multiple times to combine the options from several strings.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-num_options = 0;
-options     = (cups_option_t *)0;
-num_options = cupsParseOptions(argv[5], num_options, &options);
-
    -

    See Also

    -

    cupsAddOption(), - cupsFreeOptions(), -cupsGetOption(), -cupsMarkOptions() - -

    -

    cupsPrintFile()

    -

    Usage

    -
    -int
-cupsPrintFile(const char    *printer,
-              const char    *filename,
-              const char    *title,
-	      int           num_options,
-	      cups_option_t *options);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    printerThe printer or class to print to.
    filenameThe file to print.
    titleThe job title.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    -
    -

    Returns

    -

    The new job ID number or 0 on error.

    -

    Description

    -

    cupsPrintFile() sends a file to the specified printer or - class for printing. If the job cannot be printed the error code can be - found by calling cupsLastError().

    -

    Example

    -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-int           jobid;
-
-...
-
-jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
-                      num_options, options);
-
    -

    See Also

    -

    cupsCancelJob(), - cupsLastError(), -cupsPrintFiles() - -

    -

    cupsPrintFiles()

    -

    Usage

    -
    -int
-cupsPrintFiles(const char    *printer,
-               int           num_files,
-               const char    **files,
-               const char    *title,
-	       int           num_options,
-	       cups_option_t *options);
-
    -

    Arguments

    -
    - - - - - - - - - -
    ArgumentDescription
    printerThe printer or class to print to.
    num_filesThe number of files to print.
    filesThe files to print.
    titleThe job title.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    -
    -

    Returns

    -

    The new job ID number or 0 on error.

    -

    Description

    -

    cupsPrintFiles() sends multiple files to the specified - printer or class for printing. If the job cannot be printed the error - code can be found by calling cupsLastError().

    -

    Example

    -
    -#include <cups/cups.h>
-
-int           num_files;
-const char    *files[100];
-int           num_options;
-cups_option_t *options;
-int           jobid;
-
-...
-
-jobid = cupsPrintFiles("printer@hostname", num_files, files,
-                       "Job Title", num_options, options);
-
    -

    See Also

    -

    cupsCancelJob(), - cupsLastError(), -cupsPrintFile() - -

    -

    cupsRasterClose()

    -

    Usage

    -
    -void
-cupsRasterClose(cups_raster_t *ras);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    rasThe raster stream to close.
    -
    -

    Description

    -

    cupsRasterClose() closes the specified raster stream.

    -

    Example

    -
    -#include <cups/raster.h>
-
-cups_raster_t *ras;
-
-...
-
-cupsRasterClose(ras);
-
    -

    See Also

    -

    cupsRasterOpen(), - cupsRasterReadHeader(), - cupsRasterReadPixels(), - cupsRasterWriteHeader(), - cupsRasterWritePixels() - -

    -

    cupsRasterOpen()

    -

    Usage

    -
    -cups_raster_t *
-cupsRasterOpen(int         fd,
-               cups_mode_t mode);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    fdThe file descriptor to use.
    modeThe mode to use; CUPS_RASTER_READ or -CUPS_RASTER_WRITE.
    -
    -

    Returns

    -

    A pointer to a raster stream or NULL if there was an - error.

    -

    Description

    -

    cupsRasterOpen() opens a raster stream for reading or - writing.

    -

    Example

    -
    -#include <cups/raster.h>
-
-cups_raster_t *ras;
-
-...
-
-ras = cupsRasterOpen(0, CUPS_RASTER_READ);
-
    -

    See Also

    -

    cupsRasterClose(), - cupsRasterReadHeader(), - cupsRasterReadPixels(), - cupsRasterWriteHeader(), - cupsRasterWritePixels() - -

    -

    cupsRasterReadHeader()

    -

    Usage

    -
    -unsigned
-cupsRasterReadHeader(cups_raster_t      *ras,
-                     cups_page_header_t *header);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    rasThe raster stream to read from.
    headerA pointer to a page header structure to read - into.
    -
    -

    Returns

    -

    1 on success, 0 on EOF or error.

    -

    Description

    -

    cupsRasterReadHeader() reads a page header from the - specified raster stream.

    -

    Example

    -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ...
-
-  for (line = 0; line < header.cupsHeight; line ++)
-  {
-    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
-    ...
-  }
-}
-
    -

    See Also

    -

    cupsRasterClose(), - cupsRasterOpen(), -cupsRasterReadPixels(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - -

    -

    cupsRasterReadPixels()

    -

    Usage

    -
    -unsigned
-cupsRasterReadPixels(cups_raster_t *ras,
-                     unsigned char *pixels,
-		     unsigned      length);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    rasThe raster stream to read from.
    pixelsThe pointer to a pixel buffer.
    lengthThe number of bytes of pixel data to read.
    -
    -

    Returns

    -

    The number of bytes read or 0 on EOF or error.

    -

    Description

    -

    cupsRasterReadPixels() reads pixel data from the - specified raster stream.

    -

    Example

    -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ...
-
-  for (line = 0; line < header.cupsHeight; line ++)
-  {
-    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
-    ...
-  }
-}
-
    -

    See Also

    -

    cupsRasterClose(), - cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - -

    -

    cupsRasterWriteHeader()

    -

    Usage

    -
    -unsigned
-cupsRasterWriteHeader(cups_raster_t      *ras,
-                      cups_page_header_t *header);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    rasThe raster stream to write to.
    headerA pointer to the page header to write.
    -
    -

    Returns

    -

    1 on success, 0 on error.

    -

    Description

    -

    cupsRasterWriteHeader() writes the specified page header - to a raster stream.

    -

    Example

    -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
-  ...
-
-  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-
    -

    See Also

    -

    cupsRasterClose(), - cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWritePixels() - -

    -

    cupsRasterWritePixels()

    -

    Usage

    -
    -unsigned
-cupsRasterWritePixels(cups_raster_t *ras,
-                      unsigned char *pixels,
-		      unsigned      length);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    rasThe raster stream to write to.
    pixelsThe pixel data to write.
    lengthThe number of bytes to write.
    -
    -

    Returns

    -

    The number of bytes written.

    -

    Description

    -

    cupsRasterWritePixels() writes the specified pixel data - to a raster stream.

    -

    Example

    -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
-  ...
-
-  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-
    -

    See Also

    -

    cupsRasterClose(), - cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWriteHeader() - -

    -

    cupsServer()

    -

    Usage

    -
    -const char *
-cupsServer(void);
-
    -

    Returns

    -

    A pointer to the default server name.

    -

    Description

    -

    cupsServer() returns a pointer to the default server - name. The server name is stored in a static location and will be - overwritten with every call to cupsServer().

    -

    The default server is determined from the following locations:

    -
      -
    1. The CUPS_SERVER environment variable,
      2. -
    2. The ServerName directive in the client.conf - file,
      3. -
    3. The default host, "localhost".
      4. -
    -

    Example

    -
    -#include <cups/cups.h>
-
-const char *server;
-
-server = cupsServer();
-
    -

    See Also

    -

    cupsGetPassword(), - cupsSetPasswordCB(), -cupsSetServer(), cupsSetUser() -, cupsUser() - -

    -

    cupsSetDests()

    -

    Usage

    -
    -void
-cupsSetDests(int         num_dests,
-             cups_dest_t *dests);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    num_destsNumber of destinations.
    destsArray of destinations.
    -
    -

    Description

    -

    cupsSetDests() saves the destination array to disk. If - the current UID is 0, the destinations are saved in the - /etc/cups/lpoptions file, otherwise they are saved in the - ~/.lpoptions file. This function is typically used to save the - default options and instances that are set by the user.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-
-...
-
-cupsSetDests(num_dests, dests);
-
    -

    See Also

    -

    cupsGetDests() - -

    -

    cupsSetEncryption()

    -

    Usage

    -
    -void
-cupsSetEncryption(http_encryption_t encryption);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    encryptionThe type of encryption to use.
    -
    -

    Description

    -

    cupsSetEncryption() sets the default type of encryption - to use when connecting with the print server.

    -

    Example

    -
    -#include <cups/cups.h>
-
-cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
-
    -

    See Also

    -

    cupsEncryption() - -

    -

    cupsSetPasswordCB()

    -

    Usage

    -
    -void
-cupsSetPasswordCB(const char *(*cb)(const char *prompt));
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    cbThe password callback function.
    -
    -

    Description

    -

    cupsSetPasswordCB() sets the callback function to use - when asking the user for a password. The callback function must accept - a single character string pointer (the prompt string) and return -NULL if the user did not enter a password string or a pointer to - the password string otherwise.

    -

    Example

    -
    -#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
-  return (getpass(prompt));
-}
-
-...
-
-char *password;
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-password = cupsGetPassword("Please enter a password:");
-
    -

    See Also

    -

    cupsServer(), - cupsSetServer(), -cupsSetUser(), cupsUser() - - -

    -

    cupsSetServer()

    -

    Usage

    -
    -void
-cupsSetServer(const char *server);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    serverThe default server to use.
    -
    -

    Description

    -

    cupsSetServer() sets the default server to use for the - CUPS API. If the server argument is NULL, the - default server is used.

    -

    Example

    -
    -#include <cups/cups.h>
-
-cupsSetServer("foo.bar.com");
-
    -

    See Also

    -

    cupsServer(), - cupsSetPasswordCB(), -cupsSetUser(), cupsUser() - - -

    -

    cupsSetUser()

    -

    Usage

    -
    -void
-cupsSetUser(const char *user);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    userThe user name string to use.
    -
    -

    Description

    -

    cupsSetUser() sets the default user name for - authentication. If the user argument is NULL - then the current login user is used.

    -

    Example

    -
    -#include <cups/cups.h>
-
-...
-
-cupsSetUser("root");
-
    -

    See Also

    -

    cupsServer(), - cupsSetPasswordCB(), -cupsSetServer(), cupsUser() - - -

    -

    cupsTempFd()

    -

    Usage

    -
    -int
-cupsTempFd(char *filename,
-           int  length);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    filenameThe character string to hold the temporary - filename.
    lengthThe size of the filename string in bytes.
    -
    -

    Returns

    -

    A file descriptor open for reading and writing.

    -

    Description

    -

    cupsTempFd() create a temporary filename in the - /var/tmp directory or the directory specified by the TMPDIR - environment variable.

    -

    Example

    -
    -#include <cups/cups.h>
-
-int  fd;
-char filename[256];
-
-fd = cupsTempFd(filename, sizeof(filename));
-
    -

    See Also

    -

    cupsTempFile() - -

    -

    cupsTempFile()

    -

    Usage

    -
    -char *
-cupsTempFile(char *filename,
-             int  length);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    filenameThe character string to hold the temporary - filename.
    lengthThe size of the filename string in bytes.
    -
    -

    Returns

    -

    A pointer to filename.

    -

    Description

    -

    cupsTempFile() creates a temporary filename in the - /var/tmp directory or the directory specified by the TMPDIR - environment variable.

    -

    Example

    -
    -#include <cups/cups.h>
-
-char filename[256];
-
-cupsTempFile(filename, sizeof(filename));
-
    -

    See Also

    -

    cupsTempFd() - -

    -

    cupsUser()

    -

    Usage

    -
    -const char *
-cupsUser(void);
-
    -

    Returns

    -

    A pointer to the current username or NULL if the user ID - is undefined.

    -

    Description

    -

    cupsUser() returns the name associated with the current - user ID as reported by the getuid() system call.

    -

    Example

    -
    -#include <cups/cups.h>
-
-const char *user;
-
-user = cupsUser();
-
    -

    See Also

    -

    cupsGetPassword(), - cupsServer() - -

    -

    httpBlocking()

    -

    Usage

    -
    -void
-httpBlocking(http_t *http,
-             int    blocking)
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    blocking0 if the connection should be non-blocking, 1 - if it should be blocking
    -
    -

    Description

    -

    The httpBlocking() function sets the blocking mode for - the HTTP connection. By default HTTP connections will block (stop) the - client program until data is available or can be sent to the server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnect("server", port);
-httpBlocking(http, 0);
-
    -

    See Also

    - httpCheck(), - httpConnect() - - -

    httpCheck()

    -

    Usage

    -
    -int
-httpCheck(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Returns

    -

    0 if there is no data pending, 1 otherwise.

    -

    Description

    -

    The httpCheck() function checks to see if there is any - data pending on an HTTP connection.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-if (httpCheck(http))
-{
-  ... do something ...
-}
-
    -

    See Also

    - httpBlocking(), - httpConnect(), httpGets() -, httpRead() - - -

    httpClearFields()

    -

    Usage

    -
    -void
-httpClearFields(http_t *http)
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Description

    -

    The httpClearFields() function clears all HTTP request - fields for the HTTP connection.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpClearFields(http);
-
    -

    See Also

    - httpConnect(), - httpGetField(), -httpSetField() - - -

    httpClose()

    -

    Usage

    -
    -void
-httpClose(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Description

    -

    The httpClose() function closes an active HTTP - connection.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpClose(http);
-
    -

    See Also

    - httpConnect() - - -

    httpConnect()

    -

    Usage

    -
    -http_t *
-httpConnect(const char *hostname,
-            int        port);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    hostnameThe name or IP address of the server to connect - to
    portThe port number to use
    -
    -

    Returns

    -

    A pointer to a HTTP connection structure or NULL if the connection - could not be made.

    -

    Description

    -

    The httpConnect() function opens a HTTP connection to - the specified server and port.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnect(cupsServer(), ippPort());
-
    -

    See Also

    - httpClose(), - httpConnectEncrypt(), -httpGet(), httpGets(), - httpPost(), httpRead() -, httpWrite() - - -

    httpConnectEncrypt()

    -

    Usage

    -
    -http_t *
-httpConnectEncrypt(const char        *hostname,
-                   int               port,
-                   http_encryption_t encryption);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    hostnameThe name or IP address of the server to connect - to
    portThe port number to use
    encryptionThe level of encryption to use
    -
    -

    Returns

    -

    A pointer to a HTTP connection structure or NULL if the connection - could not be made.

    -

    Description

    -

    The httpConnectEncrypt() function opens a HTTP - connection to the specified server, port, and encryption.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-
    -

    See Also

    - httpClose(), - httpConnect(), httpGet() -, httpGets(), - httpPost(), httpRead() -, httpWrite() - - -

    httpDecode64()

    -

    Usage

    -
    -char *
-httpDecode64(char       *out,
-             const char *in);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    outThe output string
    inThe input string
    -
    -

    Returns

    -

    A pointer to the decoded string.

    -

    Description

    -

    The httpDecode64() function decodes a base-64 encoded - string to the original string.

    -

    Example

    -
    -#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpDecode64(original_string, encoded_string);
-
    -

    See Also

    - httpEncode64() - - -

    httpDelete()

    -

    Usage

    -
    -int
-httpDelete(http_t     *http,
-           const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to delete
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpDelete() function sends a HTTP DELETE request to - the server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpEncode64()

    -

    Usage

    -
    -char *
-httpEncode64(char       *out,
-             const char *in);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    outThe output string
    inThe input string
    -
    -

    Returns

    -

    A pointer to the encoded string.

    -

    Description

    -

    The httpEncode64() function decodes a base-64 encoded - string to the original string.

    -

    Example

    -
    -#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpEncode64(encoded_string, original_string);
-
    -

    See Also

    - httpDecode64() - - -

    httpEncryption()

    -

    Usage

    -
    -int
-httpEncryption(http_t            *http,
-               http_encryption_t encryption);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection.
    encryptionThe desired level of encryption.
    -
    -

    Returns

    -

    0 on success, -1 on error.

    -

    Description

    -

    httpEncryption() sets the encryption level for the HTTP - connection.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
-
    -

    See Also

    -

    httpConnectEncrypt() - -

    -

    httpError()

    -

    Usage

    -
    -int
-httpError(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Returns

    -

    The last error that occurred or 0 if no error has occurred.

    -

    Description

    -

    The httpError() function returns the last error that - occurred on the HTTP connection.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-if (httpError(http))
-{
-  ... show an error message ...
-}
-
    -

    See Also

    - httpConnect() - - -

    httpFlush()

    -

    Usage

    -
    -void
-httpFlush(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Description

    -

    The httpFlush() function flushes any remaining data left - from a GET or POST operation.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpFlush(http);
-
    -

    See Also

    - httpConnect(), - - -

    httpGet()

    -

    Usage

    -
    -int
-httpGet(http_t     *http,
-        const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to get
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpGet() function sends a HTTP GET request to the - server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpGet(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpGets()

    -

    Usage

    -
    -char *
-httpGets(char   *line,
-         int    length,
-         http_t *http)
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    lineThe string to fill with a line from the HTTP - connection
    lengthThe maximum length of the string
    httpThe HTTP connection
    -
    -

    Returns

    -

    A pointer to the string or NULL if no line could be retrieved.

    -

    Description

    -

    The httpGets() function is used to read a request line - from the HTTP connection. It is not normally used by a client program.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-char   line[1024];
-
-if (httpGets(line, sizeof(line), http))
-{
-  ... process the line ...
-}
-
    -

    See Also

    - httpConnect(), - httpUpdate() - - -

    httpGetDateString()

    -

    Usage

    -
    -const char *
-httpGetDateString(time_t time)
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    timeThe UNIX date/time value
    -
    -

    Returns

    -

    A pointer to a static string containing the HTTP date/time string for - the specified UNIX time value.

    -

    Description

    -

    The httpGetDateString() function generates a date/time - string suitable for HTTP requests from a UNIX time value.

    -

    Example

    -
    -#include <cups/http.h>
-
-puts(httpGetDateString(time(NULL)));
-
    -

    See Also

    - httpGetDateTime() - - -

    httpGetDateTime()

    -

    Usage

    -
    -time_t
-httpGetDateTime(const char *date)
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    dateThe HTTP date/time string
    -
    -

    Returns

    -

    A UNIX time value.

    -

    Description

    -

    The httpGetDateTime() function converts a HTTP date/time - string to a UNIX time value.

    -

    Example

    -
    -#include <cups/http.h>
-
-printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
-
    -

    See Also

    - httpGetDateString() - - -

    httpGetField()

    -

    Usage

    -
    -const char *
-httpGetField(http_t       *http,
-             http_field_t field);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    fieldThe HTTP field
    -
    -

    Returns

    -

    A pointer to the field value string.

    -

    Description

    -

    The httpGetField() function returns the current value - for the specified HTTP field.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
-
    -

    See Also

    - httpConnect(), - httpGetSubField(), -httpSetField() - - -

    httpGetHostByName()

    -

    Usage

    -
    -struct hostent	*
-httpGetHostByName(const char *name);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    nameName or IP address to lookup.
    -
    -

    Returns

    -

    NULL if the host could not be found or a pointer to a host entry - containing one or more addresses.

    -

    Description

    -

    httpGetHostByName() is a portable wrapper around the -gethostbyname() function which handles both hostnames and IP - addresses.

    -

    Example

    -
    -#include <cups/http.h>
-
-struct hostent *hostaddr;
-
-hostaddr = httpGetHostByName("foo.bar.com");
-
    - - -

    httpGetLength()

    -

    Usage

    -
    -int
-httpGetLength(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection.
    -
    -

    Returns

    -

    The content length of the response or MAX_INT if chunking is used.

    -

    Description

    -

    httpGetLength() returns the content length of a - response.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-printf("The length of the response is %d bytes.\n", httpGetLength(http));
-
    -

    See Also

    -

    httpGet(), -httpPost() - -

    -

    httpGetSubField()

    -

    Usage

    -
    -const char *
-httpGetSubField(http_t       *http,
-                http_field_t field,
-		const char   *name,
-		char         *value);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    httpThe HTTP connection.
    fieldThe HTTP field.
    nameThe name of the subfield.
    valueThe string to hold the subfield value.
    -
    -

    Returns

    -

    A pointer to the subfield value string or NULL if it does not exist.

    -

    Description

    -

    The httpGetSubField() function returns a subfield value - from the specified HTTP field. The destination string buffer must be at - least HTTP_MAX_VALUE bytes in length.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-char   value[HTTP_MAX_VALUE];
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
-
    -

    See Also

    - httpConnect(), - httpGetField(), -httpSetField() - - -

    httpHead()

    -

    Usage

    -
    -int
-httpHead(http_t     *http,
-         const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to head
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpHead() function sends a HTTP HEAD request to the - server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpHead(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpInitialize()

    -

    Usage

    -
    -void httpInitialize(void);
-
    -

    Description

    -

    The httpInitialize() function initializes the networking - code as needed by the underlying platform. It is called automatically - by the httpConnect() function.

    -

    Example

    -
    -#include <cups/http.h>
-
-httpInitialize();
-
    -

    See Also

    - httpConnect() - - -

    httpMD5()

    -

    Usage

    -
    -char *
-httpMD5(const char *username,
-        const char *realm,
-        const char *passwd,
-        char       md5[33]);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    usernameThe authenticating user name.
    realmThe authenticating realm name.
    passwdThe authenticating password.
    md5The MD5 sum string.
    -
    -

    Returns

    -

    A pointer to the MD5 sum string.

    -

    Description

    -

    httpMD5() computes the MD5 hash of the username, realm, - and password as required by the HTTP Digest specification.

    -

    Example

    -
    -#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5("user", "realm", "password", md5);
-
    -

    See Also

    -

    httpMD5Final(), - httpMD5String() - -

    -

    httpMD5Final()

    -

    Usage

    -
    -char *
-httpMD5Final(const char *nonce,
-             const char *method,
-             const char *resource,
-             char       md5[33]);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    nonceThe server nonce value.
    methodThe HTTP method (GET, POST, etc.)
    resourceThe resource path.
    md5The MD5 sum string.
    -
    -

    Returns

    -

    The MD5 sum string.

    -

    Description

    -

    httpMD5Final() appends the nonce, method, and resource - to the specified MD5 sum.

    -

    Example

    -
    -#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5Final("nonce", "GET", "/jobs", md5);
-
    -

    See Also

    -

    httpMD5(), - httpMD5String() - -

    -

    httpMD5String()

    -

    Usage

    -
    -char *
-httpMD5String(const md5_byte_t *sum,
-              char             md5[33]);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    sumThe raw MD5 sum data.
    md5The MD5 sum string.
    -
    -

    Returns

    -

    The MD5 sum string.

    -

    Description

    -

    httpMD5String() converts the raw MD5 sum value to a - string.

    -

    Example

    -
    -#include <cups/http.h>
-
-md5_byte_t sum[16];
-char       md5[33];
-
-...
-
-httpMD5String(sum, md5);
-
    -

    See Also

    -

    httpMD5(), - httpMD5Final() - -

    -

    httpOptions()

    -

    Usage

    -
    -int
-httpOptions(http_t     *http,
-            const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to check for options
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpOptions() function sends a HTTP OPTIONS request - to the server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpOptions(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpPost()

    -

    Usage

    -
    -int
-httpPost(http_t     *http,
-         const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to post to
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpPost() function sends a HTTP POST request to the - server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpPost(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpPrintf()

    -

    Usage

    -
    -int
-httpPrintf(http_t     *http,
-           const char *format,
-           ...);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    formatA printf-style format string
    -
    -

    Returns

    -

    The number of bytes written.

    -

    Description

    -

    The httpPrintf() function sends a formatted string to - the HTTP connection. It is normally only used by the CUPS API and - scheduler.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpPrintf(http, "GET / HTTP/1.1 \r\n");
-
    -

    See Also

    - httpConnect() - - -

    httpPut()

    -

    Usage

    -
    -int
-httpPut(http_t     *http,
-        const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to put
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpPut() function sends a HTTP PUT request to the - server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpRead()

    -

    Usage

    -
    -int
-httpRead(http_t *http,
-         char   *buffer,
-         int    length);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    bufferThe buffer to read into
    lengthThe number of bytes to read
    -
    -

    Returns

    -

    The number of bytes read or -1 on error.

    -

    Description

    -

    The httpRead() function reads data from the HTTP - connection, possibly the result of a GET or POST request.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-char buffer[1024];
-int  bytes;
-
-httpGet(http, "/");
-while (httpUpdate(http) != HTTP_CONTINUE);
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
-  buffer[bytes] = '\0';
-  fputs(buffer, stdout);
-}
-
    -

    See Also

    - httpConnect(), - httpWrite() - - -

    httpReconnect()

    -

    Usage

    -
    -int
-httpReconnect(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpReconnect() function reconnects to the HTTP - server. This is usually done automatically if the HTTP functions detect - that the server connection has terminated.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpReconnect(http);
-
    -

    See Also

    - httpConnect() - - -

    httpSeparate()

    -

    Usage

    -
    -void
-httpSeparate(const char *uri,
-             char       *method,
-             char       *username,
-             char       *host,
-             int        *port,
-             char       *resource);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    uriThe URI to separate
    methodThe method (scheme) of the URI
    usernameThe username (and password) portion of the URI, - if any
    hostThe hostname portion of the URI, if any
    portThe port number for the URI, either as specified or - as default for the method/scheme
    resourceThe resource string, usually a filename on the - server
    -
    -

    Description

    -

    The httpSeparate() function separates the specified URI - into its component parts. The method, username, hostname, and resource - strings should be at least HTTP_MAX_URI characters long to - avoid potential buffer overflow problems.

    -

    Example

    -
    -char uri[HTTP_MAX_URI];
-char method[HTTP_MAX_URI];
-char username[HTTP_MAX_URI];
-char host[HTTP_MAX_URI];
-char resource[HTTP_MAX_URI];
-int  port;
-
-...
-
-httpSeparate(uri, method, username, host, &port, resource);
-
    -

    See Also

    - httpConnect() - - -

    httpSetField()

    -

    Usage

    -
    -void
-httpSetField(http_t       *http,
-             http_field_t field,
-             const char   *value);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    fieldThe HTTP field
    valueThe string value for the field
    -
    -

    Description

    -

    The httpSetField() function sets the current value for - the specified HTTP field.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
    -

    See Also

    - httpConnect(), - httpGetField() - - -

    httpStatus()

    -

    Usage

    -
    -const char *
-httpStatus(http_status_t status);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    statusThe HTTP status code from the server.
    -
    -

    Returns

    -

    The standard HTTP status text associated with the status code.

    -

    Description

    -

    httpStatus() returns the standard HTTP status text - associated with the status code.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-puts(httpStatus(http->status));
-
    - - -

    httpTrace()

    -

    Usage

    -
    -int
-httpTrace(http_t     *http,
-          const char *uri);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to trace
    -
    -

    Returns

    -

    0 on success, non-zero on failure.

    -

    Description

    -

    The httpTrace() function sends a HTTP TRACE request to - the server.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpTrace(http, "/some/uri");
-
    -

    See Also

    - httpConnect(), - httpSetField(), -httpUpdate() - - -

    httpUpdate()

    -

    Usage

    -
    -http_status_t
-httpUpdate(http_t *http);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    httpThe HTTP connection
    -
    -

    Returns

    -

    The HTTP status of the current request.

    -

    Description

    -

    The httpUpdate() function updates the current request - status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or - TRACE request to finalize the HTTP request and retrieve the request - status.

    -

    Since proxies and the current blocking mode can cause the request to - take longer, programs should continue calling httpUpdate() -until the return status is not the constant value HTTP_CONTINUE -.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-http_status_t status;
-
-httpGet(http, "/some/uri");
-while ((status = httpUpdate(http)) == HTTP_CONTINUE);
-printf("Request status is %d\n", status);
-
    -

    See Also

    - httpConnect(), - httpDelete(), httpGet() -, httpHead(), - httpOptions(), httpPost() -, httpPut(), - httpTrace() - - -

    httpWrite()

    -

    Usage

    -
    -int
-httpWrite(http_t *http,
-          char   *buffer,
-          int    length);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    bufferThe buffer to read into
    lengthThe number of bytes to read
    -
    -

    Returns

    -

    The number of bytes read or -1 on error.

    -

    Description

    -

    The httpWrite() function reads data from the HTTP - connection, possibly the result of a GET or POST request.

    -

    Example

    -
    -#include <cups/http.h>
-
-http_t *http;
-FILE *fp;
-char buffer[1024];
-int  bytes;
-
-httpPost(http, "/");
-
-while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
-  httpWrite(http, buffer, bytes);
-
-while (httpUpdate(http) != HTTP_CONTINUE);
-
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
-  buffer[bytes] = '\0';
-  fputs(buffer, stdout);
-}
-
    -

    See Also

    - httpConnect(), - httpRead() - - -

    ippAddBoolean()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddBoolean(ipp_t      *ipp,
-              ipp_tag_t  group,
-              const char *name,
-	      char       value);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    valueThe boolean value
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddBoolean() function adds a single boolean - attribute value to the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
-
    -

    See Also

    - ippAddBooleans(), - ippAddDate(), -ippAddInteger(), -ippAddIntegers(), ippAddRange() -, ippAddRanges(), - ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddBooleans()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddBooleans(ipp_t      *ipp,
-               ipp_tag_t  group,
-               const char *name,
-               int        num_values,
-               const char *values);
-
    -

    Arguments

    -
    - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of values
    valuesThe boolean values
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddBooleans() function adds one or more boolean - attribute values to the specified IPP request. If the values - pointer is NULL then an array of num_values - false values is created.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-char values[10];
-
-ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
-
    -

    See Also

    - ippAddBoolean(), - ippAddDate(), -ippAddInteger(), -ippAddIntegers(), ippAddRange() -, ippAddRanges(), - ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddDate()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddDate(ipp_t       *ipp,
-           ipp_tag_t   group,
-           const char  *name,
-           ipp_uchar_t *value);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    valueThe date value
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddDate() function adds a single date-time - attribute value to the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", 
-           ippTimeToDate(time(NULL));
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddInteger(), -ippAddIntegers(), ippAddRange() -, ippAddRanges(), - ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings(), -ippTimeToDate() - - -

    ippAddInteger()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddInteger(ipp_t      *ipp,
-              ipp_tag_t  group,
-              ipp_tag_t  tag,
-              const char *name,
-              int        value);
-
    -

    Arguments

    -
    - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of integer value (IPP_TAG_INTEGER or - IPP_TAG_ENUM)
    nameThe name of attribute
    valueThe integer value
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddInteger() function adds a single integer - attribute value to the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), -ippAddIntegers(), ippAddRange() -, ippAddRanges(), - ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddIntegers()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddIntegers(ipp_t      *ipp,
-               ipp_tag_t  group,
-               ipp_tag_t  tag,
-               const char *name,
-               int        num_values,
-               const int  *values);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of integer value (IPP_TAG_INTEGER or - IPP_TAG_ENUM)
    nameThe name of attribute
    num_valuesThe number of values
    valuesThe integer values
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddIntegers() function adds one or more integer - attribute values to the specified IPP request. If the values - pointer is NULL then an array of num_values 0 - values is created.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int values[100];
-
-ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddRange(), - ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddRange()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddRange(ipp_t      *ipp,
-            ipp_tag_t  group,
-            const char *name,
-            int        low,
-            int        high);
-
    -

    Arguments

    -
    - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    lowThe lower value
    highThe higher value
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddRange() function adds a single range attribute - value to the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddRanges()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddRanges(ipp_t      *ipp,
-             ipp_tag_t  group,
-             const char *name,
-             int        num_values,
-             const int  *lows,
-             const int  *highs);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of range values
    lowsThe lower values
    highsThe higher values
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddRanges() function adds one or more range - attribute values to the specified IPP request. If the values - pointer is NULL then an array of num_values - 0,0 ranges is created.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int lows[2];
-int highs[2];
-
-ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddResolution()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddResolution(ipp_t      *ipp,
-                 ipp_tag_t  group,
-                 const char *name,
-                 int        xres,
-                 int        yres,
-                 ipp_res_t  units);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    xresThe horizontal resolution
    yresThe vertical resolution
    unitsThe resolution units
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddResolution() function adds a single resolution - attribute value to the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
-              720, 720, IPP_RES_PER_INCH);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddRanges(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddResolutions()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddResolutions(ipp_t           *ipp,
-                  ipp_tag_t       group,
-                  const char      *name,
-                  int             num_values,
-                  const int       *xres,
-                  const int       *yres,
-                  const ipp_res_t *units);
-
    -

    Arguments

    -
    - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of resolution values
    xresThe horizontal resolutions
    yresThe vertical resolutions
    unitsThe resolution units
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddResolutions() function adds one or more - resolution attribute values to the specified IPP request. If the -values pointer is NULL then an array of -num_values 0,0 resolutions is created.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int xres[5];
-int yres[5];
-ipp_res_t units[5];
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
-              5, xres, yres, units);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddSeparator()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddSeparator(ipp_t *ipp);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ippThe IPP request
    -
    -

    Returns

    -

    A pointer to the new separator or NULL if the separator could not be - created.

    -

    Description

    -

    The ippAddSeparator() function adds a group separator to - the specified IPP request.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddSeparator(ipp);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddString(), -ippAddStrings() - - -

    ippAddString()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddString(ipp_t      *ipp,
-             ipp_tag_t  group,
-             ipp_tag_t  tag,
-             const char *name,
-             const char *charset,
-             const char *value);
-
    -

    Arguments

    -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of string value
    nameThe name of attribute
    charsetThe character set for the string
    valueThe string value
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddString() function adds a single string - attribute value to the specified IPP request. For -IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the - charset value is provided with the string to identify the string - encoding used. Otherwise the charset value is ignored.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
-             NULL, "abc123");
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddStrings() - - -

    ippAddStrings()

    -

    Usage

    -
    -ipp_attribute_t *
-ippAddStrings(ipp_t      *ipp,
-              ipp_tag_t  group,
-              ipp_tag_t  tag,
-              const char *name,
-              int        num_values,
-              const char *charset,
-              const char **values);
-
    -

    Arguments

    -
    - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of string value
    nameThe name of attribute
    num_valuesThe number of strings
    charsetThe character set for the strings
    valuesThe string values
    -
    -

    Returns

    -

    A pointer to the new attribute or NULL if the attribute could not be - created.

    -

    Description

    -

    The ippAddStrings() function adds one or more string - attribute values to the specified IPP request. For -IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the - charset value is provided with the strings to identify the string - encoding used. Otherwise the charset value is ignored. If the -values pointer is NULL then an array of -num_values NULL strings is created.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-char *values[2] = { "one", "two" };
-
-ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
-              2, NULL, values);
-
    -

    See Also

    - ippAddBoolean(), - ippAddBooleans(), -ippAddDate(), ippAddInteger() -, ippAddIntegers(), - ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString() - - -

    ippDateToTime()

    -

    Usage

    -
    -time_t
-ippDateToTime(const ipp_uchar_t date[11]);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    dateThe IPP date-time value
    -
    -

    Returns

    -

    A UNIX time value.

    -

    Description

    -

    The ippDateToTime() function converts an IPP date-time - value to a UNIX time value.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_uchar_t date[11];
-
-printf("UNIX time is %d\n", ippDateToTime(date));
-
    -

    See Also

    - ippTimeToDate() - - -

    ippDelete()

    -

    Usage

    -
    -void
-ippDelete(ipp_t *ipp);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ippThe IPP request or response
    -
    -

    Description

    -

    The ippDelete() function deletes all memory used by an - IPP request or response.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippDelete(ipp);
-
    -

    See Also

    - ippNew() - - -

    ippErrorString()

    -

    Usage

    -
    -const char *
-ippErrorString(ipp_status_t error);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    errorIPP error code.
    -
    -

    Returns

    -

    The standard text representation of the IPP error code.

    -

    Description

    -

    ippErrorString() returns the standard text - representation of the IPP error code.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-puts(ippErrorString(IPP_OK));
-
    -

    See Also

    -

    cupsLastError() - -

    -

    ippFindAttribute()

    -

    Usage

    -
    -ipp_attribute_t *
-ippFindAttribute(ipp_t      *ipp,
-                 const char *name,
-                 ipp_tag_t  tag);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    nameThe name of the attribute
    tagThe required value tag for the attribute or -IPP_TAG_ZERO for any type of value.
    -
    -

    Returns

    -

    A pointer to the first occurrence of the requested attribute, or -NULL if it was not found.

    -

    Description

    -

    ippFindAttribute() finds the first occurrence of the - named attribute. The tag parameter restricts the search to - a specific value type - use IPP_TAG_ZERO to find any value - with the name.

    -

    The value tags IPP_TAG_NAME and IPP_TAG_TEXT - match the name/text values with or without the language code.

    -

    Example

    -
    -ipp_attribute_t *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
-  puts(attr->values[0].string.text);
-
-  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-
    -

    See Also

    - cupsDoFileRequest(), - cupsDoRequest(), -ippDelete(), -ippFindNextAttribute(), ippNew() - - - -

    ippFindNextAttribute()

    -

    Usage

    -
    -ipp_attribute_t *
-ippFindNextAttribute(ipp_t      *ipp,
-                     const char *name,
-                     ipp_tag_t  tag);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    nameThe name of the attribute
    tagThe required value tag for the attribute or -IPP_TAG_ZERO for any type of value.
    -
    -

    Returns

    -

    A pointer to the next occurrence of the requested attribute, or -NULL if it was not found.

    -

    Description

    -

    ippFindNextAttribute() finds the next occurrence of the - named attribute. The tag parameter restricts the search to - a specific value type - use IPP_TAG_ZERO to find any value - with the name.

    -

    The value tags IPP_TAG_NAME and IPP_TAG_TEXT - match the name/text values with or without the language code.

    -

    Example

    -
    -ipp_attribute_t *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
-  puts(attr->values[0].string.text);
-
-  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-
    -

    See Also

    - cupsDoFileRequest(), - cupsDoRequest(), -ippDelete(), -ippFindNextAttribute(), ippNew() - - - -

    ippLength()

    -

    Usage

    -
    -int
-ippLength(ipp_t *ipp);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ippThe IPP request or response
    -
    -

    Returns

    -

    The total encoded length of the IPP request or response in bytes.

    -

    Description

    -

    ippLength() returns the length of the IPP request or - response in bytes.

    -

    Example

    -
    -printf("The length of the response is %d bytes.\n", ippLength(response));
-
    -

    See Also

    - ippDelete(), -ippNew() - - -

    ippNew()

    -

    Usage

    -
    -ipp_t *
-ippNew(void);
-
    -

    Returns

    -

    A pointer to a new IPP request or response.

    -

    Description

    -

    The ippNew() function creates a new IPP request or - response.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ipp = ippNew();
-
    -

    See Also

    - ippDelete() - - -

    ippPort()

    -

    Usage

    -
    -int
-ippPort(void);
-
    -

    Returns

    -

    The default TCP/IP port number for IPP requests.

    -

    Description

    -

    The ippPort() function returns the default IPP port - number for requests.

    -

    Example

    -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-
-http = httpConnect(cupsServer(), ippPort());
-
    -

    See Also

    - cupsServer(), - ippSetPort() - - -

    ippRead()

    -

    Usage

    -
    -ipp_state_t
-ippRead(http_t *http,
-        ipp_t  *ipp);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    ippThe IPP request or response
    -
    -

    Returns

    -

    The current read state.

    -

    Description

    -

    The ippRead() function reads IPP attributes from the - specified HTTP connection. Programs should continue calling -ippRead() until IPP_ERROR or IPP_DATA - is returned.

    -

    Example

    -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-
-while ((status = ippRead(http, ipp)) != IPP_ERROR)
-  if (status == IPP_DATA)
-    break;
-
-if (status == IPP_DATA)
-{
-  ... read additional non-IPP data using httpRead() ...
-}
-
    -

    See Also

    - ippWrite() - - -

    ippSetPort()

    -

    Usage

    -
    -void
-ippSetPort(int port);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    portThe port number to use
    -
    -

    Description

    -

    The ippSetPort() function sets the default IPP port - number for requests.

    -

    Example

    -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-...
-
-ippSetPort(8631);
-
    -

    See Also

    - ippPort() - - -

    ippTimeToDate()

    -

    Usage

    -
    -ipp_uchar_t *
-ippTimeToDate(time_t time);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    timeThe UNIX time value
    -
    -

    Returns

    -

    A static pointer to an IPP date-time value.

    -

    Description

    -

    The ippTimeToDate() function converts a UNIX time to an - IPP date-time value.

    -

    Example

    -
    -#include <cups/ipp.h>
-
-ipp_uchar_t *date;
-
-date = ippTimeToDate(time(NULL));
-
    -

    See Also

    - ippDateToTime() - - -

    ippWrite()

    -

    Usage

    -
    -ipp_state_t
-ippWrite(http_t *http,
-         ipp_t  *ipp);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    httpThe HTTP connection
    ippThe IPP request or response
    -
    -

    Returns

    -

    The current write state.

    -

    Description

    -

    The ippWrite() function writes IPP attributes to the - specified HTTP connection. Programs should continue calling -ippWrite() until IPP_ERROR or IPP_DATA - is returned.

    -

    Example

    -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-... add attributes ...
-
-while ((status = ippWrite(http, ipp)) != IPP_ERROR)
-  if (status == IPP_DATA)
-    break;
-
-if (status == IPP_DATA)
-{
-  ... read additional non-IPP data using httpWrite() ...
-}
-
    -

    See Also

    - ippRead() - - -

    ppdClose()

    -

    Usage

    -
    -void
-ppdClose(ppd_file_t *ppd);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ppdThe PPD file
    -
    -

    Description

    -

    The ppdClose() function frees all memory associated with - the PPD file.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdClose(ppd);
-
    -

    See Also

    - ppdOpen(), -ppdOpenFd(), ppdOpenFile() - - - -

    ppdCollect()

    -

    Usage

    -
    -int
-ppdCollect(ppd_file_t    *ppd,
-           ppd_section_t section,
-           ppd_choice_t  ***choices);
-
    -

    Arguments

    -
    - - - - - - -
    ArgumentDescription
    ppdThe PPD file.
    sectionThe document section to collect.
    choicesThe array of option choices that are marked.
    -
    -

    Returns

    -

    The number of options collected.

    -

    Description

    -

    ppdCollect() collects all of the marked options in the - specified section, sorts them by their order dependency values, and - returns an array that can be used to emit option commands in the proper - order. It is normally used by the ppdEmit*() functions.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t   *ppd;
-int          num_choices;
-ppd_choice_t **choices;
-
-...
-
-num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices);
-
    -

    See Also

    -

    ppdEmit(), -ppdEmitFd(), ppdEmitJCL() - - -

    -

    ppdConflicts()

    -

    Usage

    -
    -int
-ppdConflicts(ppd_file_t *ppd);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ppdThe PPD file
    -
    -

    Returns

    -

    The number of option conflicts in the file.

    -

    Description

    -

    The ppdConflicts() function returns the number of - conflicts with the currently selected options.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("%d conflicts\n", ppdConflicts(ppd));
-
    -

    See Also

    - cupsMarkOptions(), - ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdEmit()

    -

    Usage

    -
    -int
-ppdEmit(ppd_file_t    *ppd,
-        FILE          *file,
-        ppd_section_t section);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ppdThe PPD file
    fileThe file to write to
    sectionThe option section to write
    -
    -

    Returns

    -

    0 on success, -1 on error.

    -

    Description

    -

    The ppdEmit() function sends printer-specific option - commands to the specified file.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
-
    -

    See Also

    - ppdEmitFd() - - -

    ppdEmitFd()

    -

    Usage

    -
    -int
-ppdEmitFd(ppd_file_t    *ppd,
-          int           fd,
-          ppd_section_t section);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ppdThe PPD file
    fdThe file descriptor to write to
    sectionThe option section to write
    -
    -

    Returns

    -

    0 on success, -1 on error.

    -

    Description

    -

    The ppdEmitFd() function sends printer-specific option - commands to the specified file descriptor.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
-
    -

    See Also

    - ppdEmit() - - -

    ppdFindChoice()

    -

    Usage

    -
    -ppd_choice_t *
-ppdFindChoice(ppd_option_t *option,
-              const char   *choice);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    optionA pointer to the option
    choiceThe name of the choice
    -
    -

    Returns

    -

    A pointer to the choice data or NULL if the choice does not exist.

    -

    Description

    -

    The ppdFindChoice() function returns a pointer to the - choice data for the specified option.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-ppd_choice_t *choice;
-
-option = ppdFindOption(ppd, "PageSize");
-choice = ppdFindChoice(option, "Letter");
-
    -

    See Also

    - ppdFindMarkedChoice(), ppdFindOption() - - -

    ppdFindMarkedChoice()

    -

    Usage

    -
    -ppd_choice_t *
-ppdFindMarkedChoice(ppd_file_t *ppd,
-                    const char *keyword);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    -
    -

    Returns

    -

    A pointer to the choice data or NULL if the choice does not exist or - is not marked.

    -

    Description

    -

    The ppdFindMarkedChoice() function returns a pointer to - the marked choice data for the specified option.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_choice_t *choice;
-
-choice = ppdFindMarkedChoice(ppd, "PageSize");
-
    -

    See Also

    - ppdFindChoice(), - ppdFindOption() - - -

    ppdFindOption()

    -

    Usage

    -
    -ppd_option_t *
-ppdFindOption(ppd_file_t *ppd,
-              const char *keyword);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    -
    -

    Returns

    -

    A pointer to the option data or NULL if the option does not exist.

    -

    Description

    -

    The ppdFindOption() function returns a pointer to the - option data for the specified option.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-
-option = ppdFindOption(ppd, "PageSize");
-
    -

    See Also

    - ppdFindChoice(), - ppdFindMarkedChoice() - - -

    ppdIsMarked()

    -

    Usage

    -
    -int
-ppdIsMarked(ppd_file_t *ppd,
-            const char *keyword,
-            const char *choice);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    choiceThe name of the option choice
    -
    -

    Returns

    -

    1 if the choice is marked, 0 otherwise.

    -

    Description

    -

    The ppdIsMarked() function returns whether or not the - specified option choice is marked.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Letter size %s selected.\n",
-       ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
-
    -

    See Also

    - cupsMarkOptions(), - ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdMarkDefaults()

    -

    Usage

    -
    -void
-ppdMarkDefaults(ppd_file_t *ppd);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    ppdThe PPD file
    -
    -

    Description

    -

    The ppdMarkDefaults() function marks all of the default - choices in the PPD file.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkDefaults(ppd);
-
    -

    See Also

    - cupsMarkOptions(), - ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdMarkOption()

    -

    Usage

    -
    -int
-ppdMarkOption(ppd_file_t *ppd,
-              const char *keyword,
-              const char *choice);
-
    -

    Arguments

    -
    - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    choiceThe name of the choice
    -
    -

    Returns

    -

    The number of conflicts in the PPD file.

    -

    Description

    -

    The ppdMarkOption() function marks the specified option - choice.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkOption(ppd, "PageSize", "Letter");
-
    -

    See Also

    - cupsMarkOptions(), - ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdOpen()

    -

    Usage

    -
    -ppd_file_t *
-ppdOpen(FILE *file);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    fileThe file to read from
    -
    -

    Returns

    -

    A pointer to a PPD file structure or NULL if the PPD file could not - be read.

    -

    Description

    -

    The ppdOpen() function reads a PPD file from the - specified file into memory.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-FILE *file;
-
-file = fopen("filename.ppd", "rb");
-ppd = ppdOpen(file);
-fclose(file);
-
    -

    See Also

    - ppdClose(), -ppdOpenFd(), ppdOpenFile() - - - -

    ppdOpenFd()

    -

    Usage

    -
    -ppd_file_t *
-ppdOpenFd(int fd);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    fdThe file descriptor to read from
    -
    -

    Returns

    -

    A pointer to a PPD file structure or NULL if the PPD file could not - be read.

    -

    Description

    -

    The ppdOpenFd() function reads a PPD file from the - specified file descriptor into memory.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-int        fd;
-
-fd = open("filename.ppd", O_RDONLY);
-ppd = ppdOpenFd(fd);
-close(fd);
-
    -

    See Also

    - ppdClose(), -ppdOpen(), ppdOpenFile() - - -

    ppdOpenFile()

    -

    Usage

    -
    -ppd_file_t *
-ppdOpenFile(const char *filename);
-
    -

    Arguments

    -
    - - - -
    ArgumentDescription
    filenameThe name of the file to read from
    -
    -

    Returns

    -

    A pointer to a PPD file structure or NULL if the PPD file could not - be read.

    -

    Description

    -

    The ppdOpenFile() function reads a PPD file from the - named file into memory.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("filename.ppd");
-
    -

    See Also

    - ppdClose(), -ppdOpen(), ppdOpenFd() - - -

    ppdPageLength()

    -

    Usage

    -
    -float
-ppdPageLength(ppd_file_t *ppd,
-              const char *name);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    -
    -

    Returns

    -

    The length of the specified page size in points or 0 if the page size - does not exist.

    -

    Description

    -

    The ppdPageLength() function returns the page length of - the specified page size.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
-
    -

    See Also

    - ppdPageLength(), - ppdPageSize(), -ppdPageWidth() - - -

    ppdPageSize()

    -

    Usage

    -
    -ppd_size_t *
-ppdPageSize(ppd_file_t *ppd,
-            const char *name);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    -
    -

    Returns

    -

    A pointer to the page size record of the specified page size in - points or NULL if the page size does not exist.

    -

    Description

    -

    The ppdPageSize() function returns the page size record - for the specified page size.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-
-size = ppdPageSize(ppd, "Letter");
-if (size != NULL)
-{
-  printf(" Width = %.0f\n", size->width);
-  printf("Length = %.0f\n", size->length);
-  printf("  Left = %.0f\n", size->left);
-  printf(" Right = %.0f\n", size->right);
-  printf("Bottom = %.0f\n", size->bottom);
-  printf("   Top = %.0f\n", size->top);
-}
-
    -

    See Also

    - ppdPageLength(), - ppdPageWidth() - - -

    ppdPageWidth()

    -

    Usage

    -
    -float
-ppdPageWidth(ppd_file_t *ppd,
-             const char *name);
-
    -

    Arguments

    -
    - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    -
    -

    Returns

    -

    The width of the specified page size in points or 0 if the page size - does not exist.

    -

    Description

    -

    The ppdPageWidth() function returns the page width of - the specified page size.

    -

    Example

    -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
-
    -

    See Also

    - ppdPageLength(), - ppdPageSize() - diff --git a/doc/spm.pdf b/doc/spm.pdf deleted file mode 100644 index f6a76cc2f6..0000000000 Binary files a/doc/spm.pdf and /dev/null differ diff --git a/doc/spm.shtml b/doc/spm.shtml deleted file mode 100644 index a63ad396fa..0000000000 --- a/doc/spm.shtml +++ /dev/null @@ -1,10202 +0,0 @@ - - - - - - CUPS Software Programmers Manual - - - -

    Preface

    - -

    This software programmers manual provides software -programming information for the Common UNIX Printing System -("CUPS") Version 1.2.0. - - - - -

    Document Overview

    - -

    This software programmers manual is organized into the following sections: - -

    - -

    Notation Conventions

    - -

    Various font and syntax conventions are used in this guide. Examples and -their meanings and uses are explained below: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Example   Description
     
    lpstat
    - lpstat(1)    		   The names of commands; the first mention of a command or - function in a chapter is followed by a manual page section - number.
     
    /var
    - /usr/share/cups/data/testprint.ps    		   File and directory names.
     
    Request ID is Printer-123   Screen output.
     
    lp -d printer filename ENTER   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are written using the period (.) to indicate - the decimal point.
    - - -

    Abbreviations

    - -The following abbreviations are used throughout this manual: - -
      -
      - -
      kb -
      Kilobytes, or 1024 bytes
        - -
      Mb -
      Megabytes, or 1048576 bytes
        - -
      Gb -
      Gigabytes, or 1073741824 bytes
        - -
      -
    - -

    Other References

    - -
      -
      - -
      CUPS Software Administrators Manual - -
      An administration guide for the CUPS software.
        - -
      CUPS Software Users Manual - -
      An end-user guide for using the CUPS software.
        - -
      -
    - - - - - -

    2 - The CUPS API

    - -

    This chapter describes the CUPS Application Programmers Interface ("API"). - -

    The CUPS API Library

    - -

    The CUPS library provides a whole collection of interfaces needed to -support the internal needs of the CUPS software as well as the needs of -applications, filters, printer drivers, and backends. - -

    Unlike the rest of CUPS, the CUPS API library is provided under the -GNU Library General Public License. This means that you can use the -CUPS API library in both proprietary and open-source programs. - -

    Programs that use the CUPS API library typically will include the -<cups/cups.h> header file: - -

      -#include <cups/cups.h>
-
-...
-
-jobid = cupsPrintFile("myprinter", "filename.ps", "title",
-                      num_options, options);
-
    - -

    Use the -lcups compiler option when linking to the CUPS API -library: - -

      -cc -o program program.c -lcups ENTER
-
    - -

    Additional options and libraries may be required depending on the -operating system and the location of the CUPS API library. - -

    Detecting the CUPS API Library in GNU Autoconf

    - -

    GNU autoconf is a popular configuration tool used by many programs. -Add the following lines to your configure.in file to check -for the CUPS API library in your configuration script: - -

      -AC_CHECK_LIB(socket,socket,
-if test "$uname" != "IRIX"; then
-	LIBS="-lsocket $LIBS"
-else
-	echo "Not using -lsocket since you are running IRIX."
-fi)
-AC_CHECK_LIB(nsl,gethostbyaddr,
-if test "$uname" != "IRIX"; then
-	LIBS="-lnsl $LIBS"
-else
-	echo "Not using -lnsl since you are running IRIX."
-fi)
-
-AC_CHECK_LIB(cups,httpConnect)
-
    - -

    Printing Services

    - -

    The CUPS API library provides some basic printing services for applications -that need to print files. - -

    Include Files

    - -

    The include file used by all of these functions is -<cups/cups.h>: - -

      -#include <cups/cups.h>
-
    - -

    Printing a File

    - -

    The CUPS API provides two functions for printing files. The first is -cupsPrintFile which prints a single named file: - -

      -#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-jobid = cupsPrintFile("name", "filename", "title", 0, NULL);
-
    - -

    The name string is the name of the printer or class to -print to. The filename string is the name of the file to -print. The title string is the name of the print job, e.g. -"Acme Word Document". - -

    The return value is a unique ID number for the print job or 0 if there -was an error. - -

    Printing Multiple Files

    - -

    The second printing function is cupsPrintFiles: - -

      -#include <cups/cups.h>
-
-...
-
-int        jobid;
-int        num_files;
-const char *files[100];
-...
-
-jobid = cupsPrintFiles("name", num_files, files, "title", 0, NULL);
-
    - -

    Instead of passing a filename string as with cupsPrintFile() -you pass a file count (num_files) and filename pointer array -(files) for each file that you want to print. - -

    As with cupsPrintFile() the return value is a unique ID for -the print job. - -

    Cancelling Jobs

    - -

    The cupsCancelJob() function cancels a queued print job: - -

      -#include <cups/cups.h>
-
-...
-
-int jobid;
-int status;
-...
-
-status = cupsCancelJob("name", jobid);
-
    - -

    The name string specifies the destination and is used -to determine the server to send the request to. The jobid -value is the integer returned from a previous cupsPrintFile() -or cupsPrintFiles() call. - -

    cupsCancelJob() returns 1 if the job was -successfully cancelled and 0 if there was an error. - -

    Getting the Available Printers and Classes

    - -

    The cupsGetDests() function can be used to get a list -of the available printers, classes, and instances that a user has defined: - -

      -#include <cups/cups.h>
-
-...
-
-int         num_dests;
-cups_dest_t *dests;
-
-...
-
-num_dests = cupsGetDests(&dests);
-
    - -

    Each destination is stored in a cups_dest_t structure which -defines the printer or class name, the instance name (if any), if it is the -default destination, and the default options the user has defined for the -destination: - -

      -typedef struct               /**** Destination ****/
-{
-  char          *name,       /* Printer or class name */
-                *instance;   /* Local instance name or NULL */
-  int           is_default;  /* Is this printer the default? */
-  int           num_options; /* Number of options */
-  cups_option_t *options;    /* Options */
-} cups_dest_t;
-
    - -

    The destinations are sorted by name and instance for your convenience. -Once you have the list of available destinations, you can lookup a specific -destination using the cupsGetDest() function: - -

      -#include <cups/cups.h>
-
-...
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("name", "instance", num_dests, dests);
-
    - -

    The name string is the printer or class name. You can pass -a value of NULL to get the default destination. - -

    The instance string is the user-defined instance name. Pass -NULL to select the default instance, e.g. "name" instead of -"name/instance". - -

    Printing with Options

    - -

    All of the previous printing examples have passed 0 and -NULL for the last two arguments to the cupsPrintFile() -and cupsPrintFiles() functions. These last two arguments are the -number of options and a pointer to the option array: - -

      -int cupsPrintFile(const char *name, const char *filename, const char *title,
-                  int num_options, cups_option_t *options);
-int cupsPrintFiles(const char *name, int num_files, const char **files,
-                   const char *title, int num_options,
-		   cups_option_t *options);
-
    - -

    The cups_option_t structure holds each option and its value. -These are converted as needed and passed to the CUPS server when printing a -file. - -

    The simplest way of handling options is to use the num_options -and options members of the cups_dest_t -structure described earlier: - -

      -#include <cups/cups.h>
-
-...
-
-int         jobid;
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("name", "instance", num_dests, dests);
-
-jobid  = cupsPrintFile(mydest->name, "filename", "title",
-                       mydest->num_options, mydest->options);
-
    - -

    This effectively uses the options a user has previous selected without a -lot of code. - -

    Setting Printer Options

    - -

    Options can also be set by your program using the cupsAddOption() -function: - -

      -#include <cups/cups.h>
-
-...
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-num_options = 0;
-options     = NULL;
-
-...
-
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-num_options = cupsAddOption("name", "value", num_options, &options);
-
    - -

    The name string is the name of the option, and the -value string is the value for that option. - -

    Each call to cupsAddOption() returns the new number of -options. Since adding two options with the same name overwrites the -first value with the second, do not assume that calling -cupsAddOptions() 20 times will result in 20 options. - -

    Call cupsFreeOptions once you are done using the options: - -

      -#include <cups/cups.h>
-
-...
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-
    - -

    Getting Errors

    - -

    If any of the CUPS API printing functions returns an error, the reason for -that error can be found by calling cupsLastError() and -cupsErrorString(). cupsLastError() returns the -last IPP error code that was encountered. cupsErrorString() -converts the error code to a localized message string suitable for -presentation to the user: - -

      -#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-if (jobid == 0)
-  puts(cupsErrorString(cupsLastError()));
-
    - -

    Passwords and Authentication

    - -

    CUPS supports authentication of any request, including -submission of print jobs. The default mechanism for getting the -username and password is to use the login user and a password -from the console. - -

    To support other types of applications, in particular -Graphical User Interfaces ("GUIs"), the CUPS API provides -functions to set the default username and to register a callback -function that returns a password string. - -

    The cupsSetPasswordCB() -function is used to set a password callback in your program. Only one -function can be used at any time. - -

    The cupsSetUser() function sets -the current username for authentication. This function can be called by -your password callback function to change the current username as needed. - -

    The following example shows a simple password callback that gets a -username and password from the user: - -

      -#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
-  char	user[65];
-
-
-  puts(prompt);
-
- /* Get a username from the user */
-  printf("Username: ");
-  if (fgets(user, sizeof(user), stdin) == NULL)
-    return (NULL);
-
- /* Strip the newline from the string and set the user */
-  user[strlen(user) - 1] = '\0';
-
-  cupsSetUser(user);
-
- /* Use getpass() to ask for the password... */
-  return (getpass("Password: "));
-}
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-
    - -

    Similarly, a GUI interface could display the prompt string in a -window with input fields for the username and password. The username -should probably default to the value of -cupsUser() to make things easier -on the user. - -

    PPD Services

    - -

    CUPS includes functions to access and manipulate PostScript Printer -Description ("PPD") files that are used with the printer drivers in CUPS. - -

    Each PPD file enumerates the available features provided by a -printer, including conflict information for specific options (e.g. -can't duplex output on envelopes.) - -

    Include Files

    - -

    Include the <cups/ppd.h> header file to use the PPD -functions: - -

      -#include <cups/ppd.h>
-
    - -

    This header file is also included by the -<cups/cups.h> header file. - -

    Getting a PPD File for a Printer

    - -

    The cupsGetPPD() function retrieves the PPD file for the -named printer or class: - -

      -#include <cups/cups.h>
-
-...
-
-const char *filename;
-
-filename = cupsGetPPD("name");
-
    - -

    The name string is the name of the printer or class, including -the remote server name as appropriate (e.g. "printer@server".) - -

    The return value is a pointer to a filename in static storage; this value -is overwritten with each call to cupsGetPPD(). If the printer -or class does not exist, a NULL pointer will be returned. - -

    Loading a PPD File

    - -

    The ppdOpenFile() function "opens" a PPD file and loads it -into memory: - -

      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("filename");
-
    - -

    The filename string is the name of the file to load, such as -the value returned by the cupsGetPPD() function. - -

    The return value is a pointer to a structure describing the contents of the -PPD file or NULL if the PPD file could not be read. - -

    Freeing PPD File Information

    - -

    Once you are done using a PPD file, call the ppdClose() function -to free all memory that has been used: - -

      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdClose(ppd);
-
    - -

    The PPD File Structure

    - -

    Each PPD file contains a number of capability attributes, printer options, -and conflict definitions. The page size options also include the physical -margins for the printer and the minimum and maximum sizes for the printer. -All of this information is stored in the ppd_file_t structure. - -

    Capabilities

    - -

    Each PPD file contains a number of informational attributes that -describe the capabilities of the printer. These are provided in the -ppd_file_t structure in the following members: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    accurate_screensint1 = supports accurate screens
    color_deviceint1 = color device
    colorspaceppd_cs_tDefault colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, - PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N
    contone_onlyint1 = printer is continuous tone only
    num_emulations
    - emulations    		int
    - ppd_emul_t *    		Emulations supported by the printer
    flip_duplexint1 = need to flip odd pages when duplexing
    num_fonts
    - fonts    		int
    - char **    		The fonts available on the printer.
    jcl_begin
    - jcl_ps
    - jcl_end    		char *Job Control Language commands for PostScript output
    landscapeintLandscape orientation, -90 or 90 degrees
    lang_encodingchar *The character used for the option strings
    lang_versionchar *The language used for the options strings (English, French, etc.)
    language_levelintPostScript language level, 1 to 3
    manual_copiesint1 = Copies are done manually
    model_numberintDriver-specific model number.
    patcheschar *Patch commands to send to the printer
    manufacturerchar *The Manufacturer attribute from the PPD file, if any
    modelnamechar *The ModelName attribute from the PPD file
    nicknamechar *The NickName attribute from the PPD file, if any
    productchar *The Product attribute from the PPD file, if any
    shortnicknamechar *The ShortNickName attribute from the PPD file, if any
    throughputintNumber of pages per minute
    ttrasterizerchar *The TruType font rasterizer (Type42)
    variable_sizesint1 = supports variable sizes
    - -

    Options and Groups

    - -

    PPD files support multiple options, which are stored in -ppd_option_t and ppd_choice_t structures by -the PPD functions. - -

    Each option in turn is associated with a group -stored in the ppd_group_t structure. Groups can be -specified in the PPD file; if an option is not associated with a group -then it is put in a "General" or "Extra" group depending on the option. - -

    Groups can also have sub-groups; CUPS currently limits the depth of -sub-groups to 1 level to reduce programming complexity. - -

    Conflicts

    - -

    PPD files support specification of conflict conditions between -different options. Conflicts are stored in ppd_conflict_t -structures which specify the options that conflict with each other. - -

    Page Sizes

    - -

    PPD files specify all of the available pages sizes and the physical -margins associated with them. These sizes are stored in -ppd_size_t structures and are available in the -num_sizes and sizes members of the -ppd_file_t structure. You can lookup a particular page size -with the ppdPageWidth(), ppdPageLength(), and -ppdPageSize() functions: - -

      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-float      width;
-float      length;
-
-...
-
-size   = ppdPageSize(ppd, "size");
-width  = ppdPageWidth(ppd, "size");
-length = ppdPageLength(ppd, "size");
-
    - -

    The size string is the named page size option. The -width and length are in points; there are 72 points per inch. The -ppd_size_t structure contains the width, length, and -margin information: - -

      -typedef struct    /**** Page Sizes ****/
-{
-  int   marked;   /* Page size selected? */
-  char  name[41]; /* Media size option */
-  float width,    /* Width of media in points */
-        length,   /* Length of media in points */
-        left,     /* Left printable margin in points */
-        bottom,   /* Bottom printable margin in points */
-        right,    /* Right printable margin in points */
-        top;      /* Top printable margin in points */
-} ppd_size_t;
-
    - -

    Custom Page Sizes

    - -

    Besides the standard page sizes listed in a PPD file, some printers -support variable or custom page sizes. If variables_sizes -is non-zero, the custom_min, custom_max, and -custom_margins members of the ppd_file_t -structure define the limits of the variable sizes. - -

    To get the resulting media size, use a page size string of -Custom.widthxlength, where width -and length are integer values in points: - -

      -Custom.612x792   [8.5 inches wide, 11 inches long]
-Custom.1224x792  [17 inches wide, 11 inches long]
-
    - -

    Marking Options

    - -

    Before marking any user-defined options, call the ppdMarkDefaults() -function to mark the default options from the PPD file: - -

      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdMarkDefaults(ppd);
-
    - -

    Then call the ppdMarkOption() function to mark individual -options: - -

      -#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-int        conflicts;
-
-...
-
-conflicts = ppdMarkOption(ppd, "name", "value");
-
    - -

    The name and value strings choose a -particular option and choice, respectively. The return value is 0 -if there are not conflicts created by the selection. - -

    CUPS also provides a convenience function for marking all options -in the cups_option_t structure: - -

      -#include <cups/cups.h>
-
-...
-
-ppd_file_t    *ppd;
-int           num_options;
-cups_option_t *options;
-int           conflicts;
-
-...
-
-conflicts = cupsMarkOptions(ppd, num_options, options);
-
    - -

    The cupsMarkOptions() function also handles mapping the -IPP job template attributes to PPD options. The return value is the number -of conflicts present. - -

    Checking for Conflicts

    - -

    The ppdMarkOption() and cupsMarkOptions() -functions return the number of conflicts with the currently marked options. - -

    Call the ppdConflicts() function to get the number of -conflicts after you have marked all of the options: - -

      -#include <cups/cups.h>
-
-...
-
-ppd_file_t *ppd;
-int        conflicts;
-
-...
-
-conflicts = ppdConflicts(ppd);
-
    - -

    The return value is the number of conflicting options, or 0 if there -are no conflicts. - - -

    3 - Writing Filters

    - -

    This chapter describes how to write a file filter for CUPS. - -

    Overview

    - -

    File filters are programs that convert from one or more MIME types to -another type. Filters use a common command-line and environment interface -that allows them to be joined as needed to print files to any type of -printer. - -

    Security Considerations

    - -

    Filters are normally run as a non-priviledged user, so the major -security consideration is resource utilization - filters should not -depend on unlimited amounts of memory and disk space. - -

    Users and Groups

    - -

    The default CUPS configuration runs filters as user "lp" and group "other". - -

    Temporary Files

    - -

    Temporary files should be created in the directory specified by the -"TMPDIR" environment variable. The -cupsTempFile() function can be -used to safely choose temporary files in this directory. - -

    Sending Messages to the User

    - -

    The CUPS scheduler collects messages sent to the standard error file -by the filter. These messages are relayed to the user based upon the -scheduler LogLevel directive. - -

    The type of message is determined by an initial prefix sent on each -line: - -

      - -
    • DEBUG: - a debug message - -
    • INFO: - an informational message - -
    • WARNING: - a warning message - -
    • ERROR: - an error message - -
    • PAGE: - a page accounting message - -
    - -

    If the line of text does not begin with any of the above prefixes, it -is treated as a debug message. Text following the prefix is copied to the -printer-state-message attribute for the printer, and also -added to the error_log unless it is an informational or page -accounting message. - -

    Page Accounting

    - -

    Page accounting messages are used to inform the server when one or more -pages are printed. Each line has the form: - -

      -PAGE: page-number copy-count
-
    - -

    The page-number field is the current page number, starting at 1. -The copy-count field specifies the number of copies of that page -that was produced. - -

    Page account messages are added to the page_log file and -cause the job-sheets-completed attribute to be updated for -the job. - -

    Command-Line Arguments

    - -

    Every filter accepts exactly 6 or 7 command-line arguments: - -

      -printer job user title copies options [filename]
-
      - -
    • printer - The name of the printer queue (normally - this is the name of the program being run) - -
    • job - The numeric job ID for the job being - printed - -
    • user - The string from the - originating-user-name attribute - -
    • title - The string from the - job-name attribute - -
    • copies - The numeric value from the - number-copies attribute - -
    • options - String representations of the - job template attributes, separated by spaces. Boolean attributes - are provided as "name" for true values and "noname" for false - values. All other attributes are provided as "name=value" for - single-valued attributes and "name=value1,value2,...,valueN" for - set attributes - -
    • filename - The request file - -
    - -

    The filename argument is only provided to the first filter in the -chain; all filters must be prepared to read the print file from -the standard input if the filename argument is omitted. - -

    Copy Generation

    - -

    The copies argument specifies the number of copies to produce -of the input file. In general, you should only generate copies if the -filename argument is supplied. The only exception to this are -filters that produce device-independent PostScript output (without any -printer commands from the printer's PPD file), since the PostScript -filter pstops is responsible for copy generation. - -

    Environment Variables

    - -

    Every filter receives a fixed set of environment variables that can -be used by the filter: - -

      - -
    • CHARSET - The character set used by the client for - this print file - -
    • CONTENT_TYPE - The original document type, such as - "application/postscript" - -
    • CUPS_DATADIR - The location of CUPS data files - -
    • CUPS_SERVERROOT - The location of CUPS configuration - files - -
    • DEVICE_URI - The output device URI - -
    • LANG - The language used by the client for - this print file - -
    • PATH - The execution path exported to the filter - -
    • PPD - The full filename of the printer's PPD file - -
    • PRINTER - The name of the printer queue - -
    • RIP_CACHE - The maximum amount of memory each filter - should use - -
    • SOFTWARE - The name of the CUPS software, typically - "CUPS/1.1" - -
    • TZ - The local timezone - -
    • USER - The name of the current user - -
    - -

    Dissecting the HP-GL/2 Filter

    - -

    The HP-GL/2 filter (hpgltops) provided with CUPS is a -complex program that converts HP-GL/2 files into device-independent PostScript -output. Since it produces device-independent PostScript output, it does not -need to handle copy generation or writing printer options from the printer's -PPD file. - -

    Initializing the Filter

    - -

    The first task of any filter is to ensure that the correct number of -command-line arguments are present: - -

      -if (argc < 6 || argc > 7)
-{
-  fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
-  return (1);
-}
-
    - -

    After this you open the print file or read from the standard input -as needed: - -

      -FILE *fp;
-
-/*
- * If we have 7 arguments, print the file named on the command-line.
- * Otherwise, send stdin instead...
- */
-
-if (argc == 6)
-  fp = stdin;
-else
-{
- /*
-  * Try to open the print file...
-  */
-
-  if ((fp = fopen(argv[6], "rb")) == NULL)
-  {
-    perror("ERROR: unable to open print file - ");
-    return (1);
-  }
-}
-
    - -

    Once the print file has been opened, options can be processed using -the cupsParseOptions() and -cupsGetOption() functions: - -

      -int           num_options;
-cups_option_t *options;
-const char    *val;
-
-/*
- * Process command-line options and write the prolog...
- */
-
-options     = NULL;
-num_options = cupsParseOptions(argv[5], 0, &options);
-
-if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
-  shading = 0;
-
-if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
-  FitPlot = 1;
-
-if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
-  PenWidth = (float)atoi(val) * 0.001f;
-
    - -

    After the options have been processed, the filter writes PostScript code -to the standard output based on the print file, closes the print file (as -needed), and returns 0 to the scheduler. - -

    PostScript Output

    - -

    Filters that produce PostScript output must generate output conforming -to the Adobe Document Structuring Conventions, 3.0. In general this means -the beginning of each file must begin with: - -

      -%!PS-Adobe-3.0
-%%BoundingBox: left bottom right top
-%%Pages: (atend)
-%%EndComments
-
    - -

    The left, bottom, right, and top values -are integers in points from the lower-lefthand corner of the page. - -

    Pages must be surrounded by: - -

      -%%Page: number number
-gsave
-...
-grestore
-showpage
-
    - -

    And the end of each file must contain: - -

      -%%Trailer
-%%Pages: number-pages
-%%EOF
-
    - -

    These comments allow the PostScript filter to correctly perform page -accounting, copy generation, N-up printing, and so forth. - -

    4 - Writing Printer Drivers

    - -

    This chapter discusses how to write a printer driver, which is a -special filter program that converts CUPS raster data into the -appropriate commands and data required for a printer. - -

    Overview

    - -

    Raster printers utilitize PPD files that specify one or more -device-specific filters that handle converting print files for the -printer. The simplest raster printer drivers provide a single filter -that converts CUPS raster data to the printer's native format. - -

    CUPS Raster Data

    - -

    CUPS raster data (application/vnd.cups-raster) consists of -a stream of raster page descriptions produced by one of the RIP filters, -such as pstoraster or imagetoraster. - -

    Each page of data begins with a page dictionary structure called -cups_raster_header_t. This -structure contains the colorspace, bits per color, media size, media type, -hardware resolution, and so forth. - -

    After the page dictionary comes the page data which is a full-resolution, -uncompressed bitmap representing the page in the printer's output colorspace. - -

    Page Accounting

    - -

    Printer drivers must handle all page accounting. This means they must -send "PAGE:" messages to the standard error file for each page (and in many -cases, copy) sent to the printer. - -

    Color Management

    - -

    Printer drivers can implement their color management via the -cupsColorProfile attributes in the PPD file or internally -in the driver from a device-independent colorspace. In general, color -management performed by the RIP filters is more efficient than that -performed inside printer drivers. - -

    For example, the pstoraster filter often only has to -perform a color conversion once each time the color is used for -multiple output pixels, while the raster filter must convert every -pixel on the page. - -

    Device and Bitmap Variables

    - -

    Besides the standard PostScript page device dictionary variables defined -in the Adobe PostScript Level 3 reference manual, the CUPS filters support -additional variables that are passed in the page device dictionary header for -the page and in some cases control the type of raster data that is generated: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    VariableTypeDescription
    cupsWidthread-only integerWidth of bitmap in pixels
    cupsHeightread-only integer Height of bitmap in pixels
    cupsMediaTyperead-write integerDevice-specific media type code
    cupsBitsPerColorread-write integerNumber of bits per color; 1, 2, 4, and 8 are currently - supported
    cupsBitsPerPixelread-only integer Number of bits per pixel; 1 to 32
    cupsBytesPerLineread-only integerNumber of bytes per line of raster graphics
    cupsColorOrderread-write enumThe order of color values in the bitmap: -
      -
    • CUPS_ORDER_CHUNKED - CMYK CMYK CMYK -
    • CUPS_ORDER_BANDED - CCC MMM YYY KKK -
    • CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... -
    -
    cupsColorSpaceread-write enumThe colorspace of the bitmap: -
      -
    • CUPS_CSPACE_W - White (luminance) -
    • CUPS_CSPACE_RGB - Red, green, blue -
    • CUPS_CSPACE_RGBA - Red, green, blue, alpha -
    • CUPS_CSPACE_K - Black -
    • CUPS_CSPACE_CMY - Cyan, magenta, yellow -
    • CUPS_CSPACE_YMC - Yellow, magenta, cyan -
    • CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black -
    • CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black -
    • CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow -
    • CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, - light cyan, light magenta -
    • CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, - metallic cyan, black -
    • CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, - metallic cyan, metallic grey (silver) -
    • CUPS_CSPACE_WHITE - White pigment (black as white pigment) -
    • CUPS_CSPACE_GOLD - Gold foil (black as gold foil) -
    • CUPS_CSPACE_SILVER - Silver foil (black as silver foil) -
    -
    cupsCompressionread-write integerDevice-specific compression type code
    cupsRowCountread-write integerDevice-specific row count value
    cupsRowFeedread-write integerDevice-specific row feed value
    cupsRowStepread-write integerDevice-specific row step value
    - -

    Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per -color are transmitted to the raster driver in KCMY colorspace; the driver -is responsible for producing the correct separation of normal and light -cyan and magenta inks. - -

    Dissecting the HP-PCL Driver

    - -

    The HP-PCL driver provided with CUPS (rastertohp) converts -bitmap data from the raster filters into HP-PCL commands for most -PCL-compatible printers. The actual format of the raster data is controlled -by the PPD file being used - deskjet.ppd or laserjet.ppd. - -

    PPD Files

    - -

    PPD files play an important part of all raster printer drivers. Options -defined in the PPD file contain PostScript commands that control the raster -data that is sent to the printer driver. - -

    A typical CUPS printer driver will include ColorModel, -InputSlot, PageSize, PageRegion, -and Resolution options. Each option is shown using the -standard PPD format: - -

      -*OpenUI *PageSize/Media Size: PickOne
-*OrderDependency: 10 AnySetup *PageSize
-*DefaultPageSize: Letter
-*PageSize Letter/US Letter: "<<
-/PageSize [612 792]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize Legal/US Legal: "<<
-/PageSize [612 1008]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-*CloseUI: *PageSize
-
    - -

    The OpenUI keyword specifies the new option. The first -name is the option with an asterisk (*) in front of it. The first name is -usually followed by a slash (/) and a human-readable version of the -option name. - -

    Every option must have a default value, specified using the -DefaultOption keyword. - -

    Each option begins with the option name followed by the computer and -human-readable values. The PostScript commands follow these inside double -quotes. PostScript commands can be provided on a single line: - -

      -*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
-
    - -

    or broken down on separate lines using the End keyword to -terminate them: - -

      -*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-
    - -

    The choice of the two formats is usually esthetic. However, each line in -a PPD file must not exceed 255 characters, so if your PostScript commands are -long you may need to break them up on separate lines. - -

    Reading Raster Data

    - -

    As with any filter, your printer driver should handle raster data from -a filename specified on the command-line or from the standard input. The -cupsRasterOpen() function opens -a raster stream for printing: - -

      -int           fd;   /* File descriptor */
-cups_raster_t *ras; /* Raster stream for printing */
-
-
-/*
- * Check for valid arguments...
- */
-
-if (argc < 6 || argc > 7)
-{
- /*
-  * We don't have the correct number of arguments; write an error message
-  * and return.
-  */
-
-  fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
-  return (1);
-}
-
-/*
- * Open the page stream...
- */
-
-if (argc == 7)
-{
-  if ((fd = open(argv[6], O_RDONLY)) == -1)
-  {
-    perror("ERROR: Unable to open raster file - ");
-    sleep(1);
-    return (1);
-  }
-}
-else
-  fd = 0;
-
-ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
-
    - -

    Once you have opened the raster stream you just need to read each -page and print it: - -

      -cups_raster_header_t header;
-int                  y;
-unsigned char        data[8192];
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ... initialize the printer ...
-  for (y = header.cupsHeight; y > 0; y ++)
-  {
-    cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
-    ... send raster line to printer ...
-  }
-}
-
    - -

    After you have processed all pages, close the raster stream and -return: - -

      -cupsRasterClose(ras);
-
-return (0);
-
    - -

    5 - Writing Backends

    - -

    This chapter describes how to write a backend for CUPS. Backends -communicate directly with printers and allow printer drivers and -filters to send data using any type of connection transparently. - -

    Overview

    - -

    Backends are special filters that communicate with printers directly. -They are treated slightly differently than filters, however, and have some -unique requirements. - -

    Security Considerations

    - -

    Backends are run as the root user, so special care must be taken to -avoid potential security violations. In particular, remember that a backend -will be able to manipulate disk files, devices, and other resources that -potentially could damage a system or printer. - -

    Command-Line Arguments

    - -

    Besides the standard filter arguments, backends are also run with no -arguments to get a list of available devices. This discovery process is -described later in this chapter. - -

    Copy Generation

    - -

    Like filters, backends should send multiple copies of the print file only -if a filename is supplied on the command-line. Otherwise the backend should -assume that the upstream filter has already added the necessary commands or -data to produce the multiple copies. - -

    Page Accounting

    - -

    Backend filters generally do not do page accounting, however they should -at a minimum produce a single page message for each copy that is produced -when a filename is present on the command-line. This is because the user -selected "raw" printing and no other accounting information is possible. - -

    Exclusive Access

    - -

    Backends that talk to local character or block devices should open the -device file in exclusive mode (O_EXCL) to cooperate with other -printers defined for the same device. - -

    Retries

    - -

    All backends must retry connections to the device. This -includes backends that talk to local character or block devices, as the -user may define more than one printer queue pointing at the same -physical device. - -

    To prevent excess CPU utilitization, the backend should go to sleep -for an amount of time between retries; the CUPS-supplied backends retry -once every 30 seconds. - -

    Dissecting the Serial Port Backend

    - -

    The serial port backend provides support for serial printers. Since -it does everything a good backend needs to do, it provides an excellent -example of what to do. - -

    Supporting Device Discovery

    - -

    As previously noted, backends are special filter programs that talk -to printer devices. Another task a backend must perform is to list the -available devices it supports. The backend lists the available devices -when no additioanl arguments are supplied on the command-line (i.e. -just the command name...) - -

    The serial backend lists devices by looking at serial port files in the -/dev directory, by consulting a hardware inventory (IRIX), and -in some cases by trying to open the ports to see if they actually exist. - -

    Once it finds a serial port it writes a single line for each port to -the standard error file. Each line looks like this: - -

      -serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
-
    - -

    The first word "serial" is the device class; this identifies the -class of device which can be used to categorize it in user interfaces. CUPS -currently recognizes the following classes: - -

      - -
    • "file" - a disk file. - -
    • "direct" - a parallel or fixed-rate serial data port, - currently used for Centronics, IEEE-1284, and USB printer - ports. - -
    • "serial" - a variable-rate serial port. - -
    • "network" - a network connection, typically via AppSocket, - HTTP, IPP, LPD, or SMB/CIFS protocols. - -
    - -

    After the device class is the device URI, in this case -"serial:/dev/ttyS0?baud=115200". This is the URI that should be used by -the user to select this port. For serial ports, the "baud=115200" -specifies the maximum baud rate supported by the port - the actual -value will vary based on the speed the user selects for the printer. - -

    The last two strings are the model and description for the port. The -"Unknown" string means that the printer model is unknown - some devices -are able to provide a make and model such as "HP DeskJet" that allows -users and software to choose an appropriate printer driver more easily. -Both the model and description must be enclosed inside double quotes. - -

    Opening the Serial Port

    - -

    As noted previously, all backends should open device files in exclusive -mode, and retry as needed until the port is available. The serial port does -this using a do-while loop: - -

      -do
-{
-  if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
-  {
-    if (errno == EBUSY)
-    {
-      fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
-      sleep(30);
-    }
-    else
-    {
-      perror("ERROR: Unable to open serial port device file");
-      return (1);
-    }
-  }
-}
-while (fd < 0);
-
    - -

    If the port is busy or in use by another process, the backend will -go to sleep for 30 seconds and try again. If another error is detected -a message is sent to the user and the backend aborts the print job -until the problem can be corrected. - -

    Writing Data to the Port

    - -

    Network and character devices pose an interesting problem when writing -data to the port - they may not be able to write all of the bytes in your -buffer before returning. To work around this problem you must loop until -all bytes have been written: - -

      -while (nbytes > 0)
-{
-  if ((wbytes = write(fd, bufptr, nbytes)) < 0)
-    if (errno == ENOTTY)
-      wbytes = write(fd, bufptr, nbytes);
-
-  if (wbytes < 0)
-  {
-    perror("ERROR: Unable to send print file to printer");
-    break;
-  }
-
-  nbytes -= wbytes;
-  bufptr += wbytes;
-}
-
    - -

    The check for the ENOTTY error is needed on some platforms -to clear an error from a previous ioctl() call. - -

    Finishing Up

    - -

    Once you have sent the print file, return 0 if the file printed -successfully or 1 if it did not. This will allow the scheduler to stop -the print job if there is a device error, preserving the print job for -later printing once the problem has been corrected. - -

    A - Software License Agreement

    - - - - -

    B - Constants

    - -

    This appendix lists all of the constants that are defined by the CUPS -API. - -

    CUPS Constants

    - -

    Version Number

    - -

    The CUPS_VERSION constant is a floating-point number -representing the API version number. The current version number is -1.0100 which represents CUPS version 1.1.0. - -

    Printer Capabilities

    - -

    The CUPS_PRINTER constants represent capability bits for -printers and classes: - -

      - -
    • CUPS_PRINTER_LOCAL - Is a local printer or class. - -
    • CUPS_PRINTER_REMOTE - Is a remote printer or class. - -
    • CUPS_PRINTER_CLASS - Is a class. - -
    • CUPS_PRINTER_BW - Printer prints in black and white. - -
    • CUPS_PRINTER_COLOR - Printer prints in color. - -
    • CUPS_PRINTER_DUPLEX - Printer can print double-sided. - -
    • CUPS_PRINTER_STAPLE - Printer can staple output. - -
    • CUPS_PRINTER_COPIES - Printer can produce multiple - copies on its own. - -
    • CUPS_PRINTER_COLLATE - Printer can collate copies. - -
    • CUPS_PRINTER_PUNCH - Printer can punch holes in output. - -
    • CUPS_PRINTER_COVER - Printer can put covers on output. - -
    • CUPS_PRINTER_BIND - Printer can bind output. - -
    • CUPS_PRINTER_SORT - Printer can sort output. - -
    • CUPS_PRINTER_SMALL - Printer can print on media up - to 9x14 inches. - -
    • CUPS_PRINTER_MEDIUM - Printer can print on media - from 9x14 to 18x24 inches. - -
    • CUPS_PRINTER_LARGE - Printer can print on media - larger than 18x24 inches. - -
    • CUPS_PRINTER_VARIABLE - Printer can print on - variable or custom media sizes. - -
    • CUPS_PRINTER_IMPLICIT - Is an implicit class. - -
    • CUPS_PRINTER_OPTIONS - All of the printer capability - and option bits. - -
    - -

    Encodings

    - -

    CUPS defines the following character set encoding constants: - -

      - -
    • CUPS_US_ASCII - US ASCII character set. - -
    • CUPS_UTF_8 - UTF-8 encoding of Unicode. - -
    • CUPS_ISO8859_1 - ISO-8859-1 character set. - -
    • CUPS_ISO8859_2 - ISO-8859-2 character set. - -
    • CUPS_ISO8859_3 - ISO-8859-3 character set. - -
    • CUPS_ISO8859_4 - ISO-8859-4 character set. - -
    • CUPS_ISO8859_5 - ISO-8859-5 character set. - -
    • CUPS_ISO8859_6 - ISO-8859-6 character set. - -
    • CUPS_ISO8859_7 - ISO-8859-7 character set. - -
    • CUPS_ISO8859_8 - ISO-8859-8 character set. - -
    • CUPS_ISO8859_9 - ISO-8859-9 character set. - -
    • CUPS_ISO8859_10 - ISO-8859-10 character set. - -
    • CUPS_ISO8859_13 - ISO-8859-13 character set. - -
    • CUPS_ISO8859_14 - ISO-8859-14 character set. - -
    • CUPS_ISO8859_15 - ISO-8859-15 character set. - -
    • CUPS_WINDOWS_874 - Windows code page 874. - -
    • CUPS_WINDOWS_1250 - Windows code page 1250. - -
    • CUPS_WINDOWS_1251 - Windows code page 1251. - -
    • CUPS_WINDOWS_1252 - Windows code page 1252. - -
    • CUPS_WINDOWS_1253 - Windows code page 1253. - -
    • CUPS_WINDOWS_1254 - Windows code page 1254. - -
    • CUPS_WINDOWS_1255 - Windows code page 1255. - -
    • CUPS_WINDOWS_1256 - Windows code page 1256. - -
    • CUPS_WINDOWS_1257 - Windows code page 1257. - -
    • CUPS_WINDOWS_1258 - Windows code page 1258. - -
    • CUPS_KOI8_R - Russian code page koi8-r. - -
    • CUPS_KOI8_U - Ukrainian code page koi8-r. - -
    - -

    HTTP Constants

    - -

    Limits

    - -

    The following constants define the limits for strings: - -

      - -
    • HTTP_MAX_BUFFER - Size of socket buffer. - -
    • HTTP_MAX_HOST - Maximum length of hostname. - -
    • HTTP_MAX_URI - Maximum length of URI. - -
    • HTTP_MAX_VALUE - Maximum length of field values. - -
    - -

    Status Codes

    - -

    The following status codes can be returned by httpUpdate(): - -

      - -
    • HTTP_ERROR - A network error occurred - -
    • HTTP_CONTINUE - Continue response from HTTP proxy - -
    • HTTP_OK - OPTIONS/GET/HEAD/POST/TRACE command was successful - -
    • HTTP_CREATED - PUT command was successful - -
    • HTTP_ACCEPTED - DELETE command was successful - -
    • HTTP_NOT_AUTHORITATIVE - Information isn't authoritative - -
    • HTTP_NO_CONTENT - Successful command - -
    • HTTP_RESET_CONTENT - Content was reset/recreated - -
    • HTTP_PARTIAL_CONTENT - Only a partial file was recieved/sent - -
    • HTTP_MULTIPLE_CHOICES - Multiple files match request - -
    • HTTP_MOVED_PERMANENTLY - Document has moved permanently - -
    • HTTP_MOVED_TEMPORARILY - Document has moved temporarily - -
    • HTTP_SEE_OTHER - See this other link... - -
    • HTTP_NOT_MODIFIED - File not modified - -
    • HTTP_USE_PROXY - Must use a proxy to access this URI - -
    • HTTP_BAD_REQUEST - Bad request - -
    • HTTP_UNAUTHORIZED - Unauthorized to access host - -
    • HTTP_PAYMENT_REQUIRED - Payment required - -
    • HTTP_FORBIDDEN - Forbidden to access this URI - -
    • HTTP_NOT_FOUND - URI was not found - -
    • HTTP_METHOD_NOT_ALLOWED - Method is not allowed - -
    • HTTP_NOT_ACCEPTABLE - Not Acceptable - -
    • HTTP_PROXY_AUTHENTICATION - Proxy Authentication is Required - -
    • HTTP_REQUEST_TIMEOUT - Request timed out - -
    • HTTP_CONFLICT - Request is self-conflicting - -
    • HTTP_GONE - Server has gone away - -
    • HTTP_LENGTH_REQUIRED - A content length or encoding is required - -
    • HTTP_PRECONDITION - Precondition failed - -
    • HTTP_REQUEST_TOO_LARGE - Request entity too large - -
    • HTTP_URI_TOO_LONG - URI too long - -
    • HTTP_UNSUPPORTED_MEDIATYPE - The requested media type is unsupported - -
    • HTTP_SERVER_ERROR - Internal server error - -
    • HTTP_NOT_IMPLEMENTED - Feature not implemented - -
    • HTTP_BAD_GATEWAY - Bad gateway - -
    • HTTP_SERVICE_UNAVAILABLE - Service is unavailable - -
    • HTTP_GATEWAY_TIMEOUT - Gateway connection timed out - -
    • HTTP_NOT_SUPPORTED - HTTP version not supported - -
    - -

    Fields

    - -

    The following fields are indices for each of the standard HTTP fields in -HTTP 1/1: - -

      - -
    • HTTP_FIELD_ACCEPT_LANGUAGE - Accept-Language - -
    • HTTP_FIELD_ACCEPT_RANGES - Accept-Ranges - -
    • HTTP_FIELD_AUTHORIZATION - Authorization - -
    • HTTP_FIELD_CONNECTION - Connection - -
    • HTTP_FIELD_CONTENT_ENCODING - Content-Encoding - -
    • HTTP_FIELD_CONTENT_LANGUAGE - Content-Language - -
    • HTTP_FIELD_CONTENT_LENGTH - Content-Length - -
    • HTTP_FIELD_CONTENT_LOCATION - Content-Location - -
    • HTTP_FIELD_CONTENT_MD5 - Content-MD5 - -
    • HTTP_FIELD_CONTENT_RANGE - Content-Range - -
    • HTTP_FIELD_CONTENT_TYPE - Content-Type - -
    • HTTP_FIELD_CONTENT_VERSION - Content-Version - -
    • HTTP_FIELD_DATE - Date - -
    • HTTP_FIELD_HOST - Host - -
    • HTTP_FIELD_IF_MODIFIED_SINCE - If-Modified-Since - -
    • HTTP_FIELD_IF_UNMODIFIED_SINCE - If-Unmodified-Since - -
    • HTTP_FIELD_KEEP_ALIVE - Keep-Alive - -
    • HTTP_FIELD_LAST_MODIFIED - Last-Modified - -
    • HTTP_FIELD_LINK - Link - -
    • HTTP_FIELD_LOCATION - Location - -
    • HTTP_FIELD_RANGE - Range - -
    • HTTP_FIELD_REFERER - Referer - -
    • HTTP_FIELD_RETRY_AFTER - Retry-After - -
    • HTTP_FIELD_TRANSFER_ENCODING - Transfer-Encoding - -
    • HTTP_FIELD_UPGRADE - Upgrade - -
    • HTTP_FIELD_USER_AGENT - User-Agent - -
    • HTTP_FIELD_WWW_AUTHENTICATE - WWW-Authenticate - - -
    - -

    IPP Constants

    - -

    Limits

    - -

    The following constants define array limits for IPP data: - -

      - -
    • IPP_MAX_NAME - Maximum length of an attribute name - -
    • IPP_MAX_VALUES - Maximum number of set-of values - that can be read in a request. - -
    - -

    Tags

    - -
      - -
    • IPP_TAG_ZERO - Wildcard tag value for searches; also - used to separate groups of attributes - -
    • IPP_TAG_OPERATION - Tag for values of type operation - -
    • IPP_TAG_JOB - Tag for values of type job - -
    • IPP_TAG_END - Tag for values of type end - -
    • IPP_TAG_PRINTER - Tag for values of type printer - -
    • IPP_TAG_UNSUPPORTED_GROUP - Tag for values of type unsupported_group - -
    • IPP_TAG_UNSUPPORTED_VALUE - Tag for values of type unsupported_value - -
    • IPP_TAG_DEFAULT - Tag for values of type default - -
    • IPP_TAG_UNKNOWN - Tag for values of type unknown - -
    • IPP_TAG_NOVALUE - Tag for values of type novalue - -
    • IPP_TAG_NOTSETTABLE - Tag for values of type notsettable - -
    • IPP_TAG_DELETEATTR - Tag for values of type deleteattr - -
    • IPP_TAG_ANYVALUE - Tag for values of type anyvalue - -
    • IPP_TAG_INTEGER - Tag for values of type integer - -
    • IPP_TAG_BOOLEAN - Tag for values of type boolean - -
    • IPP_TAG_ENUM - Tag for values of type enum - -
    • IPP_TAG_STRING - Tag for values of type string - -
    • IPP_TAG_DATE - Tag for values of type date - -
    • IPP_TAG_RESOLUTION - Tag for values of type resolution - -
    • IPP_TAG_RANGE - Tag for values of type range - -
    • IPP_TAG_COLLECTION - Tag for values of type collection - -
    • IPP_TAG_TEXTLANG - Tag for values of type textlang - -
    • IPP_TAG_NAMELANG - Tag for values of type namelang - -
    • IPP_TAG_TEXT - Tag for values of type text - -
    • IPP_TAG_NAME - Tag for values of type name - -
    • IPP_TAG_KEYWORD - Tag for values of type keyword - -
    • IPP_TAG_URI - Tag for values of type uri - -
    • IPP_TAG_URISCHEME - Tag for values of type urischeme - -
    • IPP_TAG_CHARSET - Tag for values of type charset - -
    • IPP_TAG_LANGUAGE - Tag for values of type language - -
    • IPP_TAG_MIMETYPE - Tag for values of type mimetype - -
    - -

    Resolution Units

    - -

    The IPP_RES_PER_INCH and IPP_RES_PER_CM constants -specify dots per inch and dots per centimeter, respectively. - -

    Finishings

    - -

    The finishing values specify special finishing operations to be -performed on the job. - -

      - -
    • IPP_FINISH_NONE - Do no finishing - -
    • IPP_FINISH_STAPLE - Staple the job - -
    • IPP_FINISH_PUNCH - Punch the job - -
    • IPP_FINISH_COVER - Cover the job - -
    • IPP_FINISH_BIND - Bind the job - -
    - -

    Orientations

    - -

    The orientation values specify the orientation of the job. - -

      - -
    • IPP_PORTRAIT - No rotation - -
    • IPP_LANDSCAPE - 90 degrees counter-clockwise - -
    • IPP_REVERSE_LANDSCAPE - 90 degrees clockwise - -
    • IPP_REVERSE_PORTRAIT - 180 degrees - -
    - -

    Qualities

    - -

    The quality values specify the desired quality of the print. -

      - -
    • IPP_QUALITY_DRAFT - Draft quality - -
    • IPP_QUALITY_NORMAL - Normal quality - -
    • IPP_QUALITY_HIGH - High quality - -
    - -

    Job States

    - -

    The job state values are used to represent the current job state. - -

      - -
    • IPP_JOB_PENDING - Job is pending - -
    • IPP_JOB_HELD - Job is held - -
    • IPP_JOB_PROCESSING - Job is processing - -
    • IPP_JOB_STOPPED - Job is stopped - -
    • IPP_JOB_CANCELLED - Job is cancelled - -
    • IPP_JOB_ABORTED - Job is aborted - -
    • IPP_JOB_COMPLETED - Job is completed - -
    - -

    Printer States

    - -

    The printer state values are used to represent the current printer -state. - -

      - -
    • IPP_PRINTER_IDLE - Printer is idle - -
    • IPP_PRINTER_PROCESSING - Printer is processing - -
    • IPP_PRINTER_STOPPED - Printer is stopped - -
    - -

    Operations

    - -

    The operation values represent the available IPP operations. - -

      - -
    • IPP_PRINT_JOB - Print a file - -
    • IPP_PRINT_URI - Print a URI - -
    • IPP_VALIDATE_JOB - Validate job attributes - -
    • IPP_CREATE_JOB - Create a new job - -
    • IPP_SEND_DOCUMENT - Send a document to a job - -
    • IPP_SEND_URI - Send a URI to a job - -
    • IPP_CANCEL_JOB - Cancel a job - -
    • IPP_GET_JOB_ATTRIBUTES - Get job attributes - -
    • IPP_GET_JOBS - Get a list of all jobs - -
    • IPP_GET_PRINTER_ATTRIBUTES - Get printer attributes - -
    • IPP_HOLD_JOB - Hold a pending job - -
    • IPP_RELEASE_JOB - Release a held job - -
    • IPP_RESTART_JOB - Restart a completed job - -
    • IPP_PAUSE_PRINTER - Pause a printer - -
    • IPP_RESUME_PRINTER - Restart a paused printer - -
    • IPP_PURGE_JOBS - Purge jobs from the queue - -
    • IPP_SET_PRINTER_ATTRIBUTES - Set printer attributes - -
    • IPP_SET_JOB_ATTRIBUTES - Set job attributes - -
    • IPP_GET_PRINTER_SUPPORTED_VALUES - Get printer supported values - -
    • CUPS_GET_DEFAULT - Get the default destination - -
    • CUPS_GET_PRINTERS - Get a list of all printers - -
    • CUPS_ADD_PRINTER - Add or modify a printer - -
    • CUPS_DELETE_PRINTER - Delete a printer - -
    • CUPS_GET_CLASSES - Get a list of all classes - -
    • CUPS_ADD_CLASS - Add or modify a class - -
    • CUPS_DELETE_CLASS - Delete a class - -
    • CUPS_ACCEPT_JOBS - Accept jobs on a printer or class - -
    • CUPS_REJECT_JOBS - Reject jobs on a printer or class - -
    • CUPS_SET_DEFAULT - Set the default destination - -
    • CUPS_GET_DEVICES - Get a list of all devices - -
    • CUPS_GET_PPDS - Get a list of all PPDs - -
    • CUPS_MOVE_JOB - Move a job to a new destination - -
    - -

    Status Codes

    - -

    Status codes are returned by all IPP requests. - -

      - -
    • IPP_OK - Request completed with no errors - -
    • IPP_OK_SUBST - Request completed but some attribute - values were substituted - -
    • IPP_OK_CONFLICT - Request completed but some attributes - conflicted - -
    • IPP_BAD_REQUEST - The request was bad - -
    • IPP_FORBIDDEN - You don't have access to the resource - -
    • IPP_NOT_AUTHENTICATED - You are not authenticated for - the resource - -
    • IPP_NOT_AUTHORIZED - You not authorized to access - the resource - -
    • IPP_NOT_POSSIBLE - The requested operation cannot be - completed - -
    • IPP_TIMEOUT - A timeout occurred - -
    • IPP_NOT_FOUND - The resource was not found - -
    • IPP_GONE - The resource has gone away - -
    • IPP_REQUEST_ENTITY - The request was too large - -
    • IPP_REQUEST_VALUE - The request contained a value - that was unknown to the server - -
    • IPP_DOCUMENT_FORMAT - The document format is not - supported by the server - -
    • IPP_ATTRIBUTES - Required attributes are missing - -
    • IPP_URI_SCHEME - The URI scheme is not supported - -
    • IPP_CHARSET - The charset is not supported - -
    • IPP_CONFLICT - One or more attributes conflict - -
    • IPP_COMPRESSION_NOT_SUPPORTED - The specified - compression is not supported - -
    • IPP_COMPRESSION_ERROR - The compressed data - contained an error - -
    • IPP_DOCUMENT_FORMAT_ERROR - The document data - contained an error in it - -
    • IPP_DOCUMENT_ACCESS_ERROR - The remote document - could not be accessed - -
    • IPP_INTERNAL_ERROR - The server encountered an - internal error - -
    • IPP_OPERATION_NOT_SUPPORTED - The requested operation - is not supported - -
    • IPP_SERVICE_UNAVAILABLE - The requested service - is unavailable - -
    • IPP_VERSION_NOT_SUPPORTED - The IPP request - version is not supported - -
    • IPP_DEVICE_ERROR - The output device encountered - an error - -
    • IPP_TEMPORARY_ERROR - A temporary error occurred - -
    • IPP_NOT_ACCEPTING - The destination is not accepting - jobs - -
    • IPP_PRINTER_BUSY - The destination is busy - -
    • IPP_ERROR_JOB_CANCELLED - The requested job has been - cancelled - -
    • IPP_MULTIPLE_JOBS_NOT_SUPPORTED - The server - does not support multiple jobs - -
    - -

    PPD Constants

    - -

    PPD Format Version

    - -

    The PPD_VERSION constant defines a floating point number -representing the newest format version that is supported by CUPS, currently -4.3. - -

    PPD User-Interface Types

    - -

    Each printer option has a type associated with it: - -

      - -
    • PPD_UI_BOOLEAN - The user can turn this option on or off - -
    • PPD_UI_PICKONE - The user can choose one option value - to use. - -
    • PPD_UI_PICKMANY - The user can choose zero or more - option values. - -
    - -

    PPD Sections

    - -

    Some options must be output before others, or in different sections of -the output document. The ppd_section_t enumeration defines -which section the option must be output in: - -

      - -
    • PPD_ORDER_ANY - The option can be output in any of - the document, page, or prolog sections of the document - -
    • PPD_ORDER_DOCUMENT - The option must be output in - the DocumentSetup section of the document - -
    • PPD_ORDER_EXIT - The option must be output before - the document - -
    • PPD_ORDER_JCL - The option must be output in the - job control section of the document - -
    • PPD_ORDER_PAGE - The option must be output in the - PageSetup section of the document - -
    • PPD_ORDER_PROLOG - The option must be output in the - Prolog section of the document - -
    - -

    PPD Colorspaces

    - -

    Each printer has a default colorspace: - -

      - -
    • PPD_CS_CMYK - The printer uses CMYK colors by default - -
    • PPD_CS_CMY - The printer uses CMY colors by default - -
    • PPD_CS_GRAY - The printer uses grayscale by default - -
    • PPD_CS_RGB - The printer uses RGB colors by default - -
    • PPD_CS_RGBK - The printer uses RGBK colors by default - -
    • PPD_CS_N - The printer uses a DeviceN colorspace - by default - -
    - -

    Raster Constants

    - -

    Raster Sync Words

    - -

    The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC -constants define the standard sync words at the beginning of each CUPS -raster file. - -

    Raster Stream Modes

    - -

    The CUPS_RASTER_READ and CUPS_RASTER_WRITE -constants are used with the -cupsRasterOpen() function to -specify a stream for reading or writing. - -

    Raster Boolean Constants

    - -

    The CUPS_FALSE and CUPS_TRUE constants -represent boolean values in the page header. - -

    Raster Jog Values

    - -

    The cups_jog_t enumeration defines constants for the -Jog page device dictionary variable: - -

      - -
    • CUPS_JOG_NONE - Do no jogging - -
    • CUPS_JOG_FILE - Jog pages after each file - -
    • CUPS_JOG_JOB - Jog pages after each job - -
    • CUPS_JOG_SET - Jog pages after each set of jobs - -
    - -

    Raster Orientation Values

    - -

    The cups_orient_t enumeration defines constants for the -Orientation page device dictionary variable: - -

      - -
    • CUPS_ORIENT_0 - Portrait orientation - -
    • CUPS_ORIENT_90 - Landscape orientation - -
    • CUPS_ORIENT_180 - Reverse-portrait orientation - -
    • CUPS_ORIENT_270 - Reverse-landscape orientation - -
    - -

    Raster CutMedia Values

    - -

    The cups_cut_t enumeration defines constants for the -CutMedia page device dictionary variable: - -

      - -
    • CUPS_CUT_NONE - Do no jogging - -
    • CUPS_CUT_FILE - Cut pages after each file - -
    • CUPS_CUT_JOB - Cut pages after each job - -
    • CUPS_CUT_SET - Cut pages after each set of jobs - -
    • CUPS_CUT_PAGE - Cut each page - -
    - -

    Raster AdvanceMedia Values

    - -

    The cups_advance_t enumeration defines constants for the -AdvanceMedia page device dictionary variable: - -

      - -
    • CUPS_ADVANCE_NONE - Do no jogging - -
    • CUPS_ADVANCE_FILE - Advance media after each file - -
    • CUPS_ADVANCE_JOB - Advance media after each job - -
    • CUPS_ADVANCE_SET - Advance media after each set of jobs - -
    • CUPS_ADVANCE_PAGE - Advance media for each page - -
    - -

    Raster LeadingEdge Values

    - -

    The cups_edge_t enumeration defines constants for the -LeadingEdge page device dictionary variable: - -

      - -
    • CUPS_EDGE_TOP - The top of the media is the leading - edge - -
    • CUPS_EDGE_RIGHT - The right of the media is the leading - edge - -
    • CUPS_EDGE_BOTTOM - The bottom of the media is the - leading edge - -
    • CUPS_EDGE_LEFT - The left of the media is the leading - edge - -
    - -

    Raster Color Order Values

    - -

    The cups_order_t enumeration defines the possible color -value orderings: - -

      - -
    • CUPS_ORDER_CHUNKED - CMYK CMYK CMYK - -
    • CUPS_ORDER_BANDED - CCC MMM YYY KKK - -
    • CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... - -
    - -

    Raster Colorspace Values

    - -

    The cups_cspace_t enumeration defines the possible colorspaces: - -

      - -
    • CUPS_CSPACE_W - White (luminance) - -
    • CUPS_CSPACE_RGB - Red, green, blue - -
    • CUPS_CSPACE_RGBA - Red, green, blue, alpha - -
    • CUPS_CSPACE_K - Black - -
    • CUPS_CSPACE_CMY - Cyan, magenta, yellow - -
    • CUPS_CSPACE_YMC - Yellow, magenta, cyan - -
    • CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black - -
    • CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black - -
    • CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow - -
    • CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, - light cyan, light magenta - -
    • CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, - metallic cyan, black - -
    • CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, - metallic cyan, metallic grey (silver) - -
    • CUPS_CSPACE_WHITE - White pigment (black as white pigment) - -
    • CUPS_CSPACE_GOLD - Gold foil (black as gold foil) - -
    • CUPS_CSPACE_SILVER - Silver foil (black as silver foil) - -
    - -

    C - Structures

    - -

    This appendix describes all of the structures that are -defined by the CUPS API. - -

    CUPS Structures

    - -

    CUPS Destinations

    - -

    The CUPS destination structure (cups_dest_t) -contains information on a specific destination or instance: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    namechar *The name of the printer or class.
    instancechar *The instance of the printer or class; NULL for the primary - instance.
    is_defaultint1 if the destination is set as the default, 0 otherwise.
    num_optionsintThe number of options associated with this destination.
    optionscups_option_t *The options associated with this destination.
    - -

    CUPS Jobs

    - -

    The CUPS job structure (cups_job_t) contains -information on a specific job: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    idintThe job ID for this job.
    destchar *The destination for this job (printer or class name).
    titlechar *The job-name for this job (title).
    userchar *The job-originating-user-name for this job (username).
    formatchar *The document-format for this job (MIME type string).
    stateipp_jstateThe current state of the job.
    sizeintThe size of this job in kilobytes.
    priorityintThe priority of this job from 1 to 100 (50 is normal).
    completed_timetime_tThe time the job was completed, or 0 if not yet completed.
    creation_timetime_tThe time the job was queued.
    processing_timetime_tThe time the job started printing.
    - -

    CUPS Messages

    - -

    The CUPS messages structure (cups_lang_t) -contains the character set, locale name, and messages array: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    nextcups_lang_t *Pointer to the next messages structure in memory.
    usedintThe number of active users of this messages structure.
    encodingcups_encoding_tThe character encoding of the message strings.
    languagechar [16]The language/locale name.
    messageschar *[]The array of message strings.
    - -

    CUPS Options

    - -

    The CUPS option structure (cups_option_t) -contains the option name and string value: - -

    - - - - - - - - - - - - - - - -
    MemberTypeDescription
    namechar *The name of the option.
    valuechar *The string value of the option.
    - -

    Networking Structures

    - -

    HTTP State

    - -

    The HTTP state structure (http_t) contains the -current state of a HTTP request or response: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    fdintThe socket for the HTTP connection.
    blockingint1 if the HTTP functions should block, 0 if not.
    errorintThe last OS error that occurred on the socket.
    activitytime_tThe last time the HTTP connection was used.
    statehttp_state_tThe current HTTP request/response state.
    statusintThe last HTTP status seen.
    versionhttp_version_tThe HTTP protocol version in use.
    keep_alivehttp_keep_alive_tWhether or not to use Keep-Alive
    hostaddrstruct sockaddr_inThe IPv4 address of the HTTP server.
    hostnamechar []The hostname of the HTTP server.
    fieldschar [][]The string values of all HTTP request/response - fields.
    datachar *Current byte in data buffer.
    data_encodinghttp_encoding_tThe transfer encoding for the request/response.
    data_remainingintThe number of bytes remaining in the current request, - response, or chunk.
    usedintThe number of bytes that are used in the buffer.
    bufferchar []The read/write buffer.
    auth_typeintThe type of authentication in use.
    md5_statemd5_state_tThe current MD5 digest state.
    noncechar []The nonce value for Digest authentication.
    nonce_countintThe nonce count value.
    tlsvoid *A pointer to private encryption data.
    encryptionhttp_encryption_tThe current encryption mode.
    - -

    IPP State

    - -

    The IPP state structure (ipp_t) contains the -current state of a IPP request or response: - -

    - - - - - - - - - - -
    MemberTypeDescription
    - -

    Raster Structures

    - -

    Raster Page Header

    - -

    The raster page header (cups_raster_header_t) -consists of the PostScript page device dictionary for the page: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    MemberTypeDescription
    MediaClasschar[64]The media class name
    MediaColorchar[64]The media color name
    MediaTypechar[64]The media type name
    OutputTypechar[64]The output type name
    AdvanceDistanceunsignedThe distance to advance the media in points
    AdvanceMediacups_adv_tWhen to advance the media
    Collatecups_bool_tWhether or not to produce collated copies
    CutMediacups_cut_tWhen to cut the media
    Duplexcups_bool_tWhether or not to print on both sides of the paper
    HWResolutionunsigned[2]The resolution of the page image in pixels per inch; the - HWResolution[0] represents the horizontal resolution and - HWResolution[1] represents the vertical resolution
    ImagingBoundingBoxunsigned[4]The bounding box for the page in points; the elements - represent the left, bottom, right, and top coordinates of the - imaged area (if 0 then the whole page is imaged)
    InsertSheetcups_bool_tWhether or not to insert a sheet before this page
    Jogcups_jog_tWhen to jog copies of the page
    LeadingEdgecups_edge_tThe leading edge of the page
    Marginsunsigned[2]The lower-lefthand margin of the page in points
    ManualFeedcups_bool_tWhether or not to manually feed the page
    MediaPositionunsignedThe input slot number to use
    MediaWeightunsignedThe weight of the output media in grams/m2
    MirrorPrintcups_bool_tWhether or not to mirror the print
    NegativePrintcups_bool_tWhether or not to invert the print
    NumCopiesunsignedThe number of copies to produce
    Orientationcups_orient_tThe orientation of the page image
    OutputFaceUpcups_bool_tWhether or not to output the page face up
    PageSizeunsigned[2]The width and height of the page in points
    Separationscups_bool_tWhether or not to output separations
    TraySwitchcups_bool_tWhether or not to automatically switch trays for the requested - media size/type
    Tumblecups_bool_tWhether or not to rotate the back side of the page
    cupsWidthunsignedThe width of the page image in pixels
    cupsHeightunsignedThe height of the page image in pixels
    cupsMediaTypeunsignedThe device-specific media type code
    cupsBitsPerColorunsignedThe number of bits per color
    cupsBitsPerPixelunsignedThe number of bits per pixel
    cupsBytesPerLineunsignedThe number of bytes per line of image data
    cupsColorOrdercups_order_tThe order of color values
    cupsColorSpacecups_cspace_tThe type of color values
    cupsCompressionunsignedThe device-specific compression code
    cupsRowCountunsignedThe device-specific row count
    cupsRowFeedunsignedThe device-specific row feed
    cupsRowStepunsignedThe device-specific row step
    - -

    D - Functions

    - -

    This appendix provides a reference for all of the CUPS API functions. - - -

    cupsAddDest()

    - -

    Usage

    - -
    -int
-cupsAddDest(const char  *name,
-            const char  *instance,
-            int         num_dests,
-	    cups_dest_t **dests);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    nameThe name of the destination.
    instanceThe instance of the destination, or NULL for the primary instance.
    num_destsThe number of destinations in the array.
    destA pointer to the destination array pointer.
    - -

    Returns

    - -

    The new number of destinations in the array. - -

    Description

    - -

    cupsAddDest() adds the named destination to the destination -array if it does not already exist. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-
-
-num_dests = cupsAddDests("foo", "bar", num_dests, &dests);
-
    - -

    See Also

    - -

    -cupsFreeDests(), -cupsGetDest(), -cupsGetDests() - - -

    cupsAddOption()

    - -

    Usage

    - -
    -int
-cupsAddOption(const char    *name,
-              const char    *value,
-              int           num_options,
-	      cups_option_t **options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    nameThe name of the option.
    valueThe value of the option.
    num_optionsNumber of options currently in the array.
    optionsPointer to the options array.
    - -

    Returns

    - -

    The new number of options. - -

    Description

    - -

    cupsAddOption() adds an option to the specified array. - -

    Example

    - -
    -#include <cups.h>
-
-...
-
-/* Declare the options array */
-int           num_options;
-cups_option_t *options;
-
-/* Initialize the options array */
-num_options = 0;
-options     = (cups_option_t *)0;
-
-/* Add options using cupsAddOption() */
-num_options = cupsAddOption("media", "letter", num_options, &options);
-num_options = cupsAddOption("resolution", "300dpi", num_options, &options);
-
    - -

    See Also

    - -cupsEncodeOptions(), -cupsFreeOptions(), -cupsGetOption(), -cupsParseOptions() - - -

    cupsCancelJob()

    - -

    Usage

    - -
    -int
-cupsCancelJob(const char *dest,
-              int        job);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    destPrinter or class name
    jobJob ID
    - -

    Returns

    - -

    1 on success, 0 on failure. On failure the error can be found by calling -cupsLastError(). - -

    Description

    - -

    cupsCancelJob() cancels the specifies job. - -

    Example

    - -
    -#include <cups.h>
-
-cupsCancelJob("LaserJet", 1);
-
    - -

    See Also

    - -

    -cupsLastError(), -cupsPrintFile(), -cupsPrintFiles() - - -

    cupsDoFileRequest()

    - -

    Usage

    - -
    -ipp_t *
-cupsDoFileRequest(http_t     *http,
-                  ipp_t      *request,
-                  const char *resource,
-		  const char *filename);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpHTTP connection to server.
    requestIPP request data.
    resourceHTTP resource name for POST.
    filenameFile to send with POST request (NULL pointer if none.)
    - -

    Returns

    - -

    IPP response data or NULL if the request fails. On failure -the error can be found by calling -cupsLastError(). - -

    Description

    - -

    cupsDoFileRequest() does a HTTP POST request and provides the -IPP request and optionally the contents of a file to the IPP server. It also -handles resubmitting the request and performing password authentication as -needed. - -

    Example

    - -
    -#include <cups.h>
-
-http_t      *http;
-cups_lang_t *language;
-ipp_t       *request;
-ipp_t       *response;
-
-...
-
-/* Get the default language */
-language = cupsLangDefault();
-
-/* Create a new IPP request */
-request  = ippNew();
-
-request->request.op.operation_id = IPP_PRINT_FILE;
-request->request.op.request_id   = 1;
-
-/* Add required attributes */
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
-             "attributes-charset", NULL, cupsLangEncoding(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
-             "attributes-natural-language", NULL,
-             language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
-             NULL, "ipp://hostname/resource");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
-             NULL, cupsUser());
-
-/* Do the request... */
-response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsUser(), -httpConnect(), -ippAddString(), -ippNew() - - -

    cupsDoRequest()

    - -

    Usage

    - -
    -ipp_t *
-cupsDoRequest(http_t *http,
-              ipp_t *request,
-              const char *resource);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpHTTP connection to server.
    requestIPP request data.
    resourceHTTP resource name for POST.
    - -

    Returns

    - -

    IPP response data or NULL if the request fails. On failure -the error can be found by calling -cupsLastError(). - -

    Description

    - -

    cupsDoRequest() does a HTTP POST request and provides -the IPP request to the IPP server. It also handles resubmitting the -request and performing password authentication as needed. - -

    Example

    - -
    -#include <cups.h>
-
-http_t      *http;
-cups_lang_t *language;
-ipp_t       *request;
-ipp_t       *response;
-
-...
-
-/* Get the default language */
-language = cupsLangDefault();
-
-/* Create a new IPP request */
-request  = ippNew();
-
-request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
-request->request.op.request_id   = 1;
-
-/* Add required attributes */
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
-             "attributes-charset", NULL, cupsLangEncoding(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
-             "attributes-natural-language", NULL,
-             language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
-             NULL, "ipp://hostname/resource");
-
-/* Do the request... */
-response = cupsDoRequest(http, request, "/resource");
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsUser(), -httpConnect(), -ippAddString(), -ippNew() - - -

    cupsEncodeOptions()

    - -

    Usage

    - -
    -void
-cupsEncodeOptions(ipp_t         *ipp,
-                  int           num_options,
-		  cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request.
    num_optionsThe number of options.
    optionsThe options.
    - -

    Description

    - -

    cupsEncodeOptions() encodes all of the options -in the specified array as IPP attributes and adds them to the -IPP request. - -

    Example

    - -
    -#include <cups/cups.h>
-
-ipp_t         *ipp;
-int           num_options;
-cups_option_t *options;
-
-
-cupsEncodeOptions(ipp, num_options, options);
-
    - -

    See Also

    - -

    -cupsAddOption(), -cupsParseOptions(), -ippNew() - - -

    cupsEncryption()

    - -

    Usage

    - -
    -http_encryption_t
-cupsEncryption(void);
-
    - -

    Returns

    - -

    The current encryption setting. - -

    Description

    - -

    cupsEncryption() returns the current encryption setting -for IPP requests such as printing. - -

    Example

    - -
    -#include <cups/cups.h>
-
-http_t *http;
-
-printf("The current encryption setting is %d.\n", cupsEncryption());
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-
    - -

    See Also

    - -

    -cupsServer(), -httpConnectEncrypt(), -ippPort() - - -

    cupsFreeDests()

    - -

    Usage

    - -
    -void
-cupsFreeDests(int         num_dests,
-              cups_dest_t *dests);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    num_destsThe number of destinations in the array.
    destsThe destination array.
    - -

    Description

    - -

    cupsFreeDests() frees a destination array that was -created using cupsGetDests(). - -

    Example

    - -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    - -

    See Also

    - -

    -cupsGetDest(), -cupsGetDests() - - -

    cupsFreeJobs()

    - -

    Usage

    - -
    -void
-cupsFreeJobs(int        num_jobs,
-             cups_job_t *jobs);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    num_jobsThe number of jobs.
    jobsThe job array.
    - -

    Description

    - -

    cupsFreeJobs() frees an array of print jobs created by -the cupsGetJobs() function. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int        i;
-int        num_jobs;
-cups_job_t *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
-  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
-         jobs[i].user, jobs[i].title,
-	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-
    - -

    See Also

    - -

    -cupsGetJobs(), -cupsGetDests() - - -

    cupsFreeOptions()

    - -

    Usage

    - -
    -void
-cupsFreeOptions(int           num_options,
-                cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    num_optionsNumber of options in array.
    optionsPointer to options array.
    - -

    Description

    - -

    cupsFreeOptions() frees all memory associated with the -option array specified. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-
    - -

    See Also

    - -

    -cupsAddOption(), -cupsEncodeOptions(), -cupsGetOption(), -cupsMarkOptions(), -cupsParseOptions() - - -

    cupsGetClasses()

    - -

    Usage

    - -
    -int
-cupsGetClasses(char ***classes);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    classesPointer to character pointer array.
    - -

    Returns

    - -

    The number of printer classes available. - -

    Description

    - -

    cupsGetClasses() gets a list of the available printer classes. -The returned array should be freed using the free() when it is -no longer needed. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int  i;
-int  num_classes;
-char **classes;
-
-...
-
-num_classes = cupsGetClasses(&classes);
-
-...
-
-if (num_classes > 0)
-{
-  for (i = 0; i < num_classes; i ++)
-    free(classes[i]);
-
-  free(classes);
-}
-
    - -

    See Also

    - -

    -cupsGetDefault(), -cupsGetPrinters() - - -

    cupsGetDefault()

    - -

    Usage

    - -
    -const char *
-cupsGetDefault(void);
-
    - -

    Returns

    - -

    A pointer to the default destination. - -

    Description

    - -

    cupsGetDefault() gets the default destination printer or class. -The default destination is stored in a static string and will be overwritten -(usually with the same value) after each call. - -

    Example

    - -
    -#include <cups/cups.h>
-
-printf("The default destination is %s\n", cupsGetDefault());
-
    - -

    See Also

    - -

    -cupsGetClasses(), -cupsGetPrinters() - - -

    cupsGetDest()

    - -

    Usage

    - -
    -cups_dest_t *
-cupsGetDest(const char  *name,
-            const char  *instance,
-            int         num_dests,
-            cups_dest_t *dests);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    nameThe name of the destination, or NULL for the default destination.
    instanceThe instance of the destination, or NULL for the primary instance.
    num_destsThe number of destinations.
    destsThe destination array.
    - -

    Returns

    - -

    A pointer to the specified destination, or NULL if none exists. - -

    Description

    - -

    cupsGetDest() finds the specified destination in the array -of destinations created by the cupsGetDests() function. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    - -

    See Also

    - -

    -cupsGetDests(), -cupsGetJobs() - - -

    cupsGetDests()

    - -

    Usage

    - -
    -int
-cupsGetDests(cups_dest_t **dests);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    destsA pointer to a destination array pointer.
    - -

    Returns

    - -

    The number of available destinations. - -

    Description

    - -

    cupsGetDests() creates an array of available -destinations that the user can print to. The array should be -freed using the cupsFreeDests() function. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest      = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
-  printf("The default destination is %s\n", dest->name);
-else
-  puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-
    - -

    See Also

    - -

    -cupsFreeDests(), -cupsGetDest(), -cupsGetJobs() - - -

    cupsGetJobs()

    - -

    Usage

    - -
    -int
-cupsGetJobs(cups_job_t **jobs,
-            const char *dest,
-            int        myjobs,
-            int        completed);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    jobsA pointer to the job array pointer.
    destThe destination name, or NULL if jobs for all destinations are requested.
    myjobs1 if only those jobs submitted by the current - cupsUser() should be returned, 0 for jobs - submitted by all users.
    completed1 if only completed jobs should be returned, 0 if only - pending/processing jobs should be returned.
    - -

    Returns

    - -

    The number of jobs. - -

    Description

    - -

    cupsGetJobs() creates an array of print jobs based on the -arguments supplied in the function call. The returned array should be freed -using the cupsFreeJobs() function. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int        i;
-int        num_jobs;
-cups_job_t *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
-  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
-         jobs[i].user, jobs[i].title,
-	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-
    - -

    See Also

    - -

    -cupsFreeJobs(), -cupsGetDests() - - -

    cupsGetOption()

    - -

    Usage

    - -
    -const char *
-cupsGetOption(const char    *name,
-              int           num_options,
-              cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    nameThe name of the option.
    num_optionsThe number of options in the array.
    optionsThe options array.
    - -

    Returns

    - -

    A pointer to the option values or NULL if the option is -not defined. - -

    Description

    - -

    cupsGetOption() returns the first occurrence of the -named option. If the option is not included in the options array then a -NULL pointer is returned. - -

    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-const char    *media;
-
-...
-
-media = cupsGetOption("media", num_options, options);
-
    - -

    See Also

    - -

    -cupsAddOption(), -cupsEncodeOptions(), -cupsFreeOptions(), -cupsMarkOptions(), -cupsParseOptions() - - -

    cupsGetPassword()

    - -

    Usage

    - -
    -const char *
-cupsGetPassword(const char *prompt);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    promptThe prompt to display to the user.
    - -

    Returns

    - -

    A pointer to the password that was entered or NULL if no -password was entered. - -

    Description

    - -

    cupsGetPassword() displays the prompt string and asks the user -for a password. The password text is not echoed to the user. - -

    Example

    - -
    -#include <cups/cups.h>
-
-char *password;
-
-...
-
-password = cupsGetPassword("Please enter a password:");
-
    - -

    See Also

    - -

    -cupsServer(), -cupsSetPasswordCB(), -cupsSetServer(), -cupsSetUser(), -cupsUser() - - -

    cupsGetPPD()

    - -

    Usage

    - -
    -const char *
-cupsGetPPD(const char *printer);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    printerThe name of the printer.
    - -

    Returns

    - -

    The name of a temporary file containing the PPD file or NULL -if the printer cannot be located or does not have a PPD file. - -

    Description

    - -

    cupsGetPPD() gets a copy of the PPD file for the named printer. -The printer name can be of the form "printer" or "printer@hostname". - -

    You should remove (unlink) the PPD file after you are done using it. The -filename is stored in a static buffer and will be overwritten with each call -to cupsGetPPD(). - -

    Example

    - -
    -#include <cups/cups.h>
-
-char *ppd;
-
-...
-
-ppd = cupsGetPPD("printer@hostname");
-
-...
-
-unlink(ppd);
-
    - - -

    cupsGetPrinters()

    - -

    Usage

    - -
    -int
-cupsGetPrinters(char ***printers);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    printersPointer to character pointer array.
    - -

    Returns

    - -

    The number of printer printers available. - -

    Description

    - -

    cupsGetPrinters() gets a list of the available printers. -The returned array should be freed using the free() when it is -no longer needed. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int  i;
-int  num_printers;
-char **printers;
-
-...
-
-num_printers = cupsGetPrinters(&printers);
-
-...
-
-if (num_printers > 0)
-{
-  for (i = 0; i < num_printers; i ++)
-    free(printers[i]);
-
-  free(printers);
-}
-
    - -

    See Also

    - -

    -cupsGetClasses() -cupsGetDefault() - - -

    cupsLangDefault()

    - -

    Usage

    - -
    -const char *
-cupsLangDefault(void);
-
    - -

    Returns

    - -

    A pointer to the default language structure. - -

    Description

    - -

    cupsLangDefault() returns a language structure for the default -language. The default language is defined by the LANG environment -variable. If the specified language cannot be located then the POSIX (English) -locale is used. - -

    Call cupsLangFree() to free any memory associated with the -language structure when you are done. - -

    Example

    - -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-...
-
-language = cupsLangDefault();
-
-...
-
-cupsLangFree(language);
-
    - -

    See Also

    - -

    -cupsLangEncoding(), -cupsLangFlush(), -cupsLangFree(), -cupsLangGet(), -cupsLangString() - - -

    cupsLangEncoding()

    - -

    Usage

    - -
    -char *
-cupsLangEncoding(cups_lang_t *language);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    languageThe language structure.
    - -

    Returns

    - -

    A pointer to the encoding string. - -

    Description

    - -

    cupsLangEncoding() returns the language encoding used for the -specified language, e.g. "iso-8859-1", "utf-8", etc. - -

    Example

    - -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-char        *encoding;
-...
-
-language = cupsLangDefault();
-encoding = cupsLangEncoding(language);
-...
-
-cupsLangFree(language);
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangFlush(), -cupsLangFree(), -cupsLangGet(), -cupsLangString() - - -

    cupsLangFlush()

    - -

    Usage

    - -
    -void
-cupsLangFlush(void);
-
    - -

    Description

    - -

    cupsLangFlush() frees all language structures that have been -allocated. - -

    Example

    - -
    -#include <cups/language.h>
-
-...
-
-cupsLangFlush();
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsLangFree(), -cupsLangGet(), -cupsLangString() - - -

    cupsLangFree()

    - -

    Usage

    - -
    -void
-cupsLangFree(cups_lang_t *language);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    languageThe language structure to free.
    - -

    Description

    - -

    cupsLangFree() frees the specified language structure. - -

    Example

    - -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-...
-
-cupsLangFree(language);
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsLangFlush(), -cupsLangGet(), -cupsLangString() - - -

    cupsLangGet()

    - -

    Usage

    - -
    -cups_lang_t *
-cupsLangGet(const char *name);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    nameThe name of the locale.
    - -

    Returns

    - -

    A pointer to a language structure. - -

    Description

    - -

    cupsLangGet() returns a language structure for the specified -locale. If the locale is not defined then the POSIX (English) locale is -substituted. - -

    Example

    - -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-
-...
-
-language = cupsLangGet("fr");
-
-...
-
-cupsLangFree(language);
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsLangFlush(), -cupsLangFree(), -cupsLangString() - - -

    cupsLangString()

    - -

    Usage

    - -
    -char *
-cupsLangString(cups_lang_t *language,
-               int         message);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    languageThe language to query.
    messageThe message number.
    - -

    Returns

    - -

    A pointer to the message string or NULL if the message is -not defined. - -

    Description

    - -

    cupsLangString() returns a pointer to the specified message -string in the specified language. - -

    Example

    - -
    -#include <cups/language.h>
-
-cups_lang_t *language;
-char        *s;
-...
-
-language = cupsLangGet("fr");
-
-s = cupsLangString(language, CUPS_MSG_YES);
-
-...
-
-cupsLangFree(language);
-
    - -

    See Also

    - -

    -cupsLangDefault(), -cupsLangEncoding(), -cupsLangFlush(), -cupsLangFree(), -cupsLangGet() - - -

    cupsLastError()

    - -

    Usage

    - -
    -ipp_status_t
-cupsLastError(void);
-
    - -

    Returns

    - -

    An enumeration containing the last IPP error. - -

    Description

    - -

    cupsLastError() returns the last IPP error that occurred. -If no error occurred then it will return IPP_OK or -IPP_OK_CONFLICT. - -

    Example

    - -
    -#include <cups/cups.h>
-
-ipp_status_t status;
-
-...
-
-status = cupsLastError();
-
    - -

    See Also

    - -

    -cupsCancelJob(), -cupsPrintFile() - - -

    cupsMarkOptions()

    - -

    Usage

    - -
    -int
-cupsMarkOptions(ppd_file_t    *ppd,
-                int           num_options,
-                cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file to mark.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    - -

    Returns

    - -

    The number of conflicts found. - -

    Description

    - -

    cupsMarkOptions() marks options in the PPD file. It also -handles mapping of IPP option names and values to PPD option names. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-ppd_file_t    *ppd;
-
-...
-
-cupsMarkOptions(ppd, num_options, options);
-
    - -

    See Also

    - -

    -cupsAddOption(), -cupsFreeOptions(), -cupsGetOption(), -cupsParseOptions() - - -

    cupsParseOptions()

    - -

    Usage

    - -
    -int
-cupsParseOptions(const char    *arg,
-                 int           num_options,
-                 cups_option_t **options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    argThe string containing one or more options.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array pointer.
    - -

    Returns

    - -

    The new number of options in the array. - -

    Description

    - -

    cupsParseOptions() parses the specifies string for one -or more options of the form "name=value", "name", or "noname". It can -be called multiple times to combine the options from several strings. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-
-...
-
-num_options = 0;
-options     = (cups_option_t *)0;
-num_options = cupsParseOptions(argv[5], num_options, &options);
-
    - -

    See Also

    - -

    -cupsAddOption(), -cupsFreeOptions(), -cupsGetOption(), -cupsMarkOptions() - - -

    cupsPrintFile()

    - -

    Usage

    - -
    -int
-cupsPrintFile(const char    *printer,
-              const char    *filename,
-              const char    *title,
-	      int           num_options,
-	      cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    printerThe printer or class to print to.
    filenameThe file to print.
    titleThe job title.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    - -

    Returns

    - -

    The new job ID number or 0 on error. - -

    Description

    - -

    cupsPrintFile() sends a file to the specified printer or -class for printing. If the job cannot be printed the error code can be -found by calling cupsLastError(). - -

    Example

    - -
    -#include <cups/cups.h>
-
-int           num_options;
-cups_option_t *options;
-int           jobid;
-
-...
-
-jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
-                      num_options, options);
-
    - -

    See Also

    - -

    -cupsCancelJob(), -cupsLastError(), -cupsPrintFiles() - - -

    cupsPrintFiles()

    - -

    Usage

    - -
    -int
-cupsPrintFiles(const char    *printer,
-               int           num_files,
-               const char    **files,
-               const char    *title,
-	       int           num_options,
-	       cups_option_t *options);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    printerThe printer or class to print to.
    num_filesThe number of files to print.
    filesThe files to print.
    titleThe job title.
    num_optionsThe number of options in the options array.
    optionsA pointer to the options array.
    - -

    Returns

    - -

    The new job ID number or 0 on error. - -

    Description

    - -

    cupsPrintFiles() sends multiple files to the specified -printer or class for printing. If the job cannot be printed the error -code can be found by calling cupsLastError(). - -

    Example

    - -
    -#include <cups/cups.h>
-
-int           num_files;
-const char    *files[100];
-int           num_options;
-cups_option_t *options;
-int           jobid;
-
-...
-
-jobid = cupsPrintFiles("printer@hostname", num_files, files,
-                       "Job Title", num_options, options);
-
    - -

    See Also

    - -

    -cupsCancelJob(), -cupsLastError(), -cupsPrintFile() - - -

    cupsRasterClose()

    - -

    Usage

    - -
    -void
-cupsRasterClose(cups_raster_t *ras);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    rasThe raster stream to close.
    - -

    Description

    - -

    cupsRasterClose() closes the specified raster stream. - -

    Example

    - -
    -#include <cups/raster.h>
-
-cups_raster_t *ras;
-
-...
-
-cupsRasterClose(ras);
-
    - -

    See Also

    - -

    -cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - - -

    cupsRasterOpen()

    - -

    Usage

    - -
    -cups_raster_t *
-cupsRasterOpen(int         fd,
-               cups_mode_t mode);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    fdThe file descriptor to use.
    modeThe mode to use; CUPS_RASTER_READ or - CUPS_RASTER_WRITE.
    - -

    Returns

    - -

    A pointer to a raster stream or NULL if there was an error. - -

    Description

    - -

    cupsRasterOpen() opens a raster stream for reading or writing. - -

    Example

    - -
    -#include <cups/raster.h>
-
-cups_raster_t *ras;
-
-...
-
-ras = cupsRasterOpen(0, CUPS_RASTER_READ);
-
    - -

    See Also

    - -

    -cupsRasterClose(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - - -

    cupsRasterReadHeader()

    - -

    Usage

    - -
    -unsigned
-cupsRasterReadHeader(cups_raster_t      *ras,
-                     cups_page_header_t *header);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    rasThe raster stream to read from.
    headerA pointer to a page header structure to read into.
    - -

    Returns

    - -

    1 on success, 0 on EOF or error. - -

    Description

    - -

    cupsRasterReadHeader() reads a page header from the specified -raster stream. - -

    Example

    - -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ...
-
-  for (line = 0; line < header.cupsHeight; line ++)
-  {
-    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
-    ...
-  }
-}
-
    - -

    See Also

    - -

    -cupsRasterClose(), -cupsRasterOpen(), -cupsRasterReadPixels(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - - -

    cupsRasterReadPixels()

    - -

    Usage

    - -
    -unsigned
-cupsRasterReadPixels(cups_raster_t *ras,
-                     unsigned char *pixels,
-		     unsigned      length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    rasThe raster stream to read from.
    pixelsThe pointer to a pixel buffer.
    lengthThe number of bytes of pixel data to read.
    - -

    Returns

    - -

    The number of bytes read or 0 on EOF or error. - -

    Description

    - -

    cupsRasterReadPixels() reads pixel data from the specified -raster stream. - -

    Example

    - -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
-  ...
-
-  for (line = 0; line < header.cupsHeight; line ++)
-  {
-    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
-    ...
-  }
-}
-
    - -

    See Also

    - -

    -cupsRasterClose(), -cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterWriteHeader(), -cupsRasterWritePixels() - - -

    cupsRasterWriteHeader()

    - -

    Usage

    - -
    -unsigned
-cupsRasterWriteHeader(cups_raster_t      *ras,
-                      cups_page_header_t *header);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    rasThe raster stream to write to.
    headerA pointer to the page header to write.
    - -

    Returns

    - -

    1 on success, 0 on error. - -

    Description

    - -

    cupsRasterWriteHeader() writes the specified page header to -a raster stream. - -

    Example

    - -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
-  ...
-
-  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-
    - -

    See Also

    - -

    -cupsRasterClose(), -cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWritePixels() - - -

    cupsRasterWritePixels()

    - -

    Usage

    - -
    -unsigned
-cupsRasterWritePixels(cups_raster_t *ras,
-                      unsigned char *pixels,
-		      unsigned      length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    rasThe raster stream to write to.
    pixelsThe pixel data to write.
    lengthThe number of bytes to write.
    - -

    Returns

    - -

    The number of bytes written. - -

    Description

    - -

    cupsRasterWritePixels() writes the specified pixel data to a -raster stream. - -

    Example

    - -
    -#include <cups/raster.h>
-
-int                  line;
-cups_raster_t        *ras;
-cups_raster_header_t header;
-unsigned char        pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
-  ...
-
-  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-
    - -

    See Also

    - -

    -cupsRasterClose(), -cupsRasterOpen(), -cupsRasterReadHeader(), -cupsRasterReadPixels(), -cupsRasterWriteHeader() - - -

    cupsServer()

    - -

    Usage

    - -
    -const char *
-cupsServer(void);
-
    - -

    Returns

    - -

    A pointer to the default server name. - -

    Description

    - -

    cupsServer() returns a pointer to the default server name. -The server name is stored in a static location and will be overwritten with -every call to cupsServer(). - -

    The default server is determined from the following locations: - -

      - -
    1. The CUPS_SERVER environment variable, - -
    2. The ServerName directive in the - client.conf file, - -
    3. The default host, "localhost". - -
    - -

    Example

    - -
    -#include <cups/cups.h>
-
-const char *server;
-
-server = cupsServer();
-
    - -

    See Also

    - -

    -cupsGetPassword(), -cupsSetPasswordCB(), -cupsSetServer(), -cupsSetUser(), -cupsUser() - - -

    cupsSetDests()

    - -

    Usage

    - -
    -void
-cupsSetDests(int         num_dests,
-             cups_dest_t *dests);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    num_destsNumber of destinations.
    destsArray of destinations.
    - -

    Description

    - -

    cupsSetDests() saves the destination array to -disk. If the current UID is 0, the destinations are saved in the -/etc/cups/lpoptions file, otherwise they are saved -in the ~/.lpoptions file. This function is typically used -to save the default options and instances that are set by the user. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int         num_dests;
-cups_dest_t *dests;
-
-...
-
-cupsSetDests(num_dests, dests);
-
    - -

    See Also

    - -

    -cupsGetDests() - - -

    cupsSetEncryption()

    - -

    Usage

    - -
    -void
-cupsSetEncryption(http_encryption_t encryption);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    encryptionThe type of encryption to use.
    - -

    Description

    - -

    cupsSetEncryption() sets the default type of encryption to -use when connecting with the print server. - -

    Example

    - -
    -#include <cups/cups.h>
-
-cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
-
    - -

    See Also

    - -

    -cupsEncryption() - - -

    cupsSetPasswordCB()

    - -

    Usage

    - -
    -void
-cupsSetPasswordCB(const char *(*cb)(const char *prompt));
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    cbThe password callback function.
    - -

    Description

    - -

    cupsSetPasswordCB() sets the callback function to use when -asking the user for a password. The callback function must accept a single -character string pointer (the prompt string) and return NULL -if the user did not enter a password string or a pointer to the password -string otherwise. - -

    Example

    - -
    -#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
-  return (getpass(prompt));
-}
-
-...
-
-char *password;
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-password = cupsGetPassword("Please enter a password:");
-
    - -

    See Also

    - -

    -cupsServer(), -cupsSetServer(), -cupsSetUser(), -cupsUser() - - -

    cupsSetServer()

    - -

    Usage

    - -
    -void
-cupsSetServer(const char *server);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    serverThe default server to use.
    - -

    Description

    - -

    cupsSetServer() sets the default server to use for -the CUPS API. If the server argument is NULL, -the default server is used. - -

    Example

    - -
    -#include <cups/cups.h>
-
-cupsSetServer("foo.bar.com");
-
    - -

    See Also

    - -

    -cupsServer(), -cupsSetPasswordCB(), -cupsSetUser(), -cupsUser() - - -

    cupsSetUser()

    - -

    Usage

    - -
    -void
-cupsSetUser(const char *user);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    userThe user name string to use.
    - -

    Description

    - -

    cupsSetUser() sets the default user name for authentication. -If the user argument is NULL then the current -login user is used. - -

    Example

    - -
    -#include <cups/cups.h>
-
-...
-
-cupsSetUser("root");
-
    - -

    See Also

    - -

    -cupsServer(), -cupsSetPasswordCB(), -cupsSetServer(), -cupsUser() - - -

    cupsTempFd()

    - -

    Usage

    - -
    -int
-cupsTempFd(char *filename,
-           int  length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    filenameThe character string to hold the temporary filename.
    lengthThe size of the filename string in bytes.
    - -

    Returns

    - -

    A file descriptor open for reading and writing. - -

    Description

    - -

    cupsTempFd() create a temporary filename in the -/var/tmp directory or the directory specified by the -TMPDIR environment variable. - -

    Example

    - -
    -#include <cups/cups.h>
-
-int  fd;
-char filename[256];
-
-fd = cupsTempFd(filename, sizeof(filename));
-
    - -

    See Also

    - -

    -cupsTempFile() - - -

    cupsTempFile()

    - -

    Usage

    - -
    -char *
-cupsTempFile(char *filename,
-             int  length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    filenameThe character string to hold the temporary filename.
    lengthThe size of the filename string in bytes.
    - -

    Returns

    - -

    A pointer to filename. - -

    Description

    - -

    cupsTempFile() creates a temporary filename in the -/var/tmp directory or the directory specified by the -TMPDIR environment variable. - -

    Example

    - -
    -#include <cups/cups.h>
-
-char filename[256];
-
-cupsTempFile(filename, sizeof(filename));
-
    - -

    See Also

    - -

    -cupsTempFd() - - -

    cupsUser()

    - -

    Usage

    - -
    -const char *
-cupsUser(void);
-
    - -

    Returns

    - -

    A pointer to the current username or NULL if the user ID is -undefined. - -

    Description

    - -

    cupsUser() returns the name associated with the current -user ID as reported by the getuid() system call. - -

    Example

    - -
    -#include <cups/cups.h>
-
-const char *user;
-
-user = cupsUser();
-
    - -

    See Also

    - -

    -cupsGetPassword(), -cupsServer() - - -

    httpBlocking()

    - -

    Usage

    - -
    -void
-httpBlocking(http_t *http,
-             int    blocking)
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    blocking0 if the connection should be non-blocking, 1 if it should - be blocking
    - -

    Description

    - -

    The httpBlocking() function sets the blocking mode for the -HTTP connection. By default HTTP connections will block (stop) the client -program until data is available or can be sent to the server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnect("server", port);
-httpBlocking(http, 0);
-
    - -

    See Also

    - -httpCheck(), -httpConnect() - - -

    httpCheck()

    - -

    Usage

    - -
    -int
-httpCheck(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Returns

    - -

    0 if there is no data pending, 1 otherwise. - -

    Description

    - -

    The httpCheck() function checks to see if there is any data -pending on an HTTP connection. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-if (httpCheck(http))
-{
-  ... do something ...
-}
-
    - -

    See Also

    - -httpBlocking(), -httpConnect(), -httpGets(), -httpRead() - - -

    httpClearFields()

    - -

    Usage

    - -
    -void
-httpClearFields(http_t *http)
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Description

    - -

    The httpClearFields() function clears all HTTP request fields -for the HTTP connection. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpClearFields(http);
-
    - -

    See Also

    - -httpConnect(), -httpGetField(), -httpSetField() - - -

    httpClose()

    - -

    Usage

    - -
    -void
-httpClose(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Description

    - -

    The httpClose() function closes an active HTTP connection. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpClose(http);
-
    - -

    See Also

    - -httpConnect() - - -

    httpConnect()

    - -

    Usage

    - -
    -http_t *
-httpConnect(const char *hostname,
-            int        port);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    hostnameThe name or IP address of the server to connect to
    portThe port number to use
    - -

    Returns

    - -

    A pointer to a HTTP connection structure or NULL if the connection could -not be made. - -

    Description

    - -

    The httpConnect() function opens a HTTP connection to the -specified server and port. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnect(cupsServer(), ippPort());
-
    - -

    See Also

    - -httpClose(), -httpConnectEncrypt(), -httpGet(), -httpGets(), -httpPost(), -httpRead(), -httpWrite() - - -

    httpConnectEncrypt()

    - -

    Usage

    - -
    -http_t *
-httpConnectEncrypt(const char        *hostname,
-                   int               port,
-                   http_encryption_t encryption);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    hostnameThe name or IP address of the server to connect to
    portThe port number to use
    encryptionThe level of encryption to use
    - -

    Returns

    - -

    A pointer to a HTTP connection structure or NULL if the connection could -not be made. - -

    Description

    - -

    The httpConnectEncrypt() function opens a HTTP -connection to the specified server, port, and encryption. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-
    - -

    See Also

    - -httpClose(), -httpConnect(), -httpGet(), -httpGets(), -httpPost(), -httpRead(), -httpWrite() - - -

    httpDecode64()

    - -

    Usage

    - -
    -char *
-httpDecode64(char       *out,
-             const char *in);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    outThe output string
    inThe input string
    - -

    Returns

    - -

    A pointer to the decoded string. - -

    Description

    - -

    The httpDecode64() function decodes a base-64 encoded string -to the original string. - -

    Example

    - -
    -#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpDecode64(original_string, encoded_string);
-
    - -

    See Also

    - -httpEncode64() - - -

    httpDelete()

    - -

    Usage

    - -
    -int
-httpDelete(http_t     *http,
-           const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to delete
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpDelete() function sends a HTTP DELETE request to -the server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpEncode64()

    - -

    Usage

    - -
    -char *
-httpEncode64(char       *out,
-             const char *in);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    outThe output string
    inThe input string
    - -

    Returns

    - -

    A pointer to the encoded string. - -

    Description

    - -

    The httpEncode64() function decodes a base-64 encoded string -to the original string. - -

    Example

    - -
    -#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpEncode64(encoded_string, original_string);
-
    - -

    See Also

    - -httpDecode64() - - -

    httpEncryption()

    - -

    Usage

    - -
    -int
-httpEncryption(http_t            *http,
-               http_encryption_t encryption);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection.
    encryptionThe desired level of encryption.
    - -

    Returns

    - -

    0 on success, -1 on error. - -

    Description

    - -

    httpEncryption() sets the encryption level for the HTTP -connection. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
-
    - -

    See Also

    - -

    -httpConnectEncrypt() - - -

    httpError()

    - -

    Usage

    - -
    -int
-httpError(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Returns

    - -

    The last error that occurred or 0 if no error has occurred. - -

    Description

    - -

    The httpError() function returns the last error that occurred -on the HTTP connection. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-if (httpError(http))
-{
-  ... show an error message ...
-}
-
    - -

    See Also

    - -httpConnect() - - -

    httpFlush()

    - -

    Usage

    - -
    -void
-httpFlush(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Description

    - -

    The httpFlush() function flushes any remaining data left from -a GET or POST operation. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpFlush(http);
-
    - -

    See Also

    - -httpConnect(), - - -

    httpGet()

    - -

    Usage

    - -
    -int
-httpGet(http_t     *http,
-        const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to get
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpGet() function sends a HTTP GET request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpGet(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpGets()

    - -

    Usage

    - -
    -char *
-httpGets(char   *line,
-         int    length,
-         http_t *http)
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    lineThe string to fill with a line from the HTTP connection
    lengthThe maximum length of the string
    httpThe HTTP connection
    - -

    Returns

    - -

    A pointer to the string or NULL if no line could be retrieved. - -

    Description

    - -

    The httpGets() function is used to read a request line from -the HTTP connection. It is not normally used by a client program. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-char   line[1024];
-
-if (httpGets(line, sizeof(line), http))
-{
-  ... process the line ...
-}
-
    - -

    See Also

    - -httpConnect(), -httpUpdate() - - -

    httpGetDateString()

    - -

    Usage

    - -
    -const char *
-httpGetDateString(time_t time)
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    timeThe UNIX date/time value
    - -

    Returns

    - -

    A pointer to a static string containing the HTTP date/time string for -the specified UNIX time value. - -

    Description

    - -

    The httpGetDateString() function generates a date/time string -suitable for HTTP requests from a UNIX time value. - -

    Example

    - -
    -#include <cups/http.h>
-
-puts(httpGetDateString(time(NULL)));
-
    - -

    See Also

    - -httpGetDateTime() - - -

    httpGetDateTime()

    - -

    Usage

    - -
    -time_t
-httpGetDateTime(const char *date)
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    dateThe HTTP date/time string
    - -

    Returns

    - -

    A UNIX time value. - -

    Description

    - -

    The httpGetDateTime() function converts a HTTP -date/time string to a UNIX time value. - -

    Example

    - -
    -#include <cups/http.h>
-
-printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
-
    - -

    See Also

    - -httpGetDateString() - - -

    httpGetField()

    - -

    Usage

    - -
    -const char *
-httpGetField(http_t       *http,
-             http_field_t field);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    fieldThe HTTP field
    - -

    Returns

    - -

    A pointer to the field value string. - -

    Description

    - -

    The httpGetField() function returns the current value for -the specified HTTP field. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
-
    - -

    See Also

    - -httpConnect(), -httpGetSubField(), -httpSetField() - - -

    httpGetHostByName()

    - -

    Usage

    - -
    -struct hostent	*
-httpGetHostByName(const char *name);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    nameName or IP address to lookup.
    - -

    Returns

    - -

    NULL if the host could not be found or a pointer to a host entry -containing one or more addresses. - -

    Description

    - -

    httpGetHostByName() is a portable wrapper around the -gethostbyname() function which handles both hostnames -and IP addresses. - -

    Example

    - -
    -#include <cups/http.h>
-
-struct hostent *hostaddr;
-
-hostaddr = httpGetHostByName("foo.bar.com");
-
    - - -

    httpGetLength()

    - -

    Usage

    - -
    -int
-httpGetLength(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection.
    - -

    Returns

    - -

    The content length of the response or MAX_INT if chunking is used. - -

    Description

    - -

    httpGetLength() returns the content length of a response. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-printf("The length of the response is %d bytes.\n", httpGetLength(http));
-
    - -

    See Also

    - -

    -httpGet(), -httpPost() - - -

    httpGetSubField()

    - -

    Usage

    - -
    -const char *
-httpGetSubField(http_t       *http,
-                http_field_t field,
-		const char   *name,
-		char         *value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection.
    fieldThe HTTP field.
    nameThe name of the subfield.
    valueThe string to hold the subfield value.
    - -

    Returns

    - -

    A pointer to the subfield value string or NULL if it does not exist. - -

    Description

    - -

    The httpGetSubField() function returns a subfield value -from the specified HTTP field. The destination string buffer must be at -least HTTP_MAX_VALUE bytes in length. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-char   value[HTTP_MAX_VALUE];
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
-
    - -

    See Also

    - -httpConnect(), -httpGetField(), -httpSetField() - - -

    httpHead()

    - -

    Usage

    - -
    -int
-httpHead(http_t     *http,
-         const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to head
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpHead() function sends a HTTP HEAD request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpHead(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpInitialize()

    - -

    Usage

    - -
    -void httpInitialize(void);
-
    - -

    Description

    - -

    The httpInitialize() function initializes the networking -code as needed by the underlying platform. It is called automatically by -the httpConnect() function. - -

    Example

    - -
    -#include <cups/http.h>
-
-httpInitialize();
-
    - -

    See Also

    - -httpConnect() - - -

    httpMD5()

    - -

    Usage

    - -
    -char *
-httpMD5(const char *username,
-        const char *realm,
-        const char *passwd,
-        char       md5[33]);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    usernameThe authenticating user name.
    realmThe authenticating realm name.
    passwdThe authenticating password.
    md5The MD5 sum string.
    - -

    Returns

    - -

    A pointer to the MD5 sum string. - -

    Description

    - -

    httpMD5() computes the MD5 hash of the username, -realm, and password as required by the HTTP Digest specification. - -

    Example

    - -
    -#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5("user", "realm", "password", md5);
-
    - -

    See Also

    - -

    -httpMD5Final(), -httpMD5String() - - -

    httpMD5Final()

    - -

    Usage

    - -
    -char *
-httpMD5Final(const char *nonce,
-             const char *method,
-             const char *resource,
-             char       md5[33]);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    nonceThe server nonce value.
    methodThe HTTP method (GET, POST, etc.)
    resourceThe resource path.
    md5The MD5 sum string.
    - -

    Returns

    - -

    The MD5 sum string. - -

    Description

    - -

    httpMD5Final() appends the nonce, method, and resource -to the specified MD5 sum. - -

    Example

    - -
    -#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5Final("nonce", "GET", "/jobs", md5);
-
    - -

    See Also

    - -

    -httpMD5(), -httpMD5String() - - -

    httpMD5String()

    - -

    Usage

    - -
    -char *
-httpMD5String(const md5_byte_t *sum,
-              char             md5[33]);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    sumThe raw MD5 sum data.
    md5The MD5 sum string.
    - -

    Returns

    - -

    The MD5 sum string. - -

    Description

    - -

    httpMD5String() converts the raw MD5 sum value to a string. - -

    Example

    - -
    -#include <cups/http.h>
-
-md5_byte_t sum[16];
-char       md5[33];
-
-...
-
-httpMD5String(sum, md5);
-
    - -

    See Also

    - -

    -httpMD5(), -httpMD5Final() - - -

    httpOptions()

    - -

    Usage

    - -
    -int
-httpOptions(http_t     *http,
-            const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to check for options
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpOptions() function sends a HTTP OPTIONS request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpOptions(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpPost()

    - -

    Usage

    - -
    -int
-httpPost(http_t     *http,
-         const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to post to
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpPost() function sends a HTTP POST request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpPost(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpPrintf()

    - -

    Usage

    - -
    -int
-httpPrintf(http_t     *http,
-           const char *format,
-           ...);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    formatA printf-style format string
    - -

    Returns

    - -

    The number of bytes written. - -

    Description

    - -

    The httpPrintf() function sends a formatted string to the -HTTP connection. It is normally only used by the CUPS API and scheduler. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpPrintf(http, "GET / HTTP/1.1 \r\n");
-
    - -

    See Also

    - -httpConnect() - - -

    httpPut()

    - -

    Usage

    - -
    -int
-httpPut(http_t     *http,
-        const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to put
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpPut() function sends a HTTP PUT request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpRead()

    - -

    Usage

    - -
    -int
-httpRead(http_t *http,
-         char   *buffer,
-         int    length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    bufferThe buffer to read into
    lengthThe number of bytes to read
    - -

    Returns

    - -

    The number of bytes read or -1 on error. - -

    Description

    - -

    The httpRead() function reads data from the HTTP connection, -possibly the result of a GET or POST request. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-char buffer[1024];
-int  bytes;
-
-httpGet(http, "/");
-while (httpUpdate(http) != HTTP_CONTINUE);
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
-  buffer[bytes] = '\0';
-  fputs(buffer, stdout);
-}
-
    - -

    See Also

    - -httpConnect(), -httpWrite() - - -

    httpReconnect()

    - -

    Usage

    - -
    -int
-httpReconnect(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpReconnect() function reconnects to the HTTP server. -This is usually done automatically if the HTTP functions detect that the -server connection has terminated. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpReconnect(http);
-
    - -

    See Also

    - -httpConnect() - - -

    httpSeparate()

    - -

    Usage

    - -
    -void
-httpSeparate(const char *uri,
-             char       *method,
-             char       *username,
-             char       *host,
-             int        *port,
-             char       *resource);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    uriThe URI to separate
    methodThe method (scheme) of the URI
    usernameThe username (and password) portion of the URI, if any
    hostThe hostname portion of the URI, if any
    portThe port number for the URI, either as specified or as - default for the method/scheme
    resourceThe resource string, usually a filename on the server
    - -

    Description

    - -

    The httpSeparate() function separates the specified URI into -its component parts. The method, username, hostname, and resource strings should -be at least HTTP_MAX_URI characters long to avoid potential -buffer overflow problems. - -

    Example

    - -
    -char uri[HTTP_MAX_URI];
-char method[HTTP_MAX_URI];
-char username[HTTP_MAX_URI];
-char host[HTTP_MAX_URI];
-char resource[HTTP_MAX_URI];
-int  port;
-
-...
-
-httpSeparate(uri, method, username, host, &port, resource);
-
    - -

    See Also

    - -httpConnect() - - -

    httpSetField()

    - -

    Usage

    - -
    -void
-httpSetField(http_t       *http,
-             http_field_t field,
-             const char   *value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    fieldThe HTTP field
    valueThe string value for the field
    - -

    Description

    - -

    The httpSetField() function sets the current value for -the specified HTTP field. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
    - -

    See Also

    - -httpConnect(), -httpGetField() - - -

    httpStatus()

    - -

    Usage

    - -
    -const char *
-httpStatus(http_status_t status);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    statusThe HTTP status code from the server.
    - -

    Returns

    - -

    The standard HTTP status text associated with the status code. - -

    Description

    - -

    httpStatus() returns the standard HTTP status text -associated with the status code. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-...
-
-puts(httpStatus(http->status));
-
    - - -

    httpTrace()

    - -

    Usage

    - -
    -int
-httpTrace(http_t     *http,
-          const char *uri);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    uriThe URI to trace
    - -

    Returns

    - -

    0 on success, non-zero on failure. - -

    Description

    - -

    The httpTrace() function sends a HTTP TRACE request to the -server. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-
-httpTrace(http, "/some/uri");
-
    - -

    See Also

    - -httpConnect(), -httpSetField(), -httpUpdate() - - -

    httpUpdate()

    - -

    Usage

    - -
    -http_status_t
-httpUpdate(http_t *http);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    - -

    Returns

    - -

    The HTTP status of the current request. - -

    Description

    - -

    The httpUpdate() function updates the current request status. -It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE -request to finalize the HTTP request and retrieve the request status. - -

    Since proxies and the current blocking mode can cause the request to -take longer, programs should continue calling httpUpdate() -until the return status is not the constant value HTTP_CONTINUE. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-http_status_t status;
-
-httpGet(http, "/some/uri");
-while ((status = httpUpdate(http)) == HTTP_CONTINUE);
-printf("Request status is %d\n", status);
-
    - -

    See Also

    - -httpConnect(), -httpDelete(), -httpGet(), -httpHead(), -httpOptions(), -httpPost(), -httpPut(), -httpTrace() - - -

    httpWrite()

    - -

    Usage

    - -
    -int
-httpWrite(http_t *http,
-          char   *buffer,
-          int    length);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    bufferThe buffer to read into
    lengthThe number of bytes to read
    - -

    Returns

    - -

    The number of bytes read or -1 on error. - -

    Description

    - -

    The httpWrite() function reads data from the HTTP connection, -possibly the result of a GET or POST request. - -

    Example

    - -
    -#include <cups/http.h>
-
-http_t *http;
-FILE *fp;
-char buffer[1024];
-int  bytes;
-
-httpPost(http, "/");
-
-while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
-  httpWrite(http, buffer, bytes);
-
-while (httpUpdate(http) != HTTP_CONTINUE);
-
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
-  buffer[bytes] = '\0';
-  fputs(buffer, stdout);
-}
-
    - -

    See Also

    - -httpConnect(), -httpRead() - - -

    ippAddBoolean()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddBoolean(ipp_t      *ipp,
-              ipp_tag_t  group,
-              const char *name,
-	      char       value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    valueThe boolean value
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddBoolean() function adds a single boolean attribute -value to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
-
    - -

    See Also

    - -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddBooleans()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddBooleans(ipp_t      *ipp,
-               ipp_tag_t  group,
-               const char *name,
-               int        num_values,
-               const char *values);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of values
    valuesThe boolean values
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddBooleans() function adds one or more boolean -attribute values to the specified IPP request. If the -values pointer is NULL then an array of -num_values false values is created. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-char values[10];
-
-ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddDate()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddDate(ipp_t       *ipp,
-           ipp_tag_t   group,
-           const char  *name,
-           ipp_uchar_t *value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    valueThe date value
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddDate() function adds a single date-time attribute -value to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", 
-           ippTimeToDate(time(NULL));
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings(), -ippTimeToDate() - - -

    ippAddInteger()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddInteger(ipp_t      *ipp,
-              ipp_tag_t  group,
-              ipp_tag_t  tag,
-              const char *name,
-              int        value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)
    nameThe name of attribute
    valueThe integer value
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddInteger() function adds a single integer attribute -value to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddIntegers()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddIntegers(ipp_t      *ipp,
-               ipp_tag_t  group,
-               ipp_tag_t  tag,
-               const char *name,
-               int        num_values,
-               const int  *values);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)
    nameThe name of attribute
    num_valuesThe number of values
    valuesThe integer values
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddIntegers() function adds one or more integer -attribute values to the specified IPP request. If the -values pointer is NULL then an array of -num_values 0 values is created. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int values[100];
-
-ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddRange()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddRange(ipp_t      *ipp,
-            ipp_tag_t  group,
-            const char *name,
-            int        low,
-            int        high);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    lowThe lower value
    highThe higher value
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddRange() function adds a single range attribute -value to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddRanges()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddRanges(ipp_t      *ipp,
-             ipp_tag_t  group,
-             const char *name,
-             int        num_values,
-             const int  *lows,
-             const int  *highs);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of range values
    lowsThe lower values
    highsThe higher values
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddRanges() function adds one or more range -attribute values to the specified IPP request. If the -values pointer is NULL then an array of -num_values 0,0 ranges is created. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int lows[2];
-int highs[2];
-
-ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddResolution()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddResolution(ipp_t      *ipp,
-                 ipp_tag_t  group,
-                 const char *name,
-                 int        xres,
-                 int        yres,
-                 ipp_res_t  units);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    xresThe horizontal resolution
    yresThe vertical resolution
    unitsThe resolution units
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddResolution() function adds a single resolution attribute -value to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
-              720, 720, IPP_RES_PER_INCH);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddResolutions()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddResolutions(ipp_t           *ipp,
-                  ipp_tag_t       group,
-                  const char      *name,
-                  int             num_values,
-                  const int       *xres,
-                  const int       *yres,
-                  const ipp_res_t *units);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    nameThe name of attribute
    num_valuesThe number of resolution values
    xresThe horizontal resolutions
    yresThe vertical resolutions
    unitsThe resolution units
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddResolutions() function adds one or more -resolution attribute values to the specified IPP request. If the -values pointer is NULL then an array of -num_values 0,0 resolutions is created. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-int xres[5];
-int yres[5];
-ipp_res_t units[5];
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
-              5, xres, yres, units);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddSeparator(), -ippAddString(), -ippAddStrings() - - -

    ippAddSeparator()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddSeparator(ipp_t *ipp);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    - -

    Returns

    - -

    A pointer to the new separator or NULL if the separator could not be -created. - -

    Description

    - -

    The ippAddSeparator() function adds a group separator -to the specified IPP request. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddSeparator(ipp);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddString(), -ippAddStrings() - - -

    ippAddString()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddString(ipp_t      *ipp,
-             ipp_tag_t  group,
-             ipp_tag_t  tag,
-             const char *name,
-             const char *charset,
-             const char *value);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of string value
    nameThe name of attribute
    charsetThe character set for the string
    valueThe string value
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddString() function adds a single string attribute -value to the specified IPP request. For IPP_TAG_NAMELANG and -IPP_TAG_TEXTLANG strings, the charset value is provided with -the string to identify the string encoding used. Otherwise the charset value -is ignored. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
-             NULL, "abc123");
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddStrings() - - -

    ippAddStrings()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippAddStrings(ipp_t      *ipp,
-              ipp_tag_t  group,
-              ipp_tag_t  tag,
-              const char *name,
-              int        num_values,
-              const char *charset,
-              const char **values);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request
    groupThe IPP group
    tagThe type of string value
    nameThe name of attribute
    num_valuesThe number of strings
    charsetThe character set for the strings
    valuesThe string values
    - -

    Returns

    - -

    A pointer to the new attribute or NULL if the attribute could not be -created. - -

    Description

    - -

    The ippAddStrings() function adds one or more string -attribute values to the specified IPP request. For -IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG -strings, the charset value is provided with the strings to identify the -string encoding used. Otherwise the charset value is ignored. If the -values pointer is NULL then an array of -num_values NULL strings is created. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-char *values[2] = { "one", "two" };
-
-ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
-              2, NULL, values);
-
    - -

    See Also

    - -ippAddBoolean(), -ippAddBooleans(), -ippAddDate(), -ippAddInteger(), -ippAddIntegers(), -ippAddRange(), -ippAddRanges(), -ippAddResolution(), -ippAddResolutions(), -ippAddSeparator(), -ippAddString() - - -

    ippDateToTime()

    - -

    Usage

    - -
    -time_t
-ippDateToTime(const ipp_uchar_t date[11]);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    dateThe IPP date-time value
    - -

    Returns

    - -

    A UNIX time value. - -

    Description

    - -

    The ippDateToTime() function converts an IPP date-time value -to a UNIX time value. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_uchar_t date[11];
-
-printf("UNIX time is %d\n", ippDateToTime(date));
-
    - -

    See Also

    - -ippTimeToDate() - - -

    ippDelete()

    - -

    Usage

    - -
    -void
-ippDelete(ipp_t *ipp);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    - -

    Description

    - -

    The ippDelete() function deletes all memory used by an IPP -request or response. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippDelete(ipp);
-
    - -

    See Also

    - -ippNew() - - -

    ippErrorString()

    - -

    Usage

    - -
    -const char *
-ippErrorString(ipp_status_t error);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    errorIPP error code.
    - -

    Returns

    - -

    The standard text representation of the IPP error code. - -

    Description

    - -

    ippErrorString() returns the standard text representation -of the IPP error code. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-puts(ippErrorString(IPP_OK));
-
    - -

    See Also

    - -

    -cupsLastError() - - -

    ippFindAttribute()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippFindAttribute(ipp_t      *ipp,
-                 const char *name,
-                 ipp_tag_t  tag);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    nameThe name of the attribute
    tagThe required value tag for the attribute or - IPP_TAG_ZERO for any type of value.
    - -

    Returns

    - -

    A pointer to the first occurrence of the requested attribute, or -NULL if it was not found. - -

    Description

    - -

    ippFindAttribute() finds the first occurrence of the named -attribute. The tag parameter restricts the search to a specific -value type - use IPP_TAG_ZERO to find any value with the name. - -

    The value tags IPP_TAG_NAME and IPP_TAG_TEXT -match the name/text values with or without the language code. - -

    Example

    - -
    -ipp_attribute_t *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
-  puts(attr->values[0].string.text);
-
-  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-
    - -

    See Also

    - -cupsDoFileRequest(), -cupsDoRequest(), -ippDelete(), -ippFindNextAttribute(), -ippNew() - - -

    ippFindNextAttribute()

    - -

    Usage

    - -
    -ipp_attribute_t *
-ippFindNextAttribute(ipp_t      *ipp,
-                     const char *name,
-                     ipp_tag_t  tag);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    nameThe name of the attribute
    tagThe required value tag for the attribute or - IPP_TAG_ZERO for any type of value.
    - -

    Returns

    - -

    A pointer to the next occurrence of the requested attribute, or -NULL if it was not found. - -

    Description

    - -

    ippFindNextAttribute() finds the next occurrence of the named -attribute. The tag parameter restricts the search to a specific -value type - use IPP_TAG_ZERO to find any value with the name. - -

    The value tags IPP_TAG_NAME and IPP_TAG_TEXT -match the name/text values with or without the language code. - -

    Example

    - -
    -ipp_attribute_t *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
-  puts(attr->values[0].string.text);
-
-  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-
    - -

    See Also

    - -cupsDoFileRequest(), -cupsDoRequest(), -ippDelete(), -ippFindNextAttribute(), -ippNew() - - -

    ippLength()

    - -

    Usage

    - -
    -int
-ippLength(ipp_t *ipp);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ippThe IPP request or response
    - -

    Returns

    - -

    The total encoded length of the IPP request or response in bytes. - -

    Description

    - -

    ippLength() returns the length of the IPP request or -response in bytes. - -

    Example

    - -
    -printf("The length of the response is %d bytes.\n", ippLength(response));
-
    - -

    See Also

    - -ippDelete(), -ippNew() - - -

    ippNew()

    - -

    Usage

    - -
    -ipp_t *
-ippNew(void);
-
    - -

    Returns

    - -

    A pointer to a new IPP request or response. - -

    Description

    - -

    The ippNew() function creates a new IPP request or response. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ipp = ippNew();
-
    - -

    See Also

    - -ippDelete() - - -

    ippPort()

    - -

    Usage

    - -
    -int
-ippPort(void);
-
    - -

    Returns

    - -

    The default TCP/IP port number for IPP requests. - -

    Description

    - -

    The ippPort() function returns the default IPP port number -for requests. - -

    Example

    - -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-
-http = httpConnect(cupsServer(), ippPort());
-
    - -

    See Also

    - -cupsServer(), -ippSetPort() - - -

    ippRead()

    - -

    Usage

    - -
    -ipp_state_t
-ippRead(http_t *http,
-        ipp_t  *ipp);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    ippThe IPP request or response
    - -

    Returns

    - -

    The current read state. - -

    Description

    - -

    The ippRead() function reads IPP attributes from the specified -HTTP connection. Programs should continue calling ippRead() until -IPP_ERROR or IPP_DATA is returned. - -

    Example

    - -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-
-while ((status = ippRead(http, ipp)) != IPP_ERROR)
-  if (status == IPP_DATA)
-    break;
-
-if (status == IPP_DATA)
-{
-  ... read additional non-IPP data using httpRead() ...
-}
-
    - -

    See Also

    - -ippWrite() - - -

    ippSetPort()

    - -

    Usage

    - -
    -void
-ippSetPort(int port);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    portThe port number to use
    - -

    Description

    - -

    The ippSetPort() function sets the default IPP port number -for requests. - -

    Example

    - -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-...
-
-ippSetPort(8631);
-
    - -

    See Also

    - -ippPort() - - -

    ippTimeToDate()

    - -

    Usage

    - -
    -ipp_uchar_t *
-ippTimeToDate(time_t time);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    timeThe UNIX time value
    - -

    Returns

    - -

    A static pointer to an IPP date-time value. - -

    Description

    - -

    The ippTimeToDate() function converts a UNIX time to an IPP -date-time value. - -

    Example

    - -
    -#include <cups/ipp.h>
-
-ipp_uchar_t *date;
-
-date = ippTimeToDate(time(NULL));
-
    - -

    See Also

    - -ippDateToTime() - - -

    ippWrite()

    - -

    Usage

    - -
    -ipp_state_t
-ippWrite(http_t *http,
-         ipp_t  *ipp);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    httpThe HTTP connection
    ippThe IPP request or response
    - -

    Returns

    - -

    The current write state. - -

    Description

    - -

    The ippWrite() function writes IPP attributes to the specified -HTTP connection. Programs should continue calling ippWrite() until -IPP_ERROR or IPP_DATA is returned. - -

    Example

    - -
    -#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-... add attributes ...
-
-while ((status = ippWrite(http, ipp)) != IPP_ERROR)
-  if (status == IPP_DATA)
-    break;
-
-if (status == IPP_DATA)
-{
-  ... read additional non-IPP data using httpWrite() ...
-}
-
    - -

    See Also

    - -ippRead() - - -

    ppdClose()

    - -

    Usage

    - -
    -void
-ppdClose(ppd_file_t *ppd);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    - -

    Description

    - -

    The ppdClose() function frees all memory associated with the -PPD file. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdClose(ppd);
-
    - -

    See Also

    - -ppdOpen(), -ppdOpenFd(), -ppdOpenFile() - - -

    ppdCollect()

    - -

    Usage

    - -
    -int
-ppdCollect(ppd_file_t    *ppd,
-           ppd_section_t section,
-           ppd_choice_t  ***choices);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file.
    sectionThe document section to collect.
    choicesThe array of option choices that are marked.
    - -

    Returns

    - -

    The number of options collected. - -

    Description

    - -

    ppdCollect() collects all of the marked options in the -specified section, sorts them by their order dependency values, and -returns an array that can be used to emit option commands in the proper -order. It is normally used by the ppdEmit*() functions. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t   *ppd;
-int          num_choices;
-ppd_choice_t **choices;
-
-...
-
-num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices);
-
    - -

    See Also

    - -

    -ppdEmit(), -ppdEmitFd(), -ppdEmitJCL() - - -

    ppdConflicts()

    - -

    Usage

    - -
    -int
-ppdConflicts(ppd_file_t *ppd);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    - -

    Returns

    - -

    The number of option conflicts in the file. - -

    Description

    - -

    The ppdConflicts() function returns the number of conflicts -with the currently selected options. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("%d conflicts\n", ppdConflicts(ppd));
-
    - -

    See Also

    - -cupsMarkOptions(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdEmit()

    - -

    Usage

    - -
    -int
-ppdEmit(ppd_file_t    *ppd,
-        FILE          *file,
-        ppd_section_t section);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    fileThe file to write to
    sectionThe option section to write
    - -

    Returns

    - -

    0 on success, -1 on error. - -

    Description

    - -

    The ppdEmit() function sends printer-specific option -commands to the specified file. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
-
    - -

    See Also

    - -ppdEmitFd() - - -

    ppdEmitFd()

    - -

    Usage

    - -
    -int
-ppdEmitFd(ppd_file_t    *ppd,
-          int           fd,
-          ppd_section_t section);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    fdThe file descriptor to write to
    sectionThe option section to write
    - -

    Returns

    - -

    0 on success, -1 on error. - -

    Description

    - -

    The ppdEmitFd() function sends printer-specific option -commands to the specified file descriptor. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
-
    - -

    See Also

    - -ppdEmit() - - -

    ppdFindChoice()

    - -

    Usage

    - -
    -ppd_choice_t *
-ppdFindChoice(ppd_option_t *option,
-              const char   *choice);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    optionA pointer to the option
    choiceThe name of the choice
    - -

    Returns

    - -

    A pointer to the choice data or NULL if the choice does not exist. - -

    Description

    - -

    The ppdFindChoice() function returns a pointer to the choice -data for the specified option. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-ppd_choice_t *choice;
-
-option = ppdFindOption(ppd, "PageSize");
-choice = ppdFindChoice(option, "Letter");
-
    - -

    See Also

    - -ppdFindMarkedChoice(), -ppdFindOption() - - -

    ppdFindMarkedChoice()

    - -

    Usage

    - -
    -ppd_choice_t *
-ppdFindMarkedChoice(ppd_file_t *ppd,
-                    const char *keyword);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    - -

    Returns

    - -

    A pointer to the choice data or NULL if the choice does not exist or -is not marked. - -

    Description

    - -

    The ppdFindMarkedChoice() function returns a pointer to -the marked choice data for the specified option. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_choice_t *choice;
-
-choice = ppdFindMarkedChoice(ppd, "PageSize");
-
    - -

    See Also

    - -ppdFindChoice(), -ppdFindOption() - - -

    ppdFindOption()

    - -

    Usage

    - -
    -ppd_option_t *
-ppdFindOption(ppd_file_t *ppd,
-              const char *keyword);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    - -

    Returns

    - -

    A pointer to the option data or NULL if the option does not exist. - -

    Description

    - -

    The ppdFindOption() function returns a pointer to the option -data for the specified option. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-
-option = ppdFindOption(ppd, "PageSize");
-
    - -

    See Also

    - -ppdFindChoice(), -ppdFindMarkedChoice() - - -

    ppdIsMarked()

    - -

    Usage

    - -
    -int
-ppdIsMarked(ppd_file_t *ppd,
-            const char *keyword,
-            const char *choice);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    choiceThe name of the option choice
    - -

    Returns

    - -

    1 if the choice is marked, 0 otherwise. - -

    Description

    - -

    The ppdIsMarked() function returns whether or not the -specified option choice is marked. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Letter size %s selected.\n",
-       ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
-
    - -

    See Also

    - -cupsMarkOptions(), -ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdMarkDefaults()

    - -

    Usage

    - -
    -void
-ppdMarkDefaults(ppd_file_t *ppd);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    - -

    Description

    - -

    The ppdMarkDefaults() function marks all of the default -choices in the PPD file. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkDefaults(ppd);
-
    - -

    See Also

    - -cupsMarkOptions(), -ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdMarkOption()

    - -

    Usage

    - -
    -int
-ppdMarkOption(ppd_file_t *ppd,
-              const char *keyword,
-              const char *choice);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    keywordThe name of the option
    choiceThe name of the choice
    - -

    Returns

    - -

    The number of conflicts in the PPD file. - -

    Description

    - -

    The ppdMarkOption() function marks the specified option -choice. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkOption(ppd, "PageSize", "Letter");
-
    - -

    See Also

    - -cupsMarkOptions(), -ppdConflicts(), -ppdIsMarked(), -ppdMarkDefaults(), -ppdMarkOption() - - -

    ppdOpen()

    - -

    Usage

    - -
    -ppd_file_t *
-ppdOpen(FILE *file);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    fileThe file to read from
    - -

    Returns

    - -

    A pointer to a PPD file structure or NULL if the PPD file could not be -read. - -

    Description

    - -

    The ppdOpen() function reads a PPD file from the specified -file into memory. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-FILE *file;
-
-file = fopen("filename.ppd", "rb");
-ppd = ppdOpen(file);
-fclose(file);
-
    - -

    See Also

    - -ppdClose(), -ppdOpenFd(), -ppdOpenFile() - - -

    ppdOpenFd()

    - -

    Usage

    - -
    -ppd_file_t *
-ppdOpenFd(int fd);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    fdThe file descriptor to read from
    - -

    Returns

    - -

    A pointer to a PPD file structure or NULL if the PPD file could not be -read. - -

    Description

    - -

    The ppdOpenFd() function reads a PPD file from the specified -file descriptor into memory. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-int        fd;
-
-fd = open("filename.ppd", O_RDONLY);
-ppd = ppdOpenFd(fd);
-close(fd);
-
    - -

    See Also

    - -ppdClose(), -ppdOpen(), -ppdOpenFile() - - -

    ppdOpenFile()

    - -

    Usage

    - -
    -ppd_file_t *
-ppdOpenFile(const char *filename);
-
    - -

    Arguments

    - -
    - - - - - - - - -
    ArgumentDescription
    filenameThe name of the file to read from
    - -

    Returns

    - -

    A pointer to a PPD file structure or NULL if the PPD file could not be -read. - -

    Description

    - -

    The ppdOpenFile() function reads a PPD file from the named -file into memory. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("filename.ppd");
-
    - -

    See Also

    - -ppdClose(), -ppdOpen(), -ppdOpenFd() - - -

    ppdPageLength()

    - -

    Usage

    - -
    -float
-ppdPageLength(ppd_file_t *ppd,
-              const char *name);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    - -

    Returns

    - -

    The length of the specified page size in points or 0 if the page size -does not exist. - -

    Description

    - -

    The ppdPageLength() function returns the page length of the -specified page size. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
-
    - -

    See Also

    - -ppdPageLength(), -ppdPageSize(), -ppdPageWidth() - - -

    ppdPageSize()

    - -

    Usage

    - -
    -ppd_size_t *
-ppdPageSize(ppd_file_t *ppd,
-            const char *name);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    - -

    Returns

    - -

    A pointer to the page size record of the specified page size in -points or NULL if the page size does not exist. - -

    Description

    - -

    The ppdPageSize() function returns the page size record for the -specified page size. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-
-size = ppdPageSize(ppd, "Letter");
-if (size != NULL)
-{
-  printf(" Width = %.0f\n", size->width);
-  printf("Length = %.0f\n", size->length);
-  printf("  Left = %.0f\n", size->left);
-  printf(" Right = %.0f\n", size->right);
-  printf("Bottom = %.0f\n", size->bottom);
-  printf("   Top = %.0f\n", size->top);
-}
-
    - -

    See Also

    - -ppdPageLength(), -ppdPageWidth() - - -

    ppdPageWidth()

    - -

    Usage

    - -
    -float
-ppdPageWidth(ppd_file_t *ppd,
-             const char *name);
-
    - -

    Arguments

    - -
    - - - - - - - - - - - - -
    ArgumentDescription
    ppdThe PPD file
    nameThe name of the page size
    - -

    Returns

    - -

    The width of the specified page size in points or 0 if the page size -does not exist. - -

    Description

    - -

    The ppdPageWidth() function returns the page width of the -specified page size. - -

    Example

    - -
    -#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
-
    - -

    See Also

    - -ppdPageLength(), -ppdPageSize() - - - - diff --git a/doc/sps.html b/doc/sps.html deleted file mode 100644 index 90b032fa8b..0000000000 --- a/doc/sps.html +++ /dev/null @@ -1,297 +0,0 @@ - - - -CUPS Software Performance Specification - - - - - - - -

    -

    CUPS Software Performance Specification


    -CUPS-SPS-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Programs -
    -
    4 Scheduler Objects -
    -
    A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    -

    This software performance specification provides an analysis of the - memory, disk, and processor utilitization of each program in the Common - UNIX Printing System ("CUPS") Version 1.2.

    -

    For the purposes of comparison, all figures are for the Linux Intel - platform. Memory utilization on other platforms should be similar.

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This software performance specification is organized into the - following sections:

    -
      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Programs
      • -
    • 4 - Scheduler Objects
      • -
    • A - Glossary
      • -
    -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Programs

    -

    The following table describes the average memory, disk, and CPU usage - of each program in CUPS.

    -

    The base memory column shows the initial memory requirements for each - program, including any shared libraries that are provided by CUPS.

    -

    The max memory column shows the maximum amount of memory that will be - used by the program based upon the default configuration settings - supplied with CUPS.

    -

    The temp files column indicates whether any temporary files are - created.

    -

    The CPU usage column specifies a relative CPU usage by the program - under normal conditions, either low, medium, or high. Low usage - indicates that the program will never use more than 33% of the - available CPU time. Medium usage indicates the program will use as much - as 66% of the available CPU time. High usage indicates the program uses - 66% or more of the available CPU time. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Backends
    ProgramBase MemoryMax MemoryTemp - FilesCPU Usage
    ipp91k256kUp to size of print file -Low
    lpd89k89kUp to size of print file -Low
    parallel85k85kUp to size of print - fileLow
    serial85k85kUp to size of print file -Low
    socket85k85kUp to size of print file -Low
    usb85k85kUp to size of print file -Low
    CGIs
    ProgramBase MemoryMax MemoryTemp - FilesCPU Usage
    admin.cgi107k256kUp to size of PPD - fileMedium
    classes.cgi95kSize of class objects -NoneMedium
    jobs.cgi93kSize of job objectsNone -Medium
    printers.cgi95kSize of printer objects -NoneMedium
    Command-Line Programs
    ProgramBase MemoryMax MemoryTemp - FilesCPU Usage
    accept88k128kNoneLow
    cancel88k128kNoneLow
    disable88k128kNoneLow
    enable88k128kNoneLow
    lp90k256kNoneLow
    lpadmin148k256kNoneLow
    lpc86kSize of job and printer objects -NoneMedium
    lpinfo89kSize of device and PPD objects -NoneMedium
    lpmove88k128kNoneLow
    lpoptions89k128kNoneLow
    lppasswd90k90kNoneLow
    lpq87kSize of job objectsNone -Medium
    lpr87k256kNoneLow
    lprm84k128kNoneLow
    lpstat119kSize of job, printer, and class - objectsNoneMedium
    reject88k128kNoneLow
    Daemons
    ProgramBase MemoryMax MemoryTemp - FilesCPU Usage
    cups-lpd92k256kOne file per control - or data file from clientLow
    cupsd308kSee Scheduler Requirements -See Scheduler RequirementsMedium
    cups-polld84kSize of printer and class objects -NoneLow
    Filters
    ProgramBase MemoryMax MemoryTemp - FilesCPU Usage
    hpgltops263k320kNoneMedium
    imagetops628k10MSwap file for - uncompressed image dataMedium
    imagetoraster652k10MSwap file for - uncompressed image dataHigh
    pstops775k840kUp to size of print - fileMedium
    pstoraster4M14MSwap file for command - listsHigh
    rastertoepson693k1MNoneLow
    rastertohp690k1MNoneLow
    texttops638k4*cols*rowsNone -Low
    -
    -

    -

    4 Scheduler Objects

    -

    The cupsd program is the CUPS scheduler process. It - manages many interdependent server objects that are used to manage and - print files to printers.

    -

    The following table provides the memory and disk cost associated with - each server object. -

    - - - - - - - - - - - - - - - -
    ObjectMemory PerDisk Per
    Browse ACL1k120
    Browse Poll2480
    Browse Relay2880
    Certificate7632
    Class9k200
    Client13k-
    Device256-
    Job2k1k + size of document files
    Location ACL1k120
    MIME Filter26880
    MIME Type34080
    PPD200656
    Printer11k32k
    -
    -

    -

    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
    -
    - - diff --git a/doc/sps.pdf b/doc/sps.pdf deleted file mode 100644 index 8a0dfa1a2f..0000000000 Binary files a/doc/sps.pdf and /dev/null differ diff --git a/doc/ssr.html b/doc/ssr.html deleted file mode 100644 index a943892be5..0000000000 --- a/doc/ssr.html +++ /dev/null @@ -1,275 +0,0 @@ - - - -CUPS Software Security Report - - - - - - - -

    -

    CUPS Software Security Report


    -CUPS-SSR-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Local Access Risks - -4 Remote Access Risks - -A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    -

    This software security report provides an analysis of possible - security concerns for the Common UNIX Printing System ("CUPS") Version - 1.2.

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This software security report is organized into the following - sections:

    -
      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Local Access Risks
      • -
    • 4 - Remote Access Risks
      • -
    • A - Glossary
      • -
    -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Local Access Risks

    -

    Local access risks are those that can be exploited only with a local - user account. This section does not address issues related to - dissemination of the root password or other security issues associated - with the UNIX operating system.

    -

    3.1 Security Breaches

    -

    There is one known security vulnerability with local access:

    -
      -
    1. Device URIs are passed to backend filters in argv[0] and in an - environment variable. Since device URIs can contain usernames and - passwords it may be possible for a local user to gain access to a - remote resource. -

      We recommend that any password-protected accounts used for remote - printing have limited access priviledges so that the possible damages - can be minimized.

      -

      The device URI is "sanitized" (the username and password are removed) - when sent to an IPP client so that a remote user cannot exploit this - vulnerability.

      -
      2. -
    -

    4 Remote Access Risks

    -

    Remote access risks are those that can be exploited without a local - user account and/or from a remote system. This section does not address - issues related to network or firewall security.

    -

    4.1 Denial of Service Attacks

    -

    Like all Internet services, the CUPS server is vulnerable to denial - of service attacks, including:

    -
      -
    1. Establishing multiple connections to the server until the server - will accept no more. -

      This cannot be protected against by the current software. It is - possible that future versions of the CUPS software could be configured - to limit the number of connections allowed from a single host, however - that still would not prevent a distributed attack.

      -
    2. Repeatedly opening and closing connections to the server as fast as - possible. -

      There is no easy way of protecting against this in the CUPS software. - If the attack is coming from outside the local network it might be - possible to filter such an attack, however once the connection request - has been received by the server it must at least accept the connection - to find out who is connecting.

      -
    3. Flooding the network with broadcast packets on port 631. -

      It might be possible to disable browsing if this condition is - detected by the CUPS software, however if there are large numbers of - printers available on the network such an algorithm might think that an - attack was occurring when instead a valid update was being received.

      -
    4. Sending partial IPP requests; specifically, sending part of an - attribute value and then stopping transmission. -

      The current code is structured to read and write the IPP request data - on-the-fly, so there is no easy way to protect against this for large - attribute values.

      -
    5. Sending large/long print jobs to printers, preventing other users - from printing. -

      There are limited facilities for protecting against large print jobs - (the MaxRequestSize attribute), however this will not - protect printers from malicious users and print files that generate - hundreds or thousands of pages. In general, we recommend restricting - printer access to known hosts or networks, and adding user-level access - control as needed for expensive printers.

      -
      6. - - - - -
    -

    4.2 Security Breaches

    -

    The current CUPS server supports Basic, Digest, and local certificate - authentication:

    -
      -
    1. Basic authentication essentially places the clear text of the - username and password on the network. Since CUPS uses the UNIX username - and password account information, the authentication information could - be used to gain access to accounts (possibly priviledged accounts) on - the server.
      2. -
    2. Digest authentication uses an MD5 checksum of the username, - password, and domain ("CUPS"), so the original username and password is - not sent over the network. However, the current implementation does not - authenticate the entire message and uses the client's IP address for - the nonce value, making it possible to launch "man in the middle" and - replay attacks from the same client. The next minor release of CUPS - will support Digest authentication of the entire message body, - effectively stopping these methods of attack.
      3. -
    3. Local certificate authentication passes 128-bit "certificates" that - identify an authenticated user. Certificates are created on-the-fly - from random data and stored in files under /etc/cups/certs -. They have restricted read permissions: root + system for the root - certificate, and lp + system for CGI certificates. Because certificates - are only available on the local system, the CUPS server does not accept - local authentication unless the client is connected to the localhost - address (127.0.0.1.)
      4. -
    -

    The default CUPS configuration disables remote administration. We do - not recommend that remote administration be enabled for all hosts. - However, if you have a trusted network or subnet, access can be - restricted accordingly. Also, we highly recommend using Digest - authentication when possible. Unfortunately, most web browsers do not - support Digest authentication at this time.

    -

    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
    -
    - - diff --git a/doc/ssr.pdf b/doc/ssr.pdf deleted file mode 100644 index 329cd173ef..0000000000 Binary files a/doc/ssr.pdf and /dev/null differ diff --git a/doc/ssr.shtml b/doc/ssr.shtml deleted file mode 100644 index 0eb283b654..0000000000 --- a/doc/ssr.shtml +++ /dev/null @@ -1,167 +0,0 @@ - - - - - - CUPS Software Security Report - - - -

    Scope

    - -

    Identification

    - -

    This software security report provides an analysis of possible security -concerns for the Common UNIX Printing System ("CUPS") Version 1.2.

    - - - -

    Document Overview

    - -

    This software security report is organized into the following sections:

    - -
      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Local Access Risks
      • -
    • 4 - Remote Access Risks
      • -
    • A - Glossary
      • -
    - - - -

    Local Access Risks

    - -

    Local access risks are those that can be exploited only with a local user -account. This section does not address issues related to dissemination of the -root password or other security issues associated with the UNIX operating -system. - -

    Security Breaches

    - -

    There is one known security vulnerability with local access: - -

      - -
    1. Device URIs are passed to backend filters in argv[0] and in - an environment variable. Since device URIs can contain - usernames and passwords it may be possible for a local user to - gain access to a remote resource. - -

      We recommend that any password-protected accounts used for - remote printing have limited access priviledges so that the - possible damages can be minimized. - -

      The device URI is "sanitized" (the username and password are - removed) when sent to an IPP client so that a remote user - cannot exploit this vulnerability. - -

    - -

    Remote Access Risks

    - -

    Remote access risks are those that can be exploited without a local user -account and/or from a remote system. This section does not address issues -related to network or firewall security. - -

    Denial of Service Attacks

    - -

    Like all Internet services, the CUPS server is vulnerable to denial of -service attacks, including: - -

      - -
    1. Establishing multiple connections to the server until the server - will accept no more. - -

      This cannot be protected against by the current software. It - is possible that future versions of the CUPS software could be - configured to limit the number of connections allowed from a - single host, however that still would not prevent a distributed - attack. - -

    2. Repeatedly opening and closing connections to the server as fast - as possible. - -

      There is no easy way of protecting against this in the CUPS - software. If the attack is coming from outside the local - network it might be possible to filter such an attack, however - once the connection request has been received by the server it - must at least accept the connection to find out who is - connecting. - -

    3. Flooding the network with broadcast packets on port 631. - -

      It might be possible to disable browsing if this condition - is detected by the CUPS software, however if there are large - numbers of printers available on the network such an algorithm - might think that an attack was occurring when instead a valid - update was being received. - -

    4. Sending partial IPP requests; specifically, sending part of an - attribute value and then stopping transmission. - -

      The current code is structured to read and write the IPP - request data on-the-fly, so there is no easy way to protect - against this for large attribute values. - -

    5. Sending large/long print jobs to printers, preventing other users - from printing. - -

      There are limited facilities for protecting against large print - jobs (the MaxRequestSize attribute), however this will - not protect printers from malicious users and print files that - generate hundreds or thousands of pages. In general, we recommend - restricting printer access to known hosts or networks, and adding - user-level access control as needed for expensive printers. - -

    - -

    Security Breaches

    - -

    The current CUPS server supports Basic, Digest, and local certificate -authentication: - -

      - -
    1. Basic authentication essentially places the clear text of - the username and password on the network. Since CUPS uses the - UNIX username and password account information, the - authentication information could be used to gain access to - accounts (possibly priviledged accounts) on the server. - -
    2. Digest authentication uses an MD5 checksum of the username, - password, and domain ("CUPS"), so the original username and - password is not sent over the network. However, the current - implementation does not authenticate the entire message and - uses the client's IP address for the nonce value, making it - possible to launch "man in the middle" and replay attacks from - the same client. The next minor release of CUPS will support - Digest authentication of the entire message body, effectively - stopping these methods of attack. - -
    3. Local certificate authentication passes 128-bit - "certificates" that identify an authenticated user. - Certificates are created on-the-fly from random data and stored - in files under /etc/cups/certs. They have - restricted read permissions: root + system for the root - certificate, and lp + system for CGI certificates. Because - certificates are only available on the local system, the CUPS - server does not accept local authentication unless the client - is connected to the localhost address (127.0.0.1.) - -
    - -

    The default CUPS configuration disables remote administration. We do -not recommend that remote administration be enabled for all hosts. -However, if you have a trusted network or subnet, access can be -restricted accordingly. - -Also, we highly recommend using Digest authentication when possible. -Unfortunately, most web browsers do not support Digest authentication -at this time. - - - - - diff --git a/doc/stp.html b/doc/stp.html deleted file mode 100644 index e354cd49a9..0000000000 --- a/doc/stp.html +++ /dev/null @@ -1,262 +0,0 @@ - - - -CUPS Software Test Plan - - - - - - - -


    -

    CUPS Software Test Plan


    -CUPS-STP-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Test Procedure -
    -
    4 IPP Compliance Tests - -5 Command Tests - -A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    -

    This software test plan provides detailed tests that are used to - evaluate the stability and compliance of the Common UNIX Printing - System ("CUPS") Version 1.2.

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This software test plan is organized into the following sections:

    -
      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Test Procedure
      • -
    • 4 - IPP Compliance Tests
      • -
    • 5 - Command Tests
      • -
    • A - Glossary
      • -
    -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Test Procedure

    -

    The test software and data files are located in the test - subdirectory of the source distribution. A script is provided to - compile the ipptest program and run all of the tests that - follow, producing a success/fail report.

    -

    The test target of the top-level makefile can be used to - run this script:

    -
      -
      -make test
-
      -
    -

    or you can run the test script directly:

    -
      -
      -cd test
-./run-stp-tests
-
      -
    -

    A Software Test Report is stored in HTML and PDF files that are - generated using the HTMLDOC - software.

    -

    4 IPP Compliance Tests

    -

    This section describes the tests used to validate the IPP standards - compliance of the CUPS server.

    -

    4.1 Request Tests

    -

    These tests verify that the CUPS scheduler only accepts valid IPP - requests that start with the attributes-charset and -attributes-natural-language attributes and also contain a -printer-uri or job-uri attribute.

    -

    It also verifies that the CUPS scheduler always responds with -attributes-charset and attributes-natural-language - attributes, using default values if they are not provided by the - client.

    -

    4.2 CUPS Printer Operation Tests

    -

    These tests verify that the CUPS printer operations are supported and - function properly. Two printers called Test1 and -Test2 are created, one as a PostScript printer and one as a - raster printer.

    -

    4.3 Job Operation Tests

    -

    These test verify that the CUPS scheduler accepts print jobs for all - supported file formats and that the cancel-job, -hold-job, and resume-job operations work.

    -

    5 Command Tests

    -

    This section describes the tests used to validate the Berkeley and - System V commands included with CUPS.

    -

    5.1 lpadmin

    -

    This test verifies that printers can be added, modified, and - defaulted using the lpadmin command.

    -

    5.2 lpc

    -

    This test verifies that the lpc command can show the - current status of all print queues.

    -

    5.3 lpq

    -

    This test verifies that the lpq command lists any jobs - in the queue.

    -

    5.4 lpstat

    -

    This test verifies that the lpstat command works with - all reports using the "-t" option.

    -

    5.5 lp

    -

    This test verifies that the lp command works with both - the default destination and a specific destination.

    -

    5.6 lpr

    -

    This test verifies that the lpr command works with both - the default destination and a specific destination.

    -

    5.7 lprm

    -

    This test verifies that the lprm command can properly - cancel a job.

    -

    5.8 cancel

    -

    This test verifies that the cancel command can properly - cancel a job or all jobs.

    -

    5.9 lpinfo

    -

    This test verifies that the lpinfo command returns a - list of available printer drivers and devices.

    -

    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
    -
    - - diff --git a/doc/stp.pdf b/doc/stp.pdf deleted file mode 100644 index 0037bd5e3b..0000000000 Binary files a/doc/stp.pdf and /dev/null differ diff --git a/doc/stp.shtml b/doc/stp.shtml deleted file mode 100644 index c94a2c160e..0000000000 --- a/doc/stp.shtml +++ /dev/null @@ -1,144 +0,0 @@ - - - - - - - CUPS Software Test Plan - - - -

    Scope

    - -

    Identification

    - -

    This software test plan provides detailed tests that are used -to evaluate the stability and compliance of the Common UNIX -Printing System ("CUPS") Version 1.2. - - - -

    Document Overview

    - -

    This software test plan is organized into the following sections: - -

      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Test Procedure
      • -
    • 4 - IPP Compliance Tests
      • -
    • 5 - Command Tests
      • -
    • A - Glossary
      • -
    - - - -

    Test Procedure

    - -

    The test software and data files are located in the test -subdirectory of the source distribution. A script is provided to compile -the ipptest program and run all of the tests that follow, -producing a success/fail report. - -

    The test target of the top-level makefile can be used to -run this script: - -

      -make test
-
    - -

    or you can run the test script directly: - -

      -cd test
-./run-stp-tests
-
    - -

    A Software Test Report is stored in HTML and PDF files that -are generated using the -HTMLDOC software. - -

    IPP Compliance Tests

    - -

    This section describes the tests used to validate the IPP -standards compliance of the CUPS server. - -

    Request Tests

    - -

    These tests verify that the CUPS scheduler only accepts valid -IPP requests that start with the attributes-charset -and attributes-natural-language attributes and also -contain a printer-uri or job-uri attribute. - -

    It also verifies that the CUPS scheduler always responds with -attributes-charset and -attributes-natural-language attributes, using -default values if they are not provided by the client. - -

    CUPS Printer Operation Tests

    - -

    These tests verify that the CUPS printer operations are supported -and function properly. Two printers called Test1 and -Test2 are created, one as a PostScript printer and one -as a raster printer. - -

    Job Operation Tests

    - -

    These test verify that the CUPS scheduler accepts print jobs for -all supported file formats and that the cancel-job, -hold-job, and resume-job operations work. - -

    Command Tests

    - -

    This section describes the tests used to validate the -Berkeley and System V commands included with CUPS. - -

    lpadmin

    - -

    This test verifies that printers can be added, modified, and -defaulted using the lpadmin command. - -

    lpc

    - -

    This test verifies that the lpc command can show -the current status of all print queues. - -

    lpq

    - -

    This test verifies that the lpq command lists -any jobs in the queue. - -

    lpstat

    - -

    This test verifies that the lpstat command works -with all reports using the "-t" option. - -

    lp

    - -

    This test verifies that the lp command works -with both the default destination and a specific destination. - -

    lpr

    - -

    This test verifies that the lpr command works -with both the default destination and a specific destination. - -

    lprm

    - -

    This test verifies that the lprm command can -properly cancel a job. - -

    cancel

    - -

    This test verifies that the cancel command can -properly cancel a job or all jobs. - -

    lpinfo

    - -

    This test verifies that the lpinfo command -returns a list of available printer drivers and devices. - - - - - diff --git a/doc/sum.html b/doc/sum.html deleted file mode 100644 index 2135cb6d20..0000000000 --- a/doc/sum.html +++ /dev/null @@ -1,1732 +0,0 @@ - - - -CUPS Software Users Manual - - - - - - - -


    -

    CUPS Software Users Manual


    -CUPS-SUM-1.2.0
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    Preface - -1 - Printing System Overview - -2 - Using the Printing System - -3 - Standard Printer Options - -4 - Saving Printer Options and Defaults - -A - Software License Agreement - -
    -

    Preface

    -

    This software users manual describes how to use the Common UNIX - Printing SystemTM ("CUPSTM") Version 1.2.0.

    -

    System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    - - -

    Document Overview

    -

    This software users manual is organized into the following sections:

    - -

    Notation Conventions

    -

    Various font and syntax conventions are used in this guide. Examples - and their meanings and uses are explained below: -

    - - - - - - - - - - - - -
    Example   Description
     
    lpstat -
    lpstat(1)    		   The names of commands; - the first mention of a command or function in a chapter is followed by - a manual page section number.
     
    /var -
    /usr/share/cups/data/testprint.ps    		    -File and directory names.
     
    Request ID is Printer-123 -   Screen output.
     
    lp -d printer filename ENTER -   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are - written using the period (.) to indicate the decimal point.
    -
    - - -

    -

    Abbreviations

    - The following abbreviations are used throughout this manual: -
      -
      -
      kb
      -
      Kilobytes, or 1024 bytes -
       
      -
      Mb
      -
      Megabytes, or 1048576 bytes -
       
      -
      Gb
      -
      Gigabytes, or 1073741824 bytes -
       
      -
      -
    -

    Other References

    -
      -
      -
      CUPS Software Administrators Manual
      -
      An administration guide for the CUPS software. -
       
      -
      CUPS Software Programmers Manual
      -
      A programmer guide for interfacing with and/or extending the CUPS - software. -
       
      -
      -
    -

    1 - Printing System Overview

    -

    This chapter provides an overview of how the Common UNIX Printing - System works.

    -

    The Printing Problem

    -

    For years the printing problem has plagued UNIX. Unlike - Microsoft® Windows® or Mac OS, UNIX has no standard interface or system - in place for supporting printers. Among the solutions currently - available, the Berkeley and System V printing systems are the most - prevalent.

    -

    These printing systems support line printers (text only) or - PostScript printers (text and graphics), and with some coaxing they can - be made to support a full range of printers and file formats. However, - because each varient of the UNIX operating system uses a different - printing system than the next developing printer drivers for a wide - range of printers and operating systems is extremely difficult. That - combined with the limited volume of customers for each UNIX varient has - forced most printer vendors to give up supporting UNIX entirely.

    -

    CUPS is designed to eliminate the printing problem. One common - printing system can be used by all UNIX varients to support the - printing needs of users. Printer vendors can use its modular filter - interface to develop a single driver program that supports a wide range - of file formats with little or no effort. Since CUPS provides both the - System V and Berkeley printing commands, users (and applications) can - reap the benefits of this new technology with no changes.

    -

    The Technology

    -

    CUPS is based upon an emerging Internet standard called the Internet - Printing Protocol. IPP has been embraced by dozens of printer and - printer server manufacturers and is supported by Microsoft Windows - 2000.

    -

    IPP defines a standard protocol for printing as well as managing - print jobs and printer options like media size, resolution, and so - forth. Like all IP-based protocols, IPP can be used locally or over the - Internet to printers hundreds or thousands of miles away. Unlike other - protocols, however, IPP also supports access control, authentication, - and encryption, making it a much more capable and secure printing - solution than older ones.

    -

    IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") - which is the basis of web servers on the Internet. This allows users to - view documentation, check status information on a printer or server, - and manage their printers, classes, and jobs using their web browser.

    -

    CUPS provides a complete IPP/1.1 based printing system that provides - Basic, Digest, and local certificate authentication and user, domain, - or IP-based access control. TLS encryption will be available in future - versions of CUPS.

    -

    Jobs

    -

    Each file or set of files that is submitted for printing is called a - job. Jobs are identified by a unique number starting at 1 and are - assigned to a particular destination, usually a printer. Jobs can also - have options associated with them such as media size, number of copies, - and priority.

    -

    Classes

    -

    CUPS supports collections of printers known as classes. Jobs - sent to a class are forwarded to the first available printer in the - class.

    -

    Filters

    -

    Filters allow a user or application to print many types of files - without extra effort. Print jobs sent to a CUPS server are filtered - before sending them to a printer. Some filters convert job files to - different formats that the printer can understand. Others perform page - selection and ordering tasks.

    -

    CUPS provides filters for printing many types of image files, HP-GL/2 - files, PDF files, and text files. CUPS also supplies PostScript and - image file Raster Image Processor ("RIP") filters that convert - PostScript or image files into bitmaps that can be sent to a raster - printer.

    -

    Backends

    -

    Backends perform the most important task of all - they send the - filtered print data to the printer.

    -

    CUPS provides backends for printing over parallel, serial, and USB - ports, and over the network via the IPP, JetDirect (AppSocket), and - Line Printer Daemon ("LPD") protocols. Additional backends are - available in network service packages such as the SMB backend included - with the popular SAMBA software.

    -

    Backends are also used to determine the available devices. On startup - each backend is asked for a list of devices it supports, and any - information that is available. This allows the parallel backend to tell - CUPS that an EPSON Stylus Color 600 printer is attached to parallel - port 1, for example.

    -

    Printer Drivers

    -

    Printer drivers in CUPS consist of one of more filters specific to a - printer. CUPS includes sample printer drivers for Hewlett-Packard - LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, - and Stylus Photo printers. While these drivers do not generate optimal - output for the different printer models, they do provide basic printing - and demonstrate how you can write your own printer drivers and - incorporate them into CUPS.

    -

    Networking

    -

    Printers and classes on the local system are automatically shared - with other systems on the network. This allows you to setup one system - to print to a printer and use this system as a printer server or spool - host for all of the others. Users may then select a local printer by - name or a remote printer using "name@server".

    -

    CUPS also provides implicit classes, which are collections of - printers and/or classes with the same name. This allows you to setup - multiple servers pointing to the same physical network printer, for - example, so that you aren't relying on a single system for printing. - Because this also works with printer classes, you can setup multiple - servers and printers and never worry about a single point of failure - unless all of the printers and servers go down!

    -

    2 - Using the Printing System -

    -

    This chapter shows you how to submit, query, and cancel print jobs to - different printers.

    -

    Submitting Files for Printing

    -

    CUPS provides both the System V (lp(1)) and Berkeley ( -lpr(1)) printing commands. Type the following command to print a - file to the default (or only) printer on the system:

    -
      -
      -lp filename ENTER
-
      -
    -

    or:

    -
      -
      -lpr filename ENTER
-
      -
    -

    CUPS understands many different types of files directly, including - PostScript and image files. This allows you to print from inside your - applications or at the command-line, whichever is most convenient!

    -

    Choosing a Printer

    -

    Many systems will have more than one printer available to the user. - These printers can be attached to the local system via a parallel, - serial, or USB port, or available over the network.

    -

    Use the lpstat(1) command to see a list of available - printers:

    -
      -
      -lpstat -p -d ENTER
-
      -
    -

    The -p option specifies that you want to see a list of - printers, and the -d option reports the current default - printer or class.

    -

    Use the -d option with the lp command to - print to a specific printer:

    -
      -
      -lp -d printer filename ENTER
-
      -
    -

    or the -P option with the lpr command:

    -
      -
      -lpr -P printer filename ENTER
-
      -
    -

    Setting Printer Options

    -

    For many types of files, the default printer options may be - sufficient for your needs. However, there may be times when you need to - change the options for a particular file you are printing.

    -

    The lp and lpr commands allow you to pass - printer options using the -o option:

    -
      -
      -lp -o landscape -o scaling=75 -o media=A4 filename.jpg
-lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
-
      -
    -

    The available printer options vary depending on the printer. The - standard options are described in Chapter - 3, "Standard Printing Options".

    -

    Printing Multiple Copies

    -

    Both the lp and lpr commands have options - for printing more than one copy of a file:

    -
      -
      -lp -n num-copies filename ENTER
-lpr -#num-copies filename ENTER
-
      -
    -

    Copies are normally not collated for you. Use the -o - Collate=True option to get collated copies :

    -
      -
      -lp -n num-copies -o Collate=True filename ENTER
-lpr -#num-copies -o Collate=True filename ENTER
-
      -
    - - -

    Checking the Printer Status from the Command-Line

    -

    The lpstat command can be used to check for jobs that - you have submitted for printing:

    -
      -
      -lpstat ENTER
-Printer-1 johndoe 4427776
-Printer-2 johndoe 15786
-Printer-3 johndoe 372842
-
      -
    -

    The jobs are listed in the order they will be printed. Use the --p option to see which files and printers are active:

    -
      -
      -lpstat -p ENTER
-printer DeskJet now printing DeskJet-1.
-
      -
    - - -

    Use the -o and -p options together to show - the jobs and the printers:

    -
      -
      -lpstat -o -p ENTER
-Printer-1 johndoe 4427776
-Printer-2 johndoe 15786
-Printer-3 johndoe 372842
-printer DeskJet now printing DeskJet-1.
-
      -
    -

    Checking the Printer Status from the Web

    -

    Since CUPS uses the Internet Printing Protocol, it is also a - fully-functional web server. To use your web browser to monitor the - printers on your system, open the URL:

    - -

    From there you can view the status of classes, jobs, and printers - with the click of a button!

    -

    Canceling a Print Job

    -

    The cancel(1) and lprm(1) commands cancel a - print job:

    -
      -
      -cancel job-id ENTER
-lprm job-id ENTER
-
      -
    -

    The job-id is the number that was reported to you by the - lp or lpstat commands.

    -

    3 - Standard Printer - Options

    -

    This chapter describes the standard printer options that are - available when printing with the lp and lpr - commands.

    -

    General Options

    -

    The following options apply when printing all types of files. - -

    -

    Selecting the Media Size, Type, and Source

    -

    The -o media=xyz option sets the media size, type, - and/or source:

    -
      -
      -lp -o media=Letter filename ENTER
-lp -o media=Letter,MultiPurpose filename ENTER
-lpr -o media=Letter,Transparency filename ENTER
-lpr -o media=Letter,MultiPurpose,Transparency filename ENTER
-
      -
    - - -

    The available media sizes, types, and sources depend on the printer, - but most support the following options (case is not significant):

    -
      -
    • Letter - US Letter (8.5x11 inches, or 216x279mm)
      • -
    • Legal - US Legal (8.5x14 inches, or 216x356mm)
      • -
    • A4 - ISO A4 (8.27x11.69 inches, or 210x297mm)
      • -
    • COM10 - US #10 Envelope (9.5x4.125 inches, or - 241x105mm)
      • -
    • DL - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
      • -
    • Transparency - Transparency media type or source
      • -
    • Upper - Upper paper tray
      • -
    • Lower - Lower paper tray
      • -
    • MultiPurpose - Multi-purpose paper tray
      • -
    • LargeCapacity - Large capacity paper tray
      • -
    -

    The actual options supported are defined in the printer's PPD file in - the PageSize, InputSlot, and MediaType - options.

    -

    Setting the Orientation

    -

    The -o landscape option will rotate the page 90 degrees - to print in landscape orientation:

    -
      -
      -lp -o landscape filename ENTER
-lpr -o landscape filename ENTER
-
      -
    -

    Printing On Both Sides of the Paper

    -

    The -o sides=two-sided-short-edge and -o - sides=two-sided-long-edge options will enable duplexing on the - printer, if the printer supports it. The -o - sides=two-sided-short-edge option is suitable for landscape - pages, while the -o sides=two-sided-long-edge option is - suitable for portrait pages:

    -
      -
      -lp -o sides=two-sided-short-edge filename ENTER
-lp -o sides=two-sided-long-edge filename ENTER
-lpr -o sides=two-sided-long-edge filename ENTER
-
      -
    -

    The default is to print single-sided:

    -
      -
      -lp -o sides=one-sided filename ENTER
-lpr -o sides=one-sided filename ENTER
-
      -
    -

    Banner Options

    -

    The following options apply when printing all types of files.

    -

    Selecting the Banner Page(s)

    -

    The -o jobsheets=start,end option sets the banner - page(s) to use for a job:

    -
      -
      -lp -o job-sheets=none filename ENTER
-lp -o job-sheets=standard filename ENTER
-lpr -o job-sheets=classified,classified filename ENTER
-
      -
    -

    If only one banner file is specified, it will be printed before the - files in the job. If a second banner file is specified, it is printed - after the files in the job.

    -

    The available banner pages depend on the local system configuration; - CUPS includes the following banner files:

    -
      -
    • none - Do not produce a banner page.
      • -
    • classified - A banner page with a "classified" label at - the top and bottom.
      • -
    • confidential - A banner page with a "confidential" - label at the top and bottom.
      • -
    • secret - A banner page with a "secret" label at the top - and bottom.
      • -
    • standard - A banner page with no label at the top and - bottom.
      • -
    • topsecret - A banner page with a "top secret" label at - the top and bottom.
      • -
    • unclassified - A banner page with an "unclassified" - label at the top and bottom.
      • -
    -

    Document Options

    -

    The following options apply when printing all types of files.

    -

    Selecting a Range of Pages

    -

    The -o page-ranges=pages option selects a range of pages - for printing:

    -
      -
      -lp -o page-ranges=1 filename ENTER
-lp -o page-ranges=1-4 filename ENTER
-lp -o page-ranges=1-4,7,9-12 filename ENTER
-lpr -o page-ranges=1-4,7,9-12 filename ENTER
-
      -
    -

    As shown above, the pages value can be a single page, a - range of pages, or a collection of page numbers and ranges separated by - commas. The pages will always be printed in ascending order, regardless - of the order of the pages in the page-ranges option.

    -

    The default is to print all pages.

    -

    Selecting Even or Odd Pages

    -

    Use the -o page-set=set option to select the even or odd - pages:

    -
      -
      -lp -o page-set=odd filename ENTER
-lp -o page-set=even filename ENTER
-lpr -o page-set=even filename ENTER
-
      -
    -

    The default is to print all pages.

    -

    N-Up Printing

    -

    The -o number-up=value option selects N-Up printing. - N-Up printing places multiple document pages on a single printed page. - CUPS supports 1, 2, 4, 6, 9, and 16-Up formats; the default format is - 1-Up:

    -
      -
      -lp -o number-up=1 filename ENTER
-lp -o number-up=2 filename ENTER
-lp -o number-up=4 filename ENTER
-lpr -o number-up=16 filename ENTER
-
      -
    -

    The -o page-border=value option chooses the border to - draw around each page:

    -
      -
    • -o page-border=double; draw two hairline borders around - each page
      • -
    • -o page-border=double-thick; draw two 1pt borders - around each page
      • -
    • -o page-border=none; do not draw a border (default)
      • -
    • -o page-border=single; draw one hairline border around - each page
      • -
    • -o page-border=single-thick; draw one 1pt border around - each page
      • -
    -

    The -o number-up-layout=value option chooses the layout - of the pages on each output page:

    -
      -
    • -o number-up-layout=btlr; Bottom to top, left to right
      • -
    • -o number-up-layout=btrl; Bottom to top, right to left
      • -
    • -o number-up-layout=lrbt; Left to right, bottom to top
      • -
    • -o number-up-layout=lrtb; Left to right, top to bottom - (default)
      • -
    • -o number-up-layout=rlbt; Right to left, bottom to top
      • -
    • -o number-up-layout=rltb; Right to left, top to bottom
      • -
    • -o number-up-layout=tblr; Top to bottom, left to right
      • -
    • -o number-up-layout=tbrl; Top to bottom, right to left
      • -
    -

    Setting the Brightness

    -

    You can control the overall brightness of the printed output using - the -o brightness=percent option:

    -
      -
      -lp -o brightness=120 filename ENTER
-lpr -o brightness=120 filename ENTER
-
      -
    -

    Values greater than 100 will lighten the print, while values less - than 100 will darken it.

    -

    Setting the Gamma Correction

    -

    You can control the overall gamma correction of the printed output - using the -o gamma=value option:

    -
      -
      -lp -o gamma=1700 filename ENTER
-lpr -o gamma=1700 filename ENTER
-
      -
    -

    Values greater than 1000 will lighten the print, while values less - than 1000 will darken it. The default gamma is 1000.

    -

    Text Options

    -

    The following options apply when printing text files.

    -

    Setting the Number of Characters Per Inch

    -

    The -o cpi=value option sets the number of characters - per inch:

    -
      -
      -lp -o cpi=10 filename ENTER
-lp -o cpi=12 filename ENTER
-lpr -o cpi=17 filename ENTER
-
      -
    -

    The default characters per inch is 10.

    -

    Setting the Number of Lines Per Inch

    -

    The -o lpi=value option sets the number of lines per - inch:

    -
      -
      -lp -o lpi=6 filename ENTER
-lpr -o lpi=8 filename ENTER
-
      -
    -

    The default lines per inch is 6.

    -

    Setting the Number of Columns

    -

    The -o columns=value option sets the number of text - columns:

    -
      -
      -lp -o columns=2 filename ENTER
-lpr -o columns=3 filename ENTER
-
      -
    -

    The default number of columns is 1.

    -

    Setting the Page Margins

    -

    Normally the page margins are set to the hard limits of the printer. - Use the -o page-left=value, -o page-right=value -, -o page-top=value, and -o page-bottom=value - options to adjust the page margins:

    -
      -
      -lp -o page-left=value filename ENTER
-lp -o page-right=value filename ENTER
-lp -o page-top=value filename ENTER
-lp -o page-bottom=value filename ENTER
-lpr -o page-bottom=value filename ENTER
-
      -
    -

    The value argument is the margin in points; each point - is 1/72 inch or 0.35mm.

    -

    Pretty Printing

    -

    The -o prettyprint option puts a header at the top of - each page with the page number, job title (usually the filename), and - the date. Also, C and C++ keywords are highlighted, and comment lines - are italicized:

    -
      -
      -lp -o prettyprint filename ENTER
-lpr -o prettyprint filename ENTER
-
      -
    -

    Image Options

    -

    The following options apply when printing image files.

    -

    Positioning the Image

    -

    The -o position=name option specifies the position of - the image on the page:

    -
      -
    • center - Center the image on the page (default)
      • -
    • top - Print the image centered at the top of the page
      • -
    • left - Print the image centered on the left of page
      • -
    • right - Print the image centered on the right of the - page
      • -
    • top-left - Print the image at the top left corner of - the page
      • -
    • top-right - Print the image at the top right corner of - the page
      • -
    • bottom - Print the image centered at the bottom of the - page
      • -
    • bottom-left - Print the image at the bottom left corner - of the page
      • -
    • bottom-right - Print the image at the bottom right - corner of the page
      • -
    -

    Scaling the Image

    -

    The -o scaling=percent, -o ppi=value, and --o natural-scaling=percent options change the size of a printed - image:

    -
      -
      -lp -o scaling=percent filename ENTER
-lp -o ppi=value filename ENTER
-lpr -o natural-scaling=percent filename ENTER
-
      -
    -

    The scaling=percent value is a number from 1 to 800 - specifying the size in relation to the page (not the image.) A - scaling of 100 percent will fill the page as completely as the image - aspect ratio allows. A scaling of 200 percent will print on up to 4 - pages.

    -

    The ppi=value value is a number from 1 to 1200 - specifying the resolution of the image in pixels per inch. An image - that is 3000x2400 pixels will print 10x8 inches at 300 pixels per inch, - for example. If the specified resolution makes the image larger than - the page, multiple pages will be printed to satisfy the request.

    -

    The natural-scaling=percent value is a number from 1 to - 800 specifying the size in relation to the natural image size. A - scaling of 100 percent will print the image at its natural size, while - a scaling of 50 percent will print the image at half its natural size. - If the specified scaling makes the image larger than the page, multiple - pages will be printed to satisfy the request.

    -

    Adjusting the Hue (Tint) of an Image

    -

    The -o hue=value option will adjust the hue of the - printed image, much like the tint control on your television:

    -
      -
      -lp -o hue=value filename ENTER
-lpr -o hue=value filename ENTER
-
      -
    - - -

    The value argument is a number from -360 to 360 and - represents the color hue rotation. The following table summarizes the - change you'll see with different colors: -

    - - - - - - - - -
    Originalhue=-45hue=45
    RedPurpleYellow-orange
    GreenYellow-greenBlue-green
    YellowOrangeGreen-yellow
    BlueSky-bluePurple
    MagentaIndigoCrimson
    CyanBlue-greenLight-navy-blue
    -
    -

    -

    The default hue adjustment is 0.

    -

    Adjusting the Saturation (Color) of an Image

    -

    The -o saturation=percent option adjusts the saturation - of the colors in an image, much like the color knob on your television:

    -
      -
      -lp -o saturation=percent filename ENTER
-lpr -o saturation=percent filename ENTER
-
      -
    -

    The percent argument specifies the color saturation from - 0 to 200. A color saturation of 0 produces a black-and-white print, - while a value of 200 will make the colors extremely intense.

    -

    The default saturation is 100. - -

    -

    HP-GL/2 Options

    -

    The following options apply to HP-GL/2 files.

    -

    Printing in Black

    -

    The -o blackplot option specifies that all pens should - plot in black:

    -
      -
      -lp -o blackplot filename ENTER
-lpr -o blackplot filename ENTER
-
      -
    -

    The default is to use the colors defined in the plot file or the - standard pen colors defined in the HP-GL/2 reference manual from - Hewlett Packard.

    -

    Fitting the Plot on the Page

    -

    The -o fitplot option specifies that the plot should be - scaled to fit on the page:

    -
      -
      -lp -o fitplot filename ENTER
-lpr -o fitplot filename ENTER
-
      -
    -

    The default is to use the absolute distances specified in the plot - file. -

    - - -
    NOTE: -

    This feature depends upon an accurate plot size (PS) - command in the HP-GL/2 file. If no plot size is given in the file than - the HP-GL/2 filter assumes the plot is ANSI E size.

    -
    -
    -

    -

    Setting the Default Pen Width

    -

    The -o penwidth=value option specifies the default pen - width for HP-GL/2 files:

    -
      -
      -lp -o penwidth=value filename ENTER
-lpr -o penwidth=value filename ENTER
-
      -
    -

    The pen width value specifies the pen width in - micrometers. The default value of 1000 produces lines that are 1 - millimeter in width. Specifying a pen width of 0 produces lines that - are exactly 1 pixel wide. -

    - - -
    NOTE: -

    This option is ignored when the pen widths are set in the plot file.

    -
    -
    -

    -

    Raw or Unfiltered Output

    -

    The -o raw option allows you to send files directly to a - printer without filtering. This is sometimes required when printing - from applications that provide their own "printer drivers" for your - printer:

    -
      -
      -lp -o raw filename ENTER
-lpr -o raw filename ENTER
-
      -
    -

    The -l option can also be used with the lpr - command to send files directly to a printer:

    -
      -
      -lpr -l filename ENTER
-
      -
    -

    4 - Saving Printer Options - and Defaults

    -

    This chapter describes how to save printer options for your printer - and set your own default printer.

    -

    Printer Options

    -

    Each printer supports a large number of options, which you learned - about in Chapter 3, "Standard Printer - Options". Rather than specifying these options each time you print - a file, CUPS allows you to save them as "default" options for the - printer.

    -

    The lpoptions(1) command saves the options for your - printers. Like the lp and lpr commands, it - accepts printer options using the -o argument:

    -
      -
      -lpoptions -o prettyprint ENTER
-lpoptions -o media=A4 -o sides=two-sided-long-edge ENTER
-lpoptions -o media=Legal -o scaling=100 ENTER
-
      -
    -

    Once saved, any lp or lpr command will use - them when you print.

    -

    Setting Options for a Specific Printer

    -

    The previous example shows how to set the options for the default - printer. The -p printer option specifies the options are - for another printer:

    -
      -
      -lpoptions -p laserjet -o prettyprint ENTER
-lpoptions -p laserjet -o media=A4 -o sides=two-sided-long-edge ENTER
-lpoptions -p deskjet -o media=Legal -o scaling=100 ENTER
-
      -
    -

    Removing Options

    -

    The previous two examples shows how to set options for the default - and a specific printer. Below, shows you how to remove the saved option - using the -r argument:

    -
      -
      -lpoptions -r prettyprint ENTER
-lpoptions -p laserjet -r prettyprint ENTER
-
      -
    -

    Viewing the Current Defaults

    -

    The lpoptions command can also be used to show the - current options by not specifying any new options on the command-line:

    -
      -
      -lpoptions ENTER
-media=A4 sides=two-sided-long-edge
-lpoptions -p deskjet ENTER
-media=Legal scaling=100
-
      -
    -

    Viewing Options for a Specific Printer

    -

    You can display the supported options using the lpoptions - command with the -l option, as follows:

    -
      -
      -lpoptions -p laserjet -l ENTER
-
      -
    -

    Setting the Default Printer

    -

    The administrator normally will set a system-wide default printer - that is normally used as the default printer by everyone. Use the --d printer option to set your own default printer:

    -
      -
      -lpoptions -d deskjet ENTER
-
      -
    -

    The printer can be local (deskjet) or remote ( -deskjet@server).

    -

    Printer Instances

    -

    Besides setting options for each print queue, CUPS supports - printer instances which allow you to define several different sets - of options for each printer. You specify a printer instance using the - slash (/) character:

    -
      -
      -lpoptions -p laserjet/duplex -o sides=two-sided-long-edge ENTER
-lpoptions -p laserjet/legal -o media=Legal ENTER
-
      -
    -

    The lp and lpr commands also understand - this notation:

    -
      -
      -lp -d laserjet/duplex filename ENTER
-lpr -P laserjet/legal filename ENTER
-
      -
    -

    Removing Instances

    -

    Use the -x printer/instance option to remove a printer - instance that you no longer need:

    -
      -
      -lpoptions -x laserjet ENTER
-lpoptions -x laserjet/duplex ENTER
-lpoptions -x laserjet/legal ENTER
-
      -
    -

    The -x option only removes the default options for that - printer and instance; the original print queue will remain until - deleted with the lpadmin(8) command by the administrator.

    -

    A - Software License Agreement

    -

    Common UNIX Printing System License - Agreement

    -

    Copyright 1997-2003 by Easy Software Products -
    44141 AIRPORT VIEW DR STE 204 -
    HOLLYWOOD, MARYLAND 20636-3111 USA -
    -
    Voice: +1.301.373.9600 -
    Email: cups-info@cups.org -
    WWW: http://www.cups.org

    -

    Introduction

    -

    The Common UNIX Printing SystemTM, ("CUPSTM"), - is provided under the GNU General Public License ("GPL") and GNU - Library General Public License ("LGPL"), Version 2, with exceptions for - Apple operating systems and the OpenSSL toolkit. A copy of the - exceptions and licenses follow this introduction.

    -

    The GNU LGPL applies to the CUPS API library, located in the "cups" - subdirectory of the CUPS source distribution and in the "cups" include - directory and library files in the binary distributions. The GNU GPL - applies to the remainder of the CUPS distribution, including the - "pdftops" filter which is based upon Xpdf and the CUPS imaging library.

    -

    For those not familiar with the GNU GPL, the license basically allows - you to:

    -
      -
    • Use the CUPS software at no charge.
      • -
    • Distribute verbatim copies of the software in source or binary form.
      • -
    • Sell verbatim copies of the software for a media fee, or sell - support for the software.
      • -
    • Distribute or sell printer drivers and filters that use CUPS so long - as source code is made available under the GPL.
      • -
    -

    What this license does not allow you to do is make changes or - add features to CUPS and then sell a binary distribution without source - code. You must provide source for any new drivers, changes, or - additions to the software, and all code must be provided under the GPL - or LGPL as appropriate. The only exceptions to this are the portions of - the CUPS software covered by the Apple operating system license - exceptions outlined later in this license agreement.

    -

    The GNU LGPL relaxes the "link-to" restriction, allowing you to - develop applications that use the CUPS API library under other licenses - and/or conditions as appropriate for your application.

    -

    License Exceptions

    -

    In addition, as the copyright holder of CUPS, Easy Software Products - grants the following special exceptions:

    -
      -
    1. Apple Operating System Development License Exception; -
        -
      1. Software that is developed by any person or entity for an Apple - Operating System ("Apple OS-Developed Software"), including but not - limited to Apple and third party printer drivers, filters, and backends - for an Apple Operating System, that is linked to the CUPS imaging - library or based on any sample filters or backends provided with CUPS - shall not be considered to be a derivative work or collective work - based on the CUPS program and is exempt from the mandatory source code - release clauses of the GNU GPL. You may therefore distribute linked - combinations of the CUPS imaging library with Apple OS-Developed - Software without releasing the source code of the Apple OS-Developed - Software. You may also use sample filters and backends provided with - CUPS to develop Apple OS-Developed Software without releasing the - source code of the Apple OS-Developed Software.
        2. -
      2. An Apple Operating System means any operating system software - developed and/or marketed by Apple Computer, Inc., including but not - limited to all existing releases and versions of Apple's Darwin, Mac OS - X, and Mac OS X Server products and all follow-on releases and future - versions thereof.
        3. -
      3. This exception is only available for Apple OS-Developed Software and - does not apply to software that is distributed for use on other - operating systems.
        4. -
      4. All CUPS software that falls under this license exception have the - following text at the top of each source file:
        This file is - subject to the Apple OS-Developed Software exception.
        5. -
      -
      2. -
    2. OpenSSL Toolkit License Exception; -
        -
      1. Easy Software Products explicitly allows the compilation and - distribution of the CUPS software with the OpenSSL Toolkit.
        2. -
      -
      3. -
    -

    No developer is required to provide these exceptions in a derived - work.

    -

    Trademarks

    -

    Easy Software Products has trademarked the Common UNIX Printing - System, CUPS, and CUPS logo. These names and logos may be used freely - in any direct port or binary distribution of CUPS. Please contract Easy - Software Products for written permission to use them in derivative - products. Our intention is to protect the value of these trademarks and - ensure that any derivative product meets the same high-quality - standards as the original.

    -

    Binary Distribution Rights

    -

    Easy Software Products also sells rights to the CUPS source code - under a binary distribution license for vendors that are unable to - release source code for their drivers, additions, and modifications to - CUPS under the GNU GPL and LGPL. For information please contact us at - the address shown above.

    -

    The Common UNIX Printing System provides a "pdftops" filter that is - based on the Xpdf software. For binary distribution licensing of this - software, please contact:

    Derek B. Noonburg -
    Email: derekn@foolabs.com -
    WWW: - http://www.foolabs.com/xpdf/

    -

    Support

    -

    Easy Software Products sells software support for CUPS as well as a - commercial printing product based on CUPS called ESP Print Pro. You can - find out more at our web site:

    - - - -

    GNU GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright 1989, 1991 Free Software Foundation, Inc.
-59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-Everyone is permitted to copy and distribute verbatim
-copies of this license document, but changing it is not allowed.
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public License is - intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users. This - General Public License applies to most of the Free Software - Foundation's software and to any other program whose authors commit to - using it. (Some other Free Software Foundation software is covered by - the GNU Library General Public License instead.) You can apply it to - your programs, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the software, or if you modify it.

    -

    For example, if you distribute copies of such a program, whether - gratis or for a fee, you must give the recipients all the rights that - you have. You must make sure that they, too, receive or can get the - source code. And you must show them these terms so they know their - rights.

    -

    We protect your rights with two steps: (1) copyright the software, - and (2) offer you this license which gives you legal permission to - copy, distribute and/or modify the software.

    -

    Also, for each author's protection and ours, we want to make certain - that everyone understands that there is no warranty for this free - software. If the software is modified by someone else and passed on, we - want its recipients to know that what they have is not the original, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that redistributors of a free - program will individually obtain patent licenses, in effect making the - program proprietary. To prevent this, we have made it clear that any - patent must be licensed for everyone's free use or not licensed at all.

    -

    The precise terms and conditions for copying, distribution and - modification follow.

    -

    GNU GENERAL PUBLIC LICENSE -
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -
      -
    1. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", below, - refers to any such program or work, and a "work based on the Program" - means either the Program or any derivative work under copyright law: - that is to say, a work containing the Program or a portion of it, - either verbatim or with modifications and/or translated into another - language. (Hereinafter, translation is included without limitation in - the term "modification".) Each licensee is addressed as "you". -

      Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - the Program is not restricted, and the output from the Program is - covered only if its contents constitute a work based on the Program - (independent of having been made by running the Program). Whether that - is true depends on what the Program does.

      -
    2. You may copy and distribute verbatim copies of the Program's source - code as you receive it, in any medium, provided that you conspicuously - and appropriately publish on each copy an appropriate copyright notice - and disclaimer of warranty; keep intact all the notices that refer to - this License and to the absence of any warranty; and give any other - recipients of the Program a copy of this License along with the - Program. -

      You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

      -
    3. You may modify your copy or copies of the Program or any portion of - it, thus forming a work based on the Program, and copy and distribute - such modifications or work under the terms of Section 1 above, provided - that you also meet all of these conditions: -
        -
      1. You must cause the modified files to carry prominent notices stating - that you changed the files and the date of any change.
        2. -
      2. You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any part - thereof, to be licensed as a whole at no charge to all third parties - under the terms of this License.
        3. -
      3. if the modified program normally reads commands interactively when - run, you must cause it, when started running for such interactive use - in the most ordinary way, to print or display an announcement including - an appropriate copyright notice and a notice that there is no warranty - (or else, saying that you provide a warranty) and that users may - redistribute the program under these conditions, and telling the user - how to view a copy of this License. (Exception: if the Program itself - is interactive but does not normally print such an announcement, your - work based on the Program is not required to print an announcement.)
        4. -
      -

      These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Program, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Program, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

      -

      Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Program.

      -

      In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

      -
    4. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms of - Sections 1 and 2 above provided that you also do one of the following: -
        -
      1. Accompany it with the complete corresponding machine-readable source - code, which must be distributed under the terms of Sections 1 and 2 - above on a medium customarily used for software interchange; or,
        2. -
      2. Accompany it with a written offer, valid for at least three years, - to give any third party, for a charge no more than your cost of - physically performing source distribution, a complete machine-readable - copy of the corresponding source code, to be distributed under the - terms of Sections 1 and 2 above on a medium customarily used for - software interchange; or,
        3. -
      3. Accompany it with the information you received as to the offer to - distribute corresponding source code. (This alternative is allowed only - for noncommercial distribution and only if you received the program in - object code or executable form with such an offer, in accord with - Subsection b above.)
        4. -
      -

      The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete source - code means all the source code for all modules it contains, plus any - associated interface definition files, plus the scripts used to control - compilation and installation of the executable. However, as a special - exception, the source code distributed need not include anything that - is normally distributed (in either source or binary form) with the - major components (compiler, kernel, and so on) of the operating system - on which the executable runs, unless that component itself accompanies - the executable.

      -

      If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent access - to copy the source code from the same place counts as distribution of - the source code, even though third parties are not compelled to copy - the source along with the object code.

      -
    5. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt otherwise - to copy, modify, sublicense or distribute the Program is void, and will - automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such parties - remain in full compliance.
      6. -
    6. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify or - distribute the Program or its derivative works. These actions are - prohibited by law if you do not accept this License. Therefore, by - modifying or distributing the Program (or any work based on the - Program), you indicate your acceptance of this License to do so, and - all its terms and conditions for copying, distributing or modifying the - Program or works based on it.
      7. -
    7. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program subject to - these terms and conditions. You may not impose any further restrictions - on the recipients' exercise of the rights granted herein. You are not - responsible for enforcing compliance by third parties to this License.
      8. -
    8. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent issues), - conditions are imposed on you (whether by court order, agreement or - otherwise) that contradict the conditions of this License, they do not - excuse you from the conditions of this License. If you cannot - distribute so as to satisfy simultaneously your obligations under this - License and any other pertinent obligations, then as a consequence you - may not distribute the Program at all. For example, if a patent license - would not permit royalty-free redistribution of the Program by all - those who receive copies directly or indirectly through you, then the - only way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. -

      If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply and the section as a whole is intended to apply in other - circumstances.

      -

      It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system, which is - implemented by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

      -

      This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

      -
    9. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, the - original copyright holder who places the Program under this License may - add an explicit geographical distribution limitation excluding those - countries, so that distribution is permitted only in or among countries - not thus excluded. In such case, this License incorporates the - limitation as if written in the body of this License.
      10. -
    10. The Free Software Foundation may publish revised and/or new versions - of the General Public License from time to time. Such new versions will - be similar in spirit to the present version, but may differ in detail - to address new problems or concerns. -

      Each version is given a distinguishing version number. If the Program - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Program does not specify a version - number of this License, you may choose any version ever published by - the Free Software Foundation.

      -
    11. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted by the - Free Software Foundation, write to the Free Software Foundation; we - sometimes make exceptions for this. Our decision will be guided by the - two goals of preserving the free status of all derivatives of our free - software and of promoting the sharing and reuse of software generally.
      12. - - - - - - -
    -

    NO WARRANTY

    -
      -
    1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY - FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN - OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES - PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER - EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE - ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH - YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL - NECESSARY SERVICING, REPAIR OR CORRECTION.
      2. -
    2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY - AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.
      3. -
    -

    END OF TERMS AND CONDITIONS

    - - -

    GNU LIBRARY GENERAL PUBLIC LICENSE

    -

    Version 2, June 1991

    -
    -Copyright (C) 1991 Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-
-[This is the first released version of the library GPL.  It is
- numbered 2 because it goes with version 2 of the ordinary GPL.]
-
    -

    Preamble

    -

    The licenses for most software are designed to take away your freedom - to share and change it. By contrast, the GNU General Public Licenses - are intended to guarantee your freedom to share and change free - software--to make sure the software is free for all its users.

    -

    This license, the Library General Public License, applies to some - specially designated Free Software Foundation software, and to any - other libraries whose authors decide to use it. You can use it for your - libraries, too.

    -

    When we speak of free software, we are referring to freedom, not - price. Our General Public Licenses are designed to make sure that you - have the freedom to distribute copies of free software (and charge for - this service if you wish), that you receive source code or can get it - if you want it, that you can change the software or use pieces of it in - new free programs; and that you know you can do these things.

    -

    To protect your rights, we need to make restrictions that forbid - anyone to deny you these rights or to ask you to surrender the rights. - These restrictions translate to certain responsibilities for you if you - distribute copies of the library, or if you modify it.

    -

    For example, if you distribute copies of the library, whether gratis - or for a fee, you must give the recipients all the rights that we gave - you. You must make sure that they, too, receive or can get the source - code. If you link a program with the library, you must provide complete - object files to the recipients so that they can relink them with the - library, after making changes to the library and recompiling it. And - you must show them these terms so they know their rights.

    -

    Our method of protecting your rights has two steps: (1) copyright the - library, and (2) offer you this license which gives you legal - permission to copy, distribute and/or modify the library.

    -

    Also, for each distributor's protection, we want to make certain that - everyone understands that there is no warranty for this free library. - If the library is modified by someone else and passed on, we want its - recipients to know that what they have is not the original version, so - that any problems introduced by others will not reflect on the original - authors' reputations.

    -

    Finally, any free program is threatened constantly by software - patents. We wish to avoid the danger that companies distributing free - software will individually obtain patent licenses, thus in effect - transforming the program into proprietary software. To prevent this, we - have made it clear that any patent must be licensed for everyone's free - use or not licensed at all.

    -

    Most GNU software, including some libraries, is covered by the - ordinary GNU General Public License, which was designed for utility - programs. This license, the GNU Library General Public License, applies - to certain designated libraries. This license is quite different from - the ordinary one; be sure to read it in full, and don't assume that - anything in it is the same as in the ordinary license.

    -

    The reason we have a separate public license for some libraries is - that they blur the distinction we usually make between modifying or - adding to a program and simply using it. Linking a program with a - library, without changing the library, is in some sense simply using - the library, and is analogous to running a utility program or - application program. However, in a textual and legal sense, the linked - executable is a combined work, a derivative of the original library, - and the ordinary General Public License treats it as such.

    -

    Because of this blurred distinction, using the ordinary General - Public License for libraries did not effectively promote software - sharing, because most developers did not use the libraries. We - concluded that weaker conditions might promote sharing better.

    -

    However, unrestricted linking of non-free programs would deprive the - users of those programs of all benefit from the free status of the - libraries themselves. This Library General Public License is intended - to permit developers of non-free programs to use free libraries, while - preserving your freedom as a user of such programs to change the free - libraries that are incorporated in them. (We have not seen how to - achieve this as regards changes in header files, but we have achieved - it as regards changes in the actual functions of the Library.) The hope - is that this will lead to faster development of free libraries.

    -

    The precise terms and conditions for copying, distribution and - modification follow. Pay close attention to the difference between a - "work based on the library" and a "work that uses the library". The - former contains code derived from the library, while the latter only - works together with the library.

    -

    Note that it is possible for a library to be covered by the ordinary - General Public License rather than by this special one.

    -

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

    -

    0. This License Agreement applies to any software - library which contains a notice placed by the copyright holder or other - authorized party saying it may be distributed under the terms of this - Library General Public License (also called "this License"). Each - licensee is addressed as "you".

    -

    A "library" means a collection of software functions and/or data - prepared so as to be conveniently linked with application programs - (which use some of those functions and data) to form executables.

    -

    The "Library", below, refers to any such software library or work - which has been distributed under these terms. A "work based on the - Library" means either the Library or any derivative work under - copyright law: that is to say, a work containing the Library or a - portion of it, either verbatim or with modifications and/or translated - straightforwardly into another language. (Hereinafter, translation is - included without limitation in the term "modification".)

    -

    "Source code" for a work means the preferred form of the work for - making modifications to it. For a library, complete source code means - all the source code for all modules it contains, plus any associated - interface definition files, plus the scripts used to control - compilation and installation of the library.

    -

    Activities other than copying, distribution and modification are not - covered by this License; they are outside its scope. The act of running - a program using the Library is not restricted, and output from such a - program is covered only if its contents constitute a work based on the - Library (independent of the use of the Library in a tool for writing - it). Whether that is true depends on what the Library does and what the - program that uses the Library does.

    -

    1. You may copy and distribute verbatim copies of - the Library's complete source code as you receive it, in any medium, - provided that you conspicuously and appropriately publish on each copy - an appropriate copyright notice and disclaimer of warranty; keep intact - all the notices that refer to this License and to the absence of any - warranty; and distribute a copy of this License along with the Library.

    -

    You may charge a fee for the physical act of transferring a copy, and - you may at your option offer warranty protection in exchange for a fee.

    -

    2. You may modify your copy or copies of the Library - or any portion of it, thus forming a work based on the Library, and - copy and distribute such modifications or work under the terms of - Section 1 above, provided that you also meet all of these conditions:

    -
      -
    1. The modified work must itself be a software library. -

      -
    2. You must cause the files modified to carry prominent notices stating - that you changed the files and the date of any change. -

      -
    3. You must cause the whole of the work to be licensed at no charge to - all third parties under the terms of this License. -

      -
    4. If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses the - facility, other than as an argument passed when the facility is - invoked, then you must make a good faith effort to ensure that, in the - event an application does not supply such function or table, the - facility still operates, and performs whatever part of its purpose - remains meaningful. -

      (For example, a function in a library to compute square roots has a - purpose that is entirely well-defined independent of the application. - Therefore, Subsection 2d requires that any application-supplied - function or table used by this function must be optional: if the - application does not supply it, the square root function must still - compute square roots.)

      -
      5. - - - -
    -

    These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the Library, - and can be reasonably considered independent and separate works in - themselves, then this License, and its terms, do not apply to those - sections when you distribute them as separate works. But when you - distribute the same sections as part of a whole which is a work based - on the Library, the distribution of the whole must be on the terms of - this License, whose permissions for other licensees extend to the - entire whole, and thus to each and every part regardless of who wrote - it.

    -

    Thus, it is not the intent of this section to claim rights or contest - your rights to work written entirely by you; rather, the intent is to - exercise the right to control the distribution of derivative or - collective works based on the Library.

    -

    In addition, mere aggregation of another work not based on the - Library with the Library (or with a work based on the Library) on a - volume of a storage or distribution medium does not bring the other - work under the scope of this License.

    -

    3. You may opt to apply the terms of the ordinary - GNU General Public License instead of this License to a given copy of - the Library. To do this, you must alter all the notices that refer to - this License, so that they refer to the ordinary GNU General Public - License, version 2, instead of to this License. (If a newer version - than version 2 of the ordinary GNU General Public License has appeared, - then you can specify that version instead if you wish.) Do not make any - other change in these notices.

    -

    Once this change is made in a given copy, it is irreversible for that - copy, so the ordinary GNU General Public License applies to all - subsequent copies and derivative works made from that copy.

    -

    This option is useful when you wish to copy part of the code of the - Library into a program that is not a library.

    -

    4. You may copy and distribute the Library (or a - portion or derivative of it, under Section 2) in object code or - executable form under the terms of Sections 1 and 2 above provided that - you accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections 1 - and 2 above on a medium customarily used for software interchange.

    -

    If distribution of object code is made by offering access to copy - from a designated place, then offering equivalent access to copy the - source code from the same place satisfies the requirement to distribute - the source code, even though third parties are not compelled to copy - the source along with the object code.

    -

    5. A program that contains no derivative of any - portion of the Library, but is designed to work with the Library by - being compiled or linked with it, is called a "work that uses the - Library". Such a work, in isolation, is not a derivative work of the - Library, and therefore falls outside the scope of this License.

    -

    However, linking a "work that uses the Library" with the Library - creates an executable that is a derivative of the Library (because it - contains portions of the Library), rather than a "work that uses the - library". The executable is therefore covered by this License. Section - 6 states terms for distribution of such executables.

    -

    When a "work that uses the Library" uses material from a header file - that is part of the Library, the object code for the work may be a - derivative work of the Library even though the source code is not. - Whether this is true is especially significant if the work can be - linked without the Library, or if the work is itself a library. The - threshold for this to be true is not precisely defined by law.

    -

    If such an object file uses only numerical parameters, data structure - layouts and accessors, and small macros and small inline functions (ten - lines or less in length), then the use of the object file is - unrestricted, regardless of whether it is legally a derivative work. - (Executables containing this object code plus portions of the Library - will still fall under Section 6.)

    -

    Otherwise, if the work is a derivative of the Library, you may - distribute the object code for the work under the terms of Section 6. - Any executables containing that work also fall under Section 6, whether - or not they are linked directly with the Library itself.

    -

    6. As an exception to the Sections above, you may - also compile or link a "work that uses the Library" with the Library to - produce a work containing portions of the Library, and distribute that - work under terms of your choice, provided that the terms permit - modification of the work for the customer's own use and reverse - engineering for debugging such modifications.

    -

    You must give prominent notice with each copy of the work that the - Library is used in it and that the Library and its use are covered by - this License. You must supply a copy of this License. If the work - during execution displays copyright notices, you must include the - copyright notice for the Library among them, as well as a reference - directing the user to the copy of this License. Also, you must do one - of these things:

    -
      -
    1. Accompany the work with the complete corresponding machine-readable - source code for the Library including whatever changes were used in the - work (which must be distributed under Sections 1 and 2 above); and, if - the work is an executable linked with the Library, with the complete - machine-readable "work that uses the Library", as object code and/or - source code, so that the user can modify the Library and then relink to - produce a modified executable containing the modified Library. (It is - understood that the user who changes the contents of definitions files - in the Library will not necessarily be able to recompile the - application to use the modified definitions.) -

      -
    2. Accompany the work with a written offer, valid for at least three - years, to give the same user the materials specified in Subsection 6a, - above, for a charge no more than the cost of performing this - distribution. -

      -
    3. If distribution of the work is made by offering access to copy from - a designated place, offer equivalent access to copy the above specified - materials from the same place. -

      -
    4. Verify that the user has already received a copy of these materials - or that you have already sent this user a copy.
      5. - - - -
    -

    For an executable, the required form of the "work that uses the - Library" must include any data and utility programs needed for - reproducing the executable from it. However, as a special exception, - the source code distributed need not include anything that is normally - distributed (in either source or binary form) with the major components - (compiler, kernel, and so on) of the operating system on which the - executable runs, unless that component itself accompanies the - executable.

    -

    It may happen that this requirement contradicts the license - restrictions of other proprietary libraries that do not normally - accompany the operating system. Such a contradiction means you cannot - use both them and the Library together in an executable that you - distribute.

    -

    7. You may place library facilities that are a work - based on the Library side-by-side in a single library together with - other library facilities not covered by this License, and distribute - such a combined library, provided that the separate distribution of the - work based on the Library and of the other library facilities is - otherwise permitted, and provided that you do these two things:

    -
      -
    1. Accompany the combined library with a copy of the same work based on - the Library, uncombined with any other library facilities. This must be - distributed under the terms of the Sections above. -

      -
    2. Give prominent notice with the combined library of the fact that - part of it is a work based on the Library, and explaining where to find - the accompanying uncombined form of the same work.
      3. - -
    -

    8. You may not copy, modify, sublicense, link with, - or distribute the Library except as expressly provided under this - License. Any attempt otherwise to copy, modify, sublicense, link with, - or distribute the Library is void, and will automatically terminate - your rights under this License. However, parties who have received - copies, or rights, from you under this License will not have their - licenses terminated so long as such parties remain in full compliance.

    -

    9. You are not required to accept this License, - since you have not signed it. However, nothing else grants you - permission to modify or distribute the Library or its derivative works. - These actions are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Library (or any work based - on the Library), you indicate your acceptance of this License to do so, - and all its terms and conditions for copying, distributing or modifying - the Library or works based on it.

    -

    10. Each time you redistribute the Library (or any - work based on the Library), the recipient automatically receives a - license from the original licensor to copy, distribute, link with or - modify the Library subject to these terms and conditions. You may not - impose any further restrictions on the recipients' exercise of the - rights granted herein. You are not responsible for enforcing compliance - by third parties to this License.

    -

    11. If, as a consequence of a court judgment or - allegation of patent infringement or for any other reason (not limited - to patent issues), conditions are imposed on you (whether by court - order, agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this License. If - you cannot distribute so as to satisfy simultaneously your obligations - under this License and any other pertinent obligations, then as a - consequence you may not distribute the Library at all. For example, if - a patent license would not permit royalty-free redistribution of the - Library by all those who receive copies directly or indirectly through - you, then the only way you could satisfy both it and this License would - be to refrain entirely from distribution of the Library.

    -

    If any portion of this section is held invalid or unenforceable under - any particular circumstance, the balance of the section is intended to - apply, and the section as a whole is intended to apply in other - circumstances.

    -

    It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of any - such claims; this section has the sole purpose of protecting the - integrity of the free software distribution system which is implemented - by public license practices. Many people have made generous - contributions to the wide range of software distributed through that - system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute - software through any other system and a licensee cannot impose that - choice.

    -

    This section is intended to make thoroughly clear what is believed to - be a consequence of the rest of this License.

    -

    12. If the distribution and/or use of the Library is - restricted in certain countries either by patents or by copyrighted - interfaces, the original copyright holder who places the Library under - this License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only in or - among countries not thus excluded. In such case, this License - incorporates the limitation as if written in the body of this License.

    -

    13. The Free Software Foundation may publish revised - and/or new versions of the Library General Public License from time to - time. Such new versions will be similar in spirit to the present - version, but may differ in detail to address new problems or concerns.

    -

    Each version is given a distinguishing version number. If the Library - specifies a version number of this License which applies to it and "any - later version", you have the option of following the terms and - conditions either of that version or of any later version published by - the Free Software Foundation. If the Library does not specify a license - version number, you may choose any version ever published by the Free - Software Foundation.

    -

    14. If you wish to incorporate parts of the Library - into other free programs whose distribution conditions are incompatible - with these, write to the author to ask for permission. For software - which is copyrighted by the Free Software Foundation, write to the Free - Software Foundation; we sometimes make exceptions for this. Our - decision will be guided by the two goals of preserving the free status - of all derivatives of our free software and of promoting the sharing - and reuse of software generally.

    -

    NO WARRANTY

    -

    15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, - THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY - APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE - OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU - ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

    -

    16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR - AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO - MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL - OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE - LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING - RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A - FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF - SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.

    -

    END OF TERMS AND CONDITIONS

    - - diff --git a/doc/sum.pdf b/doc/sum.pdf deleted file mode 100644 index 629621b644..0000000000 Binary files a/doc/sum.pdf and /dev/null differ diff --git a/doc/sum.shtml b/doc/sum.shtml deleted file mode 100644 index 7e18260c29..0000000000 --- a/doc/sum.shtml +++ /dev/null @@ -1,933 +0,0 @@ - - - - - - - CUPS Software Users Manual - - - -

    Preface

    - -

    This software users manual describes how to use the Common UNIX Printing -SystemTM ("CUPSTM") Version 1.2.0. - - - - -

    Document Overview

    - -

    This software users manual is organized into the following sections:

    - - - -

    Notation Conventions

    - -

    Various font and syntax conventions are used in this guide. Examples and -their meanings and uses are explained below: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Example   Description
     
    lpstat
    - lpstat(1)    		   The names of commands; the first mention of a command or - function in a chapter is followed by a manual page section - number.
     
    /var
    - /usr/share/cups/data/testprint.ps    		   File and directory names.
     
    Request ID is Printer-123   Screen output.
     
    lp -d printer filename ENTER   Literal user input; special keys like ENTER are - in ALL CAPS.
     
    12.3   Numbers in the text are written using the period (.) to indicate - the decimal point.
    - - -

    Abbreviations

    - -The following abbreviations are used throughout this manual: - -
      -
      - -
      kb -
      Kilobytes, or 1024 bytes
        - -
      Mb -
      Megabytes, or 1048576 bytes
        - -
      Gb -
      Gigabytes, or 1073741824 bytes
        - -
      -
    - -

    Other References

    - -
      -
      - -
      CUPS Software Administrators Manual - -
      An administration guide for the CUPS software.
        - -
      CUPS Software Programmers Manual - -
      A programmer guide for interfacing with and/or extending the CUPS - software.
        - -
      -
    - - - - - -

    2 - Using the Printing System

    - -

    This chapter shows you how to submit, query, and cancel print jobs to -different printers. - -

    Submitting Files for Printing

    - -

    CUPS provides both the System V (lp(1)) and Berkeley -(lpr(1)) printing commands. Type the following command to -print a file to the default (or only) printer on the system: - -

      -lp filename ENTER
-
    - -

    or: - -

      -lpr filename ENTER
-
    - -

    CUPS understands many different types of files directly, including -PostScript and image files. This allows you to print from inside your -applications or at the command-line, whichever is most convenient! - -

    Choosing a Printer

    - -

    Many systems will have more than one printer available to the user. These -printers can be attached to the local system via a parallel, serial, or USB -port, or available over the network. - -

    Use the lpstat(1) command to see a list of available printers: - -

      -lpstat -p -d ENTER
-
    - -

    The -p option specifies that you want to see a -list of printers, and the -d option reports the -current default printer or class. - -

    Use the -d option with the lp command to -print to a specific printer: - -

      -lp -d printer filename ENTER
-
    - -

    or the -P option with the lpr command: - -

      -lpr -P printer filename ENTER
-
    - -

    Setting Printer Options

    - -

    For many types of files, the default printer options may be sufficient for -your needs. However, there may be times when you need to change the options -for a particular file you are printing. - -

    The lp and lpr commands allow you to pass -printer options using the -o option: - -

      -lp -o landscape -o scaling=75 -o media=A4 filename.jpg
-lpr -o landscape -o scaling=75 -o media=A4 filename.jpg
-
    - -

    The available printer options vary depending on the printer. The standard -options are described in Chapter 3, "Standard -Printing Options". - -

    Printing Multiple Copies

    - -

    Both the lp and lpr commands have options for -printing more than one copy of a file: - -

      -lp -n num-copies filename ENTER
-lpr -#num-copies filename ENTER
-
    - -

    Copies are normally not collated for you. Use the -o -Collate=True option to get collated copies : - -

      -lp -n num-copies -o Collate=True filename ENTER
-lpr -#num-copies -o Collate=True filename ENTER
-
    - - -

    Checking the Printer Status from the Command-Line

    - -

    The lpstat command can be used to check for jobs that you -have submitted for printing: - -

      -lpstat ENTER
-Printer-1 johndoe 4427776
-Printer-2 johndoe 15786
-Printer-3 johndoe 372842
-
    - -

    The jobs are listed in the order they will be printed. Use the --p option to see which files and printers are active: - -

      -lpstat -p ENTER
-printer DeskJet now printing DeskJet-1.
-
    - - -

    Use the -o and -p options together to show -the jobs and the printers: - -

      -lpstat -o -p ENTER
-Printer-1 johndoe 4427776
-Printer-2 johndoe 15786
-Printer-3 johndoe 372842
-printer DeskJet now printing DeskJet-1.
-
    - -

    Checking the Printer Status from the Web

    - -

    Since CUPS uses the Internet Printing Protocol, it is also a -fully-functional web server. To use your web browser to monitor the -printers on your system, open the URL: - -

    - -

    From there you can view the status of classes, jobs, and printers -with the click of a button! - -

    Canceling a Print Job

    - -

    The cancel(1) and lprm(1) commands cancel -a print job: - -

      -cancel job-id ENTER
-lprm job-id ENTER
-
    - -

    The job-id is the number that was reported to you by -the lp or lpstat commands. - - -

    3 - Standard Printer Options

    - -

    This chapter describes the standard printer options that are available -when printing with the lp and lpr commands. - -

    General Options

    - -

    The following options apply when printing all types of files. - - -

    Selecting the Media Size, Type, and Source

    - -

    The -o media=xyz option sets the media size, type, -and/or source: - -

      -lp -o media=Letter filename ENTER
-lp -o media=Letter,MultiPurpose filename ENTER
-lpr -o media=Letter,Transparency filename ENTER
-lpr -o media=Letter,MultiPurpose,Transparency filename ENTER
-
    - - -

    The available media sizes, types, and sources depend on the printer, but -most support the following options (case is not significant): - -

      - -
    • Letter - US Letter (8.5x11 inches, or 216x279mm) - -
    • Legal - US Legal (8.5x14 inches, or 216x356mm) - -
    • A4 - ISO A4 (8.27x11.69 inches, or 210x297mm) - -
    • COM10 - US #10 Envelope (9.5x4.125 inches, or - 241x105mm) - -
    • DL - ISO DL Envelope (8.66x4.33 inches, or 220x110mm) - -
    • Transparency - Transparency media type or source - -
    • Upper - Upper paper tray - -
    • Lower - Lower paper tray - -
    • MultiPurpose - Multi-purpose paper tray - -
    • LargeCapacity - Large capacity paper tray - -
    - -

    The actual options supported are defined in the printer's PPD file -in the PageSize, InputSlot, and -MediaType options. - -

    Setting the Orientation

    - -

    The -o landscape option will rotate the page 90 degrees -to print in landscape orientation: - -

      -lp -o landscape filename ENTER
-lpr -o landscape filename ENTER
-
    - -

    Printing On Both Sides of the Paper

    - -

    The -o sides=two-sided-short-edge and -o -sides=two-sided-long-edge options will enable duplexing on the -printer, if the printer supports it. The -o -sides=two-sided-short-edge option is suitable for landscape -pages, while the -o sides=two-sided-long-edge option is -suitable for portrait pages: - -

      -lp -o sides=two-sided-short-edge filename ENTER
-lp -o sides=two-sided-long-edge filename ENTER
-lpr -o sides=two-sided-long-edge filename ENTER
-
    - -

    The default is to print single-sided: - -

      -lp -o sides=one-sided filename ENTER
-lpr -o sides=one-sided filename ENTER
-
    - -

    Banner Options

    - -

    The following options apply when printing all types of files. - -

    Selecting the Banner Page(s)

    - -

    The -o jobsheets=start,end option sets the banner page(s) to -use for a job: - -

      -lp -o job-sheets=none filename ENTER
-lp -o job-sheets=standard filename ENTER
-lpr -o job-sheets=classified,classified filename ENTER
-
    - -

    If only one banner file is specified, it will be printed before the -files in the job. If a second banner file is specified, it is printed after -the files in the job. - -

    The available banner pages depend on the local system configuration; CUPS -includes the following banner files: - -

      - -
    • none - Do not produce a banner page. - -
    • classified - A banner page with a "classified" - label at the top and bottom. - -
    • confidential - A banner page with a - "confidential" label at the top and bottom. - -
    • secret - A banner page with a "secret" label - at the top and bottom. - -
    • standard - A banner page with no label at the - top and bottom. - -
    • topsecret - A banner page with a "top secret" - label at the top and bottom. - -
    • unclassified - A banner page with an - "unclassified" label at the top and bottom. - -
    - -

    Document Options

    - -

    The following options apply when printing all types of files. - -

    Selecting a Range of Pages

    - -

    The -o page-ranges=pages option selects a range of -pages for printing: - -

      -lp -o page-ranges=1 filename ENTER
-lp -o page-ranges=1-4 filename ENTER
-lp -o page-ranges=1-4,7,9-12 filename ENTER
-lpr -o page-ranges=1-4,7,9-12 filename ENTER
-
    - -

    As shown above, the pages value can be a single page, a -range of pages, or a collection of page numbers and ranges separated by -commas. The pages will always be printed in ascending order, regardless -of the order of the pages in the page-ranges option. - -

    The default is to print all pages. - -

    Selecting Even or Odd Pages

    - -

    Use the -o page-set=set option to select the even or odd pages: - -

      -lp -o page-set=odd filename ENTER
-lp -o page-set=even filename ENTER
-lpr -o page-set=even filename ENTER
-
    - -

    The default is to print all pages. - -

    N-Up Printing

    - -

    The -o number-up=value option selects N-Up printing. -N-Up printing places multiple document pages on a single printed page. -CUPS supports 1, 2, 4, 6, 9, and 16-Up formats; the default format is -1-Up: - -

      -lp -o number-up=1 filename ENTER
-lp -o number-up=2 filename ENTER
-lp -o number-up=4 filename ENTER
-lpr -o number-up=16 filename ENTER
-
    - -

    The -o page-border=value option chooses the border -to draw around each page: - -

      -
    • -o page-border=double; draw two hairline borders around each page
      • -
    • -o page-border=double-thick; draw two 1pt borders around each page
      • -
    • -o page-border=none; do not draw a border (default)
      • -
    • -o page-border=single; draw one hairline border around each page
      • -
    • -o page-border=single-thick; draw one 1pt border around each page
      • -
    - -

    The -o number-up-layout=value option chooses the layout -of the pages on each output page: - -

      -
    • -o number-up-layout=btlr; Bottom to top, left to right
      • -
    • -o number-up-layout=btrl; Bottom to top, right to left
      • -
    • -o number-up-layout=lrbt; Left to right, bottom to top
      • -
    • -o number-up-layout=lrtb; Left to right, top to bottom (default)
      • -
    • -o number-up-layout=rlbt; Right to left, bottom to top
      • -
    • -o number-up-layout=rltb; Right to left, top to bottom
      • -
    • -o number-up-layout=tblr; Top to bottom, left to right
      • -
    • -o number-up-layout=tbrl; Top to bottom, right to left
      • -
    - -

    Setting the Brightness

    - -

    You can control the overall brightness of the printed output using the --o brightness=percent option: - -

      -lp -o brightness=120 filename ENTER
-lpr -o brightness=120 filename ENTER
-
    - -

    Values greater than 100 will lighten the print, while values less than -100 will darken it. - -

    Setting the Gamma Correction

    - -

    You can control the overall gamma correction of the printed output -using the -o gamma=value option: - -

      -lp -o gamma=1700 filename ENTER
-lpr -o gamma=1700 filename ENTER
-
    - -

    Values greater than 1000 will lighten the print, while values less -than 1000 will darken it. The default gamma is 1000. - -

    Text Options

    - -

    The following options apply when printing text files. - -

    Setting the Number of Characters Per Inch

    - -

    The -o cpi=value option sets the number of characters per inch: - -

      -lp -o cpi=10 filename ENTER
-lp -o cpi=12 filename ENTER
-lpr -o cpi=17 filename ENTER
-
    - -

    The default characters per inch is 10. - -

    Setting the Number of Lines Per Inch

    - -

    The -o lpi=value option sets the number of lines per inch: - -

      -lp -o lpi=6 filename ENTER
-lpr -o lpi=8 filename ENTER
-
    - -

    The default lines per inch is 6. - -

    Setting the Number of Columns

    - -

    The -o columns=value option sets the number of text columns: - -

      -lp -o columns=2 filename ENTER
-lpr -o columns=3 filename ENTER
-
    - -

    The default number of columns is 1. - -

    Setting the Page Margins

    - -

    Normally the page margins are set to the hard limits of the printer. -Use the -o page-left=value, -o -page-right=value, -o page-top=value, and -o -page-bottom=value options to adjust the page margins: - -

      -lp -o page-left=value filename ENTER
-lp -o page-right=value filename ENTER
-lp -o page-top=value filename ENTER
-lp -o page-bottom=value filename ENTER
-lpr -o page-bottom=value filename ENTER
-
    - -

    The value argument is the margin in points; each point is 1/72 inch -or 0.35mm. - -

    Pretty Printing

    - -

    The -o prettyprint option puts a header at the top of each page with the -page number, job title (usually the filename), and the date. Also, C and C++ -keywords are highlighted, and comment lines are italicized: - -

      -lp -o prettyprint filename ENTER
-lpr -o prettyprint filename ENTER
-
    - -

    Image Options

    - -

    The following options apply when printing image files. - -

    Positioning the Image

    - -

    The -o position=name option specifies the position of the -image on the page: - -

      - -
    • center - Center the image on the page (default) - -
    • top - Print the image centered at the top of the page - -
    • left - Print the image centered on the left of page - -
    • right - Print the image centered on the right of the page - -
    • top-left - Print the image at the top left corner of - the page - -
    • top-right - Print the image at the top right corner of - the page - -
    • bottom - Print the image centered at the bottom of - the page - -
    • bottom-left - Print the image at the bottom left - corner of the page - -
    • bottom-right - Print the image at the bottom right - corner of the page - -
    - -

    Scaling the Image

    - -

    The -o scaling=percent, -o -ppi=value, and -o natural-scaling=percent -options change the size of a printed image: - -

      -lp -o scaling=percent filename ENTER
-lp -o ppi=value filename ENTER
-lpr -o natural-scaling=percent filename ENTER
-
    - -

    The scaling=percent value is a number from 1 to 800 -specifying the size in relation to the page (not the image.) A -scaling of 100 percent will fill the page as completely as the image -aspect ratio allows. A scaling of 200 percent will print on up to 4 -pages. - -

    The ppi=value value is a number from 1 to 1200 specifying the -resolution of the image in pixels per inch. An image that is 3000x2400 -pixels will print 10x8 inches at 300 pixels per inch, for example. If -the specified resolution makes the image larger than the page, multiple -pages will be printed to satisfy the request. - -

    The natural-scaling=percent value is a number -from 1 to 800 specifying the size in relation to the natural -image size. A scaling of 100 percent will print the image at its -natural size, while a scaling of 50 percent will print the image -at half its natural size. If the specified scaling makes the -image larger than the page, multiple pages will be printed to -satisfy the request. - -

    Adjusting the Hue (Tint) of an Image

    - -

    The -o hue=value option will adjust the hue of the -printed image, much like the tint control on your television: - -

      -lp -o hue=value filename ENTER
-lpr -o hue=value filename ENTER
-
    - - -

    The value argument is a number from -360 to 360 and represents the -color hue rotation. The following table summarizes the change you'll see with -different colors: - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Originalhue=-45hue=45
    RedPurpleYellow-orange
    GreenYellow-greenBlue-green
    YellowOrangeGreen-yellow
    BlueSky-bluePurple
    MagentaIndigoCrimson
    CyanBlue-greenLight-navy-blue
    - -

    The default hue adjustment is 0. - -

    Adjusting the Saturation (Color) of an Image

    - -

    The -o saturation=percent option adjusts the saturation -of the colors in an image, much like the color knob on your television: - -

      -lp -o saturation=percent filename ENTER
-lpr -o saturation=percent filename ENTER
-
    - -

    The percent argument specifies the color saturation -from 0 to 200. A color saturation of 0 produces a black-and-white -print, while a value of 200 will make the colors extremely intense. - -

    The default saturation is 100. - - -

    HP-GL/2 Options

    - -

    The following options apply to HP-GL/2 files. - -

    Printing in Black

    - -

    The -o blackplot option specifies that all pens should -plot in black: - -

      -lp -o blackplot filename ENTER
-lpr -o blackplot filename ENTER
-
    - -

    The default is to use the colors defined in the plot file or the -standard pen colors defined in the HP-GL/2 reference manual from -Hewlett Packard. - -

    Fitting the Plot on the Page

    - -

    The -o fitplot option specifies that the plot should be -scaled to fit on the page: - -

      -lp -o fitplot filename ENTER
-lpr -o fitplot filename ENTER
-
    - -

    The default is to use the absolute distances specified in the plot -file. - -

    - - - -
    - NOTE: - -

    This feature depends upon an accurate plot size (PS) - command in the HP-GL/2 file. If no plot size is given in the file - than the HP-GL/2 filter assumes the plot is ANSI E size. -

    - -

    Setting the Default Pen Width

    - -

    The -o penwidth=value option specifies the default pen -width for HP-GL/2 files: - -

      -lp -o penwidth=value filename ENTER
-lpr -o penwidth=value filename ENTER
-
    - -

    The pen width value specifies the pen width in micrometers. -The default value of 1000 produces lines that are 1 millimeter in width. -Specifying a pen width of 0 produces lines that are exactly 1 pixel wide. - -

    - - - -
    - NOTE: - -

    This option is ignored when the pen widths are set in the - plot file. -

    - -

    Raw or Unfiltered Output

    - -

    The -o raw option allows you to send files directly to -a printer without filtering. This is sometimes required when printing -from applications that provide their own "printer drivers" for your -printer: - -

      -lp -o raw filename ENTER
-lpr -o raw filename ENTER
-
    - -

    The -l option can also be used with the -lpr command to send files directly to a printer: - -

      -lpr -l filename ENTER
-
    - - -

    4 - Saving Printer Options and Defaults

    - -

    This chapter describes how to save printer options for your printer and -set your own default printer. - -

    Printer Options

    - -

    Each printer supports a large number of options, which you learned about -in Chapter 3, "Standard Printer Options". -Rather than specifying these options each time you print a file, CUPS allows -you to save them as "default" options for the printer. - -

    The lpoptions(1) command saves the options for your printers. -Like the lp and lpr commands, it accepts printer -options using the -o argument: - -

      -lpoptions -o prettyprint ENTER
-lpoptions -o media=A4 -o sides=two-sided-long-edge ENTER
-lpoptions -o media=Legal -o scaling=100 ENTER
-
    - -

    Once saved, any lp or lpr command will -use them when you print. - -

    Setting Options for a Specific Printer

    - -

    The previous example shows how to set the options for the default -printer. The -p printer option specifies the options are -for another printer: - -

      -lpoptions -p laserjet -o prettyprint ENTER
-lpoptions -p laserjet -o media=A4 -o sides=two-sided-long-edge ENTER
-lpoptions -p deskjet -o media=Legal -o scaling=100 ENTER
-
    - -

    Removing Options

    - -

    The previous two examples shows how to set options for the default -and a specific printer. Below, shows you how to remove the saved -option using the -r argument: - -

      -lpoptions -r prettyprint ENTER
-lpoptions -p laserjet -r prettyprint ENTER
-
    - -

    Viewing the Current Defaults

    - -

    The lpoptions command can also be used to show the current -options by not specifying any new options on the command-line: - -

      -lpoptions ENTER
-media=A4 sides=two-sided-long-edge
-lpoptions -p deskjet ENTER
-media=Legal scaling=100
-
    - -

    Viewing Options for a Specific Printer

    - -

    You can display the supported options using the lpoptions -command with the -l option, as follows: - -

      -lpoptions -p laserjet -l ENTER
-
    - -

    Setting the Default Printer

    - -

    The administrator normally will set a system-wide default printer -that is normally used as the default printer by everyone. Use the --d printer option to set your own default printer: - -

      -lpoptions -d deskjet ENTER
-
    - -

    The printer can be local (deskjet) or remote -(deskjet@server). - -

    Printer Instances

    - -

    Besides setting options for each print queue, CUPS supports -printer instances which allow you to define several different -sets of options for each printer. You specify a printer instance using -the slash (/) character: - -

      -lpoptions -p laserjet/duplex -o sides=two-sided-long-edge ENTER
-lpoptions -p laserjet/legal -o media=Legal ENTER
-
    - -

    The lp and lpr commands also understand -this notation: - -

      -lp -d laserjet/duplex filename ENTER
-lpr -P laserjet/legal filename ENTER
-
    - -

    Removing Instances

    - -

    Use the -x printer/instance option to remove a printer -instance that you no longer need: - -

      -lpoptions -x laserjet ENTER
-lpoptions -x laserjet/duplex ENTER
-lpoptions -x laserjet/legal ENTER
-
    - -

    The -x option only removes the default options for that -printer and instance; the original print queue will remain until deleted -with the lpadmin(8) command by the administrator. - - -

    A - Software License -Agreement

    - - - - - diff --git a/doc/svd.html b/doc/svd.html deleted file mode 100644 index d2e8a592b5..0000000000 --- a/doc/svd.html +++ /dev/null @@ -1,296 +0,0 @@ - - - -CUPS Software Version Description - - - - - - - -

    -

    CUPS Software Version Description


    -CUPS-SVD-1.2
    -Easy Software Products
    -Copyright 1997-2003, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Additions - -4 Changes - -A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    - This software version description document provides release information - for 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 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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This software version description document is organized into the - following sections:

    - -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Additions

    -

    CUPS 1.2 includes many new features from the 1.0.x releases.

    -

    3.1 Filters

    -

    3.1.1 imagetoraster, imagetops -

    -

    The image file filters have been upgraded to support conversion of - Microsoft Bitmap ("BMP") and Alias PIX files.

    -

    3.1.2 pdftops

    -

    A new pdftops filter has been developed that is based on the - excellent Xpdf 0.90 software from Derek B. Noonburg. The new filter is - faster, smaller, and considerably more reliable than the - Ghostscript-based filter in CUPS 1.0.

    -

    3.1.3 pstoraster

    -

    The pstoraster filter has been integrated with GNU - GhostScript 5.50. The new RIP supports most Level 3 PostScript language - features.

    -

    3.1.4 rastertoepson

    -

    The new rastertoepson filter supports EPSON printers - using the ESC/P or ESC/P2 command sets. PPDs are supplied for 9-pin, - 24-pin, Stylus Color, and Stylus Photo printers.

    -

    3.2 User-Defined Printers and Options

    -

    The new lpoptions command allows users to configure - default document options and create additional "instances" of existing - printers, each with unique options.

    -

    The lp, lpr, and lpstat - commands have been upgraded to use this option and printer instance - information automatically.

    -

    3.3 Daemons

    -

    CUPS 1.2 includes two new daemons that provide enhanced network - printing support.

    -

    3.3.1 cups-lpd

    -

    The cups-lpd daemon provides support for clients using - the Line Printer Daemon protocol.

    -

    3.3.2 cups-polld

    -

    The cups-polld daemon provides remote polling services - for the scheduler.

    -

    3.4 Commands

    -

    CUPS 1.2 includes several new printing commands.

    -

    3.4.1 lpoptions

    -

    The lpoptions command provides user-defined printers and - options.

    -

    3.4.2 lpmove

    -

    The lpmove command moves a print job to a new - destination.

    -

    3.4.3 lpinfo

    -

    The lpinfo command lists the available PPD files or - devices.

    -

    3.5 IPP Implementation

    -

    CUPS 1.2 adds support for the set-job-attributes - extension operation as well as two new CUPS-specific extension - operations to determine which devices and printer drivers are available - on the system.

    -

    Further information on the CUPS implementation of IPP can be found in - CUPS-IPP-1.2.

    -

    4 Changes

    -

    CUPS 1.2 includes many changes from the 1.1.x releases.

    -

    4.1 Directory Structure

    -

    The directory structure in CUPS 1.2 has been modified to conform to - the Filesystem Hierarchy Standard, 2.2. The following table describes - the new file locations. -

    - - - - - - - - - - - - - - - - -
    Table 1: Directory structure changes - from CUPS 1.1.x to 1.2.x.
    DescriptionCUPS 1.1.xCUPS 1.2.x
    Backends/var/cups/backend/usr/lib/cups/backend
    CGI programs/var/cups/cgi-bin -/usr/lib/cups/cgi-bin
    Configuration files/var/cups/conf/etc/cups
    Documentation/usr/share/cups/doc -/usr/share/doc/cups
    Filter programs/var/cups/filter -/usr/lib/cups/filter
    Interface scripts/var/cups/interfaces -/etc/cups/interfaces
    Locale data/usr/lib/locale/usr/share/locale
    Log files/var/cups/logs/var/log/cups
    PPD files/var/cups/ppd/etc/cups/ppd
    Request files/var/cups/requests/var/spool/cups
    -
    -

    -

    4.2 IPP Implementation

    -

    CUPS 1.2 is based on version 1.1 of the Internet Printing Protocol.

    -

    The new scheduler supports the create-job and -send-document operations. In addition, the job-sheets -, job-sheets-default, and job-sheets-supported - attributes are now supported for banner pages.

    -

    The CUPS-get-printers and CUPS-get-classes - operations have been upgraded to support limited filtering based upon - the printer-type, printer-location, -printer-info, and printer-make-and-model attributes.

    -

    The CUPS-add-printer operation now supports the -ppd-name attribute to specify a locally-available PPD file rather - than sending the PPD file from the client with the request.

    -

    Further information on the CUPS implementation of IPP can be found in - CUPS-IPP-1.2.

    -

    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
    -
    - - diff --git a/doc/svd.pdf b/doc/svd.pdf deleted file mode 100644 index 22be31bc6c..0000000000 Binary files a/doc/svd.pdf and /dev/null differ diff --git a/doc/svd.shtml b/doc/svd.shtml deleted file mode 100644 index e533e8507d..0000000000 --- a/doc/svd.shtml +++ /dev/null @@ -1,212 +0,0 @@ - - - - - - CUPS Software Version Description - - - -

    Scope

    - -

    Identification

    - -This software version description document provides release information for the -Common UNIX Printing System ("CUPS") Version 1.1. - - - -

    Document Overview

    - -

    This software version description document is organized into the following -sections:

    - - - - - -

    Additions

    - -

    CUPS 1.2 includes many new features from the 1.0.x releases. - -

    Filters

    - -

    imagetoraster, imagetops

    - -

    The image file filters have been upgraded to support conversion of -Microsoft Bitmap ("BMP") and Alias PIX files. - -

    pdftops

    - -

    A new pdftops filter has been developed that is based on the -excellent Xpdf 0.90 software from Derek B. Noonburg. The new filter is -faster, smaller, and considerably more reliable than the -Ghostscript-based filter in CUPS 1.0. - -

    pstoraster

    - -

    The pstoraster filter has been integrated with GNU -GhostScript 5.50. The new RIP supports most Level 3 PostScript language -features. - -

    rastertoepson

    - -

    The new rastertoepson filter supports EPSON printers -using the ESC/P or ESC/P2 command sets. PPDs are supplied for 9-pin, -24-pin, Stylus Color, and Stylus Photo printers. - -

    User-Defined Printers and Options

    - -

    The new lpoptions command allows users to configure default -document options and create additional "instances" of existing printers, -each with unique options. - -

    The lp, lpr, and lpstat commands -have been upgraded to use this option and printer instance information -automatically. - -

    Daemons

    - -

    CUPS 1.2 includes two new daemons that provide enhanced network printing -support. - -

    cups-lpd

    - -

    The cups-lpd daemon provides support for clients using the -Line Printer Daemon protocol. - -

    cups-polld

    - -

    The cups-polld daemon provides remote polling services for -the scheduler. - -

    Commands

    - -

    CUPS 1.2 includes several new printing commands. - -

    lpoptions

    - -

    The lpoptions command provides user-defined printers and -options. - -

    lpmove

    - -

    The lpmove command moves a print job to a new destination. - -

    lpinfo

    - -

    The lpinfo command lists the available PPD files or devices. - -

    IPP Implementation

    - -

    CUPS 1.2 adds support for the set-job-attributes -extension operation as well as two new CUPS-specific extension -operations to determine which devices and printer drivers are available -on the system. - -

    Further information on the CUPS implementation of IPP can be found -in CUPS-IPP-1.2. - - -

    Changes

    - -

    CUPS 1.2 includes many changes from the 1.1.x releases. - -

    Directory Structure

    - -

    The directory structure in CUPS 1.2 has been modified to conform to the -Filesystem Hierarchy Standard, 2.2. The following table describes the -new file locations. - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Table 1: Directory structure changes from CUPS 1.1.x to 1.2.x.
    DescriptionCUPS 1.1.xCUPS 1.2.x
    Backends/var/cups/backend/usr/lib/cups/backend
    CGI programs/var/cups/cgi-bin/usr/lib/cups/cgi-bin
    Configuration files/var/cups/conf/etc/cups
    Documentation/usr/share/cups/doc/usr/share/doc/cups
    Filter programs/var/cups/filter/usr/lib/cups/filter
    Interface scripts/var/cups/interfaces/etc/cups/interfaces
    Locale data/usr/lib/locale/usr/share/locale
    Log files/var/cups/logs/var/log/cups
    PPD files/var/cups/ppd/etc/cups/ppd
    Request files/var/cups/requests/var/spool/cups
    - -

    IPP Implementation

    - -

    CUPS 1.2 is based on version 1.1 of the Internet Printing Protocol. - -

    The new scheduler supports the create-job and -send-document operations. In addition, the -job-sheets, job-sheets-default, and -job-sheets-supported attributes are now supported for -banner pages. - -

    The CUPS-get-printers and CUPS-get-classes -operations have been upgraded to support limited filtering based upon -the printer-type, printer-location, -printer-info, and printer-make-and-model -attributes. - -

    The CUPS-add-printer operation now supports the -ppd-name attribute to specify a locally-available PPD file -rather than sending the PPD file from the client with the request. - -

    Further information on the CUPS implementation of IPP can be found -in CUPS-IPP-1.2. - - - - - diff --git a/doc/translation.html b/doc/translation.html deleted file mode 100644 index 2718fd170d..0000000000 --- a/doc/translation.html +++ /dev/null @@ -1,605 +0,0 @@ - - - -CUPS Translation Guide - - - - - - - -


    -

    CUPS Translation Guide


    -CUPS-TRANS-1.2
    -Easy Software Products
    -Copyright 2001-2002, All Rights Reserved
    -
    -
    -

    Table of Contents

    -
    -
    1 Scope - -2 References - -3 Character Sets -
    -
    4 Message Catalogs -
    -
    5 Web Interfaces - -A Glossary - -
    -

    1 Scope

    -

    1.1 Identification

    -

    This translation guide provides instructions for creating - translations of the CUPS message catalogs and web pages for the Common - UNIX Printing System ("CUPS") Version 1.2 software.

    -

    1.2 System Overview

    -

    CUPS provides a portable printing layer for UNIX®-based 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 ("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 also includes a customized version of GNU Ghostscript (currently - based off GNU Ghostscript 5.50) and an image file RIP that are used to - support non-PostScript printers. Sample drivers for HP and EPSON - printers are included that use these filters.

    -

    1.3 Document Overview

    -

    This translation guide is organized into the following sections:

    -
      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Character Sets
      • -
    • 4 - Message Catalogs
      • -
    • 5 - Web Interfaces
      • -
    • A - Glossary
      • -
    -

    2 References

    -

    2.1 CUPS Documentation

    -

    The following CUPS documentation is referenced by this document:

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

    2.2 Other Documents

    -

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

    - -

    3 Character Sets

    -

    CUPS uses character set files to define the mapping of local - character sets to Unicode code points, as well as the fonts that should - be used for different ranges of characters.

    -

    CUPS includes files for common 8-bit encodings as well as UTF-8 for - Unicode text. The format of these files is described in the CUPS - Interface Design Description (IDD) document. Current character sets are - enumerated in the CUPS API, so in order to add a new character set you - must patch the CUPS source as well as provide a new charset file.

    -

    CUPS 1.2 supports the following character sets:

    -
      -
    • 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-10
      • -
    • iso-8859-13
      • -
    • iso-8859-14
      • -
    • iso-8859-15
      • -
    • koi8-r
      • -
    • koi8-u
      • -
    • us-ascii
      • -
    • utf-8
      • -
    • windows-874
      • -
    • windows-1250
      • -
    • windows-1251
      • -
    • windows-1252
      • -
    • windows-1253
      • -
    • windows-1254
      • -
    • windows-1255
      • -
    • windows-1256
      • -
    • windows-1257
      • -
    • windows-1258
      • -
    -

    4 Message Catalogs

    -

    CUPS message catalogs are text files that identify the default - character set for the locale and a list of localized message strings - for the CUPS software. The format of the message catalog files is - described in the CUPS IDD.

    -

    Message catalogs are named cups_ll, cups_ll_CC, - or cups_ll_CC.charset, where "ll" is the standard 2-letter - abbreviation for the language, "CC" is the standard 2-letter - abbreviation for the country, and "charset" is the charset name which - may differ from the list above.

    -

    Each message catalog file is stored in a subdirectory named ll -, ll_CC, or ll_CC.charset to match the trailing - portion of the message catalog filename.

    -

    When translating a new message catalog, copy the cups_C - message catalog file to a new subdirectory; to translate the message - catalog to Canadian French, you would type the following commands:

    -
      -
      -cd locale ENTER
-mkdir fr_CA ENTER
-cp C/cups_C fr_CA/cups_fr_CA ENTER
-
      -
    -

    Alternatively, you could copy the existing cups_fr message - catalog and then make any changes necessary.

    -

    Once you have make your copy of the file, edit it using your favorite - text editor to translate the text to the desired language. Be sure to - preserve any numbers starting in the first column, as they indicate a - new message number - you'll see this for the HTTP status messages.

    -

    Finally, add your locale to the list of locales in the makefile and - run the following command to install it:

    -
      -
      -make install ENTER
-
      -
    -

    5 Web Interfaces

    -

    The CUPS scheduler provides a web interface that can be used to do - many common printing and administration tasks. The built-in web server - supports localization of web pages through the use of subdirectories - for each locale, e.g. "fr" for French, "de" for German, "fr_ca" for - French in Canada, and so forth.

    -

    5.1 Template Files

    -

    Template files are HTML files with special formatting characters in - them that allow substition of variables and arrays. The CUPS CGI - programs (admin.cgi, classes.cgi, -jobs.cgi, and printers.cgi) use these template file - to provide dynamic content for the web interface. Template files are - installed in the /usr/share/cups/templates directory by - default.

    -

    Translated versions of the template files should be installed in the - appropriate subdirectories under /usr/share/cups/templates. - For example, Canadian French template files should be stored in the - /usr/share/cups/templates/fr_CA directory.

    -

    5.1.1 Inserting Attributes and Values

    -

    Template files consist of HTML with variable substitutions for named - inside curley braces "{name}". Variable names are generally the IPP - attribute names with the hyphen ("-") replaced by the underscore ("_") - character. For example, the job-printer-uri attribute is - renamed to job_printer_uri.

    -

    Curley braces ("{" and "}") to indicate substitutions, and the - backslash ("\") character for quoting. To insert any of these special - characters as-is you need to use the HTML &name; mechanism - or prefix each special character with the backslash ("\".)

    -

    You substitute the value of a variable using {NAME} in - your template file. If the variable is undefined then the {NAME} - string is output as-is.

    -

    To substitute an empty string if the variable is undefined, use -{?NAME} instead.

    -

    5.1.2 Array Substitutions

    -

    The number of array elements can be inserted using {#NAME} -. If the array is undefined then 0 is output. The current array element - (starting at 1) is inserted with {#}.

    -

    Arrays are handled using {[NAME] at the beginning of a - section and } at the end. The information between the - closing bracket ("]") and closing brace ("}") is repeated for as many - elements as are in the named array. For example, the following template - will display a list of each job in the job_id array:

    -
      -
      -<TABLE>
-<TR>
-	<TH>Job ID</TH>
-	<TH>Destination</TH>
-	<TH>Title</TH>
-</TR>
-
-{[job_id]
-<TR>
-	<TD>{?job_id}</TD>
-	<TD>{?job_printer_name}</TD>
-	<TD>{?job_name}</TD>
-</TR>
-}
-</TABLE>
-
      -
    -

    Arrays can be nested, however all elements within the curley braces - ("{" and "}") are indexed using the innermost array.

    -

    5.1.3 Conditional Tests

    -

    Templates can also test variables against specific values and - conditionally include text in the template. The format is:

    -
      -
      -{variable?true:false}
-{variable=value?true:false}
-{variable!value?true:false}
-{variable<value?true:false}
-{variable>value?true:false}
-
      -
    -

    where true is the text that is included if the condition - is true and false is the text that is included if the - condition is false. A value of # is replaced with the - current element number (starting at 1.)

    -

    The character after the variable name specifies the condition to - test: -

    - - - - - - - -
    CharCondition
    ?True if variable exists.
    =True if variable is equal to value -.
    !True if variable is not equal to value -.
    <True if variable is less than value -.
    >True if variable is greater than value -.
    -
    -

    -

    5.1.4 Template File List

    -

    The following template files are used by the web interface:

    -
    -
    add-class.tmpl
    -
    This is the initial form that is shown to add a new printer class.
    -
    add-printer.tmpl
    -
    This is the initial form that is shown to add a new printer.
    -
    admin-op.tmpl
    -
    This is the template that is used to display an error message when - the admin interface sees an undefined operation name.
    -
    admin.tmpl
    -
    This is the template that shows the initial menu of operations (add - a class, manage classes, etc.)
    -
    choose-device.tmpl
    -
    This is the form that shows the list of available devices.
    -
    choose-make.tmpl
    -
    This is the form that shows the list of available manufacturers.
    -
    choose-members.tmpl
    -
    This is the form that shows the list of available printers that can - be added to a class.
    -
    choose-model.tmpl
    -
    This is the form that shows the list of available printer - models/drivers.
    -
    choose-serial.tmpl
    -
    This is the form that allows the user to choose a serial port and - any options.
    -
    choose-uri.tmpl
    -
    This is the form that allows the user to enter a device URI for - network printers.
    -
    class-added.tmpl
    -
    This template shows the "class added" message.
    -
    class-confirm.tmpl
    -
    This is the template used to confirm the deletion of a class.
    -
    class-deleted.tmpl
    -
    This template shows the "class deleted" message.
    -
    classes.tmpl
    -
    This template shows one or more printer classes.
    -
    class-modified.tmpl
    -
    This template shows the "class modified" message.
    -
    config-printer.tmpl
    -
    This template starts the printer configuration form.
    -
    config-printer2.tmpl
    -
    This template ends the printer configuration form.
    -
    error.tmpl
    -
    This template displays a generic error message.
    -
    header.tmpl
    -
    This template is used as the standard header on all dynamic content.
    -
    job-cancel.tmpl
    -
    This template shows "job cancelled".
    -
    job-hold.tmpl
    -
    This template shows "job held".
    -
    job-op.tmpl
    -
    This is the template that is used to display an error message when - the job interface sees an undefined operation name.
    -
    job-release.tmpl
    -
    This template shows "job released".
    -
    job-restart.tmpl
    -
    This template shows "job restarted".
    -
    jobs.tmpl
    -
    This template is used to list the print jobs on a server, class, or - printer.
    -
    modify-class.tmpl
    -
    This template is used as the first form when modifying a class.
    -
    modify-printer.tmpl
    -
    This template is used as the first form when modifying a printer.
    -
    option-boolean.tmpl
    -
    This template is used to select a boolean PPD option.
    -
    option-header.tmpl
    -
    This template is used to start a PPD option group.
    -
    option-pickmany.tmpl
    -
    This template is used to select a multi-valued PPD option.
    -
    option-pickone.tmpl
    -
    This template is used to select a single-valued PPD option.
    -
    option-trailer.tmpl
    -
    This template is used to end a PPD option group.
    -
    printer-accept.tmpl
    -
    This template shows "printer now accepting jobs".
    -
    printer-added.tmpl
    -
    This template shows "printer added".
    -
    printer-configured.tmpl
    -
    This template shows "printer configured".
    -
    printer-confirm.tmpl
    -
    This template asks the user to confirm the deletion of a printer.
    -
    printer-deleted.tmpl
    -
    This template shows "printer deleted".
    -
    printer-modified.tmpl
    -
    This template shows "printer modified".
    -
    printer-purge.tmpl
    -
    This template shows "printer has been purged of all jobs".
    -
    printer-reject.tmpl
    -
    This template shows "printer now rejecting jobs".
    -
    printer-start.tmpl
    -
    This template shows "printer started".
    -
    printers.tmpl
    -
    This template is used to list information on one or more printers.
    -
    printer-stop.tmpl
    -
    This template shows "printer stopped".
    -
    test-page.tmpl
    -
    This template shows "test page printed".
    -
    trailer.tmpl
    -
    This template is used as the standard trailer on all dynamic - content.
    -
    -

    5.2 CGI Programs

    -

    CUPS uses four CGI programs to manage the dynamic web interfaces:

    -
      -
    • admin.cgi
      • -
    • classes.cgi
      • -
    • jobs.cgi
      • -
    • printers.cgi
      • -
    -

    5.2.1 admin.cgi

    -

    The admin.cgi program handles all of the printer and - class administration functions and is run for all direct accesses to - the /admin resource. For most operations it uses the -PRINTER_NAME and OP form variables to specify the - action requested.

    -

    The following OP values are supported:

    -
    -
    accept-jobs
    -
    Accepts jobs on the named destination.
    -
    add-class
    -
    Adds a new printer class. This operation also adds several other - form variables: -
    -
    MEMBER_URIS
    -
    Sets the members of the class. Multiple MEMBER_URIS - values can be provided.
    -
    PRINTER_INFO
    -
    Sets the printer-info attribute for the printer class, which is - usually the printer description.
    -
    PRINTER_LOCATION
    -
    Sets the printer-location attribute for the printer class.
    -
    -
    -
    add-printer
    -
    Adds a new printer. This operation also adds several other form - variables: -
    -
    BAUDRATE
    -
    Sets the baud rate for serial devices.
    -
    BITS
    -
    Sets the number of data bits for serial devices.
    -
    DEVICE_URI
    -
    Sets the device URI for the printer.
    -
    FLOW
    -
    Sets the flow control for serial devices.
    -
    PARITY
    -
    Sets the parity checking for serial devices.
    -
    PPD_NAME
    -
    Sets the driver name for the printer ("raw" for a raw queue.)
    -
    PRINTER_INFO
    -
    Sets the printer-info attribute for the printer, which is usually - the printer description.
    -
    PRINTER_LOCATION
    -
    Sets the printer-location attribute for the printer.
    -
    -
    -
    config-printer
    -
    Configures an existing printer. This operation uses form variables - of the same name as the options in the printer's PPD file.
    -
    delete-class
    -
    Deletes a printer class. The form variable CONFIRM may - be set to any value to bypass the confirmation page.
    -
    delete-printer
    -
    Deletes a printer. The form variable CONFIRM may be set - to any value to bypass the confirmation page.
    -
    modify-class
    -
    Modifies a printer class. See the add-class operation for a list of - form variables.
    -
    modify-printer
    -
    Modifies a printer. See the add-printer operation for a list of form - variables.
    -
    purge-jobs
    -
    Purges all jobs on the named destination.
    -
    reject-jobs
    -
    Rejects new jobs on the named destination.
    -
    start-printer
    -
    Starts the named destination.
    -
    stop-printer
    -
    Stops the named destination.
    -
    -

    5.2.2 classes.cgi

    -

    The classes.cgi program is responsible for listing class - information, including jobs destined for that class. It is for all - direct accesses to the /classes resource and supports the - optional form variables OP and WHICH_JOBS. If - no form variables are supplied then the CGI lists all or a specific - class and the active jobs on each class.

    -

    The following WHICH_JOBS values are supported:

    -
    -
    completed
    -
    Show only the completed jobs.
    -
    not-completed
    -
    Show only the active jobs.
    -
    -

    The following OP values are supported:

    -
    -
    print-test-page
    -
    Print a PostScript test page.
    -
    -

    5.2.3 jobs.cgi

    -

    The jobs.cgi program handles all of the job functions - and is run for all direct accesses to the /jobs resource. - For most operations it uses the JOB_ID, OP, - and WHICH_JOBS form variables to specify the action - requested.

    -

    The following WHICH_JOBS values are supported:

    -
    -
    completed
    -
    Show only the completed jobs.
    -
    not-completed
    -
    Show only the active jobs.
    -
    -

    The following OP values are supported:

    -
    -
    job-cancel
    -
    Cancels a job.
    -
    job-hold
    -
    Holds a job indefinitely.
    -
    job-release
    -
    Releases a job for printing.
    -
    job-restart
    -
    Restarts a stopped, cancelled, completed, or aborted print job.
    -
    -

    5.2.4 printers.cgi

    -

    The printers.cgi program is responsible for listing - printer information, including jobs destined for that printer. It is - for all direct accesses to the /printers resource and - supports the optional form variables OP and -WHICH_JOBS. If no form variables are supplied then the CGI lists - all or a specific printer and the active jobs on each printer.

    -

    The following WHICH_JOBS values are supported:

    -
    -
    completed
    -
    Show only the completed jobs.
    -
    not-completed
    -
    Show only the active jobs.
    -
    -

    The following OP values are supported:

    -
    -
    print-test-page
    -
    Print a PostScript test page.
    -
    -

    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
    -
    - - diff --git a/doc/translation.pdf b/doc/translation.pdf deleted file mode 100644 index 75a4fa938c..0000000000 Binary files a/doc/translation.pdf and /dev/null differ diff --git a/doc/translation.shtml b/doc/translation.shtml deleted file mode 100644 index 6b29326509..0000000000 --- a/doc/translation.shtml +++ /dev/null @@ -1,734 +0,0 @@ - - - - - - CUPS Translation Guide - - - -

    Scope

    - -

    Identification

    - -

    This translation guide provides instructions for creating -translations of the CUPS message catalogs and web pages for the -Common UNIX Printing System ("CUPS") Version 1.1 software. - - - -

    Document Overview

    - -

    This translation guide is organized into the following -sections: - -

      -
    • 1 - Scope
      • -
    • 2 - References
      • -
    • 3 - Character Sets
      • -
    • 4 - Message Catalogs
      • -
    • 5 - Web Interfaces
      • -
    • A - Glossary
      • -
    - - - - -

    Character Sets

    - -

    CUPS uses character set files to define the mapping of local -character sets to Unicode code points, as well as the fonts that -should be used for different ranges of characters. - -

    CUPS includes files for common 8-bit encodings as well as -UTF-8 for Unicode text. The format of these files is described -in the CUPS Interface Design Description (IDD) document. -Current character sets are enumerated in the CUPS API, so in -order to add a new character set you must patch the CUPS source -as well as provide a new charset file. - -

    CUPS 1.1 supports the following character sets: - -

      - -
    • 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-10 -
    • iso-8859-13 -
    • iso-8859-14 -
    • iso-8859-15 -
    • koi8-r -
    • koi8-u -
    • us-ascii -
    • utf-8 -
    • windows-874 -
    • windows-1250 -
    • windows-1251 -
    • windows-1252 -
    • windows-1253 -
    • windows-1254 -
    • windows-1255 -
    • windows-1256 -
    • windows-1257 -
    • windows-1258 - -
    - -

    Message Catalogs

    - -

    CUPS message catalogs are text files that identify the -default character set for the locale and a list of localized -message strings for the CUPS software. The format of the -message catalog files is described in the CUPS IDD. - -

    Message catalogs are named cups_ll, -cups_ll_CC, or cups_ll_CC.charset, where -"ll" is the standard 2-letter abbreviation for the language, -"CC" is the standard 2-letter abbreviation for the country, and -"charset" is the charset name which may differ from the list -above. - -

    Each message catalog file is stored in a subdirectory named -ll, ll_CC, or ll_CC.charset to -match the trailing portion of the message catalog filename. - -

    When translating a new message catalog, copy the cups_C -message catalog file to a new subdirectory; to translate the -message catalog to Canadian French, you would type the following -commands: - -

      -cd locale ENTER
-mkdir fr_CA ENTER
-cp C/cups_C fr_CA/cups_fr_CA ENTER
-
    - -

    Alternatively, you could copy the existing cups_fr -message catalog and then make any changes necessary. - -

    Once you have make your copy of the file, edit it using your -favorite text editor to translate the text to the desired -language. Be sure to preserve any numbers starting in the first -column, as they indicate a new message number - you'll see this -for the HTTP status messages. - -

    Finally, add your locale to the list of locales in the -makefile and run the following command to install it: - -

      -make install ENTER
-
    - -

    Web Interfaces

    - -

    The CUPS scheduler provides a web interface that can be used -to do many common printing and administration tasks. The built-in -web server supports localization of web pages through the use of -subdirectories for each locale, e.g. "fr" for French, "de" for -German, "fr_ca" for French in Canada, and so forth. - -

    Template Files

    - -

    Template files are HTML files with special formatting -characters in them that allow substition of variables and -arrays. The CUPS CGI programs (admin.cgi, -classes.cgi, jobs.cgi, and -printers.cgi) use these template file to provide -dynamic content for the web interface. Template files are -installed in the /usr/share/cups/templates directory -by default. - -

    Translated versions of the template files should be installed -in the appropriate subdirectories under -/usr/share/cups/templates. For example, Canadian -French template files should be stored in the -/usr/share/cups/templates/fr_CA directory. - -

    Inserting Attributes and Values

    - -

    Template files consist of HTML with variable substitutions -for named inside curley braces "{name}". Variable names are -generally the IPP attribute names with the hyphen ("-") replaced -by the underscore ("_") character. For example, the -job-printer-uri attribute is renamed to -job_printer_uri. - -

    Curley braces ("{" and "}") to indicate substitutions, and -the backslash ("\") character for quoting. To insert any of -these special characters as-is you need to use the HTML -&name; mechanism or prefix each special -character with the backslash ("\".)

    - -

    You substitute the value of a variable using -{NAME} in your template file. If the variable is -undefined then the {NAME} string is output -as-is.

    - -

    To substitute an empty string if the variable is undefined, use -{?NAME} instead.

    - -

    Array Substitutions

    - -

    The number of array elements can be inserted using -{#NAME}. If the array is undefined then 0 is -output. The current array element (starting at 1) is inserted -with {#}.

    - -

    Arrays are handled using {[NAME] at the beginning of a -section and } at the end. The information between the closing -bracket ("]") and closing brace ("}") is repeated for as many elements as -are in the named array. For example, the following template will display -a list of each job in the job_id array:

    - -
      -<TABLE>
-<TR>
-	<TH>Job ID</TH>
-	<TH>Destination</TH>
-	<TH>Title</TH>
-</TR>
-
-{[job_id]
-<TR>
-	<TD>{?job_id}</TD>
-	<TD>{?job_printer_name}</TD>
-	<TD>{?job_name}</TD>
-</TR>
-}
-</TABLE>
-
    - -

    Arrays can be nested, however all elements within the curley -braces ("{" and "}") are indexed using the innermost array.

    - -

    Conditional Tests

    - -

    Templates can also test variables against specific values and -conditionally include text in the template. The format is: - -

      -{variable?true:false}
-{variable=value?true:false}
-{variable!value?true:false}
-{variable<value?true:false}
-{variable>value?true:false}
-
    - -

    where true is the text that is included if the -condition is true and false is the text that is -included if the condition is false. A value of # is -replaced with the current element number (starting at 1.) - -

    The character after the variable name specifies the condition -to test: - -

    - - - - - - - - - - - - - - - - - - - - - - - - -
    CharCondition
    ?True if variable exists.
    =True if variable is equal to value.
    !True if variable is not equal to value.
    <True if variable is less than value.
    >True if variable is greater than value.
    - -

    Template File List

    - -

    The following template files are used by the web interface: - -

    - -
    add-class.tmpl - -
    This is the initial form that is shown to add a new - printer class. - -
    add-printer.tmpl - -
    This is the initial form that is shown to add a new - printer. - -
    admin-op.tmpl - -
    This is the template that is used to display an error - message when the admin interface sees an undefined - operation name. - -
    admin.tmpl - -
    This is the template that shows the initial menu of - operations (add a class, manage classes, etc.) - -
    choose-device.tmpl - -
    This is the form that shows the list of available - devices. - -
    choose-make.tmpl - -
    This is the form that shows the list of available - manufacturers. - -
    choose-members.tmpl - -
    This is the form that shows the list of available - printers that can be added to a class. - -
    choose-model.tmpl - -
    This is the form that shows the list of available - printer models/drivers. - -
    choose-serial.tmpl - -
    This is the form that allows the user to choose - a serial port and any options. - -
    choose-uri.tmpl - -
    This is the form that allows the user to enter - a device URI for network printers. - -
    class-added.tmpl - -
    This template shows the "class added" message. - -
    class-confirm.tmpl - -
    This is the template used to confirm the - deletion of a class. - -
    class-deleted.tmpl - -
    This template shows the "class deleted" message. - -
    classes.tmpl - -
    This template shows one or more printer classes. - -
    class-modified.tmpl - -
    This template shows the "class modified" message. - -
    config-printer.tmpl - -
    This template starts the printer configuration form. - -
    config-printer2.tmpl - -
    This template ends the printer configuration form. - -
    error.tmpl - -
    This template displays a generic error message. - -
    header.tmpl - -
    This template is used as the standard header on all dynamic - content. - -
    job-cancel.tmpl - -
    This template shows "job cancelled". - -
    job-hold.tmpl - -
    This template shows "job held". - -
    job-op.tmpl - -
    This is the template that is used to display an - error message when the job interface sees an undefined - operation name. - -
    job-release.tmpl - -
    This template shows "job released". - -
    job-restart.tmpl - -
    This template shows "job restarted". - -
    jobs.tmpl - -
    This template is used to list the print jobs on a server, - class, or printer. - -
    modify-class.tmpl - -
    This template is used as the first form when modifying a - class. - -
    modify-printer.tmpl - -
    This template is used as the first form when modifying a - printer. - -
    option-boolean.tmpl - -
    This template is used to select a boolean PPD option. - -
    option-header.tmpl - -
    This template is used to start a PPD option group. - -
    option-pickmany.tmpl - -
    This template is used to select a multi-valued PPD option. - -
    option-pickone.tmpl - -
    This template is used to select a single-valued PPD option. - -
    option-trailer.tmpl - -
    This template is used to end a PPD option group. - -
    printer-accept.tmpl - -
    This template shows "printer now accepting jobs". - -
    printer-added.tmpl - -
    This template shows "printer added". - -
    printer-configured.tmpl - -
    This template shows "printer configured". - -
    printer-confirm.tmpl - -
    This template asks the user to confirm the deletion of a printer. - -
    printer-deleted.tmpl - -
    This template shows "printer deleted". - -
    printer-modified.tmpl - -
    This template shows "printer modified". - -
    printer-purge.tmpl - -
    This template shows "printer has been purged of all jobs". - -
    printer-reject.tmpl - -
    This template shows "printer now rejecting jobs". - -
    printer-start.tmpl - -
    This template shows "printer started". - -
    printers.tmpl - -
    This template is used to list information on one or more - printers. - -
    printer-stop.tmpl - -
    This template shows "printer stopped". - -
    test-page.tmpl - -
    This template shows "test page printed". - -
    trailer.tmpl - -
    This template is used as the standard trailer on all dynamic - content. - -
    - -

    CGI Programs

    - -

    CUPS uses four CGI programs to manage the dynamic web interfaces: - -

      - -
    • admin.cgi
      • -
    • classes.cgi
      • -
    • jobs.cgi
      • -
    • printers.cgi
      • - -
    - -

    admin.cgi

    - -

    The admin.cgi program handles all of the printer -and class administration functions and is run for all direct -accesses to the /admin resource. For most operations it uses the -PRINTER_NAME and OP form variables to -specify the action requested. - -

    The following OP values are supported: - -

    - -
    accept-jobs
    - -
    Accepts jobs on the named destination.
    - -
    add-class
    - -
    Adds a new printer class. This operation also adds - several other form variables: - -
    - -
    MEMBER_URIS
    - -
    Sets the members of the class. Multiple - MEMBER_URIS values can be - provided.
    - -
    PRINTER_INFO
    - -
    Sets the printer-info attribute for the - printer class, which is usually the printer - description.
    - -
    PRINTER_LOCATION
    - -
    Sets the printer-location attribute for the - printer class.
    - -
    - -
    - -
    add-printer
    - -
    Adds a new printer. This operation also adds several other - form variables: - -
    - -
    BAUDRATE
    - -
    Sets the baud rate for serial devices.
    - -
    BITS
    - -
    Sets the number of data bits for serial devices.
    - -
    DEVICE_URI
    - -
    Sets the device URI for the printer.
    - -
    FLOW
    - -
    Sets the flow control for serial devices.
    - -
    PARITY
    - -
    Sets the parity checking for serial devices.
    - -
    PPD_NAME
    - -
    Sets the driver name for the printer ("raw" for a - raw queue.)
    - -
    PRINTER_INFO
    - -
    Sets the printer-info attribute for the - printer, which is usually the printer - description.
    - -
    PRINTER_LOCATION
    - -
    Sets the printer-location attribute for the - printer.
    - -
    - -
    - -
    config-printer
    - -
    Configures an existing printer. This operation uses - form variables of the same name as the options in the - printer's PPD file.
    - -
    delete-class
    - -
    Deletes a printer class. The form variable CONFIRM - may be set to any value to bypass the confirmation page.
    - -
    delete-printer
    - -
    Deletes a printer. The form variable CONFIRM - may be set to any value to bypass the confirmation page.
    - -
    modify-class
    - -
    Modifies a printer class. See the add-class operation for a - list of form variables.
    - -
    modify-printer
    - -
    Modifies a printer. See the add-printer operation for a - list of form variables.
    - -
    purge-jobs
    - -
    Purges all jobs on the named destination.
    - -
    reject-jobs
    - -
    Rejects new jobs on the named destination.
    - -
    start-printer
    - -
    Starts the named destination.
    - -
    stop-printer
    - -
    Stops the named destination.
    - -
    - - -

    classes.cgi

    - -

    The classes.cgi program is responsible for -listing class information, including jobs destined for that -class. It is for all direct accesses to the /classes resource -and supports the optional form variables OP and -WHICH_JOBS. If no form variables are supplied then -the CGI lists all or a specific class and the active jobs on -each class. - -

    The following WHICH_JOBS values are supported: - -

    - -
    completed
    - -
    Show only the completed jobs.
    - -
    not-completed
    - -
    Show only the active jobs.
    - -
    - -

    The following OP values are supported: - -

    - -
    print-test-page
    - -
    Print a PostScript test page.
    - -
    - -

    jobs.cgi

    - -

    The jobs.cgi program handles all of the job -functions and is run for all direct accesses to the /jobs -resource. For most operations it uses the -JOB_ID, OP, and -WHICH_JOBS form variables to specify the action -requested. - -

    The following WHICH_JOBS values are supported: - -

    - -
    completed
    - -
    Show only the completed jobs.
    - -
    not-completed
    - -
    Show only the active jobs.
    - -
    - -

    The following OP values are supported: - -

    - -
    job-cancel
    - -
    Cancels a job.
    - -
    job-hold
    - -
    Holds a job indefinitely.
    - -
    job-release
    - -
    Releases a job for printing.
    - -
    job-restart
    - -
    Restarts a stopped, cancelled, completed, or aborted - print job.
    - -
    - -

    printers.cgi

    - -

    The printers.cgi program is responsible for -listing printer information, including jobs destined for that -printer. It is for all direct accesses to the /printers resource -and supports the optional form variables OP and -WHICH_JOBS. If no form variables are supplied then -the CGI lists all or a specific printer and the active jobs on -each printer. - -

    The following WHICH_JOBS values are supported: - -

    - -
    completed
    - -
    Show only the completed jobs.
    - -
    not-completed
    - -
    Show only the active jobs.
    - -
    - -

    The following OP values are supported: - -

    - -
    print-test-page
    - -
    Print a PostScript test page.
    - -
    - - - - - - diff --git a/filter/pstops.c b/filter/pstops.c index 0a2de3196d..3f230052f2 100644 --- a/filter/pstops.c +++ b/filter/pstops.c @@ -1,5 +1,5 @@ /* - * "$Id: pstops.c 5092 2006-02-09 00:54:31Z mike $" + * "$Id: pstops.c 5205 2006-02-28 21:05:24Z mike $" * * PostScript filter for the Common UNIX Printing System (CUPS). * @@ -2185,11 +2185,11 @@ start_nup(int number, /* I - Page number */ */ printf("%d %d translate\n", -lbrt[0], -lbrt[1]); - printf("0 0 %.1f %.1f ESPrc\n", w, l); + printf("0 0 %d %d ESPrc\n", lbrt[2] - lbrt[0], lbrt[3] - lbrt[1]); } } /* - * End of "$Id: pstops.c 5092 2006-02-09 00:54:31Z mike $". + * End of "$Id: pstops.c 5205 2006-02-28 21:05:24Z mike $". */ diff --git a/locale/Makefile b/locale/Makefile index eb0a3d6978..1fef472e74 100644 --- a/locale/Makefile +++ b/locale/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 5193 2006-02-27 20:27:07Z mike $" +# "$Id: Makefile 5224 2006-03-04 02:00:43Z mike $" # # Locale file makefile for the Common UNIX Printing System (CUPS). # @@ -28,7 +28,7 @@ include ../Makedefs # Locales... # -LOCALES = ja +LANGUAGES = ja # @@ -59,7 +59,7 @@ depend: install: all $(INSTALL_DIR) -m 755 $(LOCALEDIR) - for loc in $(LOCALES) ; do \ + for loc in $(LANGUAGES) ; do \ $(INSTALL_DIR) -m 755 $(LOCALEDIR)/$$loc ; \ $(INSTALL_DATA) cups_$$loc.po $(LOCALEDIR)/$$loc/cups_$$loc.po ; \ done @@ -81,7 +81,7 @@ pot: -e '1,$$s/charset=CHARSET/charset=utf-8/'; \ cat cups.footer) > cups.pot.N mv cups.pot.N cups.pot - for loc in $(LOCALES) ; do \ + for loc in $(LANGUAGES) ; do \ echo Merging changes into cups_$$loc.po... ; \ msgmerge -o cups_$$loc.po cups_$$loc.po cups.pot ; \ done @@ -102,5 +102,5 @@ translate.o: ../cups/http.h ../cups/i18n.h ../cups/language.h ../cups/string.h # -# End of "$Id: Makefile 5193 2006-02-27 20:27:07Z mike $". +# End of "$Id: Makefile 5224 2006-03-04 02:00:43Z mike $". # diff --git a/packaging/cups.list.in b/packaging/cups.list.in index 2f19c85ba7..a26298856a 100644 --- a/packaging/cups.list.in +++ b/packaging/cups.list.in @@ -1,5 +1,5 @@ # -# "$Id: cups.list.in 5193 2006-02-27 20:27:07Z mike $" +# "$Id: cups.list.in 5224 2006-03-04 02:00:43Z mike $" # # ESP Package Manager (EPM) file list for the Common UNIX Printing # System (CUPS). @@ -28,7 +28,7 @@ %copyright 1993-2006 by Easy Software Products, All Rights Reserved. %vendor Easy Software Products %license LICENSE.txt -%readme README.txt +%readme packaging/cups.license %version @CUPS_VERSION@ %description The Common UNIX Printing System provides a portable printing %description layer for UNIX(r) operating systems. It has been developed by @@ -388,6 +388,7 @@ f 0644 root sys $LIBDIR/libcupsimage.a filter/libcupsimage.a d 0755 root sys $DOCDIR/help - f 0644 root sys $DOCDIR/help doc/help/api*.html +f 0644 root sys $DOCDIR/help doc/help/spec*.html %subpackage # Documentation files @@ -395,9 +396,21 @@ d 0755 root sys $DOCDIR - f 0644 root sys $DOCDIR doc/*.css f 0644 root sys $DOCDIR doc/*.html d 0755 root sys $DOCDIR/help - -f 0644 root sys $DOCDIR/help doc/*-reference.html +f 0644 root sys $DOCDIR/help/cgi.html doc/help/cgi.html +f 0644 root sys $DOCDIR/help/glossary.html doc/help/glossary.html +f 0644 root sys $DOCDIR/help/license.html doc/help/license.html +f 0644 root sys $DOCDIR/help/network.html doc/help/network.html +f 0644 root sys $DOCDIR/help/options.html doc/help/options.html +f 0644 root sys $DOCDIR/help/overview.html doc/help/overview.html +f 0644 root sys $DOCDIR/help/security.html doc/help/security.html +f 0644 root sys $DOCDIR/help/standard.html doc/help/standard.html +f 0644 root sys $DOCDIR/help/translation.html doc/help/translation.html +f 0644 root sys $DOCDIR/help/whatsnew.html doc/help/whatsnew.html +f 0644 root sys $DOCDIR/help doc/help/man-*.html +f 0644 root sys $DOCDIR/help doc/help/ref-*.html d 0755 root sys $DOCDIR/images - f 0644 root sys $DOCDIR/images doc/images/*.gif +f 0644 root sys $DOCDIR/images doc/images/*.png f 0644 root sys $DOCDIR/robots.txt doc/robots.txt # Japanese documentation files @@ -460,5 +473,5 @@ f 0644 root sys $AMANDIR/man$MAN8DIR/cups-lpd.$MAN8EXT man/cups-lpd.$MAN8EXT i 0755 root sys cups init/cups.sh # -# End of "$Id: cups.list.in 5193 2006-02-27 20:27:07Z mike $". +# End of "$Id: cups.list.in 5224 2006-03-04 02:00:43Z mike $". # diff --git a/packaging/cups.readme b/packaging/cups.readme new file mode 100644 index 0000000000..c2f9648324 --- /dev/null +++ b/packaging/cups.readme @@ -0,0 +1,290 @@ +README - CUPS v1.2.0b1 - 01/10/2006 +----------------------------------- + +***************************************************************** +***************************************************************** +**** **** +**** WARNING: THIS IS BETA RELEASE SOFTWARE AND MAY BE **** +**** TOTALLY UNSTABLE. DO NOT USE IN ENVIRONMENTS **** +**** WHERE RELIABLE SOFTWARE IS REQUIRED! **** +**** **** +***************************************************************** +***************************************************************** + +Looking for compile instructions? Read the file "INSTALL.txt" +instead... + +***************************************************************** +***************************************************************** +**** **** +**** IF YOU HAVE A NON-POSTSCRIPT PRINTER, YOU WILL ALSO **** +**** NEED TO INSTALL ESP GHOSTSCRIPT OR A PATCHED VERSION **** +**** OF A STANDARD GHOSTSCRIPT RELEASE. **** +**** **** +***************************************************************** +***************************************************************** + + +INTRODUCTION + +CUPS provides a portable printing layer for UNIX(r)-based +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 ("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 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/ + +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. + + +SYSTEM REQUIREMENTS + +Binary distributions require a minimum of 10MB of free disk +space. We do not recommend using CUPS on a workstation with less +than 32MB of RAM or a PC with less than 16MB of RAM. + +If you are installing from source you'll need ANSI-compliant C +and C++ compilers and optionally one or more image file support +libraries. Complete source installation instructions can be +found in the file "INSTALL.txt". + + +SOFTWARE REQUIREMENTS + +The following operating system software is required to install +one of the binary distributions from Easy Software Products: + + - AIX 4.3 or higher + - HP-UX 11.00 or higher + - IRIX 6.5 or higher + - Linux 2.4 with glibc 2.2 or higher + - Solaris 7 or higher (SPARC or Intel) + + +INSTALLING "PORTABLE" CUPS DISTRIBUTIONS + +We are currently distributing "portable" CUPS binary +distributions in TAR format with installation and removal +scripts generated by our ESP Package Manager (EPM) software, +which is available from: + + http://www.easysw.com/epm + +WARNING: Installing CUPS will overwrite your existing printing +system. Backup files are made by the installation script and +restored by the removal script, so if you experience problems +you should be able to remove the CUPS software to restore your +previous configuration. However, Easy Software Products makes +no warranty for this and will not be liable for any lost +revenues, etc. + +To install the CUPS software you will need to be logged in as +root (doing an "su" is good enough). Once you are the root +user, run the installation script with: + + ./cups.install ENTER + +After asking you a few yes/no questions the CUPS software will +be installed and the scheduler will be started automatically. + + +INSTALLING HOST-SPECIFIC (RPM, DEBIAN, ETC.) DISTRIBUTIONS + +The host-specific distributions use the operating system +software installation tools. To install a host-specific +distribution please consult the CUPS Software Administrators +Manual or your operating system documentation. + + +READING THE DOCUMENTATION + +Once you have installed the software you can access the +documentation (and a bunch of other stuff) on-line at: + + http://localhost:631 + +If you're having trouble getting that far, the documentation is +located in the "/usr/share/doc/cups" directory in the binary +distributions, and under the "doc" directory in the source +archives. + +Please read the documentation before asking questions. + + +GETTING SUPPORT AND OTHER RESOURCES + +If you have problems, READ THE DOCUMENTATION FIRST! We also +provide many discussion forums which are available at: + + http://www.cups.org/newsgroups.php + +Commercial support (with a guaranteed response time) is available +from Easy Software Products. For more information see: + + http://www.easysw.com/cups/ + +See the CUPS web site at "http://www.cups.org/" for other site +links. + + +SETTING UP PRINTER QUEUES USING YOUR WEB BROWSER + +CUPS 1.2 includes a web-based administration tool that allows you +to manage printers, classes, and jobs on your server. To access +the printer administration tools open the following URL in your +browser: + + http://localhost:631/admin + +You will be asked for the administration password (root or any +other user in the sys/system/root group on your system) and then +shown a menu of available functions. + +DO NOT use the hostname for your machine - it will not work with +the default CUPS configuration. To enable administration access +on other addresses, consult the CUPS Software Administrators +Manual. + + +SETTING UP PRINTER QUEUES FROM THE COMMAND-LINE + +CUPS works best with PPD (PostScript Printer Description) +files. In a pinch you can also use System V style printer +interface scripts. + +Six sample PPD files are provided with this distribution that +utilize the PostScript and image file RIPs and the sample EPSON +and HP printer drivers. To add the sample DeskJet driver to the +system for a printer connected to the parallel port, use one of +the following commands: + + HP-UX: + + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/c2t0d0_lp -E + + IRIX: + + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/plp -E + + Linux: + + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp0 -E + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp1 -E + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/lp2 -E + + Solaris: + + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/bpp0 -E + /usr/lib/lpadmin -p DeskJet -m deskjet.ppd -v parallel:/dev/ecpp0 -E + +Similarly, for the other sample drivers you can use: + + Driver PPD File + ----------------------------- ------------ + Dymo Label Printers dymo.ppd + EPSON Stylus Color Series stcolor.ppd + EPSON Stylus Photo Series stphoto.ppd + EPSON Stylus New Color Series stcolor2.ppd + EPSON Stylus New Photo Series stphoto2.ppd + EPSON 9-pin Series epson9.ppd + EPSON 24-pin Series epson24.ppd + HP DeskJet Series deskjet.ppd + HP New DeskJet Series deskjet2.ppd + HP LaserJet Series laserjet.ppd + OKIDATA 9-Pin Series okidata9.ppd + OKIDATA 24-Pin Series okidat24.ppd + +These sample drivers provide basic printing capabilities, but +generally do not exercise the full potential of the printers or +CUPS. For commercial printer drivers check out our ESP Print +Pro software at: + + http://www.easysw.com/printpro/ + + +PRINTING FILES + +CUPS provides both the System V "lp" and Berkeley "lpr" commands +for printing: + + lp filename + lpr filename + +Both the "lp" and "lpr" commands support printing options for +the driver: + + lp -omedia=A4 -oresolution=600dpi filename + lpr -omedia=A4 -oresolution=600dpi filename + +CUPS recognizes many types of images files as well as PDF, +PostScript, HP-GL/2, and text files, so you can print those +files directly rather than through an application. + +If you have an application that generates output specifically +for your printer then you need to use the "-oraw" or "-l" +options: + + lp -oraw filename + lpr -l filename + +This will prevent the filters from misinterpreting your print +file. + + +LEGAL STUFF + +CUPS is Copyright 1993-2006 by Easy Software Products. CUPS, +the CUPS logo, and the Common UNIX Printing System are the +trademark property of Easy Software Products. + +The MD5 Digest code is Copyright 1999 Aladdin Enterprises. + +The PDF filter (pdftops) is based on the Xpdf software, +Copyright 1996-2005 by Derek B. Noonburg. + +This software is based in part on the work of the Independent +JPEG Group. + +CUPS is provided under the terms of the GNU General Public +License and GNU Library General Public License. This program is +distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the "LICENSE.html", +"LICENSE.txt", or "cups.license" files for more information. + +For commercial licensing information, please contact: + + Attn: CUPS Licensing Information + Easy Software Products + 44141 Airport View Drive, Suite 204 + Hollywood, Maryland 20636 USA + + Voice: +1.301.373.9600 + Email: cups-info@cups.org + WWW: http://www.cups.org + +Note that commercial licensors may also require a license from +Derek B. Noonburg who developed the Xpdf software used to print +PDF files. diff --git a/packaging/cups.spec.in b/packaging/cups.spec.in index 1cdee77514..2516be2536 100644 --- a/packaging/cups.spec.in +++ b/packaging/cups.spec.in @@ -1,5 +1,5 @@ # -# "$Id: cups.spec.in 5193 2006-02-27 20:27:07Z mike $" +# "$Id: cups.spec.in 5224 2006-03-04 02:00:43Z mike $" # # RPM "spec" file for the Common UNIX Printing System (CUPS). # @@ -232,11 +232,17 @@ rm -rf $RPM_BUILD_ROOT %dir /usr/share/doc/cups /usr/share/doc/cups/*.* %dir /usr/share/doc/cups/help -/usr/share/doc/cups/help/*-reference.html +/usr/share/doc/cups/help/cgi.html +/usr/share/doc/cups/help/glossary.html +/usr/share/doc/cups/help/license.html /usr/share/doc/cups/help/man-*.html /usr/share/doc/cups/help/network.html +/usr/share/doc/cups/help/options.html /usr/share/doc/cups/help/overview.html +/usr/share/doc/cups/help/ref-*.html +/usr/share/doc/cups/help/security.html /usr/share/doc/cups/help/standard.html +/usr/share/doc/cups/help/translation.html /usr/share/doc/cups/help/whatsnew.html %dir /usr/share/doc/cups/images /usr/share/doc/cups/images/* @@ -323,5 +329,5 @@ rm -rf $RPM_BUILD_ROOT # -# End of "$Id: cups.spec.in 5193 2006-02-27 20:27:07Z mike $". +# End of "$Id: cups.spec.in 5224 2006-03-04 02:00:43Z mike $". # diff --git a/pstoraster/README.pstoraster b/pstoraster/README.pstoraster deleted file mode 100644 index 980def2194..0000000000 --- a/pstoraster/README.pstoraster +++ /dev/null @@ -1,73 +0,0 @@ -README.pstoraster - 11/14/2003 ------------------------------- - -INTRODUCTION - - This directory contains the CUPS "driver" for Ghostscript - 7.x and 8.x, the pstoraster script that is used to run - Ghostscript as a CUPS filter, the pstoraster.convs file that - defines the PostScript to raster filter for CUPS drivers, a - makefile fragment that adds the CUPS driver, and the wrapper - script (pstopxl) and PPD files (pxl*.ppd) to support PCL - XL/PCL 6 printers. - - This software is included with both the CUPS and ESP - Ghostscript 7.07.1 distributions. While the files will also - compile with earlier versions of Ghostscript, there are bugs - in older versions of Ghostscript which may cause problems. - - Also, this driver may not be used in any commercial - Ghostscript distributions without prior written - permission/licensing from Easy Software Products. See the - contact information in the file "gdevcups.c" for more - information. - - -COMPILING ESP GHOSTSCRIPT WITH THE CUPS DRIVER - - Normally the CUPS driver will be automatically included when - you use the configure script supplied with ESP Ghostscript. - - Once you have compiled and installed Ghostscript, restart - the cupsd process, either by sending the HUP signal to the - process or using the init script supplied with CUPS. - - To use the PCL XL/PCL 6 drivers, make sure that you also - configure Ghostscript with the pxlmono and pxlcolor drivers. - - -COMPILING AFPL/GNU GHOSTSCRIPT WITH THE CUPS DRIVER - - Before configuring AFPL or GNU Ghostscript, first copy this - directory to the Ghostscript source directory, e.g.: - - cp -r pstoraster /some/path/to/ghostscript-7.07 - - Then apply the appropriate patch: - - cd /some/path/to/ghostscript-7.07 - patch -p1 pstoraster/gs707-lib.patch - - or: - - cd /some/path/to/ghostscript-8.11 - patch -p1 pstoraster/gs811-lib.patch - - Next, run the configure script to configure the Ghostscript - software: - - ./configure [any configure options you want] - - Finally, add the following include line to the end of the - makefile: - - include pstoraster/cups.mak - - and add "$(DD)cups.dev" to any of the DEVICE_DEVS lines. - - Once you have compiled and installed Ghostscript, restart - the cupsd process, either by sending the HUP signal to the - process or using the init script supplied with CUPS. - - To use the PCL XL/PCL 6 drivers, make sure that you also - configure Ghostscript with the pxlmono and pxlcolor drivers. diff --git a/pstoraster/cups.mak b/pstoraster/cups.mak deleted file mode 100644 index 129e8b8afb..0000000000 --- a/pstoraster/cups.mak +++ /dev/null @@ -1,53 +0,0 @@ -# -# "$Id: cups.mak 4493 2005-02-18 02:09:53Z mike $" -# -# CUPS driver makefile for Ghostscript. -# -# Copyright 2001-2005 by Easy Software Products. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -# - -### ----------------- CUPS Ghostscript Driver ---------------------- ### - -cups_= $(GLOBJ)gdevcups.$(OBJ) - -CUPSSERVER= $(install_prefix)`cups-config --serverbin` -CUPSCONFIG= $(install_prefix)`cups-config --serverroot` -CUPSDATA= $(install_prefix)`cups-config --datadir` - -$(DD)cups.dev: $(cups_) $(GLD)page.dev - $(ADDMOD) $(DD)cups -lib cupsimage -lib cups - $(SETPDEV2) $(DD)cups $(cups_) - -$(GLOBJ)gdevcups.$(OBJ): pstoraster/gdevcups.c $(PDEVH) - $(GLCC) $(GLO_)gdevcups.$(OBJ) $(C_) pstoraster/gdevcups.c - -install: install-cups - -install-cups: - -mkdir -p $(CUPSSERVER)/filter - $(INSTALL_PROGRAM) pstoraster/pstoraster $(CUPSSERVER)/filter - $(INSTALL_PROGRAM) pstoraster/pstopxl $(CUPSSERVER)/filter - -mkdir -p $(CUPSCONFIG) - $(INSTALL_DATA) pstoraster/pstoraster.convs $(CUPSCONFIG) - -mkdir -p $(CUPSDATA)/model - $(INSTALL_DATA) pstoraster/pxlcolor.ppd $(CUPSDATA)/model - $(INSTALL_DATA) pstoraster/pxlmono.ppd $(CUPSDATA)/model - - -# -# End of "$Id: cups.mak 4493 2005-02-18 02:09:53Z mike $". -# diff --git a/pstoraster/gdevcups.c b/pstoraster/gdevcups.c deleted file mode 100644 index 89a5df20e9..0000000000 --- a/pstoraster/gdevcups.c +++ /dev/null @@ -1,4464 +0,0 @@ -/* - * "$Id: gdevcups.c 4493 2005-02-18 02:09:53Z mike $" - * - * GNU Ghostscript raster output driver for the Common UNIX Printing - * System (CUPS). - * - * Copyright 1993-2005 by Easy Software Products. - * - * These coded instructions, statements, and computer programs are the - * property of Easy Software Products and are protected by Federal - * copyright law. Distribution and use rights are outlined in the file - * "LICENSE.txt" which should have been included with this file. If this - * file is missing or damaged please contact Easy Software Products - * at: - * - * Attn: CUPS Licensing Information - * Easy Software Products - * 44141 Airport View Drive, Suite 204 - * Hollywood, Maryland 20636 USA - * - * Voice: (301) 373-9600 - * EMail: cups-info@cups.org - * WWW: http://www.cups.org/ - * - * This code and any derivative of it may be used and distributed - * freely under the terms of the GNU General Public License when - * used with GNU Ghostscript or its derivatives. Use of the code - * (or any derivative of it) with software other than GNU - * GhostScript (or its derivatives) is governed by the CUPS license - * agreement. - * - * Contents: - * - * cups_close() - Close the output file. - * cups_get_matrix() - Generate the default page matrix. - * cups_get_params() - Get pagedevice parameters. - * cups_get_space_params() - Get space parameters from the RIP_CACHE env var. - * cups_map_color_rgb() - Map a color index to an RGB color. - * cups_map_cielab() - Map CIE Lab transformation... - * cups_map_rgb_color() - Map an RGB color to a color index. We map the - * RGB color to the output colorspace & bits (we - * figure out the format when we output a page). - * cups_open() - Open the output file and initialize things. - * cups_print_pages() - Send one or more pages to the output file. - * cups_put_params() - Set pagedevice parameters. - * cups_set_color_info() - Set the color information structure based on - * the required output. - * cups_print_chunked() - Print a page of chunked pixels. - * cups_print_banded() - Print a page of banded pixels. - * cups_print_planar() - Print a page of planar pixels. - */ - -/* - * Include necessary headers... - */ - -#include "std.h" /* to stop stdlib.h redefining types */ -#include "gdevprn.h" -#include "gsparam.h" -#include "gsexit.h" - -#include -#include -#include -#include -#include - -#undef private -#define private - - -/* - * Check if we are compiling against CUPS 1.2. If so, enable - * certain extended attributes and use a different page header - * structure and write function... - */ - -#ifdef CUPS_RASTER_SYNCv1 -# define cups_page_header_t cups_page_header2_t -# define cupsRasterWriteHeader cupsRasterWriteHeader2 -#endif /* CUPS_RASTER_SYNCv1 */ - - -/* - * Newer versions of Ghostscript don't provide gs_exit() function anymore. - * It has been renamed to gs_to_exit()... - */ - -#ifdef dev_t_proc_encode_color -# define gs_exit gs_to_exit -#endif /* dev_t_proc_encode_color */ - - -/* - * CIE XYZ color constants... - */ - -#define D65_X (0.412453 + 0.357580 + 0.180423) -#define D65_Y (0.212671 + 0.715160 + 0.072169) -#define D65_Z (0.019334 + 0.119193 + 0.950227) - - -/* - * Size of a tile in pixels... - */ - -#define CUPS_TILE_SIZE 256 - - -/* - * Size of profile LUTs... - */ - -#ifdef dev_t_proc_encode_color -# define CUPS_MAX_VALUE frac_1 -#else -# define CUPS_MAX_VALUE gx_max_color_value -#endif /* dev_t_proc_encode_color */ - - -/* - * Macros... - */ - -#define x_dpi (pdev->HWResolution[0]) -#define y_dpi (pdev->HWResolution[1]) -#define cups ((gx_device_cups *)pdev) - -/* - * Macros from ; we can't include because it also - * defines DEBUG, one of our flags to insert various debugging code. - */ - -#ifndef max -# define max(a,b) ((a)<(b) ? (b) : (a)) -#endif /* !max */ - -#ifndef min -# define min(a,b) ((a)>(b) ? (b) : (a)) -#endif /* !min */ - -#ifndef abs -# define abs(x) ((x)>=0 ? (x) : -(x)) -#endif /* !abs */ - - -/* - * Procedures - */ - -private dev_proc_close_device(cups_close); -private dev_proc_get_initial_matrix(cups_get_matrix); -private int cups_get_params(gx_device *, gs_param_list *); -private dev_proc_open_device(cups_open); -private int cups_print_pages(gx_device_printer *, FILE *, int); -private int cups_put_params(gx_device *, gs_param_list *); -private void cups_set_color_info(gx_device *); -private dev_proc_sync_output(cups_sync_output); -private prn_dev_proc_get_space_params(cups_get_space_params); - -#ifdef dev_t_proc_encode_color -private cm_map_proc_gray(cups_map_gray); -private cm_map_proc_rgb(cups_map_rgb); -private cm_map_proc_cmyk(cups_map_cmyk); -private dev_proc_decode_color(cups_decode_color); -private dev_proc_encode_color(cups_encode_color); -private dev_proc_get_color_mapping_procs(cups_get_color_mapping_procs); - -static const gx_cm_color_map_procs cups_color_mapping_procs = -{ - cups_map_gray, - cups_map_rgb, - cups_map_cmyk -}; -#else -private dev_proc_map_cmyk_color(cups_map_cmyk_color); -private dev_proc_map_color_rgb(cups_map_color_rgb); -private dev_proc_map_rgb_color(cups_map_rgb_color); -#endif /* dev_t_proc_encode_color */ - - -/* - * The device descriptors... - */ - -typedef struct gx_device_cups_s -{ - gx_device_common; /* Standard GhostScript device stuff */ - gx_prn_device_common; /* Standard printer device stuff */ - int page; /* Page number */ - cups_raster_t *stream; /* Raster stream */ - cups_page_header_t header; /* PostScript page device info */ - int landscape; /* Non-zero if this is landscape */ -} gx_device_cups; - -private gx_device_procs cups_procs = -{ - cups_open, - cups_get_matrix, - cups_sync_output, - gdev_prn_output_page, - cups_close, -#ifdef dev_t_proc_encode_color - NULL, /* map_rgb_color */ - NULL, /* map_color_rgb */ -#else - cups_map_rgb_color, - cups_map_color_rgb, -#endif /* dev_t_proc_encode_color */ - NULL, /* fill_rectangle */ - NULL, /* tile_rectangle */ - NULL, /* copy_mono */ - NULL, /* copy_color */ - NULL, /* draw_line */ - gx_default_get_bits, - cups_get_params, - cups_put_params, -#ifdef dev_t_proc_encode_color - NULL, /* map_cmyk_color */ -#else - cups_map_cmyk_color, -#endif /* dev_t_proc_encode_color */ - NULL, /* get_xfont_procs */ - NULL, /* get_xfont_device */ - NULL, /* map_rgb_alpha_color */ - gx_page_device_get_page_device, - NULL, /* get_alpha_bits */ - NULL, /* copy_alpha */ - NULL, /* get_band */ - NULL, /* copy_rop */ - NULL, /* fill_path */ - NULL, /* stroke_path */ - NULL, /* fill_mask */ - NULL, /* fill_trapezoid */ - NULL, /* fill_parallelogram */ - NULL, /* fill_triangle */ - NULL, /* draw_thin_line */ - NULL, /* begin_image */ - NULL, /* image_data */ - NULL, /* end_image */ - NULL, /* strip_tile_rectangle */ - NULL /* strip_copy_rop */ -#ifdef dev_t_proc_encode_color - , - NULL, /* get_clipping_box */ - NULL, /* begin_typed_image */ - NULL, /* get_bits_rectangle */ - NULL, /* map_color_rgb_alpha */ - NULL, /* create_compositor */ - NULL, /* get_hardware_params */ - NULL, /* text_begin */ - NULL, /* finish_copydevice */ - NULL, /* begin_transparency_group */ - NULL, /* end_transparency_group */ - NULL, /* begin_transparency_mask */ - NULL, /* end_transparency_mask */ - NULL, /* discard_transparency_layer */ - cups_get_color_mapping_procs, - NULL, /* get_color_comp_index */ - cups_encode_color, - cups_decode_color -#endif /* dev_t_proc_encode_color */ -}; - -#define prn_device_body_copies(dtype, procs, dname, w10, h10, xdpi, ydpi, lo, to, lm, bm, rm, tm, ncomp, depth, mg, mc, dg, dc, print_pages)\ - std_device_full_body_type(dtype, &procs, dname, &st_device_printer,\ - (int)((long)(w10) * (xdpi) / 10),\ - (int)((long)(h10) * (ydpi) / 10),\ - xdpi, ydpi,\ - ncomp, depth, mg, mc, dg, dc,\ - -(lo) * (xdpi), -(to) * (ydpi),\ - (lm) * 72.0, (bm) * 72.0,\ - (rm) * 72.0, (tm) * 72.0\ - ),\ - prn_device_body_copies_rest_(print_pages) - -gx_device_cups gs_cups_device = -{ - prn_device_body_copies(gx_device_cups,/* type */ - cups_procs, /* procedures */ - "cups", /* device name */ - 85, /* initial width */ - 110, /* initial height */ - 100, /* initial x resolution */ - 100, /* initial y resolution */ - 0, /* initial left offset */ - 0, /* initial top offset */ - 0, /* initial left margin */ - 0, /* initial bottom margin */ - 0, /* initial right margin */ - 0, /* initial top margin */ - 1, /* number of color components */ - 1, /* number of color bits */ - 1, /* maximum gray value */ - 0, /* maximum color value */ - 2, /* number of gray values */ - 0, /* number of color values */ - cups_print_pages), - /* print procedure */ - 0, /* page */ - NULL, /* stream */ - { /* header */ - "", /* MediaClass */ - "", /* MediaColor */ - "", /* MediaType */ - "", /* OutputType */ - 0, /* AdvanceDistance */ - CUPS_ADVANCE_NONE, /* AdvanceMedia */ - CUPS_FALSE, /* Collate */ - CUPS_CUT_NONE, /* CutMedia */ - CUPS_FALSE, /* Duplex */ - { 100, 100 }, /* HWResolution */ - { 0, 0, 612, 792 }, /* ImagingBoundingBox */ - CUPS_FALSE, /* InsertSheet */ - CUPS_JOG_NONE, /* Jog */ - CUPS_EDGE_TOP, /* LeadingEdge */ - { 0, 0 }, /* Margins */ - CUPS_FALSE, /* ManualFeed */ - 0, /* MediaPosition */ - 0, /* MediaWeight */ - CUPS_FALSE, /* MirrorPrint */ - CUPS_FALSE, /* NegativePrint */ - 1, /* NumCopies */ - CUPS_ORIENT_0, /* Orientation */ - CUPS_FALSE, /* OutputFaceUp */ - { 612, 792 }, /* PageSize */ - CUPS_FALSE, /* Separations */ - CUPS_FALSE, /* TraySwitch */ - CUPS_FALSE, /* Tumble */ - 850, /* cupsWidth */ - 1100, /* cupsHeight */ - 0, /* cupsMediaType */ - 1, /* cupsBitsPerColor */ - 1, /* cupsBitsPerPixel */ - 107, /* cupsBytesPerLine */ - CUPS_ORDER_CHUNKED, /* cupsColorOrder */ - CUPS_CSPACE_K, /* cupsColorSpace */ - 0, /* cupsCompression */ - 0, /* cupsRowCount */ - 0, /* cupsRowFeed */ - 0 /* cupsRowStep */ - } -}; - -/* - * Globals... - */ - -static gx_color_value cupsDecodeLUT[256]; - /* Output color to RGB value LUT */ -static unsigned char cupsEncodeLUT[gx_max_color_value + 1]; - /* RGB value to output color LUT */ - -static ppd_file_t *cupsPPD = 0; /* PPD file for this device */ -static char *cupsProfile = NULL; - /* Current simple color profile string */ -static int cupsHaveProfile = 0; - /* Has a color profile been defined? */ -static int cupsMatrix[3][3][CUPS_MAX_VALUE + 1]; - /* Color transform matrix LUT */ -static int cupsDensity[CUPS_MAX_VALUE + 1]; - /* Density LUT */ -static unsigned char cupsRevLower1[16] = - { /* Lower 1-bit reversal table */ - 0x00, 0x08, 0x04, 0x0c, 0x02, 0x0a, 0x06, 0x0e, - 0x01, 0x09, 0x05, 0x0d, 0x03, 0x0b, 0x07, 0x0f - }, - cupsRevUpper1[16] = - { /* Upper 1-bit reversal table */ - 0x00, 0x80, 0x40, 0xc0, 0x20, 0xa0, 0x60, 0xe0, - 0x10, 0x90, 0x50, 0xd0, 0x30, 0xb0, 0x70, 0xf0 - }, - cupsRevLower2[16] = - { /* Lower 2-bit reversal table */ - 0x00, 0x04, 0x08, 0x0c, 0x01, 0x05, 0x09, 0x0d, - 0x02, 0x06, 0x0a, 0x0e, 0x03, 0x07, 0x0b, 0x0f - }, - cupsRevUpper2[16] = - { /* Upper 2-bit reversal table */ - 0x00, 0x40, 0x80, 0xc0, 0x10, 0x50, 0x90, 0xd0, - 0x20, 0x60, 0xa0, 0xe0, 0x30, 0x70, 0xb0, 0xf0 - }; - - -/* - * Local functions... - */ - -static double cups_map_cielab(double, double); -static void cups_print_chunked(gx_device_printer *, unsigned char *, - unsigned char *, int); -static void cups_print_banded(gx_device_printer *, unsigned char *, - unsigned char *, int); -static void cups_print_planar(gx_device_printer *, unsigned char *, - unsigned char *, int); - -/*static void cups_set_margins(gx_device *);*/ - - -/* - * 'cups_close()' - Close the output file. - */ - -private int -cups_close(gx_device *pdev) /* I - Device info */ -{ -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_close(%p)\n", pdev); -#endif /* DEBUG */ - - if (cups->stream != NULL) - { - cupsRasterClose(cups->stream); - cups->stream = NULL; - } - -#if 0 /* Can't do this here because put_params() might close the device */ - if (cupsPPD != NULL) - { - ppdClose(cupsPPD); - cupsPPD = NULL; - } - - if (cupsProfile != NULL) - { - free(cupsProfile); - cupsProfile = NULL; - } -#endif /* 0 */ - - return (gdev_prn_close(pdev)); -} - - -#ifdef dev_t_proc_encode_color -/* - * 'cups_decode_color()' - Decode a color value. - */ - -private int /* O - Status (0 = OK) */ -cups_decode_color(gx_device *pdev, /* I - Device info */ - gx_color_index ci, /* I - Color index */ - gx_color_value *cv) /* O - Colors */ -{ - int i; /* Looping var */ - int shift; /* Bits to shift */ - int mask; /* Bits to mask */ - - - if (cups->header.cupsColorSpace == CUPS_CSPACE_KCMYcm && - cups->header.cupsBitsPerColor == 1) - { - /* - * KCMYcm data is represented internally by Ghostscript as CMYK... - */ - - cv[0] = (ci & 0x20) ? frac_1 : frac_0; - cv[1] = (ci & 0x12) ? frac_1 : frac_0; - cv[2] = (ci & 0x09) ? frac_1 : frac_0; - cv[3] = (ci & 0x04) ? frac_1 : frac_0; - } - else - { - shift = cups->header.cupsBitsPerColor; - mask = (1 << shift) - 1; - - for (i = cups->color_info.num_components - 1; i > 0; i --, ci >>= shift) - cv[i] = cupsDecodeLUT[ci & mask]; - - cv[0] = cupsDecodeLUT[ci & mask]; - } - - return (0); -} - - -/* - * 'cups_encode_color()' - Encode a color value. - */ - -private gx_color_index /* O - Color index */ -cups_encode_color(gx_device *pdev, - /* I - Device info */ - const gx_color_value *cv) - /* I - Colors */ -{ - int i; /* Looping var */ - gx_color_index ci; /* Color index */ - int shift; /* Bits to shift */ - - - /* - * Encode the color index... - */ - - shift = cups->header.cupsBitsPerColor; - - for (ci = cupsEncodeLUT[cv[0]], i = 1; - i < cups->color_info.num_components; - i ++) - ci = (ci << shift) | cupsEncodeLUT[cv[i]]; - - /* - * Handle 6-color output... - */ - - if (cups->header.cupsColorSpace == CUPS_CSPACE_KCMYcm && - cups->header.cupsBitsPerColor == 1) - { - /* - * Welcome to hackville, where we map CMYK data to the - * light inks in draft mode... Map blue to light magenta and - * cyan and green to light cyan and yellow... - */ - - ci <<= 2; /* Leave room for light inks */ - - if (ci == 0x18) /* Blue */ - ci = 0x11; /* == cyan + light magenta */ - else if (ci == 0x14) /* Green */ - ci = 0x06; /* == light cyan + yellow */ - } - - /* - * Range check the return value... - */ - - if (ci == gx_no_color_index) - ci --; - - /* - * Return the color index... - */ - - return (ci); -} - - -/* - * 'cups_get_color_mapping_procs()' - Get the list of color mapping procedures. - */ - -private const gx_cm_color_map_procs * /* O - List of device procedures */ -cups_get_color_mapping_procs(const gx_device *pdev) - /* I - Device info */ -{ - return (&cups_color_mapping_procs); -} -#endif /* dev_t_proc_encode_color */ - - -/* - * 'cups_get_matrix()' - Generate the default page matrix. - */ - -private void -cups_get_matrix(gx_device *pdev, /* I - Device info */ - gs_matrix *pmat) /* O - Physical transform matrix */ -{ -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_get_matrix(%p, %p)\n", pdev, pmat); -#endif /* DEBUG */ - - /* - * Set the raster width and height... - */ - - cups->header.cupsWidth = cups->width; - cups->header.cupsHeight = cups->height; - - /* - * Set the transform matrix... - */ - - fprintf(stderr, "DEBUG: cups->header.Duplex = %d\n", cups->header.Duplex); - fprintf(stderr, "DEBUG: cups->page = %d\n", cups->page); - - if (cupsPPD) - { - fprintf(stderr, "DEBUG: cupsPPD = %p\n", cupsPPD); - fprintf(stderr, "DEBUG: cupsPPD->flip_duplex = %d\n", cupsPPD->flip_duplex); - } - - if (cups->landscape) - { - /* - * Do landscape orientation... - */ - - if (cups->header.Duplex && !cups->header.Tumble && - cupsPPD && cupsPPD->flip_duplex && !(cups->page & 1)) - { - pmat->xx = 0.0; - pmat->xy = (float)cups->header.HWResolution[0] / 72.0; - pmat->yx = -(float)cups->header.HWResolution[1] / 72.0; - pmat->yy = 0.0; - pmat->tx = -(float)cups->header.HWResolution[0] * pdev->HWMargins[2] / 72.0; - pmat->ty = (float)cups->header.HWResolution[1] * - ((float)cups->header.PageSize[0] - pdev->HWMargins[3]) / 72.0; - } - else - { - pmat->xx = 0.0; - pmat->xy = (float)cups->header.HWResolution[0] / 72.0; - pmat->yx = (float)cups->header.HWResolution[1] / 72.0; - pmat->yy = 0.0; - pmat->tx = -(float)cups->header.HWResolution[0] * pdev->HWMargins[0] / 72.0; - pmat->ty = -(float)cups->header.HWResolution[1] * pdev->HWMargins[1] / 72.0; - } - } - else if (cups->header.Duplex && !cups->header.Tumble && - cupsPPD && cupsPPD->flip_duplex && !(cups->page & 1)) - { - pmat->xx = (float)cups->header.HWResolution[0] / 72.0; - pmat->xy = 0.0; - pmat->yx = 0.0; - pmat->yy = (float)cups->header.HWResolution[1] / 72.0; - pmat->tx = -(float)cups->header.HWResolution[0] * pdev->HWMargins[2] / 72.0; - pmat->ty = -(float)cups->header.HWResolution[1] * pdev->HWMargins[3] / 72.0; - } - else - { - pmat->xx = (float)cups->header.HWResolution[0] / 72.0; - pmat->xy = 0.0; - pmat->yx = 0.0; - pmat->yy = -(float)cups->header.HWResolution[1] / 72.0; - pmat->tx = -(float)cups->header.HWResolution[0] * pdev->HWMargins[0] / 72.0; - pmat->ty = (float)cups->header.HWResolution[1] * - ((float)cups->header.PageSize[1] - pdev->HWMargins[3]) / 72.0; - } - - fprintf(stderr, "DEBUG: width = %d, height = %d\n", cups->width, - cups->height); - fprintf(stderr, "DEBUG: PageSize = [ %d %d ], HWResolution = [ %d %d ]\n", - cups->header.PageSize[0], cups->header.PageSize[1], - cups->header.HWResolution[0], cups->header.HWResolution[1]); - fprintf(stderr, "DEBUG: HWMargins = [ %.3f %.3f %.3f %.3f ]\n", - pdev->HWMargins[0], pdev->HWMargins[1], pdev->HWMargins[2], - pdev->HWMargins[3]); - fprintf(stderr, "DEBUG: matrix = [ %.3f %.3f %.3f %.3f %.3f %.3f ]\n", - pmat->xx, pmat->xy, pmat->yx, pmat->yy, pmat->tx, pmat->ty); -} - - -/* - * 'cups_get_params()' - Get pagedevice parameters. - */ - -private int /* O - Error status */ -cups_get_params(gx_device *pdev, /* I - Device info */ - gs_param_list *plist) /* I - Parameter list */ -{ -#ifdef CUPS_RASTER_SYNCv1 - int i; /* Looping var */ - char name[255]; /* Attribute name */ -#endif /* CUPS_RASTER_SYNCv1 */ - int code; /* Return code */ - gs_param_string s; /* Temporary string value */ - bool b; /* Temporary boolean value */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_get_params(%p, %p)\n", pdev, plist); -#endif /* DEBUG */ - - /* - * First process the "standard" page device parameters... - */ - -#ifdef DEBUG - fputs("DEBUG2: before gdev_prn_get_params()\n", stderr); -#endif /* DEBUG */ - - if ((code = gdev_prn_get_params(pdev, plist)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: after gdev_prn_get_params()\n", stderr); -#endif /* DEBUG */ - - /* - * Then write the CUPS parameters... - */ - -#ifdef DEBUG - fputs("DEBUG2: Adding MediaClass\n", stderr); -#endif /* DEBUG */ - - param_string_from_string(s, cups->header.MediaClass); - if ((code = param_write_string(plist, "MediaClass", &s)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding AdvanceDistance\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "AdvanceDistance", - (int *)&(cups->header.AdvanceDistance))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding AdvanceDistance\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "AdvanceMedia", - (int *)&(cups->header.AdvanceMedia))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding Collate\n", stderr); -#endif /* DEBUG */ - - b = cups->header.Collate; - if ((code = param_write_bool(plist, "Collate", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding CutMedia\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "CutMedia", - (int *)&(cups->header.CutMedia))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding InsertSheet\n", stderr); -#endif /* DEBUG */ - - b = cups->header.InsertSheet; - if ((code = param_write_bool(plist, "InsertSheet", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding Jog\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "Jog", - (int *)&(cups->header.Jog))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding LeadingEdge\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "LeadingEdge", - (int *)&(cups->header.LeadingEdge))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding ManualFeed\n", stderr); -#endif /* DEBUG */ - - b = cups->header.ManualFeed; - if ((code = param_write_bool(plist, "ManualFeed", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding MediaPosition\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "MediaPosition", - (int *)&(cups->header.MediaPosition))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding MirrorPrint\n", stderr); -#endif /* DEBUG */ - - b = cups->header.MirrorPrint; - if ((code = param_write_bool(plist, "MirrorPrint", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding NegativePrint\n", stderr); -#endif /* DEBUG */ - - b = cups->header.NegativePrint; - if ((code = param_write_bool(plist, "NegativePrint", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding OutputFaceUp\n", stderr); -#endif /* DEBUG */ - - b = cups->header.OutputFaceUp; - if ((code = param_write_bool(plist, "OutputFaceUp", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding Separations\n", stderr); -#endif /* DEBUG */ - - b = cups->header.Separations; - if ((code = param_write_bool(plist, "Separations", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding TraySwitch\n", stderr); -#endif /* DEBUG */ - - b = cups->header.TraySwitch; - if ((code = param_write_bool(plist, "TraySwitch", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding Tumble\n", stderr); -#endif /* DEBUG */ - - b = cups->header.Tumble; - if ((code = param_write_bool(plist, "Tumble", &b)) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsWidth\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsWidth", - (int *)&(cups->header.cupsWidth))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsHeight\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsHeight", - (int *)&(cups->header.cupsHeight))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsMediaType\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsMediaType", - (int *)&(cups->header.cupsMediaType))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsBitsPerColor\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsBitsPerColor", - (int *)&(cups->header.cupsBitsPerColor))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsBitsPerPixel\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsBitsPerPixel", - (int *)&(cups->header.cupsBitsPerPixel))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsBytesPerLine\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsBytesPerLine", - (int *)&(cups->header.cupsBytesPerLine))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsColorOrder\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsColorOrder", - (int *)&(cups->header.cupsColorOrder))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsColorSpace\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsColorSpace", - (int *)&(cups->header.cupsColorSpace))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsCompression\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsCompression", - (int *)&(cups->header.cupsCompression))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsRowCount\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsRowCount", - (int *)&(cups->header.cupsRowCount))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsRowFeed\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsRowFeed", - (int *)&(cups->header.cupsRowFeed))) < 0) - return (code); - -#ifdef DEBUG - fputs("DEBUG2: Adding cupsRowStep\n", stderr); -#endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsRowStep", - (int *)&(cups->header.cupsRowStep))) < 0) - return (code); - -#ifdef CUPS_RASTER_SYNCv1 -# ifdef DEBUG - fputs("DEBUG2: Adding cupsNumColors\n", stderr); -# endif /* DEBUG */ - - if ((code = param_write_int(plist, "cupsNumColors", - (int *)&(cups->header.cupsNumColors))) < 0) - return (code); - -# ifdef DEBUG - fputs("DEBUG2: Adding cupsInteger\n", stderr); -# endif /* DEBUG */ - - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsInteger%d", i); - if ((code = param_write_int(plist, name, - (int *)(cups->header.cupsInteger + i))) < 0) - return (code); - } - -# ifdef DEBUG - fputs("DEBUG2: Adding cupsReal\n", stderr); -# endif /* DEBUG */ - - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsReal%d", i); - if ((code = param_write_float(plist, name, - cups->header.cupsReal + i)) < 0) - return (code); - } - -# ifdef DEBUG - fputs("DEBUG2: Adding cupsString\n", stderr); -# endif /* DEBUG */ - - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsReal%d", i); - param_string_from_string(s, cups->header.cupsString[i]); - if ((code = param_write_string(plist, name, &s)) < 0) - return (code); - } - -# ifdef DEBUG - fputs("DEBUG2: Adding cupsMarkerType\n", stderr); -# endif /* DEBUG */ - - param_string_from_string(s, cups->header.cupsMarkerType); - if ((code = param_write_string(plist, "cupsMarkerType", &s)) < 0) - return (code); - -# ifdef DEBUG - fputs("DEBUG2: Adding cupsRenderingIntent\n", stderr); -# endif /* DEBUG */ - - param_string_from_string(s, cups->header.cupsRenderingIntent); - if ((code = param_write_string(plist, "cupsRenderingIntent", &s)) < 0) - return (code); -#endif /* CUPS_RASTER_SYNCv1 */ - -#ifdef DEBUG - fputs("DEBUG2: Leaving cups_get_params()\n", stderr); -#endif /* DEBUG */ - - return (0); -} - - -/* - * 'cups_get_space_params()' - Get space parameters from the RIP_CACHE env var. - */ - -void -cups_get_space_params(const gx_device_printer *pdev, - /* I - Printer device */ - gdev_prn_space_params *space_params) - /* O - Space parameters */ -{ - float cache_size; /* Size of tile cache in bytes */ - char *cache_env, /* Cache size environment variable */ - cache_units[255]; /* Cache size units */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_get_space_params(%p, %p)\n", pdev, space_params); -#endif /* DEBUG */ - - if ((cache_env = getenv("RIP_MAX_CACHE")) != NULL) - { - switch (sscanf(cache_env, "%f%254s", &cache_size, cache_units)) - { - case 0 : - cache_size = 8 * 1024 * 1024; - break; - case 1 : - cache_size *= 4 * CUPS_TILE_SIZE * CUPS_TILE_SIZE; - break; - case 2 : - if (tolower(cache_units[0]) == 'g') - cache_size *= 1024 * 1024 * 1024; - else if (tolower(cache_units[0]) == 'm') - cache_size *= 1024 * 1024; - else if (tolower(cache_units[0]) == 'k') - cache_size *= 1024; - else if (tolower(cache_units[0]) == 't') - cache_size *= 4 * CUPS_TILE_SIZE * CUPS_TILE_SIZE; - break; - } - } - else - cache_size = 8 * 1024 * 1024; - - fprintf(stderr, "DEBUG: cache_size = %.0f\n", cache_size); - - space_params->MaxBitmap = (int)cache_size; - space_params->BufferSpace = (int)cache_size / 10; -} - - -/* - * 'cups_map_cielab()' - Map CIE Lab transformation... - */ - -static double /* O - Adjusted color value */ -cups_map_cielab(double x, /* I - Raw color value */ - double xn) /* I - Whitepoint color value */ -{ - double x_xn; /* Fraction of whitepoint */ - - - x_xn = x / xn; - - if (x_xn > 0.008856) - return (cbrt(x_xn)); - else - return (7.787 * x_xn + 16.0 / 116.0); -} - - -#ifdef dev_t_proc_encode_color -/* - * 'cups_map_cmyk()' - Map a CMYK color value to device colors. - */ - -private void -cups_map_cmyk(gx_device *pdev, /* I - Device info */ - frac c, /* I - Cyan value */ - frac m, /* I - Magenta value */ - frac y, /* I - Yellow value */ - frac k, /* I - Black value */ - frac *out) /* O - Device colors */ -{ - int c0, c1, c2; /* Temporary color values */ - float rr, rg, rb, /* Real RGB colors */ - ciex, ciey, ciez, /* CIE XYZ colors */ - ciey_yn, /* Normalized luminance */ - ciel, ciea, cieb; /* CIE Lab colors */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_cmyk(%p, %d, %d, %d, %d, %p)\n", - pdev, c, m, y, k, out); -#endif /* DEBUG */ - - /* - * Convert the CMYK color to the destination colorspace... - */ - - switch (cups->header.cupsColorSpace) - { - case CUPS_CSPACE_W : - c0 = frac_1 - (c * 31 + m * 61 + y * 8) / 100 - k; - - if (c0 < 0) - out[0] = 0; - else if (c0 > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c0]; - break; - - case CUPS_CSPACE_RGBA : - out[3] = frac_1; - - case CUPS_CSPACE_RGB : - c0 = frac_1 - c - k; - c1 = frac_1 - m - k; - c2 = frac_1 - y - k; - - if (c0 < 0) - out[0] = 0; - else if (c0 > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c0]; - - if (c1 < 0) - out[1] = 0; - else if (c1 > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[c1]; - - if (c2 < 0) - out[2] = 0; - else if (c2 > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[c2]; - break; - - default : - case CUPS_CSPACE_K : - c0 = (c * 31 + m * 61 + y * 8) / 100 + k; - - if (c0 < 0) - out[0] = 0; - else if (c0 > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c0]; - break; - - case CUPS_CSPACE_CMY : - c0 = c + k; - c1 = m + k; - c2 = y + k; - - if (c0 < 0) - out[0] = 0; - else if (c0 > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c0]; - - if (c1 < 0) - out[1] = 0; - else if (c1 > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[c1]; - - if (c2 < 0) - out[2] = 0; - else if (c2 > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[c2]; - break; - - case CUPS_CSPACE_YMC : - c0 = y + k; - c1 = m + k; - c2 = c + k; - - if (c0 < 0) - out[0] = 0; - else if (c0 > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c0]; - - if (c1 < 0) - out[1] = 0; - else if (c1 > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[c1]; - - if (c2 < 0) - out[2] = 0; - else if (c2 > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[c2]; - break; - - case CUPS_CSPACE_CMYK : - if (c < 0) - out[0] = 0; - else if (c > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[c]; - - if (m < 0) - out[1] = 0; - else if (m > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[m]; - - if (y < 0) - out[2] = 0; - else if (y > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[y]; - - if (k < 0) - out[3] = 0; - else if (k > frac_1) - out[3] = (frac)cupsDensity[frac_1]; - else - out[3] = (frac)cupsDensity[k]; - break; - - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - if (y < 0) - out[0] = 0; - else if (y > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[y]; - - if (m < 0) - out[1] = 0; - else if (m > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[m]; - - if (c < 0) - out[2] = 0; - else if (c > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[c]; - - if (k < 0) - out[3] = 0; - else if (k > frac_1) - out[3] = (frac)cupsDensity[frac_1]; - else - out[3] = (frac)cupsDensity[k]; - break; - - case CUPS_CSPACE_KCMYcm : - case CUPS_CSPACE_KCMY : - if (k < 0) - out[0] = 0; - else if (k > frac_1) - out[0] = (frac)cupsDensity[frac_1]; - else - out[0] = (frac)cupsDensity[k]; - - if (c < 0) - out[1] = 0; - else if (c > frac_1) - out[1] = (frac)cupsDensity[frac_1]; - else - out[1] = (frac)cupsDensity[c]; - - if (m < 0) - out[2] = 0; - else if (m > frac_1) - out[2] = (frac)cupsDensity[frac_1]; - else - out[2] = (frac)cupsDensity[m]; - - if (y < 0) - out[3] = 0; - else if (y > frac_1) - out[3] = (frac)cupsDensity[frac_1]; - else - out[3] = (frac)cupsDensity[y]; - break; - -# ifdef CUPS_RASTER_HAVE_COLORIMETRIC - case CUPS_CSPACE_CIEXYZ : - case CUPS_CSPACE_CIELab : - case CUPS_CSPACE_ICC1 : - case CUPS_CSPACE_ICC2 : - case CUPS_CSPACE_ICC3 : - case CUPS_CSPACE_ICC4 : - case CUPS_CSPACE_ICC5 : - case CUPS_CSPACE_ICC6 : - case CUPS_CSPACE_ICC7 : - case CUPS_CSPACE_ICC8 : - case CUPS_CSPACE_ICC9 : - case CUPS_CSPACE_ICCA : - case CUPS_CSPACE_ICCB : - case CUPS_CSPACE_ICCC : - case CUPS_CSPACE_ICCD : - case CUPS_CSPACE_ICCE : - case CUPS_CSPACE_ICCF : - /* - * Convert CMYK to sRGB... - */ - - c0 = frac_1 - c - k; - c1 = frac_1 - m - k; - c2 = frac_1 - y - k; - - if (c0 < 0) - c0 = 0; - else if (c0 > frac_1) - c0 = frac_1; - - if (c1 < 0) - c1 = 0; - else if (c1 > frac_1) - c1 = frac_1; - - if (c2 < 0) - c2 = 0; - else if (c2 > frac_1) - c2 = frac_1; - - /* - * Convert sRGB to linear RGB... - */ - - rr = pow((double)c0 / (double)frac_1, 0.58823529412); - rg = pow((double)c1 / (double)frac_1, 0.58823529412); - rb = pow((double)c2 / (double)frac_1, 0.58823529412); - - /* - * Convert to CIE XYZ... - */ - - ciex = 0.412453 * rr + 0.357580 * rg + 0.180423 * rb; - ciey = 0.212671 * rr + 0.715160 * rg + 0.072169 * rb; - ciez = 0.019334 * rr + 0.119193 * rg + 0.950227 * rb; - - if (cups->header.cupsColorSpace == CUPS_CSPACE_CIEXYZ) - { - /* - * Convert to an integer XYZ color value... - */ - - if (ciex > 1.0) - c0 = frac_1; - else if (ciex > 0.0) - c0 = (int)(ciex * frac_1); - else - c0 = 0; - - if (ciey > 1.0) - c1 = frac_1; - else if (ciey > 0.0) - c1 = (int)(ciey * frac_1); - else - c1 = 0; - - if (ciez > 1.0) - c2 = frac_1; - else if (ciez > 0.0) - c2 = (int)(ciez * frac_1); - else - c2 = 0; - } - else - { - /* - * Convert CIE XYZ to Lab... - */ - - ciey_yn = ciey / D65_Y; - - if (ciey_yn > 0.008856) - ciel = 116 * cbrt(ciey_yn) - 16; - else - ciel = 903.3 * ciey_yn; - - ciea = 500 * (cups_map_cielab(ciex, D65_X) - - cups_map_cielab(ciey, D65_Y)); - cieb = 200 * (cups_map_cielab(ciey, D65_Y) - - cups_map_cielab(ciez, D65_Z)); - - /* - * Scale the L value and bias the a and b values by 128 - * so that all values are in the range of 0 to 255. - */ - - ciel *= 2.55; - ciea += 128; - cieb += 128; - - /* - * Convert to frac values... - */ - - if (ciel < 0.0) - c0 = 0; - else if (ciel < 255.0) - c0 = (int)(ciel * frac_1 / 255.0); - else - c0 = frac_1; - - if (ciea < 0.0) - c1 = 0; - else if (ciea < 255.0) - c1 = (int)(ciea * frac_1 / 255.0); - else - c1 = frac_1; - - if (cieb < 0.0) - c2 = 0; - else if (cieb < 255.0) - c2 = (int)(cieb * frac_1 / 255.0); - else - c2 = frac_1; - } - - /* - * Put the final color value together... - */ - - out[0] = c0; - out[1] = c1; - out[2] = c2; - break; -# endif /* CUPS_RASTER_HAVE_COLORIMETRIC */ - } - - switch (cups->color_info.num_components) - { - default : - case 1 : -#ifdef DEBUG - fprintf(stderr, "DEBUG2: \\=== COLOR %d\n", out[0]); -#endif /* DEBUG */ - break; - - case 3 : -#ifdef DEBUG - fprintf(stderr, "DEBUG2: \\=== COLOR %d, %d, %d\n", - out[0], out[1], out[2]); -#endif /* DEBUG */ - break; - - case 4 : -#ifdef DEBUG - fprintf(stderr, "DEBUG2: \\=== COLOR %d, %d, %d, %d\n", - out[0], out[1], out[2], out[3]); -#endif /* DEBUG */ - break; - } -} - - -/* - * 'cups_map_gray()' - Map a grayscale value to device colors. - */ - -private void -cups_map_gray(gx_device *pdev, /* I - Device info */ - frac g, /* I - Grayscale value */ - frac *out) /* O - Device colors */ -{ -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_gray(%p, %d, %p)\n", - pdev, g, out); -#endif /* DEBUG */ - - /* - * Just use the CMYK mapper... - */ - - cups_map_cmyk(pdev, 0, 0, 0, frac_1 - g, out); -} - - -/* - * 'cups_map_rgb()' - Map a RGB color value to device colors. - */ - -private void -cups_map_rgb(gx_device *pdev, - /* I - Device info */ - const gs_imager_state *pis,/* I - Device state */ - frac r, /* I - Red value */ - frac g, /* I - Green value */ - frac b, /* I - Blue value */ - frac *out)/* O - Device colors */ -{ - frac c, m, y, k; /* CMYK values */ - frac mk; /* Maximum K value */ - int tc, tm, ty; /* Temporary color values */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_rgb(%p, %p, %d, %d, %d, %p)\n", - pdev, pis, r, g, b, out); -#endif /* DEBUG */ - - /* - * Compute CMYK values... - */ - - c = frac_1 - r; - m = frac_1 - g; - y = frac_1 - b; - k = min(c, min(m, y)); - - if ((mk = max(c, max(m, y))) > k) - k = (int)((float)k * (float)k * (float)k / ((float)mk * (float)mk)); - - c -= k; - m -= k; - y -= k; - - /* - * Do color correction as needed... - */ - - if (cupsHaveProfile) - { - /* - * Color correct CMY... - */ - - tc = cupsMatrix[0][0][c] + - cupsMatrix[0][1][m] + - cupsMatrix[0][2][y]; - tm = cupsMatrix[1][0][c] + - cupsMatrix[1][1][m] + - cupsMatrix[1][2][y]; - ty = cupsMatrix[2][0][c] + - cupsMatrix[2][1][m] + - cupsMatrix[2][2][y]; - - if (tc < 0) - c = 0; - else if (tc > frac_1) - c = frac_1; - else - c = (frac)tc; - - if (tm < 0) - m = 0; - else if (tm > frac_1) - m = frac_1; - else - m = (frac)tm; - - if (ty < 0) - y = 0; - else if (ty > frac_1) - y = frac_1; - else - y = (frac)ty; - } - - /* - * Use the CMYK mapping function to produce the device colors... - */ - - cups_map_cmyk(pdev, c, m, y, k, out); -} -#else -/* - * 'cups_map_cmyk_color()' - Map a CMYK color to a color index. - * - * This function is only called when a 4 or 6 color colorspace is - * selected for output. CMYK colors are *not* corrected but *are* - * density adjusted. - */ - -private gx_color_index /* O - Color index */ -cups_map_cmyk_color(gx_device *pdev, - /* I - Device info */ - gx_color_value c, /* I - Cyan value */ - gx_color_value m, /* I - Magenta value */ - gx_color_value y, /* I - Yellow value */ - gx_color_value k) /* I - Black value */ -{ - gx_color_index i; /* Temporary index */ - gx_color_value ic, im, iy, ik; /* Integral CMYK values */ - - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_cmyk_color(%p, %d, %d, %d, %d)\n", pdev, - c, m, y, k); -# endif /* DEBUG */ - - /* - * Setup the color info data as needed... - */ - - if (pdev->color_info.num_components == 0) - cups_set_color_info(pdev); - - /* - * Density correct... - */ - - if (cupsHaveProfile) - { - c = cupsDensity[c]; - m = cupsDensity[m]; - y = cupsDensity[y]; - k = cupsDensity[k]; - } - - ic = cupsEncodeLUT[c]; - im = cupsEncodeLUT[m]; - iy = cupsEncodeLUT[y]; - ik = cupsEncodeLUT[k]; - - /* - * Convert the CMYK color to a color index... - */ - - switch (cups->header.cupsColorSpace) - { - default : - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((ic << 1) | im) << 1) | iy) << 1) | ik; - break; - case 2 : - i = (((((ic << 2) | im) << 2) | iy) << 2) | ik; - break; - case 4 : - i = (((((ic << 4) | im) << 4) | iy) << 4) | ik; - break; - case 8 : - i = (((((ic << 8) | im) << 8) | iy) << 8) | ik; - break; - } - break; - - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((iy << 1) | im) << 1) | ic) << 1) | ik; - break; - case 2 : - i = (((((iy << 2) | im) << 2) | ic) << 2) | ik; - break; - case 4 : - i = (((((iy << 4) | im) << 4) | ic) << 4) | ik; - break; - case 8 : - i = (((((iy << 8) | im) << 8) | ic) << 8) | ik; - break; - } - break; - - case CUPS_CSPACE_KCMYcm : - if (cups->header.cupsBitsPerColor == 1) - { - if (ik) - i = 32; - else - i = 0; - - if (ic && im) - i |= 17; - else if (ic && iy) - i |= 6; - else if (im && iy) - i |= 12; - else if (ic) - i |= 16; - else if (im) - i |= 8; - else if (iy) - i |= 4; - break; - } - - case CUPS_CSPACE_KCMY : - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((ik << 1) | ic) << 1) | im) << 1) | iy; - break; - case 2 : - i = (((((ik << 2) | ic) << 2) | im) << 2) | iy; - break; - case 4 : - i = (((((ik << 4) | ic) << 4) | im) << 4) | iy; - break; - case 8 : - i = (((((ik << 8) | ic) << 8) | im) << 8) | iy; - break; - } - break; - } - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: CMYK (%d,%d,%d,%d) -> CMYK %08x (%d,%d,%d,%d)\n", - c, m, y, k, (unsigned)i, ic, im, iy, ik); -# endif /* DEBUG */ - - /* - * Make sure we don't get a CMYK color of 255, 255, 255, 255... - */ - - if (i == gx_no_color_index) - i --; - - return (i); -} - - -/* - * 'cups_map_color_rgb()' - Map a color index to an RGB color. - */ - -private int -cups_map_color_rgb(gx_device *pdev,/* I - Device info */ - gx_color_index color,/* I - Color index */ - gx_color_value prgb[3]) - /* O - RGB values */ -{ - unsigned char c0, c1, c2, c3; /* Color index components */ - gx_color_value k, divk; /* Black & divisor */ - - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_color_rgb(%p, %d, %p)\n", pdev, - (unsigned)color, prgb); -# endif /* DEBUG */ - - /* - * Setup the color info data as needed... - */ - - if (pdev->color_info.num_components == 0) - cups_set_color_info(pdev); - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: COLOR %08x = ", (unsigned)color); -# endif /* DEBUG */ - - /* - * Extract the color components from the color index... - */ - - switch (cups->header.cupsBitsPerColor) - { - default : - c3 = color & 1; - color >>= 1; - c2 = color & 1; - color >>= 1; - c1 = color & 1; - color >>= 1; - c0 = color; - break; - case 2 : - c3 = color & 3; - color >>= 2; - c2 = color & 3; - color >>= 2; - c1 = color & 3; - color >>= 2; - c0 = color; - break; - case 4 : - c3 = color & 15; - color >>= 4; - c2 = color & 15; - color >>= 4; - c1 = color & 15; - color >>= 4; - c0 = color; - break; - case 8 : - c3 = color & 255; - color >>= 8; - c2 = color & 255; - color >>= 8; - c1 = color & 255; - color >>= 8; - c0 = color; - break; - } - - /* - * Convert the color components to RGB... - */ - - switch (cups->header.cupsColorSpace) - { - case CUPS_CSPACE_K : - case CUPS_CSPACE_WHITE : - case CUPS_CSPACE_GOLD : - case CUPS_CSPACE_SILVER : - prgb[0] = - prgb[1] = - prgb[2] = cupsDecodeLUT[c3]; - break; - - case CUPS_CSPACE_W : - prgb[0] = - prgb[1] = - prgb[2] = cupsDecodeLUT[c3]; - break; - - case CUPS_CSPACE_RGB : - prgb[0] = cupsDecodeLUT[c1]; - prgb[1] = cupsDecodeLUT[c2]; - prgb[2] = cupsDecodeLUT[c3]; - break; - - case CUPS_CSPACE_RGBA : - prgb[0] = cupsDecodeLUT[c0]; - prgb[1] = cupsDecodeLUT[c1]; - prgb[2] = cupsDecodeLUT[c2]; - break; - - case CUPS_CSPACE_CMY : - prgb[0] = cupsDecodeLUT[c1]; - prgb[1] = cupsDecodeLUT[c2]; - prgb[2] = cupsDecodeLUT[c3]; - break; - - case CUPS_CSPACE_YMC : - prgb[0] = cupsDecodeLUT[c3]; - prgb[1] = cupsDecodeLUT[c2]; - prgb[2] = cupsDecodeLUT[c1]; - break; - - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - k = cupsDecodeLUT[c0]; - divk = gx_max_color_value - k; - if (divk == 0) - { - prgb[0] = 0; - prgb[1] = 0; - prgb[2] = 0; - } - else - { - prgb[0] = gx_max_color_value + divk - - gx_max_color_value * c1 / divk; - prgb[1] = gx_max_color_value + divk - - gx_max_color_value * c2 / divk; - prgb[2] = gx_max_color_value + divk - - gx_max_color_value * c3 / divk; - } - break; - - case CUPS_CSPACE_CMYK : - k = cupsDecodeLUT[c3]; - divk = gx_max_color_value - k; - if (divk == 0) - { - prgb[0] = 0; - prgb[1] = 0; - prgb[2] = 0; - } - else - { - prgb[0] = gx_max_color_value + divk - - gx_max_color_value * c0 / divk; - prgb[1] = gx_max_color_value + divk - - gx_max_color_value * c1 / divk; - prgb[2] = gx_max_color_value + divk - - gx_max_color_value * c2 / divk; - } - break; - - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - k = cupsDecodeLUT[c3]; - divk = gx_max_color_value - k; - if (divk == 0) - { - prgb[0] = 0; - prgb[1] = 0; - prgb[2] = 0; - } - else - { - prgb[0] = gx_max_color_value + divk - - gx_max_color_value * c2 / divk; - prgb[1] = gx_max_color_value + divk - - gx_max_color_value * c1 / divk; - prgb[2] = gx_max_color_value + divk - - gx_max_color_value * c0 / divk; - } - break; - -# ifdef CUPS_RASTER_HAVE_COLORIMETRIC - case CUPS_CSPACE_CIEXYZ : - case CUPS_CSPACE_CIELab : - case CUPS_CSPACE_ICC1 : - case CUPS_CSPACE_ICC2 : - case CUPS_CSPACE_ICC3 : - case CUPS_CSPACE_ICC4 : - case CUPS_CSPACE_ICC5 : - case CUPS_CSPACE_ICC6 : - case CUPS_CSPACE_ICC7 : - case CUPS_CSPACE_ICC8 : - case CUPS_CSPACE_ICC9 : - case CUPS_CSPACE_ICCA : - case CUPS_CSPACE_ICCB : - case CUPS_CSPACE_ICCC : - case CUPS_CSPACE_ICCD : - case CUPS_CSPACE_ICCE : - case CUPS_CSPACE_ICCF : - break; -# endif /* CUPS_RASTER_HAVE_COLORIMETRIC */ - } - -# ifdef DEBUG - fprintf(stderr, "%d,%d,%d\n", prgb[0], prgb[1], prgb[2]); -# endif /* DEBUG */ - - return (0); -} - - -/* - * 'cups_map_rgb_color()' - Map an RGB color to a color index. We map the - * RGB color to the output colorspace & bits (we - * figure out the format when we output a page). - */ - -private gx_color_index /* O - Color index */ -cups_map_rgb_color(gx_device *pdev,/* I - Device info */ - gx_color_value r, /* I - Red value */ - gx_color_value g, /* I - Green value */ - gx_color_value b) /* I - Blue value */ -{ - gx_color_index i; /* Temporary index */ - gx_color_value ic, im, iy, ik; /* Integral CMYK values */ - gx_color_value mk; /* Maximum K value */ - int tc, tm, ty; /* Temporary color values */ - float rr, rg, rb, /* Real RGB colors */ - ciex, ciey, ciez, - /* CIE XYZ colors */ - ciey_yn, /* Normalized luminance */ - ciel, ciea, cieb; - /* CIE Lab colors */ - - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_map_rgb_color(%p, %d, %d, %d)\n", pdev, r, g, b); -# endif /* DEBUG */ - - /* - * Setup the color info data as needed... - */ - - if (pdev->color_info.num_components == 0) - cups_set_color_info(pdev); - - /* - * Do color correction as needed... - */ - - if (cupsHaveProfile) - { - /* - * Compute CMYK values... - */ - - ic = gx_max_color_value - r; - im = gx_max_color_value - g; - iy = gx_max_color_value - b; - ik = min(ic, min(im, iy)); - - if ((mk = max(ic, max(im, iy))) > ik) - ik = (int)((float)ik * (float)ik * (float)ik / ((float)mk * (float)mk)); - - ic -= ik; - im -= ik; - iy -= ik; - - /* - * Color correct CMY... - */ - - tc = cupsMatrix[0][0][ic] + - cupsMatrix[0][1][im] + - cupsMatrix[0][2][iy] + - ik; - tm = cupsMatrix[1][0][ic] + - cupsMatrix[1][1][im] + - cupsMatrix[1][2][iy] + - ik; - ty = cupsMatrix[2][0][ic] + - cupsMatrix[2][1][im] + - cupsMatrix[2][2][iy] + - ik; - - /* - * Density correct combined CMYK... - */ - - if (tc < 0) - r = gx_max_color_value; - else if (tc > gx_max_color_value) - r = gx_max_color_value - cupsDensity[gx_max_color_value]; - else - r = gx_max_color_value - cupsDensity[tc]; - - if (tm < 0) - g = gx_max_color_value; - else if (tm > gx_max_color_value) - g = gx_max_color_value - cupsDensity[gx_max_color_value]; - else - g = gx_max_color_value - cupsDensity[tm]; - - if (ty < 0) - b = gx_max_color_value; - else if (ty > gx_max_color_value) - b = gx_max_color_value - cupsDensity[gx_max_color_value]; - else - b = gx_max_color_value - cupsDensity[ty]; - } - - /* - * Convert the RGB color to a color index... - */ - - switch (cups->header.cupsColorSpace) - { - case CUPS_CSPACE_W : - i = cupsEncodeLUT[(r * 31 + g * 61 + b * 8) / 100]; - break; - - case CUPS_CSPACE_RGB : - ic = cupsEncodeLUT[r]; - im = cupsEncodeLUT[g]; - iy = cupsEncodeLUT[b]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((ic << 1) | im) << 1) | iy; - break; - case 2 : - i = (((ic << 2) | im) << 2) | iy; - break; - case 4 : - i = (((ic << 4) | im) << 4) | iy; - break; - case 8 : - i = (((ic << 8) | im) << 8) | iy; - break; - } - break; - - case CUPS_CSPACE_RGBA : - ic = cupsEncodeLUT[r]; - im = cupsEncodeLUT[g]; - iy = cupsEncodeLUT[b]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((ic << 1) | im) << 1) | iy) << 1) | 0x01; - break; - case 2 : - i = (((((ic << 2) | im) << 2) | iy) << 2) | 0x03; - break; - case 4 : - i = (((((ic << 4) | im) << 4) | iy) << 4) | 0x0f; - break; - case 8 : - i = (((((ic << 8) | im) << 8) | iy) << 8) | 0xff; - break; - } - break; - - default : - i = cupsEncodeLUT[gx_max_color_value - (r * 31 + g * 61 + b * 8) / 100]; - break; - - case CUPS_CSPACE_CMY : - ic = cupsEncodeLUT[gx_max_color_value - r]; - im = cupsEncodeLUT[gx_max_color_value - g]; - iy = cupsEncodeLUT[gx_max_color_value - b]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((ic << 1) | im) << 1) | iy; - break; - case 2 : - i = (((ic << 2) | im) << 2) | iy; - break; - case 4 : - i = (((ic << 4) | im) << 4) | iy; - break; - case 8 : - i = (((ic << 8) | im) << 8) | iy; - break; - } - break; - - case CUPS_CSPACE_YMC : - ic = cupsEncodeLUT[gx_max_color_value - r]; - im = cupsEncodeLUT[gx_max_color_value - g]; - iy = cupsEncodeLUT[gx_max_color_value - b]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((iy << 1) | im) << 1) | ic; - break; - case 2 : - i = (((iy << 2) | im) << 2) | ic; - break; - case 4 : - i = (((iy << 4) | im) << 4) | ic; - break; - case 8 : - i = (((iy << 8) | im) << 8) | ic; - break; - } - break; - - case CUPS_CSPACE_CMYK : - ic = gx_max_color_value - r; - im = gx_max_color_value - g; - iy = gx_max_color_value - b; - ik = min(ic, min(im, iy)); - - if ((mk = max(ic, max(im, iy))) > ik) - ik = (int)((float)ik * (float)ik * (float)ik / - ((float)mk * (float)mk)); - - ic = cupsEncodeLUT[ic - ik]; - im = cupsEncodeLUT[im - ik]; - iy = cupsEncodeLUT[iy - ik]; - ik = cupsEncodeLUT[ik]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((ic << 1) | im) << 1) | iy) << 1) | ik; - break; - case 2 : - i = (((((ic << 2) | im) << 2) | iy) << 2) | ik; - break; - case 4 : - i = (((((ic << 4) | im) << 4) | iy) << 4) | ik; - break; - case 8 : - i = (((((ic << 8) | im) << 8) | iy) << 8) | ik; - break; - } - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: CMY (%d,%d,%d) -> CMYK %08x (%d,%d,%d,%d)\n", - r, g, b, (unsigned)i, ic, im, iy, ik); -# endif /* DEBUG */ - break; - - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - ic = gx_max_color_value - r; - im = gx_max_color_value - g; - iy = gx_max_color_value - b; - ik = min(ic, min(im, iy)); - - if ((mk = max(ic, max(im, iy))) > ik) - ik = (int)((float)ik * (float)ik * (float)ik / - ((float)mk * (float)mk)); - - ic = cupsEncodeLUT[ic - ik]; - im = cupsEncodeLUT[im - ik]; - iy = cupsEncodeLUT[iy - ik]; - ik = cupsEncodeLUT[ik]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((iy << 1) | im) << 1) | ic) << 1) | ik; - break; - case 2 : - i = (((((iy << 2) | im) << 2) | ic) << 2) | ik; - break; - case 4 : - i = (((((iy << 4) | im) << 4) | ic) << 4) | ik; - break; - case 8 : - i = (((((iy << 8) | im) << 8) | ic) << 8) | ik; - break; - } - break; - - case CUPS_CSPACE_KCMYcm : - if (cups->header.cupsBitsPerColor == 1) - { - ic = gx_max_color_value - r; - im = gx_max_color_value - g; - iy = gx_max_color_value - b; - ik = min(ic, min(im, iy)); - - if ((mk = max(ic, max(im, iy))) > ik) - ik = (int)((float)ik * (float)ik * (float)ik / - ((float)mk * (float)mk)); - - ic = cupsEncodeLUT[ic - ik]; - im = cupsEncodeLUT[im - ik]; - iy = cupsEncodeLUT[iy - ik]; - ik = cupsEncodeLUT[ik]; - if (ik) - i = 32; - else if (ic && im) - i = 17; - else if (ic && iy) - i = 6; - else if (im && iy) - i = 12; - else if (ic) - i = 16; - else if (im) - i = 8; - else if (iy) - i = 4; - else - i = 0; - break; - } - - case CUPS_CSPACE_KCMY : - ic = gx_max_color_value - r; - im = gx_max_color_value - g; - iy = gx_max_color_value - b; - ik = min(ic, min(im, iy)); - - if ((mk = max(ic, max(im, iy))) > ik) - ik = (int)((float)ik * (float)ik * (float)ik / - ((float)mk * (float)mk)); - - ic = cupsEncodeLUT[ic - ik]; - im = cupsEncodeLUT[im - ik]; - iy = cupsEncodeLUT[iy - ik]; - ik = cupsEncodeLUT[ik]; - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((((ik << 1) | ic) << 1) | im) << 1) | iy; - break; - case 2 : - i = (((((ik << 2) | ic) << 2) | im) << 2) | iy; - break; - case 4 : - i = (((((ik << 4) | ic) << 4) | im) << 4) | iy; - break; - case 8 : - i = (((((ik << 8) | ic) << 8) | im) << 8) | iy; - break; - } - break; - -# ifdef CUPS_RASTER_HAVE_COLORIMETRIC - case CUPS_CSPACE_CIEXYZ : - case CUPS_CSPACE_CIELab : - case CUPS_CSPACE_ICC1 : - case CUPS_CSPACE_ICC2 : - case CUPS_CSPACE_ICC3 : - case CUPS_CSPACE_ICC4 : - case CUPS_CSPACE_ICC5 : - case CUPS_CSPACE_ICC6 : - case CUPS_CSPACE_ICC7 : - case CUPS_CSPACE_ICC8 : - case CUPS_CSPACE_ICC9 : - case CUPS_CSPACE_ICCA : - case CUPS_CSPACE_ICCB : - case CUPS_CSPACE_ICCC : - case CUPS_CSPACE_ICCD : - case CUPS_CSPACE_ICCE : - case CUPS_CSPACE_ICCF : - /* - * Convert sRGB to linear RGB... - */ - - rr = pow((double)r / (double)gx_max_color_value, 0.58823529412); - rg = pow((double)g / (double)gx_max_color_value, 0.58823529412); - rb = pow((double)b / (double)gx_max_color_value, 0.58823529412); - - /* - * Convert to CIE XYZ... - */ - - ciex = 0.412453 * rr + 0.357580 * rg + 0.180423 * rb; - ciey = 0.212671 * rr + 0.715160 * rg + 0.072169 * rb; - ciez = 0.019334 * rr + 0.119193 * rg + 0.950227 * rb; - - if (cups->header.cupsColorSpace == CUPS_CSPACE_CIEXYZ) - { - /* - * Convert to an integer XYZ color value... - */ - - if (ciex > 1.0) - ic = 255; - else if (ciex > 0.0) - ic = (int)(ciex * 255.0); - else - ic = 0; - - if (ciey > 1.0) - im = 255; - else if (ciey > 0.0) - im = (int)(ciey * 255.0); - else - im = 0; - - if (ciez > 1.0) - iy = 255; - else if (ciez > 0.0) - iy = (int)(ciez * 255.0); - else - iy = 0; - } - else - { - /* - * Convert CIE XYZ to Lab... - */ - - ciey_yn = ciey / D65_Y; - - if (ciey_yn > 0.008856) - ciel = 116 * cbrt(ciey_yn) - 16; - else - ciel = 903.3 * ciey_yn; - - ciea = 500 * (cups_map_cielab(ciex, D65_X) - - cups_map_cielab(ciey, D65_Y)); - cieb = 200 * (cups_map_cielab(ciey, D65_Y) - - cups_map_cielab(ciez, D65_Z)); - - /* - * Scale the L value and bias the a and b values by 128 - * so that all values are in the range of 0 to 255. - */ - - ciel *= 2.55; - ciea += 128; - cieb += 128; - - /* - * Convert to 8-bit values... - */ - - if (ciel < 0.0) - ic = 0; - else if (ciel < 255.0) - ic = ciel; - else - ic = 255; - - if (ciea < 0.0) - im = 0; - else if (ciea < 255.0) - im = ciea; - else - im = 255; - - if (cieb < 0.0) - iy = 0; - else if (cieb < 255.0) - iy = cieb; - else - iy = 255; - } - - /* - * Put the final color value together... - */ - - switch (cups->header.cupsBitsPerColor) - { - default : - i = (((ic << 1) | im) << 1) | iy; - break; - case 2 : - i = (((ic << 2) | im) << 2) | iy; - break; - case 4 : - i = (((ic << 4) | im) << 4) | iy; - break; - case 8 : - i = (((ic << 8) | im) << 8) | iy; - break; - } - break; -# endif /* CUPS_RASTER_HAVE_COLORIMETRIC */ - } - -# ifdef DEBUG - fprintf(stderr, "DEBUG2: RGB %d,%d,%d = %08x\n", r, g, b, (unsigned)i); -# endif /* DEBUG */ - - return (i); -} -#endif /* dev_t_proc_encode_color */ - - -/* - * 'cups_open()' - Open the output file and initialize things. - */ - -private int /* O - Error status */ -cups_open(gx_device *pdev) /* I - Device info */ -{ - int code; /* Return status */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_open(%p)\n", pdev); -#endif /* DEBUG */ - - cups->printer_procs.get_space_params = cups_get_space_params; - - if (cups->page == 0) - { - fputs("INFO: Processing page 1...\n", stderr); - cups->page = 1; - } - - cups_set_color_info(pdev); - - if ((code = gdev_prn_open(pdev)) != 0) - return (code); - - if (cupsPPD == NULL) - cupsPPD = ppdOpenFile(getenv("PPD")); - - return (0); -} - - -/* - * 'cups_print_pages()' - Send one or more pages to the output file. - */ - -private int /* O - 0 if everything is OK */ -cups_print_pages(gx_device_printer *pdev, - /* I - Device info */ - FILE *fp, /* I - Output file */ - int num_copies) - /* I - Number of copies */ -{ - int copy; /* Copy number */ - int srcbytes; /* Byte width of scanline */ - unsigned char *src, /* Scanline data */ - *dst; /* Bitmap data */ - - - (void)fp; /* reference unused file pointer to prevent compiler warning */ - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_print_pages(%p, %p, %d)\n", pdev, fp, - num_copies); -#endif /* DEBUG */ - - /* - * Figure out the number of bytes per line... - */ - - switch (cups->header.cupsColorOrder) - { - case CUPS_ORDER_CHUNKED : - cups->header.cupsBytesPerLine = (cups->header.cupsBitsPerPixel * - cups->header.cupsWidth + 7) / 8; - break; - - case CUPS_ORDER_BANDED : - if (cups->header.cupsColorSpace == CUPS_CSPACE_KCMYcm && - cups->header.cupsBitsPerColor == 1) - cups->header.cupsBytesPerLine = (cups->header.cupsBitsPerColor * - cups->header.cupsWidth + 7) / 8 * 6; - else - cups->header.cupsBytesPerLine = (cups->header.cupsBitsPerColor * - cups->header.cupsWidth + 7) / 8 * - cups->color_info.num_components; - break; - - case CUPS_ORDER_PLANAR : - cups->header.cupsBytesPerLine = (cups->header.cupsBitsPerColor * - cups->header.cupsWidth + 7) / 8; - break; - } - - /* - * Compute the width of a scanline and allocate input/output buffers... - */ - - srcbytes = gdev_prn_raster(pdev); - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cupsBitsPerPixel = %d, cupsWidth = %d, cupsBytesPerLine = %d, srcbytes = %d\n", - cups->header.cupsBitsPerPixel, cups->header.cupsWidth, - cups->header.cupsBytesPerLine, srcbytes); -#endif /* DEBUG */ - - src = (unsigned char *)gs_malloc(srcbytes, 1, "cups_print_pages"); - - if (src == NULL) /* can't allocate input buffer */ - return_error(gs_error_VMerror); - - /* - * Need an output buffer, too... - */ - - dst = (unsigned char *)gs_malloc(cups->header.cupsBytesPerLine, 2, - "cups_print_pages"); - - if (dst == NULL) /* can't allocate working area */ - return_error(gs_error_VMerror); - - /* - * See if the stream has been initialized yet... - */ - - if (cups->stream == NULL) - { - if ((cups->stream = cupsRasterOpen(fileno(cups->file), - CUPS_RASTER_WRITE)) == NULL) - { - perror("ERROR: Unable to open raster stream - "); - gs_exit(0); - } - } - - /* - * Output a page of graphics... - */ - - if (num_copies < 1) - num_copies = 1; - - if (cupsPPD != NULL && !cupsPPD->manual_copies) - { - cups->header.NumCopies = num_copies; - num_copies = 1; - } - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cupsWidth = %d, cupsHeight = %d, cupsBytesPerLine = %d\n", - cups->header.cupsWidth, cups->header.cupsHeight, - cups->header.cupsBytesPerLine); -#endif /* DEBUG */ - - for (copy = num_copies; copy > 0; copy --) - { - cupsRasterWriteHeader(cups->stream, &(cups->header)); - - if (pdev->color_info.num_components == 1) - cups_print_chunked(pdev, src, dst, srcbytes); - else - switch (cups->header.cupsColorOrder) - { - case CUPS_ORDER_CHUNKED : - cups_print_chunked(pdev, src, dst, srcbytes); - break; - case CUPS_ORDER_BANDED : - cups_print_banded(pdev, src, dst, srcbytes); - break; - case CUPS_ORDER_PLANAR : - cups_print_planar(pdev, src, dst, srcbytes); - break; - } - } - - /* - * Free temporary storage and return... - */ - - gs_free((char *)src, srcbytes, 1, "cups_print_pages"); - gs_free((char *)dst, cups->header.cupsBytesPerLine, 1, "cups_print_pages"); - - cups->page ++; - fprintf(stderr, "INFO: Processing page %d...\n", cups->page); - - return (0); -} - - -/* - * 'cups_put_params()' - Set pagedevice parameters. - */ - -private int /* O - Error status */ -cups_put_params(gx_device *pdev, /* I - Device info */ - gs_param_list *plist) /* I - Parameter list */ -{ - int i; /* Looping var */ -#ifdef CUPS_RASTER_SYNCv1 - char name[255]; /* Name of attribute */ -#endif /* CUPS_RASTER_SYNCv1 */ - float margins[4]; /* Physical margins of print */ - ppd_size_t *size; /* Page size */ - int code; /* Error code */ - int intval; /* Integer value */ - bool boolval; /* Boolean value */ - float floatval; /* Floating point value */ - gs_param_string stringval; /* String value */ - gs_param_float_array arrayval; /* Float array value */ - int size_set; /* Was the size set? */ - int color_set; /* Were the color attrs set? */ - gdev_prn_space_params sp; /* Space parameter data */ - int width, /* New width of page */ - height; /* New height of page */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_put_params(%p, %p)\n", pdev, plist); -#endif /* DEBUG */ - - /* - * Process other options for CUPS... - */ - -#define stringoption(name, sname) \ - if ((code = param_read_string(plist, sname, &stringval)) < 0) \ - { \ - param_signal_error(plist, sname, code); \ - return (code); \ - } \ - else if (code == 0) \ - { \ - strncpy(cups->header.name, (const char *)stringval.data, \ - stringval.size); \ - cups->header.name[stringval.size] = '\0'; \ - } - -#define intoption(name, sname, type) \ - if ((code = param_read_int(plist, sname, &intval)) < 0) \ - { \ - param_signal_error(plist, sname, code); \ - return (code); \ - } \ - else if (code == 0) \ - { \ - fprintf(stderr, "DEBUG: Setting %s to %d...\n", sname, intval); \ - cups->header.name = (type)intval; \ - } - -#define floatoption(name, sname) \ - if ((code = param_read_float(plist, sname, &floatval)) < 0) \ - { \ - param_signal_error(plist, sname, code); \ - return (code); \ - } \ - else if (code == 0) \ - cups->header.name = (unsigned)floatval; - -#define booloption(name, sname) \ - if ((code = param_read_bool(plist, sname, &boolval)) < 0) \ - { \ - if ((code = param_read_null(plist, sname)) < 0) \ - { \ - param_signal_error(plist, sname, code); \ - return (code); \ - } \ - if (code == 0) \ - cups->header.name = CUPS_FALSE; \ - } \ - else if (code == 0) \ - cups->header.name = (cups_bool_t)boolval; - -#define arrayoption(name, sname, count) \ - if ((code = param_read_float_array(plist, sname, &arrayval)) < 0) \ - { \ - if ((code = param_read_null(plist, sname)) < 0) \ - { \ - param_signal_error(plist, sname, code); \ - return (code); \ - } \ - if (code == 0) \ - for (i = 0; i < count; i ++) \ - cups->header.name[i] = 0; \ - } \ - else if (code == 0) \ - { \ - for (i = 0; i < count; i ++) \ - cups->header.name[i] = (unsigned)arrayval.data[i]; \ - } - - size_set = param_read_float_array(plist, ".MediaSize", &arrayval) == 0 || - param_read_float_array(plist, "PageSize", &arrayval) == 0; - color_set = param_read_int(plist, "cupsColorSpace", &intval) == 0 || - param_read_int(plist, "cupsBitsPerColor", &intval) == 0; - - stringoption(MediaClass, "MediaClass") - stringoption(MediaColor, "MediaColor") - stringoption(MediaType, "MediaType") - stringoption(OutputType, "OutputType") - floatoption(AdvanceDistance, "AdvanceDistance") - intoption(AdvanceMedia, "AdvanceMedia", cups_adv_t) - booloption(Collate, "Collate") - intoption(CutMedia, "CutMedia", cups_cut_t) - booloption(Duplex, "Duplex") - arrayoption(ImagingBoundingBox, "ImagingBoundingBox", 4) - booloption(InsertSheet, "InsertSheet") - intoption(Jog, "Jog", cups_jog_t) - intoption(LeadingEdge, "LeadingEdge", cups_edge_t) - arrayoption(Margins, "Margins", 2) - booloption(ManualFeed, "ManualFeed") - intoption(MediaPosition, "cupsMediaPosition", unsigned) /* Compatibility */ - intoption(MediaPosition, "MediaPosition", unsigned) - floatoption(MediaWeight, "MediaWeight") - booloption(MirrorPrint, "MirrorPrint") - booloption(NegativePrint, "NegativePrint") - intoption(Orientation, "Orientation", cups_orient_t) - booloption(OutputFaceUp, "OutputFaceUp") - booloption(Separations, "Separations") - booloption(TraySwitch, "TraySwitch") - booloption(Tumble, "Tumble") - intoption(cupsMediaType, "cupsMediaType", unsigned) - intoption(cupsBitsPerColor, "cupsBitsPerColor", unsigned) - intoption(cupsColorOrder, "cupsColorOrder", cups_order_t) - intoption(cupsColorSpace, "cupsColorSpace", cups_cspace_t) - intoption(cupsCompression, "cupsCompression", unsigned) - intoption(cupsRowCount, "cupsRowCount", unsigned) - intoption(cupsRowFeed, "cupsRowFeed", unsigned) - intoption(cupsRowStep, "cupsRowStep", unsigned) - -#ifdef CUPS_RASTER_SYNCv1 - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsInteger%d", i); - intoption(cupsInteger[i], name, unsigned) - } - - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsReal%d", i); - floatoption(cupsReal[i], name) - } - - for (i = 0; i < 16; i ++) - { - sprintf(name, "cupsString%d", i); - stringoption(cupsString[i], name) - } - - stringoption(cupsMarkerType, "cupsMarkerType"); - stringoption(cupsRenderingIntent, "cupsRenderingIntent"); -#endif /* CUPS_RASTER_SYNCv1 */ - - if ((code = param_read_string(plist, "cupsProfile", &stringval)) < 0) - { - param_signal_error(plist, "cupsProfile", code); - return (code); - } - else if (code == 0) - { - if (cupsProfile != NULL) - free(cupsProfile); - - cupsProfile = strdup(stringval.data); - } - - cups_set_color_info(pdev); - - /* - * Then process standard page device options... - */ - - if ((code = gdev_prn_put_params(pdev, plist)) < 0) - return (code); - - /* - * Update margins/sizes as needed... - */ - - if (size_set) - { - /* - * Compute the page margins... - */ - - fprintf(stderr, "DEBUG: Updating PageSize to [%.0f %.0f]...\n", - cups->MediaSize[0], cups->MediaSize[1]); - - memset(margins, 0, sizeof(margins)); - - cups->landscape = 0; - - if (cupsPPD != NULL) - { - /* - * Find the matching page size... - */ - - for (i = cupsPPD->num_sizes, size = cupsPPD->sizes; - i > 0; - i --, size ++) - if (fabs(cups->MediaSize[1] - size->length) < 5.0 && - fabs(cups->MediaSize[0] - size->width) < 5.0) - break; - - if (i > 0) - { - /* - * Standard size... - */ - - fprintf(stderr, "DEBUG: size = %s\n", size->name); - - gx_device_set_media_size(pdev, size->width, size->length); - - margins[0] = size->left / 72.0; - margins[1] = size->bottom / 72.0; - margins[2] = (size->width - size->right) / 72.0; - margins[3] = (size->length - size->top) / 72.0; - } - else - { - /* - * No matching portrait size; look for a matching size in - * landscape orientation... - */ - - for (i = cupsPPD->num_sizes, size = cupsPPD->sizes; - i > 0; - i --, size ++) - if (fabs(cups->MediaSize[0] - size->length) < 5.0 && - fabs(cups->MediaSize[1] - size->width) < 5.0) - break; - - if (i > 0) - { - /* - * Standard size in landscape orientation... - */ - - fprintf(stderr, "DEBUG: landscape size = %s\n", size->name); - - gx_device_set_media_size(pdev, size->length, size->width); - - cups->landscape = 1; - - margins[0] = size->left / 72.0; - margins[1] = size->bottom / 72.0; - margins[2] = (size->width - size->right) / 72.0; - margins[3] = (size->length - size->top) / 72.0; - } - else - { - /* - * Custom size... - */ - - fputs("DEBUG: size = Custom\n", stderr); - - for (i = 0; i < 4; i ++) - margins[i] = cupsPPD->custom_margins[i] / 72.0; - } - } - - fprintf(stderr, "DEBUG: margins[] = [ %f %f %f %f ]\n", - margins[0], margins[1], margins[2], margins[3]); - } - - /* - * Set the margins to update the bitmap size... - */ - - gx_device_set_margins(pdev, margins, false); - } - - /* - * Set CUPS raster header values... - */ - - cups->header.HWResolution[0] = pdev->HWResolution[0]; - cups->header.HWResolution[1] = pdev->HWResolution[1]; - - cups->header.Margins[0] = pdev->HWMargins[0]; - cups->header.Margins[1] = pdev->HWMargins[1]; - - cups->header.PageSize[0] = pdev->MediaSize[0]; - cups->header.PageSize[1] = pdev->MediaSize[1]; - - cups->header.ImagingBoundingBox[0] = pdev->HWMargins[0]; - cups->header.ImagingBoundingBox[1] = pdev->HWMargins[3]; - cups->header.ImagingBoundingBox[2] = pdev->MediaSize[0] - pdev->HWMargins[2]; - cups->header.ImagingBoundingBox[3] = pdev->MediaSize[1] - pdev->HWMargins[1]; - - /* - * Reallocate memory if the size or color depth was changed... - */ - - if (color_set || size_set) - { - /* - * Make sure the page image is the correct size - current Ghostscript - * does not keep track of the margins in the bitmap size... - */ - - if (cups->landscape) - { - width = (pdev->MediaSize[1] - pdev->HWMargins[0] - pdev->HWMargins[2]) * - pdev->HWResolution[0] / 72.0f + 0.499f; - height = (pdev->MediaSize[0] - pdev->HWMargins[1] - pdev->HWMargins[3]) * - pdev->HWResolution[1] / 72.0f + 0.499f; - } - else - { - width = (pdev->MediaSize[0] - pdev->HWMargins[0] - pdev->HWMargins[2]) * - pdev->HWResolution[0] / 72.0f + 0.499f; - height = (pdev->MediaSize[1] - pdev->HWMargins[1] - pdev->HWMargins[3]) * - pdev->HWResolution[1] / 72.0f + 0.499f; - } - - /* - * Don't reallocate memory unless the device has been opened... - */ - - if (pdev->is_open) - { - /* - * Device is open, so reallocate... - */ - - fprintf(stderr, "DEBUG: Reallocating memory, [%.0f %.0f] = %dx%d pixels...\n", - pdev->MediaSize[0], pdev->MediaSize[1], width, height); - - sp = ((gx_device_printer *)pdev)->space_params; - - if ((code = gdev_prn_reallocate_memory(pdev, &sp, width, height)) < 0) - return (code); - } - else - { - /* - * Device isn't yet open, so just save the new width and height... - */ - - fprintf(stderr, "DEBUG: Setting initial media size, [%.0f %.0f] = %dx%d pixels...\n", - pdev->MediaSize[0], pdev->MediaSize[1], width, height); - - pdev->width = width; - pdev->height = height; - } - } - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: ppd = %p\n", cupsPPD); - fprintf(stderr, "DEBUG2: PageSize = [ %.3f %.3f ]\n", - pdev->MediaSize[0], pdev->MediaSize[1]); - fprintf(stderr, "DEBUG2: margins = [ %.3f %.3f %.3f %.3f ]\n", - margins[0], margins[1], margins[2], margins[3]); - fprintf(stderr, "DEBUG2: HWResolution = [ %.3f %.3f ]\n", - pdev->HWResolution[0], pdev->HWResolution[1]); - fprintf(stderr, "DEBUG2: width = %d, height = %d\n", - pdev->width, pdev->height); - fprintf(stderr, "DEBUG2: HWMargins = [ %.3f %.3f %.3f %.3f ]\n", - pdev->HWMargins[0], pdev->HWMargins[1], - pdev->HWMargins[2], pdev->HWMargins[3]); -#endif /* DEBUG */ - - return (0); -} - - -/* - * 'cups_set_color_info()' - Set the color information structure based on - * the required output. - */ - -private void -cups_set_color_info(gx_device *pdev) /* I - Device info */ -{ - int i, j, k; /* Looping vars */ - int max_lut; /* Maximum LUT value */ - float d, g; /* Density and gamma correction */ - float m[3][3]; /* Color correction matrix */ - char resolution[41]; /* Resolution string */ - ppd_profile_t *profile; /* Color profile information */ - - -#ifdef DEBUG - fprintf(stderr, "DEBUG2: cups_set_color_info(%p)\n", pdev); -#endif /* DEBUG */ - - switch (cups->header.cupsColorSpace) - { - default : - case CUPS_CSPACE_W : - case CUPS_CSPACE_K : - case CUPS_CSPACE_WHITE : - case CUPS_CSPACE_GOLD : - case CUPS_CSPACE_SILVER : - cups->header.cupsBitsPerPixel = cups->header.cupsBitsPerColor; - cups->color_info.depth = cups->header.cupsBitsPerPixel; - cups->color_info.num_components = 1; - break; - - case CUPS_CSPACE_CMY : - case CUPS_CSPACE_YMC : - case CUPS_CSPACE_RGB : - if (cups->header.cupsColorOrder != CUPS_ORDER_CHUNKED) - cups->header.cupsBitsPerPixel = cups->header.cupsBitsPerColor; - else if (cups->header.cupsBitsPerColor < 8) - cups->header.cupsBitsPerPixel = 4 * cups->header.cupsBitsPerColor; - else - cups->header.cupsBitsPerPixel = 3 * cups->header.cupsBitsPerColor; - - if (cups->header.cupsBitsPerColor < 8) - cups->color_info.depth = 4 * cups->header.cupsBitsPerColor; - else - cups->color_info.depth = 3 * cups->header.cupsBitsPerColor; - - cups->color_info.num_components = 3; - break; - - case CUPS_CSPACE_KCMYcm : - if (cups->header.cupsBitsPerColor == 1) - { - cups->header.cupsBitsPerPixel = 8; - cups->color_info.depth = 8; - cups->color_info.num_components = 4; - break; - } - - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - if (cups->header.cupsColorOrder != CUPS_ORDER_CHUNKED) - cups->header.cupsBitsPerPixel = cups->header.cupsBitsPerColor; - else - cups->header.cupsBitsPerPixel = 4 * cups->header.cupsBitsPerColor; - - cups->color_info.depth = 4 * cups->header.cupsBitsPerColor; - cups->color_info.num_components = 4; - break; - -#ifdef CUPS_RASTER_HAVE_COLORIMETRIC - case CUPS_CSPACE_CIEXYZ : - case CUPS_CSPACE_CIELab : - case CUPS_CSPACE_ICC1 : - case CUPS_CSPACE_ICC2 : - case CUPS_CSPACE_ICC3 : - case CUPS_CSPACE_ICC4 : - case CUPS_CSPACE_ICC5 : - case CUPS_CSPACE_ICC6 : - case CUPS_CSPACE_ICC7 : - case CUPS_CSPACE_ICC8 : - case CUPS_CSPACE_ICC9 : - case CUPS_CSPACE_ICCA : - case CUPS_CSPACE_ICCB : - case CUPS_CSPACE_ICCC : - case CUPS_CSPACE_ICCD : - case CUPS_CSPACE_ICCE : - case CUPS_CSPACE_ICCF : - /* - * Colorimetric color spaces currently are implemented as 24-bit - * mapping to XYZ or Lab, which are then converted as needed to - * the final representation... - * - * This code enforces a minimum output depth of 8 bits per - * component... - */ - - if (cups->header.cupsBitsPerColor < 8) - cups->header.cupsBitsPerColor = 8; - - if (cups->header.cupsColorOrder != CUPS_ORDER_CHUNKED) - cups->header.cupsBitsPerPixel = cups->header.cupsBitsPerColor; - else - cups->header.cupsBitsPerPixel = 3 * cups->header.cupsBitsPerColor; - - cups->color_info.depth = 24; - cups->color_info.num_components = 3; - break; -#endif /* CUPS_RASTER_HAVE_COLORIMETRIC */ - } - -#ifdef dev_t_proc_encode_color - switch (cups->header.cupsColorSpace) - { - default : - cups->color_info.gray_index = GX_CINFO_COMP_NO_INDEX; - break; - - case CUPS_CSPACE_W : - case CUPS_CSPACE_WHITE : - case CUPS_CSPACE_K : - case CUPS_CSPACE_GOLD : - case CUPS_CSPACE_SILVER : - case CUPS_CSPACE_KCMYcm : - case CUPS_CSPACE_KCMY : - cups->color_info.gray_index = 0; - break; - - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - cups->color_info.gray_index = 3; - break; - } - - switch (cups->header.cupsColorSpace) - { - default : - case CUPS_CSPACE_W : - case CUPS_CSPACE_WHITE : - case CUPS_CSPACE_RGB : -# ifdef CUPS_RASTER_HAVE_COLORIMETRIC - case CUPS_CSPACE_CIEXYZ : - case CUPS_CSPACE_CIELab : - case CUPS_CSPACE_ICC1 : - case CUPS_CSPACE_ICC2 : - case CUPS_CSPACE_ICC3 : - case CUPS_CSPACE_ICC4 : - case CUPS_CSPACE_ICC5 : - case CUPS_CSPACE_ICC6 : - case CUPS_CSPACE_ICC7 : - case CUPS_CSPACE_ICC8 : - case CUPS_CSPACE_ICC9 : - case CUPS_CSPACE_ICCA : - case CUPS_CSPACE_ICCB : - case CUPS_CSPACE_ICCC : - case CUPS_CSPACE_ICCD : - case CUPS_CSPACE_ICCE : - case CUPS_CSPACE_ICCF : -# endif /* CUPS_RASTER_HAVE_COLORIMETRIC */ - cups->color_info.polarity = GX_CINFO_POLARITY_ADDITIVE; - break; - - case CUPS_CSPACE_K : - case CUPS_CSPACE_GOLD : - case CUPS_CSPACE_SILVER : - case CUPS_CSPACE_CMY : - case CUPS_CSPACE_YMC : - case CUPS_CSPACE_KCMYcm : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - cups->color_info.polarity = GX_CINFO_POLARITY_SUBTRACTIVE; - break; - } - - cups->color_info.separable_and_linear = GX_CINFO_SEP_LIN_NONE; -#endif /* dev_t_proc_encode_color */ - - if ((i = cups->header.cupsBitsPerColor) > 8) - i = 8; - - max_lut = (1 << i) - 1; - - switch (cups->color_info.num_components) - { - default : - case 1 : - cups->color_info.max_gray = max_lut; - cups->color_info.max_color = 0; - cups->color_info.dither_grays = max_lut + 1; - cups->color_info.dither_colors = 0; - break; - - case 3 : - cups->color_info.max_gray = 0; - cups->color_info.max_color = max_lut; - cups->color_info.dither_grays = 0; - cups->color_info.dither_colors = max_lut + 1; - break; - - case 4 : - cups->color_info.max_gray = max_lut; - cups->color_info.max_color = max_lut; - cups->color_info.dither_grays = max_lut + 1; - cups->color_info.dither_colors = max_lut + 1; - break; - } - - /* - * Enable/disable CMYK color support... - */ - -#ifdef dev_t_proc_encode_color - cups->color_info.max_components = cups->color_info.num_components; -#endif /* dev_t_proc_encode_color */ - - /* - * Tell Ghostscript to forget any colors it has cached... - */ - - gx_device_decache_colors(pdev); - - /* - * Compute the lookup tables... - */ - - for (i = 0; i <= gx_max_color_value; i ++) - { - cupsEncodeLUT[i] = (max_lut * i + gx_max_color_value / 2) / - gx_max_color_value; - -#ifdef DEBUG - if (i == 0 || cupsEncodeLUT[i] != cupsEncodeLUT[i - 1]) - fprintf(stderr, "DEBUG2: cupsEncodeLUT[%d] = %d\n", i, cupsEncodeLUT[i]); -#endif /* DEBUG */ - } - - for (i = 0; i < cups->color_info.dither_grays; i ++) - cupsDecodeLUT[i] = gx_max_color_value * i / max_lut; - - fprintf(stderr, "DEBUG: num_components = %d, depth = %d\n", - cups->color_info.num_components, cups->color_info.depth); - fprintf(stderr, "DEBUG: cupsColorSpace = %d, cupsColorOrder = %d\n", - cups->header.cupsColorSpace, cups->header.cupsColorOrder); - fprintf(stderr, "DEBUG: cupsBitsPerPixel = %d, cupsBitsPerColor = %d\n", - cups->header.cupsBitsPerPixel, cups->header.cupsBitsPerColor); - fprintf(stderr, "DEBUG: max_gray = %d, dither_grays = %d\n", - cups->color_info.max_gray, cups->color_info.dither_grays); - fprintf(stderr, "DEBUG: max_color = %d, dither_colors = %d\n", - cups->color_info.max_color, cups->color_info.dither_colors); - - /* - * Set the color profile as needed... - */ - - cupsHaveProfile = 0; - -#ifdef dev_t_proc_encode_color - if (cupsProfile) -#else - if (cupsProfile && cups->header.cupsBitsPerColor == 8) -#endif /* dev_t_proc_encode_color */ - { - fprintf(stderr, "DEBUG: Using user-defined profile \"%s\"...\n", cupsProfile); - - if (sscanf(cupsProfile, "%f,%f,%f,%f,%f,%f,%f,%f,%f,%f,%f", &d, &g, - m[0] + 0, m[0] + 1, m[0] + 2, - m[1] + 0, m[1] + 1, m[1] + 2, - m[2] + 0, m[2] + 1, m[2] + 2) != 11) - fputs("DEBUG: User-defined profile does not contain 11 integers!\n", stderr); - else - { - cupsHaveProfile = 1; - - d *= 0.001f; - g *= 0.001f; - m[0][0] *= 0.001f; - m[0][1] *= 0.001f; - m[0][2] *= 0.001f; - m[1][0] *= 0.001f; - m[1][1] *= 0.001f; - m[1][2] *= 0.001f; - m[2][0] *= 0.001f; - m[2][1] *= 0.001f; - m[2][2] *= 0.001f; - } - } -#ifdef dev_t_proc_encode_color - else if (cupsPPD) -#else - else if (cupsPPD && cups->header.cupsBitsPerColor == 8) -#endif /* dev_t_proc_encode_color */ - { - /* - * Find the appropriate color profile... - */ - - if (pdev->HWResolution[0] != pdev->HWResolution[1]) - sprintf(resolution, "%.0fx%.0fdpi", pdev->HWResolution[0], - pdev->HWResolution[1]); - else - sprintf(resolution, "%.0fdpi", pdev->HWResolution[0]); - - for (i = 0, profile = cupsPPD->profiles; - i < cupsPPD->num_profiles; - i ++, profile ++) - if ((strcmp(profile->resolution, resolution) == 0 || - profile->resolution[0] == '-') && - (strcmp(profile->media_type, cups->header.MediaType) == 0 || - profile->media_type[0] == '-')) - break; - - /* - * If we found a color profile, use it! - */ - - if (i < cupsPPD->num_profiles) - { - fputs("DEBUG: Using color profile in PPD file!\n", stderr); - - cupsHaveProfile = 1; - - d = profile->density; - g = profile->gamma; - - memcpy(m, profile->matrix, sizeof(m)); - } - } - - if (cupsHaveProfile) - { - for (i = 0; i < 3; i ++) - for (j = 0; j < 3; j ++) - for (k = 0; k <= CUPS_MAX_VALUE; k ++) - { - cupsMatrix[i][j][k] = (int)((float)k * m[i][j] + 0.5); - -#ifdef DEBUG - if ((k & 4095) == 0) - fprintf(stderr, "DEBUG2: cupsMatrix[%d][%d][%d] = %d\n", - i, j, k, cupsMatrix[i][j][k]); -#endif /* DEBUG */ - } - - - for (k = 0; k <= CUPS_MAX_VALUE; k ++) - { - cupsDensity[k] = (int)((float)CUPS_MAX_VALUE * d * - pow((float)k / (float)CUPS_MAX_VALUE, g) + - 0.5); - -#ifdef DEBUG - if ((k & 4095) == 0) - fprintf(stderr, "DEBUG2: cupsDensity[%d] = %d\n", k, cupsDensity[k]); -#endif /* DEBUG */ - } - } - else - { - for (k = 0; k <= CUPS_MAX_VALUE; k ++) - cupsDensity[k] = k; - } -} - - -/* - * 'cups_sync_output()' - Keep the user informed of our status... - */ - -private int /* O - Error status */ -cups_sync_output(gx_device *pdev) /* I - Device info */ -{ - fprintf(stderr, "INFO: Processing page %d...\n", cups->page); - - return (0); -} - - -/* - * 'cups_print_chunked()' - Print a page of chunked pixels. - */ - -static void -cups_print_chunked(gx_device_printer *pdev, - /* I - Printer device */ - unsigned char *src, - /* I - Scanline buffer */ - unsigned char *dst, - /* I - Bitmap buffer */ - int srcbytes) - /* I - Number of bytes in src */ -{ - int y; /* Looping var */ - unsigned char *srcptr, /* Pointer to data */ - *dstptr; /* Pointer to bits */ - int count; /* Count for loop */ - int flip; /* Flip scanline? */ - - - if (cups->header.Duplex && !cups->header.Tumble && - cupsPPD && cupsPPD->flip_duplex && !(cups->page & 1)) - flip = 1; - else - flip = 0; - - fprintf(stderr, "DEBUG: cups_print_chunked - flip = %d, height = %d\n", - flip, cups->height); - - /* - * Loop through the page bitmap and write chunked pixels, reversing as - * needed... - */ - - for (y = 0; y < cups->height; y ++) - { - /* - * Grab the scanline data... - */ - - if (gdev_prn_get_bits((gx_device_printer *)pdev, y, src, &srcptr) < 0) - { - fprintf(stderr, "ERROR: Unable to get scanline %d!\n", y); - gs_exit(1); - } - - if (flip) - { - /* - * Flip the raster data before writing it... - */ - - if (srcptr[0] == 0 && memcmp(srcptr, srcptr + 1, srcbytes - 1) == 0) - memset(dst, 0, cups->header.cupsBytesPerLine); - else - { - dstptr = dst; - count = srcbytes; - - switch (cups->color_info.depth) - { - case 1 : /* B&W bitmap */ - for (srcptr += srcbytes - 1; - count > 0; - count --, srcptr --, dstptr ++) - { - *dstptr = cupsRevUpper1[*srcptr & 15] | - cupsRevLower1[*srcptr >> 4]; - } - break; - - case 2 : /* 2-bit grayscale */ - for (srcptr += srcbytes - 1; - count > 0; - count --, srcptr --, dstptr ++) - { - *dstptr = cupsRevUpper2[*srcptr & 15] | - cupsRevLower2[*srcptr >> 4]; - } - break; - - case 4 : /* 4-bit grayscale, or RGB, CMY, or CMYK bitmap */ - for (srcptr += srcbytes - 1; - count > 0; - count --, srcptr --, dstptr ++) - *dstptr = (*srcptr >> 4) | (*srcptr << 4); - break; - - case 8 : /* 8-bit grayscale, or 2-bit RGB, CMY, or CMYK image */ - for (srcptr += srcbytes - 1; - count > 0; - count --, srcptr --, dstptr ++) - *dstptr = *srcptr; - break; - - case 16 : /* 4-bit RGB, CMY or CMYK image */ - for (srcptr += srcbytes - 2; - count > 0; - count -= 2, srcptr -= 2, dstptr += 2) - { - dstptr[0] = srcptr[0]; - dstptr[1] = srcptr[1]; - } - break; - - case 24 : /* 8-bit RGB or CMY image */ - for (srcptr += srcbytes - 3; - count > 0; - count -= 3, srcptr -= 3, dstptr += 3) - { - dstptr[0] = srcptr[0]; - dstptr[1] = srcptr[1]; - dstptr[2] = srcptr[2]; - } - break; - - case 32 : /* 4-bit RGB, CMY or CMYK bitmap */ - for (srcptr += srcbytes - 4; - count > 0; - count -= 4, srcptr -= 4, dstptr += 4) - { - dstptr[0] = srcptr[0]; - dstptr[1] = srcptr[1]; - dstptr[2] = srcptr[2]; - dstptr[3] = srcptr[3]; - } - break; - } - } - - /* - * Write the bitmap data to the raster stream... - */ - - cupsRasterWritePixels(cups->stream, dst, cups->header.cupsBytesPerLine); - } - else - { - /* - * Write the scanline data to the raster stream... - */ - - cupsRasterWritePixels(cups->stream, srcptr, cups->header.cupsBytesPerLine); - } - } -} - - -/* - * 'cups_print_banded()' - Print a page of banded pixels. - */ - -static void -cups_print_banded(gx_device_printer *pdev, - /* I - Printer device */ - unsigned char *src, - /* I - Scanline buffer */ - unsigned char *dst, - /* I - Bitmap buffer */ - int srcbytes) - /* I - Number of bytes in src */ -{ - int x; /* Looping var */ - int y; /* Looping var */ - int bandbytes; /* Bytes per band */ - unsigned char bit; /* Current bit */ - unsigned char temp; /* Temporary variable */ - unsigned char *srcptr; /* Pointer to data */ - unsigned char *cptr, *mptr, *yptr, /* Pointer to components */ - *kptr, *lcptr, *lmptr; /* ... */ - int flip; /* Flip scanline? */ - - - if (cups->header.Duplex && !cups->header.Tumble && - cupsPPD && cupsPPD->flip_duplex && !(cups->page & 1)) - flip = 1; - else - flip = 0; - - fprintf(stderr, "DEBUG: cups_print_banded - flip = %d, height = %d\n", - flip, cups->height); - - /* - * Loop through the page bitmap and write banded pixels... We have - * to separate each chunked color as needed... - */ - - bandbytes = (cups->header.cupsWidth * cups->header.cupsBitsPerColor + 7) / 8; - - for (y = 0; y < cups->height; y ++) - { - /* - * Grab the scanline data... - */ - - if (gdev_prn_get_bits((gx_device_printer *)pdev, y, src, &srcptr) < 0) - { - fprintf(stderr, "ERROR: Unable to get scanline %d!\n", y); - gs_exit(1); - } - - /* - * Separate the chunked colors into their components... - */ - - if (srcptr[0] == 0 && memcmp(srcptr, srcptr + 1, srcbytes - 1) == 0) - memset(dst, 0, cups->header.cupsBytesPerLine); - else - { - if (flip) - cptr = dst + bandbytes - 1; - else - cptr = dst; - - mptr = cptr + bandbytes; - yptr = mptr + bandbytes; - kptr = yptr + bandbytes; - lcptr = yptr + bandbytes; - lmptr = lcptr + bandbytes; - - switch (cups->header.cupsBitsPerColor) - { - default : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - for (x = cups->width, bit = flip ? 1 << (x & 7) : 128; - x > 0; - x --, srcptr ++) - { - if (*srcptr & 0x40) - *cptr |= bit; - if (*srcptr & 0x20) - *mptr |= bit; - if (*srcptr & 0x10) - *yptr |= bit; - - if (flip) - { - if (bit < 128) - bit <<= 1; - else - { - cptr --; - mptr --; - yptr --; - bit = 1; - } - } - else - bit >>= 1; - - x --; - if (x == 0) - break; - - if (*srcptr & 0x4) - *cptr |= bit; - if (*srcptr & 0x2) - *mptr |= bit; - if (*srcptr & 0x1) - *yptr |= bit; - - if (flip) - { - if (bit < 128) - bit <<= 1; - else - { - cptr --; - mptr --; - yptr --; - bit = 1; - } - } - else if (bit > 1) - bit >>= 1; - else - { - cptr ++; - mptr ++; - yptr ++; - bit = 128; - } - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - for (x = cups->width, bit = flip ? 1 << (x & 7) : 128; - x > 0; - x --, srcptr ++) - { - if (*srcptr & 0x80) - *cptr |= bit; - if (*srcptr & 0x40) - *mptr |= bit; - if (*srcptr & 0x20) - *yptr |= bit; - if (*srcptr & 0x10) - *kptr |= bit; - - if (flip) - { - if (bit < 128) - bit <<= 1; - else - { - cptr --; - mptr --; - yptr --; - kptr --; - bit = 1; - } - } - else - bit >>= 1; - - x --; - if (x == 0) - break; - - if (*srcptr & 0x8) - *cptr |= bit; - if (*srcptr & 0x4) - *mptr |= bit; - if (*srcptr & 0x2) - *yptr |= bit; - if (*srcptr & 0x1) - *kptr |= bit; - - if (flip) - { - if (bit < 128) - bit <<= 1; - else - { - cptr --; - mptr --; - yptr --; - kptr --; - bit = 1; - } - } - else if (bit > 1) - bit >>= 1; - else - { - cptr ++; - mptr ++; - yptr ++; - kptr ++; - bit = 128; - } - } - break; - case CUPS_CSPACE_KCMYcm : - for (x = cups->width, bit = flip ? 1 << (x & 7) : 128; - x > 0; - x --, srcptr ++) - { - /* - * Note: Because of the way the pointers are setup, - * the following code is correct even though - * the names don't match... - */ - - if (*srcptr & 0x20) - *cptr |= bit; - if (*srcptr & 0x10) - *mptr |= bit; - if (*srcptr & 0x08) - *yptr |= bit; - if (*srcptr & 0x04) - *kptr |= bit; - if (*srcptr & 0x02) - *lcptr |= bit; - if (*srcptr & 0x01) - *lmptr |= bit; - - if (flip) - { - if (bit < 128) - bit <<= 1; - else - { - cptr --; - mptr --; - yptr --; - kptr --; - lcptr --; - lmptr --; - bit = 1; - } - } - else if (bit > 1) - bit >>= 1; - else - { - cptr ++; - mptr ++; - yptr ++; - kptr ++; - lcptr ++; - lmptr ++; - bit = 128; - } - } - break; - } - break; - - case 2 : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - for (x = cups->width, bit = flip ? 3 << (2 * (x & 3)) : 0xc0; - x > 0; - x --, srcptr ++) - switch (bit) - { - case 0xc0 : - if ((temp = *srcptr & 0x30) != 0) - *cptr |= temp << 2; - if ((temp = *srcptr & 0x0c) != 0) - *mptr |= temp << 4; - if ((temp = *srcptr & 0x03) != 0) - *yptr |= temp << 6; - - if (flip) - { - bit = 0x03; - cptr --; - mptr --; - yptr --; - } - else - bit = 0x30; - break; - case 0x30 : - if ((temp = *srcptr & 0x30) != 0) - *cptr |= temp; - if ((temp = *srcptr & 0x0c) != 0) - *mptr |= temp << 2; - if ((temp = *srcptr & 0x03) != 0) - *yptr |= temp << 4; - - if (flip) - bit = 0xc0; - else - bit = 0x0c; - break; - case 0x0c : - if ((temp = *srcptr & 0x30) != 0) - *cptr |= temp >> 2; - if ((temp = *srcptr & 0x0c) != 0) - *mptr |= temp; - if ((temp = *srcptr & 0x03) != 0) - *yptr |= temp << 2; - - if (flip) - bit = 0x30; - else - bit = 0x03; - break; - case 0x03 : - if ((temp = *srcptr & 0x30) != 0) - *cptr |= temp >> 4; - if ((temp = *srcptr & 0x0c) != 0) - *mptr |= temp >> 2; - if ((temp = *srcptr & 0x03) != 0) - *yptr |= temp; - - if (flip) - bit = 0x0c; - else - { - bit = 0xc0; - cptr ++; - mptr ++; - yptr ++; - } - break; - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - for (x = cups->width, bit = flip ? 3 << (2 * (x & 3)) : 0xc0; - x > 0; - x --, srcptr ++) - switch (bit) - { - case 0xc0 : - if ((temp = *srcptr & 0xc0) != 0) - *cptr |= temp; - if ((temp = *srcptr & 0x30) != 0) - *mptr |= temp << 2; - if ((temp = *srcptr & 0x0c) != 0) - *yptr |= temp << 4; - if ((temp = *srcptr & 0x03) != 0) - *kptr |= temp << 6; - - if (flip) - { - bit = 0x03; - cptr --; - mptr --; - yptr --; - kptr --; - } - else - bit = 0x30; - break; - case 0x30 : - if ((temp = *srcptr & 0xc0) != 0) - *cptr |= temp >> 2; - if ((temp = *srcptr & 0x30) != 0) - *mptr |= temp; - if ((temp = *srcptr & 0x0c) != 0) - *yptr |= temp << 2; - if ((temp = *srcptr & 0x03) != 0) - *kptr |= temp << 4; - - if (flip) - bit = 0xc0; - else - bit = 0x0c; - break; - case 0x0c : - if ((temp = *srcptr & 0xc0) != 0) - *cptr |= temp >> 4; - if ((temp = *srcptr & 0x30) != 0) - *mptr |= temp >> 2; - if ((temp = *srcptr & 0x0c) != 0) - *yptr |= temp; - if ((temp = *srcptr & 0x03) != 0) - *kptr |= temp << 2; - - if (flip) - bit = 0x30; - else - bit = 0x03; - break; - case 0x03 : - if ((temp = *srcptr & 0xc0) != 0) - *cptr |= temp >> 6; - if ((temp = *srcptr & 0x30) != 0) - *mptr |= temp >> 4; - if ((temp = *srcptr & 0x0c) != 0) - *yptr |= temp >> 2; - if ((temp = *srcptr & 0x03) != 0) - *kptr |= temp; - - if (flip) - bit = 0x0c; - else - { - bit = 0xc0; - cptr ++; - mptr ++; - yptr ++; - kptr ++; - } - break; - } - break; - } - break; - - case 4 : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - for (x = cups->width, bit = flip && (x & 1) ? 0xf0 : 0x0f; - x > 0; - x --, srcptr += 2) - switch (bit) - { - case 0xf0 : - if ((temp = srcptr[0] & 0x0f) != 0) - *cptr |= temp << 4; - if ((temp = srcptr[1] & 0xf0) != 0) - *mptr |= temp; - if ((temp = srcptr[1] & 0x0f) != 0) - *yptr |= temp << 4; - - bit = 0x0f; - - if (flip) - { - cptr --; - mptr --; - yptr --; - } - break; - case 0x0f : - if ((temp = srcptr[0] & 0x0f) != 0) - *cptr |= temp; - if ((temp = srcptr[1] & 0xf0) != 0) - *mptr |= temp >> 4; - if ((temp = srcptr[1] & 0x0f) != 0) - *yptr |= temp; - - bit = 0xf0; - - if (!flip) - { - cptr ++; - mptr ++; - yptr ++; - } - break; - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - for (x = cups->width, bit = flip && (x & 1) ? 0xf0 : 0x0f; - x > 0; - x --, srcptr += 2) - switch (bit) - { - case 0xf0 : - if ((temp = srcptr[0] & 0xf0) != 0) - *cptr |= temp; - if ((temp = srcptr[0] & 0x0f) != 0) - *mptr |= temp << 4; - if ((temp = srcptr[1] & 0xf0) != 0) - *yptr |= temp; - if ((temp = srcptr[1] & 0x0f) != 0) - *kptr |= temp << 4; - - bit = 0x0f; - - if (flip) - { - cptr --; - mptr --; - yptr --; - kptr --; - } - break; - case 0x0f : - if ((temp = srcptr[0] & 0xf0) != 0) - *cptr |= temp >> 4; - if ((temp = srcptr[0] & 0x0f) != 0) - *mptr |= temp; - if ((temp = srcptr[1] & 0xf0) != 0) - *yptr |= temp >> 4; - if ((temp = srcptr[1] & 0x0f) != 0) - *kptr |= temp; - - bit = 0xf0; - - if (!flip) - { - cptr ++; - mptr ++; - yptr ++; - kptr ++; - } - break; - } - break; - } - break; - - case 8 : - switch (cups->header.cupsColorSpace) - { - default : - if (flip) - for (x = cups->width; x > 0; x --) - { - *cptr-- = *srcptr++; - *mptr-- = *srcptr++; - *yptr-- = *srcptr++; - } - else - for (x = cups->width; x > 0; x --) - { - *cptr++ = *srcptr++; - *mptr++ = *srcptr++; - *yptr++ = *srcptr++; - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - if (flip) - for (x = cups->width; x > 0; x --) - { - *cptr-- = *srcptr++; - *mptr-- = *srcptr++; - *yptr-- = *srcptr++; - *kptr-- = *srcptr++; - } - else - for (x = cups->width; x > 0; x --) - { - *cptr++ = *srcptr++; - *mptr++ = *srcptr++; - *yptr++ = *srcptr++; - *kptr++ = *srcptr++; - } - break; - } - break; - } - } - - /* - * Write the bitmap data to the raster stream... - */ - - cupsRasterWritePixels(cups->stream, dst, cups->header.cupsBytesPerLine); - } -} - - -/* - * 'cups_print_planar()' - Print a page of planar pixels. - */ - -static void -cups_print_planar(gx_device_printer *pdev, - /* I - Printer device */ - unsigned char *src, - /* I - Scanline buffer */ - unsigned char *dst, - /* I - Bitmap buffer */ - int srcbytes) - /* I - Number of bytes in src */ -{ - int x; /* Looping var */ - int y; /* Looping var */ - int z; /* Looping var */ - unsigned char srcbit; /* Current source bit */ - unsigned char dstbit; /* Current destination bit */ - unsigned char temp; /* Temporary variable */ - unsigned char *srcptr; /* Pointer to data */ - unsigned char *dstptr; /* Pointer to bitmap */ - - - /**** NOTE: Currently planar output doesn't support flipped duplex!!! ****/ - - /* - * Loop through the page bitmap and write planar pixels... We have - * to separate each chunked color as needed... - */ - - for (z = 0; z < pdev->color_info.num_components; z ++) - for (y = 0; y < cups->height; y ++) - { - /* - * Grab the scanline data... - */ - - if (gdev_prn_get_bits((gx_device_printer *)pdev, y, src, &srcptr) < 0) - { - fprintf(stderr, "ERROR: Unable to get scanline %d!\n", y); - gs_exit(1); - } - - /* - * Pull the individual color planes out of the pixels... - */ - - if (srcptr[0] == 0 && memcmp(srcptr, srcptr + 1, srcbytes - 1) == 0) - memset(dst, 0, cups->header.cupsBytesPerLine); - else - switch (cups->header.cupsBitsPerColor) - { - default : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - for (dstptr = dst, x = cups->width, srcbit = 64 >> z, - dstbit = 128; - x > 0; - x --) - { - if (*srcptr & srcbit) - *dstptr |= dstbit; - - if (srcbit >= 16) - srcbit >>= 4; - else - { - srcbit = 64 >> z; - srcptr ++; - } - - if (dstbit > 1) - dstbit >>= 1; - else - { - dstbit = 128; - dstptr ++; - } - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - for (dstptr = dst, x = cups->width, srcbit = 128 >> z, - dstbit = 128; - x > 0; - x --) - { - if (*srcptr & srcbit) - *dstptr |= dstbit; - - if (srcbit >= 16) - srcbit >>= 4; - else - { - srcbit = 128 >> z; - srcptr ++; - } - - if (dstbit > 1) - dstbit >>= 1; - else - { - dstbit = 128; - dstptr ++; - } - } - break; - case CUPS_CSPACE_KCMYcm : - for (dstptr = dst, x = cups->width, srcbit = 32 >> z, - dstbit = 128; - x > 0; - x --, srcptr ++) - { - if (*srcptr & srcbit) - *dstptr |= dstbit; - - if (dstbit > 1) - dstbit >>= 1; - else - { - dstbit = 128; - dstptr ++; - } - } - break; - } - break; - - case 2 : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - for (dstptr = dst, x = cups->width, srcbit = 48 >> (z * 2), - dstbit = 0xc0; - x > 0; - x --, srcptr ++) - { - if ((temp = *srcptr & srcbit) != 0) - { - if (srcbit == dstbit) - *dstptr |= temp; - else - { - switch (srcbit) - { - case 0x30 : - temp >>= 4; - break; - case 0x0c : - temp >>= 2; - break; - } - - switch (dstbit) - { - case 0xc0 : - *dstptr |= temp << 6; - break; - case 0x30 : - *dstptr |= temp << 4; - break; - case 0x0c : - *dstptr |= temp << 2; - break; - case 0x03 : - *dstptr |= temp; - break; - } - } - } - - if (dstbit > 0x03) - dstbit >>= 2; - else - { - dstbit = 0xc0; - dstptr ++; - } - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - for (dstptr = dst, x = cups->width, srcbit = 192 >> (z * 2), - dstbit = 0xc0; - x > 0; - x --, srcptr ++) - { - if ((temp = *srcptr & srcbit) != 0) - { - if (srcbit == dstbit) - *dstptr |= temp; - else - { - switch (srcbit) - { - case 0xc0 : - temp >>= 6; - break; - case 0x30 : - temp >>= 4; - break; - case 0x0c : - temp >>= 2; - break; - } - - switch (dstbit) - { - case 0xc0 : - *dstptr |= temp << 6; - break; - case 0x30 : - *dstptr |= temp << 4; - break; - case 0x0c : - *dstptr |= temp << 2; - break; - case 0x03 : - *dstptr |= temp; - break; - } - } - } - - if (dstbit > 0x03) - dstbit >>= 2; - else - { - dstbit = 0xc0; - dstptr ++; - } - } - break; - } - break; - - case 4 : - memset(dst, 0, cups->header.cupsBytesPerLine); - - switch (cups->header.cupsColorSpace) - { - default : - if (z > 0) - srcptr ++; - - if (z == 1) - srcbit = 0xf0; - else - srcbit = 0x0f; - - for (dstptr = dst, x = cups->width, dstbit = 0xf0; - x > 0; - x --, srcptr += 2) - { - if ((temp = *srcptr & srcbit) != 0) - { - if (srcbit == dstbit) - *dstptr |= temp; - else - { - if (srcbit == 0xf0) - temp >>= 4; - - if (dstbit == 0xf0) - *dstptr |= temp << 4; - else - *dstptr |= temp; - } - } - - if (dstbit == 0xf0) - dstbit = 0x0f; - else - { - dstbit = 0xf0; - dstptr ++; - } - } - break; - case CUPS_CSPACE_GMCK : - case CUPS_CSPACE_GMCS : - case CUPS_CSPACE_RGBA : - case CUPS_CSPACE_CMYK : - case CUPS_CSPACE_YMCK : - case CUPS_CSPACE_KCMY : - case CUPS_CSPACE_KCMYcm : - if (z > 1) - srcptr ++; - - if (z & 1) - srcbit = 0x0f; - else - srcbit = 0xf0; - - for (dstptr = dst, x = cups->width, dstbit = 0xf0; - x > 0; - x --, srcptr += 2) - { - if ((temp = *srcptr & srcbit) != 0) - { - if (srcbit == dstbit) - *dstptr |= temp; - else - { - if (srcbit == 0xf0) - temp >>= 4; - - if (dstbit == 0xf0) - *dstptr |= temp << 4; - else - *dstptr |= temp; - } - } - - if (dstbit == 0xf0) - dstbit = 0x0f; - else - { - dstbit = 0xf0; - dstptr ++; - } - } - break; - } - break; - - case 8 : - for (srcptr += z, dstptr = dst, x = cups->header.cupsBytesPerLine; - x > 0; - srcptr += pdev->color_info.num_components, x --) - *dstptr++ = *srcptr; - break; - } - - /* - * Write the bitmap data to the raster stream... - */ - - cupsRasterWritePixels(cups->stream, dst, cups->header.cupsBytesPerLine); - } -} - - -/* - * End of "$Id: gdevcups.c 4493 2005-02-18 02:09:53Z mike $". - */ diff --git a/pstoraster/gs707-lib.patch b/pstoraster/gs707-lib.patch deleted file mode 100644 index 32b011dd9d..0000000000 --- a/pstoraster/gs707-lib.patch +++ /dev/null @@ -1,110 +0,0 @@ -diff -u ghostscript-7.07/lib/gs_init.ps ghostscript-7.07-easysw/lib/gs_init.ps ---- ghostscript-7.07/lib/gs_init.ps 2003-04-12 10:02:38.000000000 -0400 -+++ ghostscript-7.07-easysw/lib/gs_init.ps 2003-11-14 16:38:44.000000000 -0500 -@@ -119,6 +119,7 @@ - currentdict /NOFONTPATH known /NOFONTPATH exch def - currentdict /NOGC known /NOGC exch def - currentdict /NOINTERPOLATE .knownget { /INTERPOLATE exch not def } if -+currentdict /NOMEDIAATTRS known /NOMEDIAATTRS exch def - currentdict /NOPAGEPROMPT known /NOPAGEPROMPT exch def - currentdict /NOPAUSE known /NOPAUSE exch def - currentdict /NOPLATFONTS known /NOPLATFONTS exch def -diff -u ghostscript-7.07/lib/gs_setpd.ps ghostscript-7.07-easysw/lib/gs_setpd.ps ---- ghostscript-7.07/lib/gs_setpd.ps 2003-04-12 10:02:38.000000000 -0400 -+++ ghostscript-7.07-easysw/lib/gs_setpd.ps 2003-11-14 16:38:06.000000000 -0500 -@@ -324,21 +324,42 @@ - } bind - .dicttomark readonly def - --% Define the keys used in input attribute matching. --/.inputattrkeys [ -- /PageSize /MediaColor /MediaWeight /MediaType /InsertSheet -- % The following are documented in Adobe's supplement for v2017. -- /LeadingEdge /MediaClass --] readonly def --% Define other keys used in media selection. --/.inputselectionkeys [ -- /MediaPosition /Orientation --] readonly def -- --% Define the keys used in output attribute matching. --/.outputattrkeys [ -- /OutputType --] readonly def -+% M. Sweet, Easy Software Products: -+% -+% Define NOMEDIAATTRS to turn off the default (but unimplementable) media -+% selection policies for setpagedevice. This is used by CUPS to support -+% the standard Adobe media attributes. -+NOMEDIAATTRS { -+ % Define only PageSize for input attribute matching. -+ /.inputattrkeys [ -+ /PageSize -+ ] readonly def -+ % Define no other keys used in media selection. -+ /.inputselectionkeys [ -+ /noInputSelectionsKeys -+ ] readonly def -+ -+ % Define no keys used in output attribute matching. -+ /.outputattrkeys [ -+ /noOutputAttrKeys -+ ] readonly def -+} { -+ % Define the keys used in input attribute matching. -+ /.inputattrkeys [ -+ /PageSize /MediaColor /MediaWeight /MediaType /InsertSheet -+ % The following are documented in Adobe's supplement for v2017. -+ /LeadingEdge /MediaClass -+ ] readonly def -+ % Define other keys used in media selection. -+ /.inputselectionkeys [ -+ /MediaPosition /Orientation -+ ] readonly def -+ -+ % Define the keys used in output attribute matching. -+ /.outputattrkeys [ -+ /OutputType -+ ] readonly def -+} ifelse - - % Define all the parameters that should always be copied to the merged - % dictionary. -@@ -367,7 +388,13 @@ - /PageSize false % obsolete alias for .MediaSize - /InputAttributes false - .inputattrkeys -- { dup /PageSize eq -+ % M. Sweet, Easy Software Products: -+ % -+ % Treat LeadingEdge like PageSize so that a common Ghostscript driver -+ % doesn't need the NOMEDIAATTRS definition. -+ % -+ % { dup /PageSize eq -+ { dup dup /PageSize eq exch /LeadingEdge eq or - { pop } - { { 2 index /InputAttributes .knownget { null eq } { true } ifelse } } - ifelse -@@ -442,11 +469,22 @@ - % They are expected to consume the top 2 operands. - % NOTE: we currently treat all values other than 0, 1, or 7 (for PageSize) - % the same as 0, i.e., we signal an error. -+% -+% M. Sweet, Easy Software Products: -+% -+% Define NOMEDIAATTRS to turn off the default (but unimplementable) media -+% selection policies for setpagedevice. This is used by CUPS to support -+% the standard Adobe media attributes. - 0 { % Set errorinfo and signal a configurationerror. -+ NOMEDIAATTRS { -+ % NOMEDIAATTRS means that the default policy is 7... -+ pop 2 index exch 7 put -+ } { - pop dup 4 index exch get 2 array astore - $error /errorinfo 3 -1 roll put - cleartomark - /setpagedevice load /configurationerror signalerror -+ } ifelse - } bind - 1 { % Roll back the failed request to its previous status. - DEBUG { (Rolling back.) = pstack flush } if diff --git a/pstoraster/gs811-lib.patch b/pstoraster/gs811-lib.patch deleted file mode 100644 index 9cd1253055..0000000000 --- a/pstoraster/gs811-lib.patch +++ /dev/null @@ -1,110 +0,0 @@ -diff -u ghostscript-8.11/lib/gs_init.ps ghostscript-8.11-easysw/lib/gs_init.ps ---- ghostscript-8.11/lib/gs_init.ps 2003-07-30 03:26:55.000000000 -0400 -+++ ghostscript-8.11-easysw/lib/gs_init.ps 2003-11-13 13:04:17.000000000 -0500 -@@ -139,6 +139,7 @@ - currentdict /NOFONTPATH known /NOFONTPATH exch def - currentdict /NOGC known /NOGC exch def - currentdict /NOINTERPOLATE .knownget { /INTERPOLATE exch not def } if -+currentdict /NOMEDIAATTRS known /NOMEDIAATTRS exch def - currentdict /NOOUTERSAVE known /NOOUTERSAVE exch def - currentdict /NOPAGEPROMPT known /NOPAGEPROMPT exch def - currentdict /NOPAUSE known /NOPAUSE exch def -diff -u ghostscript-8.11/lib/gs_setpd.ps ghostscript-8.11-easysw/lib/gs_setpd.ps ---- ghostscript-8.11/lib/gs_setpd.ps 2003-04-12 14:08:18.000000000 -0400 -+++ ghostscript-8.11-easysw/lib/gs_setpd.ps 2003-11-14 16:32:55.000000000 -0500 -@@ -344,21 +344,42 @@ - } bind - .dicttomark readonly def - --% Define the keys used in input attribute matching. --/.inputattrkeys [ -- /PageSize /MediaColor /MediaWeight /MediaType /InsertSheet -- % The following are documented in Adobe's supplement for v2017. -- /LeadingEdge /MediaClass --] readonly def --% Define other keys used in media selection. --/.inputselectionkeys [ -- /MediaPosition /Orientation --] readonly def -- --% Define the keys used in output attribute matching. --/.outputattrkeys [ -- /OutputType --] readonly def -+% M. Sweet, Easy Software Products: -+% -+% Define NOMEDIAATTRS to turn off the default (but unimplementable) media -+% selection policies for setpagedevice. This is used by CUPS to support -+% the standard Adobe media attributes. -+NOMEDIAATTRS { -+ % Define only PageSize for input attribute matching. -+ /.inputattrkeys [ -+ /PageSize -+ ] readonly def -+ % Define no other keys used in media selection. -+ /.inputselectionkeys [ -+ /noInputSelectionsKeys -+ ] readonly def -+ -+ % Define no keys used in output attribute matching. -+ /.outputattrkeys [ -+ /noOutputAttrKeys -+ ] readonly def -+} { -+ % Define the keys used in input attribute matching. -+ /.inputattrkeys [ -+ /PageSize /MediaColor /MediaWeight /MediaType /InsertSheet -+ % The following are documented in Adobe's supplement for v2017. -+ /LeadingEdge /MediaClass -+ ] readonly def -+ % Define other keys used in media selection. -+ /.inputselectionkeys [ -+ /MediaPosition /Orientation -+ ] readonly def -+ -+ % Define the keys used in output attribute matching. -+ /.outputattrkeys [ -+ /OutputType -+ ] readonly def -+} ifelse - - % Define all the parameters that should always be copied to the merged - % dictionary. -@@ -387,7 +408,13 @@ - /PageSize //false % obsolete alias for .MediaSize - /InputAttributes //false - .inputattrkeys -- { dup /PageSize eq -+ % M. Sweet, Easy Software Products: -+ % -+ % Treat LeadingEdge like PageSize so that a common Ghostscript driver -+ % doesn't need the NOMEDIAATTRS definition. -+ % -+ % { dup /PageSize eq -+ { dup dup /PageSize eq exch /LeadingEdge eq or - { pop } - { { 2 index /InputAttributes .knownget { //null eq } { //true } ifelse } } - ifelse -@@ -468,11 +495,22 @@ - % They are expected to consume the top 2 operands. - % NOTE: we currently treat all values other than 0, 1, or 7 (for PageSize) - % the same as 0, i.e., we signal an error. -+% -+% M. Sweet, Easy Software Products: -+% -+% Define NOMEDIAATTRS to turn off the default (but unimplementable) media -+% selection policies for setpagedevice. This is used by CUPS to support -+% the standard Adobe media attributes. - 0 { % Set errorinfo and signal a configurationerror. -+ NOMEDIAATTRS { -+ % NOMEDIAATTRS means that the default policy is 7... -+ pop 2 index exch 7 put -+ } { - pop dup 4 index exch get 2 array astore - $error /errorinfo 3 -1 roll put - cleartomark - /setpagedevice load /configurationerror signalerror -+ } ifelse - } bind - 1 { % Roll back the failed request to its previous status. - SETPDDEBUG { (Rolling back.) = pstack flush } if diff --git a/pstoraster/pstopxl b/pstoraster/pstopxl deleted file mode 100644 index 227f5f4cdb..0000000000 --- a/pstoraster/pstopxl +++ /dev/null @@ -1,67 +0,0 @@ -#!/bin/sh -# -# "$Id: pstopxl 4076 2004-02-24 21:59:13Z mike $" -# -# CUPS PCL XL/PCL 6 filter script for Ghostscript. -# -# Copyright 2001-2003 by Easy Software Products. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -# - -# Installation directories... -prefix=/usr/local -exec_prefix=${prefix} -bindir=/usr/lib/cups/filter - -# Set the library/font path... -GS_LIB="${CUPS_FONTPATH:=/usr/share/cups/fonts}" -export GS_LIB - -# Determine the PCL XL/PCL 6 driver to use... -if test "x$PPD" != x; then - colordevice=`grep '^*ColorDevice:' "$PPD" | awk -F: '{print $2}'` - case "$colordevice" in - *True* | *true*) - device="pxlcolor" - ;; - *) - device="pxlmono" - ;; - esac -else - device="pxlmono" -fi - -# Options we use with Ghostscript... -gsopts="-dQUIET -dDEBUG -dPARANOIDSAFER -dNOPAUSE -dBATCH" -gsopts="$gsopts -dNOMEDIAATTRS -sDEVICE=$device -sstdout=%stderr" - -# See if we have a filename on the command-line... -if test -z "$6"; then - ifile="-" -else - ifile="$6" -fi - -echo INFO: Starting ESP Ghostscript 7.07.1... 1>&2 -echo DEBUG: Running $bindir/gsrip $gsopts -sOUTPUTFILE="%stdout" "$ifile" 1>&2 - -# Now run Ghostscript... -$bindir/gsrip $gsopts -sOUTPUTFILE="%stdout" "$ifile" - -# -# End of "$Id: pstopxl 4076 2004-02-24 21:59:13Z mike $". -# diff --git a/pstoraster/pstopxl.in b/pstoraster/pstopxl.in deleted file mode 100755 index c57d15e0c3..0000000000 --- a/pstoraster/pstopxl.in +++ /dev/null @@ -1,67 +0,0 @@ -#!/bin/sh -# -# "$Id: pstopxl.in 4493 2005-02-18 02:09:53Z mike $" -# -# CUPS PCL XL/PCL 6 filter script for Ghostscript. -# -# Copyright 2001-2005 by Easy Software Products. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -# - -# Installation directories... -prefix=@prefix@ -exec_prefix=@exec_prefix@ -bindir=@bindir@ - -# Set the library/font path... -GS_LIB="${CUPS_FONTPATH:=/usr/share/cups/fonts}" -export GS_LIB - -# Determine the PCL XL/PCL 6 driver to use... -if test "x$PPD" != x; then - colordevice=`grep '^*ColorDevice:' "$PPD" | awk -F: '{print $2}'` - case "$colordevice" in - *True* | *true*) - device="pxlcolor" - ;; - *) - device="pxlmono" - ;; - esac -else - device="pxlmono" -fi - -# Options we use with Ghostscript... -gsopts="-dQUIET -dDEBUG -dPARANOIDSAFER -dNOPAUSE -dBATCH" -gsopts="$gsopts -dNOMEDIAATTRS -sDEVICE=$device -sstdout=%stderr" - -# See if we have a filename on the command-line... -if test -z "$6"; then - ifile="-" -else - ifile="$6" -fi - -echo INFO: Starting ESP Ghostscript 7.07.1... 1>&2 -echo DEBUG: Running $bindir/@GS@ $gsopts -sOUTPUTFILE="%stdout" "$ifile" 1>&2 - -# Now run Ghostscript... -$bindir/@GS@ $gsopts -sOUTPUTFILE="%stdout" "$ifile" - -# -# End of "$Id: pstopxl.in 4493 2005-02-18 02:09:53Z mike $". -# diff --git a/pstoraster/pstoraster b/pstoraster/pstoraster deleted file mode 100755 index e5ec266c89..0000000000 --- a/pstoraster/pstoraster +++ /dev/null @@ -1,52 +0,0 @@ -#!/bin/sh -# -# "$Id: pstoraster 4493 2005-02-18 02:09:53Z mike $" -# -# CUPS filter script for Ghostscript. -# -# Copyright 2001-2005 by Easy Software Products. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -# - -# Installation directories... -prefix=/usr/local -exec_prefix=${prefix} -bindir=${exec_prefix}/bin - -# Set the library/font path... -GS_FONTPATH="$CUPS_FONTPATH" -export GS_FONTPATH - -# Options we use with Ghostscript... -gsopts="-dQUIET -dDEBUG -dPARANOIDSAFER -dNOPAUSE -dBATCH " -gsopts="$gsopts -dNOMEDIAATTRS -sDEVICE=cups -sstdout=%stderr" - -# See if we have a profile=n,n,n,n,n,n,n,n,n,n,n option... -profile="" -for option in $5; do - case $option in - profile=*) - profile="-scupsProfile=`echo $option | awk -F= '{print $2}'`" - ;; - esac -done - -# Now run Ghostscript... -$bindir/gs $gsopts -sOUTPUTFILE="%stdout" $profile $6 - -# -# End of "$Id: pstoraster 4493 2005-02-18 02:09:53Z mike $". -# diff --git a/pstoraster/pstoraster.convs b/pstoraster/pstoraster.convs deleted file mode 100644 index 9e5f0006a3..0000000000 --- a/pstoraster/pstoraster.convs +++ /dev/null @@ -1,29 +0,0 @@ -# -# "$Id: pstoraster.convs 4493 2005-02-18 02:09:53Z mike $" -# -# MIME converts file for Ghostscript. -# -# Copyright 1997-2005 by Easy Software Products. -# -# These coded instructions, statements, and computer programs are the -# property of Easy Software Products and are protected by Federal -# copyright law. Distribution and use rights are outlined in the file -# "LICENSE.txt" which should have been included with this file. If this -# file is missing or damaged please contact Easy Software Products -# at: -# -# Attn: CUPS Licensing Information -# Easy Software Products -# 44141 Airport View Drive, Suite 204 -# Hollywood, Maryland 20636 USA -# -# Voice: (301) 373-9600 -# EMail: cups-info@cups.org -# WWW: http://www.cups.org -# - -application/vnd.cups-postscript application/vnd.cups-raster 100 pstoraster - -# -# End of "$Id: pstoraster.convs 4493 2005-02-18 02:09:53Z mike $". -# diff --git a/pstoraster/pstoraster.in b/pstoraster/pstoraster.in deleted file mode 100755 index 4019009d68..0000000000 --- a/pstoraster/pstoraster.in +++ /dev/null @@ -1,62 +0,0 @@ -#!/bin/sh -# -# "$Id: pstoraster.in 4493 2005-02-18 02:09:53Z mike $" -# -# CUPS raster filter script for Ghostscript. -# -# Copyright 2001-2005 by Easy Software Products. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -# - -# Installation directories... -prefix=@prefix@ -exec_prefix=@exec_prefix@ -bindir=@bindir@ - -# Set the library/font path... -GS_LIB="${CUPS_FONTPATH:=/usr/share/cups/fonts}" -export GS_LIB - -# Options we use with Ghostscript... -gsopts="-dQUIET -dDEBUG -dPARANOIDSAFER -dNOPAUSE -dBATCH" -gsopts="$gsopts -dNOMEDIAATTRS -sDEVICE=cups -sstdout=%stderr" - -# See if we have a profile=n,n,n,n,n,n,n,n,n,n,n option... -profile="" -for option in $5; do - case $option in - profile=*) - profile="<>setpagedevice" - ;; - esac -done - -# See if we have a filename on the command-line... -if test -z "$6"; then - ifile="-" -else - ifile="$6" -fi - -echo INFO: Starting ESP Ghostscript 7.07.1... 1>&2 -echo DEBUG: Running $bindir/@GS@ $gsopts -sOUTPUTFILE="%stdout" -c"$profile" "$ifile" 1>&2 - -# Now run Ghostscript... -$bindir/@GS@ $gsopts -sOUTPUTFILE="%stdout" -c"$profile" "$ifile" - -# -# End of "$Id: pstoraster.in 4493 2005-02-18 02:09:53Z mike $". -# diff --git a/pstoraster/pxlcolor.ppd b/pstoraster/pxlcolor.ppd deleted file mode 100644 index c7d16ecd4f..0000000000 --- a/pstoraster/pxlcolor.ppd +++ /dev/null @@ -1,205 +0,0 @@ -*PPD-Adobe: "4.3" -*% -*% "$Id: pxlcolor.ppd 4493 2005-02-18 02:09:53Z mike $" -*% -*% Sample color PCL XL/PCL 6 driver PPD file for the Common UNIX -*% Printing System (CUPS). -*% -*% Copyright 1997-2005 by Easy Software Products. -*% -*% These coded instructions, statements, and computer programs are the -*% property of Easy Software Products and are protected by Federal -*% copyright law. Distribution and use rights are outlined in the file -*% "LICENSE.txt" which should have been included with this file. If this -*% file is missing or damaged please contact Easy Software Products -*% at: -*% -*% Attn: CUPS Licensing Information -*% Easy Software Products -*% 44141 Airport View Drive, Suite 204 -*% Hollywood, Maryland 20636 USA -*% -*% Voice: (301) 373-9600 -*% EMail: cups-info@cups.org -*% WWW: http://www.cups.org -*% -*FormatVersion: "4.3" -*FileVersion: "1.1" -*LanguageVersion: English -*LanguageEncoding: ISOLatin1 -*PCFileName: "PCLCOLOR.PPD" -*Manufacturer: "ESP" -*Product: "(CUPS v1.1)" -*cupsVersion: 1.1 -*cupsManualCopies: False -*cupsFilter: "application/vnd.cups-postscript 0 pstopxl" -*ModelName: "HP Color LaserJet Series PCL 6" -*ShortNickName: "HP Color LaserJet Series PCL 6" -*NickName: "HP Color LaserJet Series PCL 6 CUPS v1.1" -*PSVersion: "(3010.000) 707" -*LanguageLevel: "3" -*ColorDevice: True -*DefaultColorSpace: RGB -*FileSystem: False -*Throughput: "8" -*LandscapeOrientation: Plus90 -*TTRasterizer: Type42 - -*UIConstraints: *PageSize Executive *InputSlot Envelope -*UIConstraints: *PageSize Letter *InputSlot Envelope -*UIConstraints: *PageSize Legal *InputSlot Envelope -*UIConstraints: *PageSize Tabloid *InputSlot Envelope -*UIConstraints: *PageSize A3 *InputSlot Envelope -*UIConstraints: *PageSize A4 *InputSlot Envelope -*UIConstraints: *PageSize A5 *InputSlot Envelope -*UIConstraints: *PageSize B5 *InputSlot Envelope -*UIConstraints: *Duplex *Option1 False - -*OpenUI *PageSize/Media Size: PickOne -*OrderDependency: 10 AnySetup *PageSize -*DefaultPageSize: Letter -*PageSize Letter/US Letter: "<>setpagedevice" -*PageSize Legal/US Legal: "<>setpagedevice" -*PageSize Executive/US Executive: "<>setpagedevice" -*PageSize Tabloid/US Tabloid: "<>setpagedevice" -*PageSize A3/A3: "<>setpagedevice" -*PageSize A4/A4: "<>setpagedevice" -*PageSize A5/A5: "<>setpagedevice" -*PageSize B5/B5 (JIS): "<>setpagedevice" -*PageSize EnvISOB5/Envelope B5: "<>setpagedevice" -*PageSize Env10/Envelope #10: "<>setpagedevice" -*PageSize EnvC5/Envelope C5: "<>setpagedevice" -*PageSize EnvDL/Envelope DL: "<>setpagedevice" -*PageSize EnvMonarch/Envelope Monarch: "<>setpagedevice" -*CloseUI: *PageSize - -*OpenUI *PageRegion: PickOne -*OrderDependency: 10 AnySetup *PageRegion -*DefaultPageRegion: Letter -*PageRegion Letter/US Letter: "<>setpagedevice" -*PageRegion Legal/US Legal: "<>setpagedevice" -*PageRegion Executive/US Executive: "<>setpagedevice" -*PageRegion Tabloid/US Tabloid: "<>setpagedevice" -*PageRegion A3/A3: "<>setpagedevice" -*PageRegion A4/A4: "<>setpagedevice" -*PageRegion A5/A5: "<>setpagedevice" -*PageRegion B5/B5 (JIS): "<>setpagedevice" -*PageRegion EnvISOB5/Envelope B5: "<>setpagedevice" -*PageRegion Env10/Envelope #10: "<>setpagedevice" -*PageRegion EnvC5/Envelope C5: "<>setpagedevice" -*PageRegion EnvDL/Envelope DL: "<>setpagedevice" -*PageRegion EnvMonarch/Envelope Monarch: "<>setpagedevice" -*CloseUI: *PageRegion - -*DefaultImageableArea: Letter -*ImageableArea Letter/US Letter: "12 12 600 780" -*ImageableArea Legal/US Legal: "12 12 600 996" -*ImageableArea Executive/US Executive: "12 12 510 708" -*ImageableArea Tabloid/US Tabloid: "12 12 780 1212" -*ImageableArea A3/A3: "12 12 830 1179" -*ImageableArea A4/A4: "12 12 583 830" -*ImageableArea A5/A5: "12 12 409 583" -*ImageableArea B5/JIS B5: "12 12 504 717" -*ImageableArea EnvISOB5/B5 (ISO): "12 12 469 697" -*ImageableArea Env10/Com-10: "12 12 285 672" -*ImageableArea EnvC5/EnvC5: "12 12 447 637" -*ImageableArea EnvDL/EnvDL: "12 12 300 612" -*ImageableArea EnvMonarch/Envelope Monarch: "12 12 267 528" - -*DefaultPaperDimension: Letter -*PaperDimension Letter/US Letter: "612 792" -*PaperDimension Legal/US Legal: "612 1008" -*PaperDimension Executive/US Executive: "522 756" -*PaperDimension Tabloid/US Tabloid: "792 1224" -*PaperDimension A3/A3: "842 1191" -*PaperDimension A4/A4: "595 842" -*PaperDimension A5/A5: "421 595" -*PaperDimension B5/B5 (JIS): "516 729" -*PaperDimension EnvISOB5/Envelope B5: "499 709" -*PaperDimension Env10/Envelope #10: "297 684" -*PaperDimension EnvC5/Envelope C5: "459 649" -*PaperDimension EnvDL/Envelope DL: "312 624" -*PaperDimension EnvMonarch/Envelope Monarch: "279 540" - -*OpenUI *InputSlot/Media Source: PickOne -*OrderDependency: 10 AnySetup *InputSlot -*DefaultInputSlot: Default -*InputSlot Default/Default: "<>setpagedevice" -*InputSlot Tray1/Tray 1: "<>setpagedevice" -*InputSlot Tray2/Tray 2: "<>setpagedevice" -*InputSlot Tray3/Tray 3: "<>setpagedevice" -*InputSlot Tray4/Tray 4: "<>setpagedevice" -*InputSlot Manual/Manual Feed: "<>setpagedevice" -*InputSlot Envelope/Envelope Feed: "<>setpagedevice" -*CloseUI: *InputSlot - -*OpenUI *ColorModel/Output Mode: PickOne -*OrderDependency: 10 AnySetup *ColorModel -*DefaultColorModel: RGB -*ColorModel RGB/Color: "<>setpagedevice" -*ColorModel Gray/Grayscale: "<>setpagedevice" -*CloseUI: *ColorModel - -*OpenUI *Resolution/Output Resolution: PickOne -*OrderDependency: 20 AnySetup *Resolution -*DefaultResolution: 300dpi -*Resolution 150dpi/150 DPI: "<>setpagedevice" -*Resolution 300dpi/300 DPI: "<>setpagedevice" -*Resolution 600dpi/600 DPI: "<>setpagedevice" -*CloseUI: *Resolution - -*OpenUI *Duplex/Double-Sided Printing: PickOne -*OrderDependency: 20 AnySetup *Duplex -*DefaultDuplex: None -*Duplex None/Off: "<>setpagedevice" -*Duplex DuplexNoTumble/Long Edge (Standard): "<>setpagedevice" -*Duplex DuplexTumble/Short Edge (Flip): "<>setpagedevice" -*CloseUI: *Duplex - -*OpenGroup: InstallableOptions -*OpenUI *Option1/Duplexer: Boolean -*DefaultOption1: False -*Option1 True/Installed: "" -*Option1 False/Not Installed: "" -*CloseUI: *Option1 -*CloseGroup: InstallableOptions - -*DefaultFont: Courier -*Font AvantGarde-Book: Standard "(001.006S)" Standard ROM -*Font AvantGarde-BookOblique: Standard "(001.006S)" Standard ROM -*Font AvantGarde-Demi: Standard "(001.007S)" Standard ROM -*Font AvantGarde-DemiOblique: Standard "(001.007S)" Standard ROM -*Font Bookman-Demi: Standard "(001.004S)" Standard ROM -*Font Bookman-DemiItalic: Standard "(001.004S)" Standard ROM -*Font Bookman-Light: Standard "(001.004S)" Standard ROM -*Font Bookman-LightItalic: Standard "(001.004S)" Standard ROM -*Font Courier: Standard "(002.004S)" Standard ROM -*Font Courier-Bold: Standard "(002.004S)" Standard ROM -*Font Courier-BoldOblique: Standard "(002.004S)" Standard ROM -*Font Courier-Oblique: Standard "(002.004S)" Standard ROM -*Font Helvetica: Standard "(001.006S)" Standard ROM -*Font Helvetica-Bold: Standard "(001.007S)" Standard ROM -*Font Helvetica-BoldOblique: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow: Standard "(001.006S)" Standard ROM -*Font Helvetica-Narrow-Bold: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow-BoldOblique: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow-Oblique: Standard "(001.006S)" Standard ROM -*Font Helvetica-Oblique: Standard "(001.006S)" Standard ROM -*Font NewCenturySchlbk-Bold: Standard "(001.009S)" Standard ROM -*Font NewCenturySchlbk-BoldItalic: Standard "(001.007S)" Standard ROM -*Font NewCenturySchlbk-Italic: Standard "(001.006S)" Standard ROM -*Font NewCenturySchlbk-Roman: Standard "(001.007S)" Standard ROM -*Font Palatino-Bold: Standard "(001.005S)" Standard ROM -*Font Palatino-BoldItalic: Standard "(001.005S)" Standard ROM -*Font Palatino-Italic: Standard "(001.005S)" Standard ROM -*Font Palatino-Roman: Standard "(001.005S)" Standard ROM -*Font Symbol: Special "(001.007S)" Special ROM -*Font Times-Bold: Standard "(001.007S)" Standard ROM -*Font Times-BoldItalic: Standard "(001.009S)" Standard ROM -*Font Times-Italic: Standard "(001.007S)" Standard ROM -*Font Times-Roman: Standard "(001.007S)" Standard ROM -*Font ZapfChancery-MediumItalic: Standard "(001.007S)" Standard ROM -*Font ZapfDingbats: Special "(001.004S)" Standard ROM -*% -*% End of "$Id: pxlcolor.ppd 4493 2005-02-18 02:09:53Z mike $". -*% diff --git a/pstoraster/pxlmono.ppd b/pstoraster/pxlmono.ppd deleted file mode 100644 index 1870ca0bbc..0000000000 --- a/pstoraster/pxlmono.ppd +++ /dev/null @@ -1,199 +0,0 @@ -*PPD-Adobe: "4.3" -*% -*% "$Id: pxlmono.ppd 4493 2005-02-18 02:09:53Z mike $" -*% -*% Sample monochrome PCL XL/PCL 6 driver PPD file for the Common UNIX -*% Printing System (CUPS). -*% -*% Copyright 1997-2005 by Easy Software Products. -*% -*% These coded instructions, statements, and computer programs are the -*% property of Easy Software Products and are protected by Federal -*% copyright law. Distribution and use rights are outlined in the file -*% "LICENSE.txt" which should have been included with this file. If this -*% file is missing or damaged please contact Easy Software Products -*% at: -*% -*% Attn: CUPS Licensing Information -*% Easy Software Products -*% 44141 Airport View Drive, Suite 204 -*% Hollywood, Maryland 20636 USA -*% -*% Voice: (301) 373-9600 -*% EMail: cups-info@cups.org -*% WWW: http://www.cups.org -*% -*FormatVersion: "4.3" -*FileVersion: "1.1" -*LanguageVersion: English -*LanguageEncoding: ISOLatin1 -*PCFileName: "PCLMONO.PPD" -*Manufacturer: "ESP" -*Product: "(CUPS v1.1)" -*cupsVersion: 1.1 -*cupsManualCopies: False -*cupsFilter: "application/vnd.cups-postscript 0 pstopxl" -*ModelName: "HP LaserJet Series PCL 6" -*ShortNickName: "HP LaserJet Series PCL 6" -*NickName: "HP LaserJet Series PCL 6 CUPS v1.1" -*PSVersion: "(3010.000) 707" -*LanguageLevel: "3" -*ColorDevice: False -*DefaultColorSpace: Gray -*FileSystem: False -*Throughput: "8" -*LandscapeOrientation: Plus90 -*TTRasterizer: Type42 - -*UIConstraints: *PageSize Executive *InputSlot Envelope -*UIConstraints: *PageSize Letter *InputSlot Envelope -*UIConstraints: *PageSize Legal *InputSlot Envelope -*UIConstraints: *PageSize Tabloid *InputSlot Envelope -*UIConstraints: *PageSize A3 *InputSlot Envelope -*UIConstraints: *PageSize A4 *InputSlot Envelope -*UIConstraints: *PageSize A5 *InputSlot Envelope -*UIConstraints: *PageSize B5 *InputSlot Envelope -*UIConstraints: *Duplex *Option1 False - -*OpenUI *PageSize/Media Size: PickOne -*OrderDependency: 10 AnySetup *PageSize -*DefaultPageSize: Letter -*PageSize Letter/US Letter: "<>setpagedevice" -*PageSize Legal/US Legal: "<>setpagedevice" -*PageSize Executive/US Executive: "<>setpagedevice" -*PageSize Tabloid/US Tabloid: "<>setpagedevice" -*PageSize A3/A3: "<>setpagedevice" -*PageSize A4/A4: "<>setpagedevice" -*PageSize A5/A5: "<>setpagedevice" -*PageSize B5/B5 (JIS): "<>setpagedevice" -*PageSize EnvISOB5/Envelope B5: "<>setpagedevice" -*PageSize Env10/Envelope #10: "<>setpagedevice" -*PageSize EnvC5/Envelope C5: "<>setpagedevice" -*PageSize EnvDL/Envelope DL: "<>setpagedevice" -*PageSize EnvMonarch/Envelope Monarch: "<>setpagedevice" -*CloseUI: *PageSize - -*OpenUI *PageRegion: PickOne -*OrderDependency: 10 AnySetup *PageRegion -*DefaultPageRegion: Letter -*PageRegion Letter/US Letter: "<>setpagedevice" -*PageRegion Legal/US Legal: "<>setpagedevice" -*PageRegion Executive/US Executive: "<>setpagedevice" -*PageRegion Tabloid/US Tabloid: "<>setpagedevice" -*PageRegion A3/A3: "<>setpagedevice" -*PageRegion A4/A4: "<>setpagedevice" -*PageRegion A5/A5: "<>setpagedevice" -*PageRegion B5/B5 (JIS): "<>setpagedevice" -*PageRegion EnvISOB5/Envelope B5: "<>setpagedevice" -*PageRegion Env10/Envelope #10: "<>setpagedevice" -*PageRegion EnvC5/Envelope C5: "<>setpagedevice" -*PageRegion EnvDL/Envelope DL: "<>setpagedevice" -*PageRegion EnvMonarch/Envelope Monarch: "<>setpagedevice" -*CloseUI: *PageRegion - -*DefaultImageableArea: Letter -*ImageableArea Letter/US Letter: "12 12 600 780" -*ImageableArea Legal/US Legal: "12 12 600 996" -*ImageableArea Executive/US Executive: "12 12 510 708" -*ImageableArea Tabloid/US Tabloid: "12 12 780 1212" -*ImageableArea A3/A3: "12 12 830 1179" -*ImageableArea A4/A4: "12 12 583 830" -*ImageableArea A5/A5: "12 12 409 583" -*ImageableArea B5/JIS B5: "12 12 504 717" -*ImageableArea EnvISOB5/B5 (ISO): "12 12 469 697" -*ImageableArea Env10/Com-10: "12 12 285 672" -*ImageableArea EnvC5/EnvC5: "12 12 447 637" -*ImageableArea EnvDL/EnvDL: "12 12 300 612" -*ImageableArea EnvMonarch/Envelope Monarch: "12 12 267 528" - -*DefaultPaperDimension: Letter -*PaperDimension Letter/US Letter: "612 792" -*PaperDimension Legal/US Legal: "612 1008" -*PaperDimension Executive/US Executive: "522 756" -*PaperDimension Tabloid/US Tabloid: "792 1224" -*PaperDimension A3/A3: "842 1191" -*PaperDimension A4/A4: "595 842" -*PaperDimension A5/A5: "421 595" -*PaperDimension B5/B5 (JIS): "516 729" -*PaperDimension EnvISOB5/Envelope B5: "499 709" -*PaperDimension Env10/Envelope #10: "297 684" -*PaperDimension EnvC5/Envelope C5: "459 649" -*PaperDimension EnvDL/Envelope DL: "312 624" -*PaperDimension EnvMonarch/Envelope Monarch: "279 540" - -*OpenUI *InputSlot/Media Source: PickOne -*OrderDependency: 10 AnySetup *InputSlot -*DefaultInputSlot: Default -*InputSlot Default/Default: "<>setpagedevice" -*InputSlot Tray1/Tray 1: "<>setpagedevice" -*InputSlot Tray2/Tray 2: "<>setpagedevice" -*InputSlot Tray3/Tray 3: "<>setpagedevice" -*InputSlot Tray4/Tray 4: "<>setpagedevice" -*InputSlot Manual/Manual Feed: "<>setpagedevice" -*InputSlot Envelope/Envelope Feed: "<>setpagedevice" -*CloseUI: *InputSlot - -*OpenUI *Resolution/Output Resolution: PickOne -*OrderDependency: 20 AnySetup *Resolution -*DefaultResolution: 600dpi -*Resolution 150dpi/150 DPI: "<>setpagedevice" -*Resolution 300dpi/300 DPI: "<>setpagedevice" -*Resolution 600dpi/600 DPI: "<>setpagedevice" -*Resolution 1200dpi/1200 DPI: "<>setpagedevice" -*CloseUI: *Resolution - -*OpenUI *Duplex/Double-Sided Printing: PickOne -*OrderDependency: 20 AnySetup *Duplex -*DefaultDuplex: None -*Duplex None/Off: "<>setpagedevice" -*Duplex DuplexNoTumble/Long Edge (Standard): "<>setpagedevice" -*Duplex DuplexTumble/Short Edge (Flip): "<>setpagedevice" -*CloseUI: *Duplex - -*OpenGroup: InstallableOptions -*OpenUI *Option1/Duplexer: Boolean -*DefaultOption1: False -*Option1 True/Installed: "" -*Option1 False/Not Installed: "" -*CloseUI: *Option1 -*CloseGroup: InstallableOptions - -*DefaultFont: Courier -*Font AvantGarde-Book: Standard "(001.006S)" Standard ROM -*Font AvantGarde-BookOblique: Standard "(001.006S)" Standard ROM -*Font AvantGarde-Demi: Standard "(001.007S)" Standard ROM -*Font AvantGarde-DemiOblique: Standard "(001.007S)" Standard ROM -*Font Bookman-Demi: Standard "(001.004S)" Standard ROM -*Font Bookman-DemiItalic: Standard "(001.004S)" Standard ROM -*Font Bookman-Light: Standard "(001.004S)" Standard ROM -*Font Bookman-LightItalic: Standard "(001.004S)" Standard ROM -*Font Courier: Standard "(002.004S)" Standard ROM -*Font Courier-Bold: Standard "(002.004S)" Standard ROM -*Font Courier-BoldOblique: Standard "(002.004S)" Standard ROM -*Font Courier-Oblique: Standard "(002.004S)" Standard ROM -*Font Helvetica: Standard "(001.006S)" Standard ROM -*Font Helvetica-Bold: Standard "(001.007S)" Standard ROM -*Font Helvetica-BoldOblique: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow: Standard "(001.006S)" Standard ROM -*Font Helvetica-Narrow-Bold: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow-BoldOblique: Standard "(001.007S)" Standard ROM -*Font Helvetica-Narrow-Oblique: Standard "(001.006S)" Standard ROM -*Font Helvetica-Oblique: Standard "(001.006S)" Standard ROM -*Font NewCenturySchlbk-Bold: Standard "(001.009S)" Standard ROM -*Font NewCenturySchlbk-BoldItalic: Standard "(001.007S)" Standard ROM -*Font NewCenturySchlbk-Italic: Standard "(001.006S)" Standard ROM -*Font NewCenturySchlbk-Roman: Standard "(001.007S)" Standard ROM -*Font Palatino-Bold: Standard "(001.005S)" Standard ROM -*Font Palatino-BoldItalic: Standard "(001.005S)" Standard ROM -*Font Palatino-Italic: Standard "(001.005S)" Standard ROM -*Font Palatino-Roman: Standard "(001.005S)" Standard ROM -*Font Symbol: Special "(001.007S)" Special ROM -*Font Times-Bold: Standard "(001.007S)" Standard ROM -*Font Times-BoldItalic: Standard "(001.009S)" Standard ROM -*Font Times-Italic: Standard "(001.007S)" Standard ROM -*Font Times-Roman: Standard "(001.007S)" Standard ROM -*Font ZapfChancery-MediumItalic: Standard "(001.007S)" Standard ROM -*Font ZapfDingbats: Special "(001.004S)" Standard ROM -*% -*% End of "$Id: pxlmono.ppd 4493 2005-02-18 02:09:53Z mike $". -*% diff --git a/scheduler/auth.c b/scheduler/auth.c index bee2ad395c..7843fe15b3 100644 --- a/scheduler/auth.c +++ b/scheduler/auth.c @@ -1,5 +1,5 @@ /* - * "$Id: auth.c 5197 2006-02-27 21:30:20Z mike $" + * "$Id: auth.c 5222 2006-03-03 18:57:56Z mike $" * * Authorization routines for the Common UNIX Printing System (CUPS). * @@ -1618,7 +1618,7 @@ cupsdIsAuthorized(cupsd_client_t *con, /* I - Connection */ if (!strcasecmp(con->http.hostname, "localhost")) { /* - * Access from localhost (127.0.0.1 or :::1) is always allowed... + * Access from localhost (127.0.0.1 or ::1) is always allowed... */ auth = AUTH_ALLOW; @@ -2156,5 +2156,5 @@ to64(char *s, /* O - Output string */ /* - * End of "$Id: auth.c 5197 2006-02-27 21:30:20Z mike $". + * End of "$Id: auth.c 5222 2006-03-03 18:57:56Z mike $". */ diff --git a/scheduler/auth.h b/scheduler/auth.h index 2d4dcb3268..e18f8defa6 100644 --- a/scheduler/auth.h +++ b/scheduler/auth.h @@ -1,5 +1,5 @@ /* - * "$Id: auth.h 5069 2006-02-04 05:24:35Z mike $" + * "$Id: auth.h 5222 2006-03-03 18:57:56Z mike $" * * Authorization definitions for the Common UNIX Printing System (CUPS) * scheduler. @@ -125,6 +125,10 @@ VAR cups_array_t *Locations VALUE(NULL); /* Authorization locations */ VAR int DefaultAuthType VALUE(AUTH_BASIC); /* Default AuthType, if not specified */ +#ifdef HAVE_SSL +VAR http_encryption_t DefaultEncryption VALUE(HTTP_ENCRYPT_REQUIRED); + /* Default encryption for authentication */ +#endif /* HAVE_SSL */ /* @@ -156,5 +160,5 @@ extern http_status_t cupsdIsAuthorized(cupsd_client_t *con, const char *owner); /* - * End of "$Id: auth.h 5069 2006-02-04 05:24:35Z mike $". + * End of "$Id: auth.h 5222 2006-03-03 18:57:56Z mike $". */ diff --git a/scheduler/cert.c b/scheduler/cert.c index 195db7842e..91c2af888f 100644 --- a/scheduler/cert.c +++ b/scheduler/cert.c @@ -1,5 +1,5 @@ /* - * "$Id: cert.c 5080 2006-02-05 18:28:27Z mike $" + * "$Id: cert.c 5213 2006-03-02 00:37:34Z mike $" * * Authentication certificate routines for the Common UNIX * Printing System (CUPS). @@ -174,7 +174,7 @@ cupsdAddCert(int pid, /* I - Process ID */ /* Others */ acl_create_entry(&acl, &entry); acl_get_permset(entry, &permset); - acl_add_perm(permset, ACL_READ); + acl_add_perm(permset, 0); acl_set_tag_type(entry, ACL_OTHER); acl_set_permset(entry, permset); @@ -415,5 +415,5 @@ cupsdInitCerts(void) /* - * End of "$Id: cert.c 5080 2006-02-05 18:28:27Z mike $". + * End of "$Id: cert.c 5213 2006-03-02 00:37:34Z mike $". */ diff --git a/scheduler/client.c b/scheduler/client.c index c9ae16f010..f9226223d5 100644 --- a/scheduler/client.c +++ b/scheduler/client.c @@ -1,5 +1,5 @@ /* - * "$Id: client.c 5200 2006-02-28 00:10:32Z mike $" + * "$Id: client.c 5225 2006-03-04 12:28:10Z mike $" * * Client routines for the Common UNIX Printing System (CUPS) scheduler. * @@ -41,6 +41,7 @@ * get_file() - Get a filename and state info. * install_conf_file() - Install a configuration file. * is_path_absolute() - Is a path absolute and free of relative elements. + * make_certificate() - Make a self-signed SSL/TLS certificate. * pipe_command() - Pipe the output of a command to the remote client. */ @@ -54,6 +55,9 @@ #ifdef HAVE_CDSASSL # include #endif /* HAVE_CDSASSL */ +#ifdef HAVE_GNUTLS +# include +#endif /* HAVE_GNUTLS */ /* @@ -69,6 +73,9 @@ static char *get_file(cupsd_client_t *con, struct stat *filestats, char *filename, int len); static http_status_t install_conf_file(cupsd_client_t *con); static int is_path_absolute(const char *path); +#ifdef HAVE_GNUTLS +static void make_certificate(void); +#endif /* HAVE_GNUTLS */ static int pipe_command(cupsd_client_t *con, int infile, int *outfile, char *command, char *options, int root); @@ -698,6 +705,20 @@ cupsdEncryptClient(cupsd_client_t *con) /* I - Client to encrypt */ gnutls_certificate_server_credentials *credentials; /* TLS credentials */ + + /* + * Verify that we have a certificate... + */ + + if (access(ServerKey, 0) || access(ServerCertificate, 0)) + { + /* + * Nope, make a self-signed certificate... + */ + + make_certificate(); + } + /* * Create the SSL object and perform the SSL handshake... */ @@ -727,7 +748,7 @@ cupsdEncryptClient(cupsd_client_t *con) /* I - Client to encrypt */ gnutls_init(&(conn->session), GNUTLS_SERVER); gnutls_set_default_priority(conn->session); gnutls_credentials_set(conn->session, GNUTLS_CRD_CERTIFICATE, *credentials); - gnutls_transport_set_ptr(conn->session, con->http.fd); + gnutls_transport_set_ptr(conn->session, (gnutls_transport_ptr)con->http.fd); error = gnutls_handshake(conn->session); @@ -2256,6 +2277,23 @@ int /* O - 1 if successful, 0 otherwise */ cupsdSendError(cupsd_client_t *con, /* I - Connection */ http_status_t code) /* I - Error code */ { +#ifdef HAVE_SSL + /* + * Force client to upgrade for authentication if that is how the + * server is configured... + */ + + if (code == HTTP_UNAUTHORIZED && + DefaultEncryption == HTTP_ENCRYPT_REQUIRED && + strcasecmp(con->http.hostname, "localhost") && + !con->http.tls) + { + cupsdLogMessage(CUPSD_LOG_DEBUG2, + "cupsdSendError: Encryption before authentication!"); + code = HTTP_UPGRADE_REQUIRED; + } +#endif /* HAVE_SSL */ + /* * Put the request in the access_log file... */ @@ -2416,12 +2454,20 @@ cupsdSendHeader(cupsd_client_t *con, /* I - Client to send to */ http_status_t code, /* I - HTTP status code */ char *type) /* I - MIME type of document */ { + /* + * Send the HTTP status header... + */ + if (httpPrintf(HTTP(con), "HTTP/%d.%d %d %s\r\n", con->http.version / 100, con->http.version % 100, code, httpStatus(code)) < 0) return (0); if (code == HTTP_CONTINUE) { + /* + * 100-continue doesn't send any headers... + */ + if (httpPrintf(HTTP(con), "\r\n") < 0) return (0); else @@ -2589,17 +2635,19 @@ cupsdWriteClient(cupsd_client_t *con) /* I - Client connection */ if (!strncasecmp(buf, "Location:", 9)) cupsdSendHeader(con, HTTP_SEE_OTHER, NULL); else if (!strncasecmp(buf, "Status:", 7)) - cupsdSendHeader(con, atoi(buf + 7), NULL); + cupsdSendError(con, atoi(buf + 7)); else + { cupsdSendHeader(con, HTTP_OK, NULL); - if (con->http.version == HTTP_1_1) - { - con->http.data_encoding = HTTP_ENCODE_CHUNKED; + if (con->http.version == HTTP_1_1) + { + con->http.data_encoding = HTTP_ENCODE_CHUNKED; - if (httpPrintf(HTTP(con), "Transfer-Encoding: chunked\r\n") < 0) - return (0); - } + if (httpPrintf(HTTP(con), "Transfer-Encoding: chunked\r\n") < 0) + return (0); + } + } con->sent_header = 1; } @@ -2646,26 +2694,26 @@ cupsdWriteClient(cupsd_client_t *con) /* I - Client connection */ return (1); } else if (bytes == 0) - { con->http.activity = time(NULL); - return (1); - } } - if (httpWrite2(HTTP(con), buf, bytes) < 0) + if (bytes > 0) { - cupsdLogMessage(CUPSD_LOG_DEBUG2, - "cupsdWriteClient: %d Write of %d bytes failed!", - con->http.fd, bytes); + if (httpWrite2(HTTP(con), buf, bytes) < 0) + { + cupsdLogMessage(CUPSD_LOG_DEBUG2, + "cupsdWriteClient: %d Write of %d bytes failed!", + con->http.fd, bytes); - cupsdCloseClient(con); - return (0); - } + cupsdCloseClient(con); + return (0); + } - con->bytes += bytes; + con->bytes += bytes; - if (con->http.state == HTTP_WAITING) - bytes = 0; + if (con->http.state == HTTP_WAITING) + bytes = 0; + } } if (bytes <= 0) @@ -3247,6 +3295,148 @@ is_path_absolute(const char *path) /* I - Input path */ } +#ifdef HAVE_GNUTLS +/* + * 'make_certificate()' - Make a self-signed SSL/TLS certificate. + */ + +static void +make_certificate(void) +{ + gnutls_x509_crt crt; /* Self-signed certificate */ + gnutls_x509_privkey key; /* Encryption key */ + cups_lang_t *language; /* Default language info */ + cups_file_t *fp; /* Key/cert file */ + unsigned char buffer[8192]; /* Buffer for x509 data */ + size_t bytes; /* Number of bytes of data */ + unsigned char serial[4]; /* Serial number buffer */ + time_t curtime; /* Current time */ + int result; /* Result of GNU TLS calls */ + + + /* + * Create the encryption key... + */ + + cupsdLogMessage(CUPSD_LOG_INFO, "Generating server key..."); + + gnutls_x509_privkey_init(&key); + gnutls_x509_privkey_generate(key, GNUTLS_PK_RSA, 2048, 0); + + /* + * Save it... + */ + + bytes = sizeof(buffer); + + if ((result = gnutls_x509_privkey_export(key, GNUTLS_X509_FMT_PEM, + buffer, &bytes)) < 0) + { + cupsdLogMessage(CUPSD_LOG_ERROR, "Unable to export server key - %s", + gnutls_strerror(result)); + gnutls_x509_privkey_deinit(key); + return; + } + else if ((fp = cupsFileOpen(ServerKey, "w")) != NULL) + { + cupsFileWrite(fp, (char *)buffer, bytes); + cupsFileClose(fp); + + cupsdLogMessage(CUPSD_LOG_INFO, "Created server key file \"%s\"...", + ServerKey); + } + else + { + cupsdLogMessage(CUPSD_LOG_ERROR, + "Unable to create server key file \"%s\" - %s", + ServerKey, strerror(errno)); + gnutls_x509_privkey_deinit(key); + return; + } + + /* + * Create the self-signed certificate... + */ + + cupsdLogMessage(CUPSD_LOG_INFO, "Generating self-signed certificate..."); + + language = cupsLangDefault(); + curtime = time(NULL); + serial[0] = curtime >> 24; + serial[1] = curtime >> 16; + serial[2] = curtime >> 8; + serial[3] = curtime; + + gnutls_x509_crt_init(&crt); + if (strlen(language->language) == 5) + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_COUNTRY_NAME, 0, + language->language + 3, 2); + else + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_COUNTRY_NAME, 0, + "US", 2); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_COMMON_NAME, 0, + ServerName, strlen(ServerName)); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_ORGANIZATION_NAME, 0, + ServerName, strlen(ServerName)); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_ORGANIZATIONAL_UNIT_NAME, + 0, "Unknown", 7); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_STATE_OR_PROVINCE_NAME, 0, + "Unknown", 7); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_X520_LOCALITY_NAME, 0, + "Unknown", 7); + gnutls_x509_crt_set_dn_by_oid(crt, GNUTLS_OID_PKCS9_EMAIL, 0, + ServerAdmin, strlen(ServerAdmin)); + gnutls_x509_crt_set_key(crt, key); + gnutls_x509_crt_set_serial(crt, serial, sizeof(serial)); + gnutls_x509_crt_set_activation_time(crt, curtime); + gnutls_x509_crt_set_expiration_time(crt, curtime + 10 * 365 * 86400); + gnutls_x509_crt_set_ca_status(crt, 0); + gnutls_x509_crt_set_subject_alternative_name(crt, GNUTLS_SAN_DNSNAME, + ServerName); + gnutls_x509_crt_set_key_purpose_oid(crt, GNUTLS_KP_TLS_WWW_SERVER, 0); + gnutls_x509_crt_set_key_usage(crt, GNUTLS_KEY_KEY_ENCIPHERMENT); + gnutls_x509_crt_set_version(crt, 3); + + bytes = sizeof(buffer); + if (gnutls_x509_crt_get_key_id(crt, 0, buffer, &bytes) >= 0) + gnutls_x509_crt_set_subject_key_id(crt, buffer, bytes); + + gnutls_x509_crt_sign(crt, crt, key); + + /* + * Save it... + */ + + bytes = sizeof(buffer); + if ((result = gnutls_x509_crt_export(crt, GNUTLS_X509_FMT_PEM, + buffer, &bytes)) < 0) + cupsdLogMessage(CUPSD_LOG_ERROR, + "Unable to export server certificate - %s", + gnutls_strerror(result)); + else if ((fp = cupsFileOpen(ServerCertificate, "w")) != NULL) + { + cupsFileWrite(fp, (char *)buffer, bytes); + cupsFileClose(fp); + + cupsdLogMessage(CUPSD_LOG_INFO, + "Created 10-year server certificate file \"%s\"...", + ServerCertificate); + } + else + cupsdLogMessage(CUPSD_LOG_ERROR, + "Unable to create server certificate file \"%s\" - %s", + ServerCertificate, strerror(errno)); + + /* + * Cleanup... + */ + + gnutls_x509_crt_deinit(crt); + gnutls_x509_privkey_deinit(key); +} +#endif /* HAVE_GNUTLS */ + + /* * 'pipe_command()' - Pipe the output of a command to the remote client. */ @@ -3569,5 +3759,5 @@ pipe_command(cupsd_client_t *con, /* I - Client connection */ /* - * End of "$Id: client.c 5200 2006-02-28 00:10:32Z mike $". + * End of "$Id: client.c 5225 2006-03-04 12:28:10Z mike $". */ diff --git a/scheduler/conf.c b/scheduler/conf.c index cc8c782b40..ccb02579ca 100644 --- a/scheduler/conf.c +++ b/scheduler/conf.c @@ -1,5 +1,5 @@ /* - * "$Id: conf.c 5167 2006-02-25 02:11:44Z mike $" + * "$Id: conf.c 5222 2006-03-03 18:57:56Z mike $" * * Configuration routines for the Common UNIX Printing System (CUPS). * @@ -152,7 +152,6 @@ static cupsd_var_t variables[] = { "RemoteRoot", &RemoteRoot, CUPSD_VARTYPE_STRING }, { "RequestRoot", &RequestRoot, CUPSD_VARTYPE_STRING }, { "RIPCache", &RIPCache, CUPSD_VARTYPE_STRING }, - { "RunAsUser", &RunAsUser, CUPSD_VARTYPE_BOOLEAN }, { "RootCertDuration", &RootCertDuration, CUPSD_VARTYPE_INTEGER }, { "ServerAdmin", &ServerAdmin, CUPSD_VARTYPE_STRING }, { "ServerBin", &ServerBin, CUPSD_VARTYPE_STRING }, @@ -363,6 +362,9 @@ cupsdReadConfiguration(void) ConfigFilePerm = CUPS_DEFAULT_CONFIG_FILE_PERM; DefaultAuthType = AUTH_BASIC; +#ifdef HAVE_SSL + DefaultEncryption = HTTP_ENCRYPT_REQUIRED; +#endif /* HAVE_SSL */ JobRetryLimit = 5; JobRetryInterval = 300; FileDevice = FALSE; @@ -385,7 +387,6 @@ cupsdReadConfiguration(void) MaxRequestSize = 0; ReloadTimeout = 60; RootCertDuration = 300; - RunAsUser = FALSE; Timeout = DEFAULT_TIMEOUT; NumSystemGroups = 0; @@ -446,10 +447,7 @@ cupsdReadConfiguration(void) if (!status) return (0); - if (RunAsUser) - RunUser = User; - else - RunUser = getuid(); + RunUser = getuid(); /* * Use the default system group if none was supplied in cupsd.conf... @@ -2672,6 +2670,28 @@ read_configuration(cups_file_t *fp) /* I - File to read from */ return (0); } } +#ifdef HAVE_SSL + else if (!strcasecmp(line, "DefaultEncryption")) + { + /* + * DefaultEncryption {Never,IfRequested,Required} + */ + + if (!value || !strcasecmp(value, "never")) + DefaultEncryption = HTTP_ENCRYPT_NEVER; + else if (!strcasecmp(value, "required")) + DefaultEncryption = HTTP_ENCRYPT_REQUIRED; + else if (!strcasecmp(value, "ifrequested")) + DefaultEncryption = HTTP_ENCRYPT_IF_REQUESTED; + else + { + cupsdLogMessage(CUPSD_LOG_WARN, + "Unknown default encryption %s on line %d.", + value, linenum); + return (0); + } + } +#endif /* HAVE_SSL */ else if (!strcasecmp(line, "User")) { /* @@ -3217,5 +3237,5 @@ read_policy(cups_file_t *fp, /* I - Configuration file */ /* - * End of "$Id: conf.c 5167 2006-02-25 02:11:44Z mike $". + * End of "$Id: conf.c 5222 2006-03-03 18:57:56Z mike $". */ diff --git a/scheduler/conf.h b/scheduler/conf.h index ee151148cf..7b6eea95c0 100644 --- a/scheduler/conf.h +++ b/scheduler/conf.h @@ -1,5 +1,5 @@ /* - * "$Id: conf.h 5200 2006-02-28 00:10:32Z mike $" + * "$Id: conf.h 5216 2006-03-02 17:47:53Z mike $" * * Configuration file definitions for the Common UNIX Printing System (CUPS) * scheduler. @@ -160,8 +160,6 @@ VAR int ClassifyOverride VALUE(0), /* Timeout before reload from SIGHUP */ RootCertDuration VALUE(300), /* Root certificate update interval */ - RunAsUser VALUE(FALSE), - /* Run as unpriviledged user? */ RunUser, /* User to run as, used for files */ PrintcapFormat VALUE(PRINTCAP_BSD), /* Format of printcap file? */ @@ -212,5 +210,5 @@ extern int cupsdLogPage(cupsd_job_t *job, const char *page); /* - * End of "$Id: conf.h 5200 2006-02-28 00:10:32Z mike $". + * End of "$Id: conf.h 5216 2006-03-02 17:47:53Z mike $". */ diff --git a/scheduler/cups-lpd.c b/scheduler/cups-lpd.c index eda350c526..e5b5460503 100644 --- a/scheduler/cups-lpd.c +++ b/scheduler/cups-lpd.c @@ -1,5 +1,5 @@ /* - * "$Id: cups-lpd.c 5196 2006-02-27 21:23:00Z mike $" + * "$Id: cups-lpd.c 5204 2006-02-28 20:32:43Z mike $" * * Line Printer Daemon interface for the Common UNIX Printing System (CUPS). * @@ -732,8 +732,6 @@ get_printer(http_t *http, /* I - HTTP connection */ CFRelease(plist); } - - CFRelease(prefsok); } CFRelease(prefsurl); @@ -1708,5 +1706,5 @@ smart_gets(char *s, /* I - Pointer to line buffer */ /* - * End of "$Id: cups-lpd.c 5196 2006-02-27 21:23:00Z mike $". + * End of "$Id: cups-lpd.c 5204 2006-02-28 20:32:43Z mike $". */ diff --git a/scheduler/dirsvc.c b/scheduler/dirsvc.c index f4c72b9ece..9cb76dfd4b 100644 --- a/scheduler/dirsvc.c +++ b/scheduler/dirsvc.c @@ -1,5 +1,5 @@ /* - * "$Id: dirsvc.c 5178 2006-02-26 00:24:23Z mike $" + * "$Id: dirsvc.c 5223 2006-03-04 01:10:17Z mike $" * * Directory services routines for the Common UNIX Printing System (CUPS). * @@ -641,10 +641,11 @@ cupsdSendBrowseDelete( cupsd_printer_t *p) /* I - Printer to delete */ { /* - * Only announce if browsing is enabled... + * Only announce if browsing is enabled and this is a local queue... */ - if (!Browsing || !p->shared) + if (!Browsing || !p->shared || + (p->type & (CUPS_PRINTER_REMOTE | CUPS_PRINTER_IMPLICIT))) return; /* @@ -843,8 +844,8 @@ cupsdSendCUPSBrowse(cupsd_printer_t *p) /* I - Printer to send */ * printer-make-and-model attributes... */ - dequote(location, p->location, sizeof(p->location)); - dequote(info, p->info, sizeof(p->info)); + dequote(location, p->location, sizeof(location)); + dequote(info, p->info, sizeof(info)); dequote(make_model, p->make_model ? p->make_model : "Unknown", sizeof(make_model)); @@ -3110,5 +3111,5 @@ slp_url_callback( /* - * End of "$Id: dirsvc.c 5178 2006-02-26 00:24:23Z mike $". + * End of "$Id: dirsvc.c 5223 2006-03-04 01:10:17Z mike $". */ diff --git a/scheduler/main.c b/scheduler/main.c index 018fba69af..b0b581cdec 100644 --- a/scheduler/main.c +++ b/scheduler/main.c @@ -1,5 +1,5 @@ /* - * "$Id: main.c 5157 2006-02-23 20:58:57Z mike $" + * "$Id: main.c 5216 2006-03-02 17:47:53Z mike $" * * Scheduler main loop for the Common UNIX Printing System (CUPS). * @@ -428,11 +428,7 @@ main(int argc, /* I - Number of command-line args */ */ #ifdef HAVE_SIGSET /* Use System V signals over POSIX to avoid bugs */ - if (RunAsUser) - sigset(SIGHUP, sigterm_handler); - else - sigset(SIGHUP, sighup_handler); - + sigset(SIGHUP, sighup_handler); sigset(SIGPIPE, SIG_IGN); sigset(SIGTERM, sigterm_handler); #elif defined(HAVE_SIGACTION) @@ -440,12 +436,7 @@ main(int argc, /* I - Number of command-line args */ sigemptyset(&action.sa_mask); sigaddset(&action.sa_mask, SIGHUP); - - if (RunAsUser) - action.sa_handler = sigterm_handler; - else - action.sa_handler = sighup_handler; - + action.sa_handler = sighup_handler; sigaction(SIGHUP, &action, NULL); sigemptyset(&action.sa_mask); @@ -458,11 +449,7 @@ main(int argc, /* I - Number of command-line args */ action.sa_handler = sigterm_handler; sigaction(SIGTERM, &action, NULL); #else - if (RunAsUser) - signal(SIGHUP, sigterm_handler); - else - signal(SIGHUP, sighup_handler); - + signal(SIGHUP, sighup_handler); signal(SIGPIPE, SIG_IGN); signal(SIGTERM, sigterm_handler); #endif /* HAVE_SIGSET */ @@ -520,18 +507,6 @@ main(int argc, /* I - Number of command-line args */ cupsdStartSystemMonitor(); - /* - * If the administrator has configured the server to run as an unpriviledged - * user, change to that user now... - */ - - if (RunAsUser) - { - setgid(Group); - setgroups(1, &Group); - setuid(User); - } - /* * Catch signals... */ @@ -2338,5 +2313,5 @@ usage(int status) /* O - Exit status */ /* - * End of "$Id: main.c 5157 2006-02-23 20:58:57Z mike $". + * End of "$Id: main.c 5216 2006-03-02 17:47:53Z mike $". */ diff --git a/standards/rfc4122.txt b/standards/rfc4122.txt new file mode 100644 index 0000000000..31ceaab4b6 --- /dev/null +++ b/standards/rfc4122.txt @@ -0,0 +1,1795 @@ + + + + + + +Network Working Group P. Leach +Request for Comments: 4122 Microsoft +Category: Standards Track M. Mealling + Refactored Networks, LLC + R. Salz + DataPower Technology, Inc. + July 2005 + + + A Universally Unique IDentifier (UUID) URN Namespace + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + This specification defines a Uniform Resource Name namespace for + UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally + Unique IDentifier). A UUID is 128 bits long, and can guarantee + uniqueness across space and time. UUIDs were originally used in the + Apollo Network Computing System and later in the Open Software + Foundation's (OSF) Distributed Computing Environment (DCE), and then + in Microsoft Windows platforms. + + This specification is derived from the DCE specification with the + kind permission of the OSF (now known as The Open Group). + Information from earlier versions of the DCE specification have been + incorporated into this document. + + + + + + + + + + + + + + +Leach, et al. Standards Track [Page 1] + +RFC 4122 A UUID URN Namespace July 2005 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Namespace Registration Template . . . . . . . . . . . . . . . 3 + 4. Specification . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.1. Format. . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.1.1. Variant. . . . . . . . . . . . . . . . . . . . . . 6 + 4.1.2. Layout and Byte Order. . . . . . . . . . . . . . . 6 + 4.1.3. Version. . . . . . . . . . . . . . . . . . . . . . 7 + 4.1.4. Timestamp. . . . . . . . . . . . . . . . . . . . . 8 + 4.1.5. Clock Sequence . . . . . . . . . . . . . . . . . . 8 + 4.1.6. Node . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.1.7. Nil UUID . . . . . . . . . . . . . . . . . . . . . 9 + 4.2. Algorithms for Creating a Time-Based UUID . . . . . . . . 9 + 4.2.1. Basic Algorithm. . . . . . . . . . . . . . . . . . 10 + 4.2.2. Generation Details . . . . . . . . . . . . . . . . 12 + 4.3. Algorithm for Creating a Name-Based UUID. . . . . . . . . 13 + 4.4. Algorithms for Creating a UUID from Truly Random or + Pseudo-Random Numbers . . . . . . . . . . . . . . . . . . 14 + 4.5. Node IDs that Do Not Identify the Host. . . . . . . . . . 15 + 5. Community Considerations . . . . . . . . . . . . . . . . . . . 15 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 + 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 + 8. Normative References . . . . . . . . . . . . . . . . . . . . . 16 + A. Appendix A - Sample Implementation . . . . . . . . . . . . . . 18 + B. Appendix B - Sample Output of utest . . . . . . . . . . . . . 29 + C. Appendix C - Some Name Space IDs . . . . . . . . . . . . . . . 30 + +1. Introduction + + This specification defines a Uniform Resource Name namespace for + UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally + Unique IDentifier). A UUID is 128 bits long, and requires no central + registration process. + + The information here is meant to be a concise guide for those wishing + to implement services using UUIDs as URNs. Nothing in this document + should be construed to override the DCE standards that defined UUIDs. + + There is an ITU-T Recommendation and ISO/IEC Standard [3] that are + derived from earlier versions of this document. Both sets of + specifications have been aligned, and are fully technically + compatible. In addition, a global registration function is being + provided by the Telecommunications Standardisation Bureau of ITU-T; + for details see . + + + + + +Leach, et al. Standards Track [Page 2] + +RFC 4122 A UUID URN Namespace July 2005 + + +2. Motivation + + One of the main reasons for using UUIDs is that no centralized + authority is required to administer them (although one format uses + IEEE 802 node identifiers, others do not). As a result, generation + on demand can be completely automated, and used for a variety of + purposes. The UUID generation algorithm described here supports very + high allocation rates of up to 10 million per second per machine if + necessary, so that they could even be used as transaction IDs. + + UUIDs are of a fixed size (128 bits) which is reasonably small + compared to other alternatives. This lends itself well to sorting, + ordering, and hashing of all sorts, storing in databases, simple + allocation, and ease of programming in general. + + Since UUIDs are unique and persistent, they make excellent Uniform + Resource Names. The unique ability to generate a new UUID without a + registration process allows for UUIDs to be one of the URNs with the + lowest minting cost. + +3. Namespace Registration Template + + Namespace ID: UUID + Registration Information: + Registration date: 2003-10-01 + + Declared registrant of the namespace: + JTC 1/SC6 (ASN.1 Rapporteur Group) + + Declaration of syntactic structure: + A UUID is an identifier that is unique across both space and time, + with respect to the space of all UUIDs. Since a UUID is a fixed + size and contains a time field, it is possible for values to + rollover (around A.D. 3400, depending on the specific algorithm + used). A UUID can be used for multiple purposes, from tagging + objects with an extremely short lifetime, to reliably identifying + very persistent objects across a network. + + The internal representation of a UUID is a specific sequence of + bits in memory, as described in Section 4. To accurately + represent a UUID as a URN, it is necessary to convert the bit + sequence to a string representation. + + Each field is treated as an integer and has its value printed as a + zero-filled hexadecimal digit string with the most significant + digit first. The hexadecimal values "a" through "f" are output as + lower case characters and are case insensitive on input. + + + + +Leach, et al. Standards Track [Page 3] + +RFC 4122 A UUID URN Namespace July 2005 + + + The formal definition of the UUID string representation is + provided by the following ABNF [7]: + + UUID = time-low "-" time-mid "-" + time-high-and-version "-" + clock-seq-and-reserved + clock-seq-low "-" node + time-low = 4hexOctet + time-mid = 2hexOctet + time-high-and-version = 2hexOctet + clock-seq-and-reserved = hexOctet + clock-seq-low = hexOctet + node = 6hexOctet + hexOctet = hexDigit hexDigit + hexDigit = + "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" / + "a" / "b" / "c" / "d" / "e" / "f" / + "A" / "B" / "C" / "D" / "E" / "F" + + The following is an example of the string representation of a UUID as + a URN: + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 + + Relevant ancillary documentation: + [1][2] + Identifier uniqueness considerations: + This document specifies three algorithms to generate UUIDs: the + first leverages the unique values of 802 MAC addresses to + guarantee uniqueness, the second uses pseudo-random number + generators, and the third uses cryptographic hashing and + application-provided text strings. As a result, the UUIDs + generated according to the mechanisms here will be unique from all + other UUIDs that have been or will be assigned. + + Identifier persistence considerations: + UUIDs are inherently very difficult to resolve in a global sense. + This, coupled with the fact that UUIDs are temporally unique + within their spatial context, ensures that UUIDs will remain as + persistent as possible. + + Process of identifier assignment: + Generating a UUID does not require that a registration authority + be contacted. One algorithm requires a unique value over space + for each generator. This value is typically an IEEE 802 MAC + address, usually already available on network-connected hosts. + The address can be assigned from an address block obtained from + the IEEE registration authority. If no such address is available, + + + +Leach, et al. Standards Track [Page 4] + +RFC 4122 A UUID URN Namespace July 2005 + + + or privacy concerns make its use undesirable, Section 4.5 + specifies two alternatives. Another approach is to use version 3 + or version 4 UUIDs as defined below. + + Process for identifier resolution: + Since UUIDs are not globally resolvable, this is not applicable. + + Rules for Lexical Equivalence: + Consider each field of the UUID to be an unsigned integer as shown + in the table in section Section 4.1.2. Then, to compare a pair of + UUIDs, arithmetically compare the corresponding fields from each + UUID in order of significance and according to their data type. + Two UUIDs are equal if and only if all the corresponding fields + are equal. + + As an implementation note, equality comparison can be performed on + many systems by doing the appropriate byte-order canonicalization, + and then treating the two UUIDs as 128-bit unsigned integers. + + UUIDs, as defined in this document, can also be ordered + lexicographically. For a pair of UUIDs, the first one follows the + second if the most significant field in which the UUIDs differ is + greater for the first UUID. The second precedes the first if the + most significant field in which the UUIDs differ is greater for + the second UUID. + + Conformance with URN Syntax: + The string representation of a UUID is fully compatible with the + URN syntax. When converting from a bit-oriented, in-memory + representation of a UUID into a URN, care must be taken to + strictly adhere to the byte order issues mentioned in the string + representation section. + + Validation mechanism: + Apart from determining whether the timestamp portion of the UUID + is in the future and therefore not yet assignable, there is no + mechanism for determining whether a UUID is 'valid'. + + Scope: + UUIDs are global in scope. + +4. Specification + +4.1. Format + + The UUID format is 16 octets; some bits of the eight octet variant + field specified below determine finer structure. + + + + +Leach, et al. Standards Track [Page 5] + +RFC 4122 A UUID URN Namespace July 2005 + + +4.1.1. Variant + + The variant field determines the layout of the UUID. That is, the + interpretation of all other bits in the UUID depends on the setting + of the bits in the variant field. As such, it could more accurately + be called a type field; we retain the original term for + compatibility. The variant field consists of a variable number of + the most significant bits of octet 8 of the UUID. + + The following table lists the contents of the variant field, where + the letter "x" indicates a "don't-care" value. + + Msb0 Msb1 Msb2 Description + + 0 x x Reserved, NCS backward compatibility. + + 1 0 x The variant specified in this document. + + 1 1 0 Reserved, Microsoft Corporation backward + compatibility + + 1 1 1 Reserved for future definition. + + Interoperability, in any form, with variants other than the one + defined here is not guaranteed, and is not likely to be an issue in + practice. + +4.1.2. Layout and Byte Order + + To minimize confusion about bit assignments within octets, the UUID + record definition is defined only in terms of fields that are + integral numbers of octets. The fields are presented with the most + significant one first. + + Field Data Type Octet Note + # + + time_low unsigned 32 0-3 The low field of the + bit integer timestamp + + time_mid unsigned 16 4-5 The middle field of the + bit integer timestamp + + time_hi_and_version unsigned 16 6-7 The high field of the + bit integer timestamp multiplexed + with the version number + + + + + +Leach, et al. Standards Track [Page 6] + +RFC 4122 A UUID URN Namespace July 2005 + + + clock_seq_hi_and_rese unsigned 8 8 The high field of the + rved bit integer clock sequence + multiplexed with the + variant + + clock_seq_low unsigned 8 9 The low field of the + bit integer clock sequence + + node unsigned 48 10-15 The spatially unique + bit integer node identifier + + In the absence of explicit application or presentation protocol + specification to the contrary, a UUID is encoded as a 128-bit object, + as follows: + + The fields are encoded as 16 octets, with the sizes and order of the + fields defined above, and with each field encoded with the Most + Significant Byte first (known as network byte order). Note that the + field names, particularly for multiplexed fields, follow historical + practice. + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | time_low | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | time_mid | time_hi_and_version | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |clk_seq_hi_res | clk_seq_low | node (0-1) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | node (2-5) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +4.1.3. Version + + The version number is in the most significant 4 bits of the time + stamp (bits 4 through 7 of the time_hi_and_version field). + + The following table lists the currently-defined versions for this + UUID variant. + + Msb0 Msb1 Msb2 Msb3 Version Description + + 0 0 0 1 1 The time-based version + specified in this document. + + 0 0 1 0 2 DCE Security version, with + embedded POSIX UIDs. + + + +Leach, et al. Standards Track [Page 7] + +RFC 4122 A UUID URN Namespace July 2005 + + + 0 0 1 1 3 The name-based version + specified in this document + that uses MD5 hashing. + + 0 1 0 0 4 The randomly or pseudo- + randomly generated version + specified in this document. + + 0 1 0 1 5 The name-based version + specified in this document + that uses SHA-1 hashing. + + The version is more accurately a sub-type; again, we retain the term + for compatibility. + +4.1.4. Timestamp + + The timestamp is a 60-bit value. For UUID version 1, this is + represented by Coordinated Universal Time (UTC) as a count of 100- + nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of + Gregorian reform to the Christian calendar). + + For systems that do not have UTC available, but do have the local + time, they may use that instead of UTC, as long as they do so + consistently throughout the system. However, this is not recommended + since generating the UTC from local time only needs a time zone + offset. + + For UUID version 3 or 5, the timestamp is a 60-bit value constructed + from a name as described in Section 4.3. + + For UUID version 4, the timestamp is a randomly or pseudo-randomly + generated 60-bit value, as described in Section 4.4. + +4.1.5. Clock Sequence + + For UUID version 1, the clock sequence is used to help avoid + duplicates that could arise when the clock is set backwards in time + or if the node ID changes. + + If the clock is set backwards, or might have been set backwards + (e.g., while the system was powered off), and the UUID generator can + not be sure that no UUIDs were generated with timestamps larger than + the value to which the clock was set, then the clock sequence has to + be changed. If the previous value of the clock sequence is known, it + can just be incremented; otherwise it should be set to a random or + high-quality pseudo-random value. + + + + +Leach, et al. Standards Track [Page 8] + +RFC 4122 A UUID URN Namespace July 2005 + + + Similarly, if the node ID changes (e.g., because a network card has + been moved between machines), setting the clock sequence to a random + number minimizes the probability of a duplicate due to slight + differences in the clock settings of the machines. If the value of + clock sequence associated with the changed node ID were known, then + the clock sequence could just be incremented, but that is unlikely. + + The clock sequence MUST be originally (i.e., once in the lifetime of + a system) initialized to a random number to minimize the correlation + across systems. This provides maximum protection against node + identifiers that may move or switch from system to system rapidly. + The initial value MUST NOT be correlated to the node identifier. + + For UUID version 3 or 5, the clock sequence is a 14-bit value + constructed from a name as described in Section 4.3. + + For UUID version 4, clock sequence is a randomly or pseudo-randomly + generated 14-bit value as described in Section 4.4. + +4.1.6. Node + + For UUID version 1, the node field consists of an IEEE 802 MAC + address, usually the host address. For systems with multiple IEEE + 802 addresses, any available one can be used. The lowest addressed + octet (octet number 10) contains the global/local bit and the + unicast/multicast bit, and is the first octet of the address + transmitted on an 802.3 LAN. + + For systems with no IEEE address, a randomly or pseudo-randomly + generated value may be used; see Section 4.5. The multicast bit must + be set in such addresses, in order that they will never conflict with + addresses obtained from network cards. + + For UUID version 3 or 5, the node field is a 48-bit value constructed + from a name as described in Section 4.3. + + For UUID version 4, the node field is a randomly or pseudo-randomly + generated 48-bit value as described in Section 4.4. + +4.1.7. Nil UUID + + The nil UUID is special form of UUID that is specified to have all + 128 bits set to zero. + +4.2. Algorithms for Creating a Time-Based UUID + + Various aspects of the algorithm for creating a version 1 UUID are + discussed in the following sections. + + + +Leach, et al. Standards Track [Page 9] + +RFC 4122 A UUID URN Namespace July 2005 + + +4.2.1. Basic Algorithm + + The following algorithm is simple, correct, and inefficient: + + o Obtain a system-wide global lock + + o From a system-wide shared stable store (e.g., a file), read the + UUID generator state: the values of the timestamp, clock sequence, + and node ID used to generate the last UUID. + + o Get the current time as a 60-bit count of 100-nanosecond intervals + since 00:00:00.00, 15 October 1582. + + o Get the current node ID. + + o If the state was unavailable (e.g., non-existent or corrupted), or + the saved node ID is different than the current node ID, generate + a random clock sequence value. + + o If the state was available, but the saved timestamp is later than + the current timestamp, increment the clock sequence value. + + o Save the state (current timestamp, clock sequence, and node ID) + back to the stable store. + + o Release the global lock. + + o Format a UUID from the current timestamp, clock sequence, and node + ID values according to the steps in Section 4.2.2. + + If UUIDs do not need to be frequently generated, the above algorithm + may be perfectly adequate. For higher performance requirements, + however, issues with the basic algorithm include: + + o Reading the state from stable storage each time is inefficient. + + o The resolution of the system clock may not be 100-nanoseconds. + + o Writing the state to stable storage each time is inefficient. + + o Sharing the state across process boundaries may be inefficient. + + Each of these issues can be addressed in a modular fashion by local + improvements in the functions that read and write the state and read + the clock. We address each of them in turn in the following + sections. + + + + + +Leach, et al. Standards Track [Page 10] + +RFC 4122 A UUID URN Namespace July 2005 + + +4.2.1.1. Reading Stable Storage + + The state only needs to be read from stable storage once at boot + time, if it is read into a system-wide shared volatile store (and + updated whenever the stable store is updated). + + If an implementation does not have any stable store available, then + it can always say that the values were unavailable. This is the + least desirable implementation because it will increase the frequency + of creation of new clock sequence numbers, which increases the + probability of duplicates. + + If the node ID can never change (e.g., the net card is inseparable + from the system), or if any change also reinitializes the clock + sequence to a random value, then instead of keeping it in stable + store, the current node ID may be returned. + +4.2.1.2. System Clock Resolution + + The timestamp is generated from the system time, whose resolution may + be less than the resolution of the UUID timestamp. + + If UUIDs do not need to be frequently generated, the timestamp can + simply be the system time multiplied by the number of 100-nanosecond + intervals per system time interval. + + If a system overruns the generator by requesting too many UUIDs + within a single system time interval, the UUID service MUST either + return an error, or stall the UUID generator until the system clock + catches up. + + A high resolution timestamp can be simulated by keeping a count of + the number of UUIDs that have been generated with the same value of + the system time, and using it to construct the low order bits of the + timestamp. The count will range between zero and the number of + 100-nanosecond intervals per system time interval. + + Note: If the processors overrun the UUID generation frequently, + additional node identifiers can be allocated to the system, which + will permit higher speed allocation by making multiple UUIDs + potentially available for each time stamp value. + +4.2.1.3. Writing Stable Storage + + The state does not always need to be written to stable store every + time a UUID is generated. The timestamp in the stable store can be + periodically set to a value larger than any yet used in a UUID. As + long as the generated UUIDs have timestamps less than that value, and + + + +Leach, et al. Standards Track [Page 11] + +RFC 4122 A UUID URN Namespace July 2005 + + + the clock sequence and node ID remain unchanged, only the shared + volatile copy of the state needs to be updated. Furthermore, if the + timestamp value in stable store is in the future by less than the + typical time it takes the system to reboot, a crash will not cause a + reinitialization of the clock sequence. + +4.2.1.4. Sharing State Across Processes + + If it is too expensive to access shared state each time a UUID is + generated, then the system-wide generator can be implemented to + allocate a block of time stamps each time it is called; a per- + process generator can allocate from that block until it is exhausted. + +4.2.2. Generation Details + + Version 1 UUIDs are generated according to the following algorithm: + + o Determine the values for the UTC-based timestamp and clock + sequence to be used in the UUID, as described in Section 4.2.1. + + o For the purposes of this algorithm, consider the timestamp to be a + 60-bit unsigned integer and the clock sequence to be a 14-bit + unsigned integer. Sequentially number the bits in a field, + starting with zero for the least significant bit. + + o Set the time_low field equal to the least significant 32 bits + (bits zero through 31) of the timestamp in the same order of + significance. + + o Set the time_mid field equal to bits 32 through 47 from the + timestamp in the same order of significance. + + o Set the 12 least significant bits (bits zero through 11) of the + time_hi_and_version field equal to bits 48 through 59 from the + timestamp in the same order of significance. + + o Set the four most significant bits (bits 12 through 15) of the + time_hi_and_version field to the 4-bit version number + corresponding to the UUID version being created, as shown in the + table above. + + o Set the clock_seq_low field to the eight least significant bits + (bits zero through 7) of the clock sequence in the same order of + significance. + + + + + + + +Leach, et al. Standards Track [Page 12] + +RFC 4122 A UUID URN Namespace July 2005 + + + o Set the 6 least significant bits (bits zero through 5) of the + clock_seq_hi_and_reserved field to the 6 most significant bits + (bits 8 through 13) of the clock sequence in the same order of + significance. + + o Set the two most significant bits (bits 6 and 7) of the + clock_seq_hi_and_reserved to zero and one, respectively. + + o Set the node field to the 48-bit IEEE address in the same order of + significance as the address. + +4.3. Algorithm for Creating a Name-Based UUID + + The version 3 or 5 UUID is meant for generating UUIDs from "names" + that are drawn from, and unique within, some "name space". The + concept of name and name space should be broadly construed, and not + limited to textual names. For example, some name spaces are the + domain name system, URLs, ISO Object IDs (OIDs), X.500 Distinguished + Names (DNs), and reserved words in a programming language. The + mechanisms or conventions used for allocating names and ensuring + their uniqueness within their name spaces are beyond the scope of + this specification. + + The requirements for these types of UUIDs are as follows: + + o The UUIDs generated at different times from the same name in the + same namespace MUST be equal. + + o The UUIDs generated from two different names in the same namespace + should be different (with very high probability). + + o The UUIDs generated from the same name in two different namespaces + should be different with (very high probability). + + o If two UUIDs that were generated from names are equal, then they + were generated from the same name in the same namespace (with very + high probability). + + The algorithm for generating a UUID from a name and a name space are + as follows: + + o Allocate a UUID to use as a "name space ID" for all UUIDs + generated from names in that name space; see Appendix C for some + pre-defined values. + + o Choose either MD5 [4] or SHA-1 [8] as the hash algorithm; If + backward compatibility is not an issue, SHA-1 is preferred. + + + + +Leach, et al. Standards Track [Page 13] + +RFC 4122 A UUID URN Namespace July 2005 + + + o Convert the name to a canonical sequence of octets (as defined by + the standards or conventions of its name space); put the name + space ID in network byte order. + + o Compute the hash of the name space ID concatenated with the name. + + o Set octets zero through 3 of the time_low field to octets zero + through 3 of the hash. + + o Set octets zero and one of the time_mid field to octets 4 and 5 of + the hash. + + o Set octets zero and one of the time_hi_and_version field to octets + 6 and 7 of the hash. + + o Set the four most significant bits (bits 12 through 15) of the + time_hi_and_version field to the appropriate 4-bit version number + from Section 4.1.3. + + o Set the clock_seq_hi_and_reserved field to octet 8 of the hash. + + o Set the two most significant bits (bits 6 and 7) of the + clock_seq_hi_and_reserved to zero and one, respectively. + + o Set the clock_seq_low field to octet 9 of the hash. + + o Set octets zero through five of the node field to octets 10 + through 15 of the hash. + + o Convert the resulting UUID to local byte order. + +4.4. Algorithms for Creating a UUID from Truly Random or + Pseudo-Random Numbers + + The version 4 UUID is meant for generating UUIDs from truly-random or + pseudo-random numbers. + + The algorithm is as follows: + + o Set the two most significant bits (bits 6 and 7) of the + clock_seq_hi_and_reserved to zero and one, respectively. + + o Set the four most significant bits (bits 12 through 15) of the + time_hi_and_version field to the 4-bit version number from + Section 4.1.3. + + o Set all the other bits to randomly (or pseudo-randomly) chosen + values. + + + +Leach, et al. Standards Track [Page 14] + +RFC 4122 A UUID URN Namespace July 2005 + + + See Section 4.5 for a discussion on random numbers. + +4.5. Node IDs that Do Not Identify the Host + + This section describes how to generate a version 1 UUID if an IEEE + 802 address is not available, or its use is not desired. + + One approach is to contact the IEEE and get a separate block of + addresses. At the time of writing, the application could be found at + , and the cost + was US$550. + + A better solution is to obtain a 47-bit cryptographic quality random + number and use it as the low 47 bits of the node ID, with the least + significant bit of the first octet of the node ID set to one. This + bit is the unicast/multicast bit, which will never be set in IEEE 802 + addresses obtained from network cards. Hence, there can never be a + conflict between UUIDs generated by machines with and without network + cards. (Recall that the IEEE 802 spec talks about transmission + order, which is the opposite of the in-memory representation that is + discussed in this document.) + + For compatibility with earlier specifications, note that this + document uses the unicast/multicast bit, instead of the arguably more + correct local/global bit. + + Advice on generating cryptographic-quality random numbers can be + found in RFC1750 [5]. + + In addition, items such as the computer's name and the name of the + operating system, while not strictly speaking random, will help + differentiate the results from those obtained by other systems. + + The exact algorithm to generate a node ID using these data is system + specific, because both the data available and the functions to obtain + them are often very system specific. A generic approach, however, is + to accumulate as many sources as possible into a buffer, use a + message digest such as MD5 [4] or SHA-1 [8], take an arbitrary 6 + bytes from the hash value, and set the multicast bit as described + above. + +5. Community Considerations + + The use of UUIDs is extremely pervasive in computing. They comprise + the core identifier infrastructure for many operating systems + (Microsoft Windows) and applications (the Mozilla browser) and in + many cases, become exposed to the Web in many non-standard ways. + + + + +Leach, et al. Standards Track [Page 15] + +RFC 4122 A UUID URN Namespace July 2005 + + + This specification attempts to standardize that practice as openly as + possible and in a way that attempts to benefit the entire Internet. + +6. Security Considerations + + Do not assume that UUIDs are hard to guess; they should not be used + as security capabilities (identifiers whose mere possession grants + access), for example. A predictable random number source will + exacerbate the situation. + + Do not assume that it is easy to determine if a UUID has been + slightly transposed in order to redirect a reference to another + object. Humans do not have the ability to easily check the integrity + of a UUID by simply glancing at it. + + Distributed applications generating UUIDs at a variety of hosts must + be willing to rely on the random number source at all hosts. If this + is not feasible, the namespace variant should be used. + +7. Acknowledgments + + This document draws heavily on the OSF DCE specification for UUIDs. + Ted Ts'o provided helpful comments, especially on the byte ordering + section which we mostly plagiarized from a proposed wording he + supplied (all errors in that section are our responsibility, + however). + + We are also grateful to the careful reading and bit-twiddling of Ralf + S. Engelschall, John Larmouth, and Paul Thorpe. Professor Larmouth + was also invaluable in achieving coordination with ISO/IEC. + +8. Normative References + + [1] Zahn, L., Dineen, T., and P. Leach, "Network Computing + Architecture", ISBN 0-13-611674-4, January 1990. + + [2] "DCE: Remote Procedure Call", Open Group CAE Specification C309, + ISBN 1-85912-041-5, August 1994. + + [3] ISO/IEC 9834-8:2004 Information Technology, "Procedures for the + operation of OSI Registration Authorities: Generation and + registration of Universally Unique Identifiers (UUIDs) and their + use as ASN.1 Object Identifier components" ITU-T Rec. X.667, + 2004. + + [4] Rivest, R., "The MD5 Message-Digest Algorithm ", RFC 1321, April + 1992. + + + + +Leach, et al. Standards Track [Page 16] + +RFC 4122 A UUID URN Namespace July 2005 + + + [5] Eastlake, D., 3rd, Schiller, J., and S. Crocker, "Randomness + Requirements for Security", BCP 106, RFC 4086, June 2005. + + [6] Moats, R., "URN Syntax", RFC 2141, May 1997. + + [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [8] National Institute of Standards and Technology, "Secure Hash + Standard", FIPS PUB 180-1, April 1995, + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leach, et al. Standards Track [Page 17] + +RFC 4122 A UUID URN Namespace July 2005 + + +Appendix A. Appendix A - Sample Implementation + + This implementation consists of 5 files: uuid.h, uuid.c, sysdep.h, + sysdep.c and utest.c. The uuid.* files are the system independent + implementation of the UUID generation algorithms described above, + with all the optimizations described above except efficient state + sharing across processes included. The code has been tested on Linux + (Red Hat 4.0) with GCC (2.7.2), and Windows NT 4.0 with VC++ 5.0. + The code assumes 64-bit integer support, which makes it much clearer. + + All the following source files should have the following copyright + notice included: + +copyrt.h + +/* +** Copyright (c) 1990- 1993, 1996 Open Software Foundation, Inc. +** Copyright (c) 1989 by Hewlett-Packard Company, Palo Alto, Ca. & +** Digital Equipment Corporation, Maynard, Mass. +** Copyright (c) 1998 Microsoft. +** To anyone who acknowledges that this file is provided "AS IS" +** without any express or implied warranty: permission to use, copy, +** modify, and distribute this file for any purpose is hereby +** granted without fee, provided that the above copyright notices and +** this notice appears in all source code copies, and that none of +** the names of Open Software Foundation, Inc., Hewlett-Packard +** Company, Microsoft, or Digital Equipment Corporation be used in +** advertising or publicity pertaining to distribution of the software +** without specific, written prior permission. Neither Open Software +** Foundation, Inc., Hewlett-Packard Company, Microsoft, nor Digital +** Equipment Corporation makes any representations about the +** suitability of this software for any purpose. +*/ + + +uuid.h + +#include "copyrt.h" +#undef uuid_t +typedef struct { + unsigned32 time_low; + unsigned16 time_mid; + unsigned16 time_hi_and_version; + unsigned8 clock_seq_hi_and_reserved; + unsigned8 clock_seq_low; + byte node[6]; +} uuid_t; + + + + +Leach, et al. Standards Track [Page 18] + +RFC 4122 A UUID URN Namespace July 2005 + + +/* uuid_create -- generate a UUID */ +int uuid_create(uuid_t * uuid); + +/* uuid_create_md5_from_name -- create a version 3 (MD5) UUID using a + "name" from a "name space" */ +void uuid_create_md5_from_name( + uuid_t *uuid, /* resulting UUID */ + uuid_t nsid, /* UUID of the namespace */ + void *name, /* the name from which to generate a UUID */ + int namelen /* the length of the name */ +); + +/* uuid_create_sha1_from_name -- create a version 5 (SHA-1) UUID + using a "name" from a "name space" */ +void uuid_create_sha1_from_name( + + uuid_t *uuid, /* resulting UUID */ + uuid_t nsid, /* UUID of the namespace */ + void *name, /* the name from which to generate a UUID */ + int namelen /* the length of the name */ +); + +/* uuid_compare -- Compare two UUID's "lexically" and return + -1 u1 is lexically before u2 + 0 u1 is equal to u2 + 1 u1 is lexically after u2 + Note that lexical ordering is not temporal ordering! +*/ +int uuid_compare(uuid_t *u1, uuid_t *u2); + + +uuid.c + +#include "copyrt.h" +#include +#include +#include +#include +#include "sysdep.h" +#include "uuid.h" + +/* various forward declarations */ +static int read_state(unsigned16 *clockseq, uuid_time_t *timestamp, + uuid_node_t *node); +static void write_state(unsigned16 clockseq, uuid_time_t timestamp, + uuid_node_t node); +static void format_uuid_v1(uuid_t *uuid, unsigned16 clockseq, + uuid_time_t timestamp, uuid_node_t node); + + + +Leach, et al. Standards Track [Page 19] + +RFC 4122 A UUID URN Namespace July 2005 + + +static void format_uuid_v3or5(uuid_t *uuid, unsigned char hash[16], + int v); +static void get_current_time(uuid_time_t *timestamp); +static unsigned16 true_random(void); + +/* uuid_create -- generator a UUID */ +int uuid_create(uuid_t *uuid) +{ + uuid_time_t timestamp, last_time; + unsigned16 clockseq; + uuid_node_t node; + uuid_node_t last_node; + int f; + + /* acquire system-wide lock so we're alone */ + LOCK; + /* get time, node ID, saved state from non-volatile storage */ + get_current_time(×tamp); + get_ieee_node_identifier(&node); + f = read_state(&clockseq, &last_time, &last_node); + + /* if no NV state, or if clock went backwards, or node ID + changed (e.g., new network card) change clockseq */ + if (!f || memcmp(&node, &last_node, sizeof node)) + clockseq = true_random(); + else if (timestamp < last_time) + clockseq++; + + /* save the state for next time */ + write_state(clockseq, timestamp, node); + + UNLOCK; + + /* stuff fields into the UUID */ + format_uuid_v1(uuid, clockseq, timestamp, node); + return 1; +} + +/* format_uuid_v1 -- make a UUID from the timestamp, clockseq, + and node ID */ +void format_uuid_v1(uuid_t* uuid, unsigned16 clock_seq, + uuid_time_t timestamp, uuid_node_t node) +{ + /* Construct a version 1 uuid with the information we've gathered + plus a few constants. */ + uuid->time_low = (unsigned long)(timestamp & 0xFFFFFFFF); + uuid->time_mid = (unsigned short)((timestamp >> 32) & 0xFFFF); + uuid->time_hi_and_version = + + + +Leach, et al. Standards Track [Page 20] + +RFC 4122 A UUID URN Namespace July 2005 + + + (unsigned short)((timestamp >> 48) & 0x0FFF); + uuid->time_hi_and_version |= (1 << 12); + uuid->clock_seq_low = clock_seq & 0xFF; + uuid->clock_seq_hi_and_reserved = (clock_seq & 0x3F00) >> 8; + uuid->clock_seq_hi_and_reserved |= 0x80; + memcpy(&uuid->node, &node, sizeof uuid->node); +} + +/* data type for UUID generator persistent state */ +typedef struct { + uuid_time_t ts; /* saved timestamp */ + uuid_node_t node; /* saved node ID */ + unsigned16 cs; /* saved clock sequence */ +} uuid_state; + +static uuid_state st; + +/* read_state -- read UUID generator state from non-volatile store */ +int read_state(unsigned16 *clockseq, uuid_time_t *timestamp, + uuid_node_t *node) +{ + static int inited = 0; + FILE *fp; + + /* only need to read state once per boot */ + if (!inited) { + fp = fopen("state", "rb"); + if (fp == NULL) + return 0; + fread(&st, sizeof st, 1, fp); + fclose(fp); + inited = 1; + } + *clockseq = st.cs; + *timestamp = st.ts; + *node = st.node; + return 1; +} + +/* write_state -- save UUID generator state back to non-volatile + storage */ +void write_state(unsigned16 clockseq, uuid_time_t timestamp, + uuid_node_t node) +{ + static int inited = 0; + static uuid_time_t next_save; + FILE* fp; + + + + +Leach, et al. Standards Track [Page 21] + +RFC 4122 A UUID URN Namespace July 2005 + + + if (!inited) { + next_save = timestamp; + inited = 1; + } + + /* always save state to volatile shared state */ + st.cs = clockseq; + st.ts = timestamp; + st.node = node; + if (timestamp >= next_save) { + fp = fopen("state", "wb"); + fwrite(&st, sizeof st, 1, fp); + fclose(fp); + /* schedule next save for 10 seconds from now */ + next_save = timestamp + (10 * 10 * 1000 * 1000); + } +} + +/* get-current_time -- get time as 60-bit 100ns ticks since UUID epoch. + Compensate for the fact that real clock resolution is + less than 100ns. */ +void get_current_time(uuid_time_t *timestamp) +{ + static int inited = 0; + static uuid_time_t time_last; + static unsigned16 uuids_this_tick; + uuid_time_t time_now; + + if (!inited) { + get_system_time(&time_now); + uuids_this_tick = UUIDS_PER_TICK; + inited = 1; + } + + for ( ; ; ) { + get_system_time(&time_now); + + /* if clock reading changed since last UUID generated, */ + if (time_last != time_now) { + /* reset count of uuids gen'd with this clock reading */ + uuids_this_tick = 0; + time_last = time_now; + break; + } + if (uuids_this_tick < UUIDS_PER_TICK) { + uuids_this_tick++; + break; + } + + + +Leach, et al. Standards Track [Page 22] + +RFC 4122 A UUID URN Namespace July 2005 + + + /* going too fast for our clock; spin */ + } + /* add the count of uuids to low order bits of the clock reading */ + *timestamp = time_now + uuids_this_tick; +} + +/* true_random -- generate a crypto-quality random number. + **This sample doesn't do that.** */ +static unsigned16 true_random(void) +{ + static int inited = 0; + uuid_time_t time_now; + + if (!inited) { + get_system_time(&time_now); + time_now = time_now / UUIDS_PER_TICK; + srand((unsigned int) + (((time_now >> 32) ^ time_now) & 0xffffffff)); + inited = 1; + } + + return rand(); +} + +/* uuid_create_md5_from_name -- create a version 3 (MD5) UUID using a + "name" from a "name space" */ +void uuid_create_md5_from_name(uuid_t *uuid, uuid_t nsid, void *name, + int namelen) +{ + MD5_CTX c; + unsigned char hash[16]; + uuid_t net_nsid; + + /* put name space ID in network byte order so it hashes the same + no matter what endian machine we're on */ + net_nsid = nsid; + net_nsid.time_low = htonl(net_nsid.time_low); + net_nsid.time_mid = htons(net_nsid.time_mid); + net_nsid.time_hi_and_version = htons(net_nsid.time_hi_and_version); + + MD5Init(&c); + MD5Update(&c, &net_nsid, sizeof net_nsid); + MD5Update(&c, name, namelen); + MD5Final(hash, &c); + + /* the hash is in network byte order at this point */ + format_uuid_v3or5(uuid, hash, 3); +} + + + +Leach, et al. Standards Track [Page 23] + +RFC 4122 A UUID URN Namespace July 2005 + + +void uuid_create_sha1_from_name(uuid_t *uuid, uuid_t nsid, void *name, + int namelen) +{ + SHA_CTX c; + unsigned char hash[20]; + uuid_t net_nsid; + + /* put name space ID in network byte order so it hashes the same + no matter what endian machine we're on */ + net_nsid = nsid; + net_nsid.time_low = htonl(net_nsid.time_low); + net_nsid.time_mid = htons(net_nsid.time_mid); + net_nsid.time_hi_and_version = htons(net_nsid.time_hi_and_version); + + SHA1_Init(&c); + SHA1_Update(&c, &net_nsid, sizeof net_nsid); + SHA1_Update(&c, name, namelen); + SHA1_Final(hash, &c); + + /* the hash is in network byte order at this point */ + format_uuid_v3or5(uuid, hash, 5); +} + +/* format_uuid_v3or5 -- make a UUID from a (pseudo)random 128-bit + number */ +void format_uuid_v3or5(uuid_t *uuid, unsigned char hash[16], int v) +{ + /* convert UUID to local byte order */ + memcpy(uuid, hash, sizeof *uuid); + uuid->time_low = ntohl(uuid->time_low); + uuid->time_mid = ntohs(uuid->time_mid); + uuid->time_hi_and_version = ntohs(uuid->time_hi_and_version); + + /* put in the variant and version bits */ + uuid->time_hi_and_version &= 0x0FFF; + uuid->time_hi_and_version |= (v << 12); + uuid->clock_seq_hi_and_reserved &= 0x3F; + uuid->clock_seq_hi_and_reserved |= 0x80; +} + +/* uuid_compare -- Compare two UUID's "lexically" and return */ +#define CHECK(f1, f2) if (f1 != f2) return f1 < f2 ? -1 : 1; +int uuid_compare(uuid_t *u1, uuid_t *u2) +{ + int i; + + CHECK(u1->time_low, u2->time_low); + CHECK(u1->time_mid, u2->time_mid); + + + +Leach, et al. Standards Track [Page 24] + +RFC 4122 A UUID URN Namespace July 2005 + + + CHECK(u1->time_hi_and_version, u2->time_hi_and_version); + CHECK(u1->clock_seq_hi_and_reserved, u2->clock_seq_hi_and_reserved); + CHECK(u1->clock_seq_low, u2->clock_seq_low) + for (i = 0; i < 6; i++) { + if (u1->node[i] < u2->node[i]) + return -1; + if (u1->node[i] > u2->node[i]) + return 1; + } + return 0; +} +#undef CHECK + + +sysdep.h + +#include "copyrt.h" +/* remove the following define if you aren't running WIN32 */ +#define WININC 0 + +#ifdef WININC +#include +#else +#include +#include +#include +#endif + +#include "global.h" +/* change to point to where MD5 .h's live; RFC 1321 has sample + implementation */ +#include "md5.h" + +/* set the following to the number of 100ns ticks of the actual + resolution of your system's clock */ +#define UUIDS_PER_TICK 1024 + +/* Set the following to a calls to get and release a global lock */ +#define LOCK +#define UNLOCK + +typedef unsigned long unsigned32; +typedef unsigned short unsigned16; +typedef unsigned char unsigned8; +typedef unsigned char byte; + +/* Set this to what your compiler uses for 64-bit data type */ +#ifdef WININC + + + +Leach, et al. Standards Track [Page 25] + +RFC 4122 A UUID URN Namespace July 2005 + + +#define unsigned64_t unsigned __int64 +#define I64(C) C +#else +#define unsigned64_t unsigned long long +#define I64(C) C##LL +#endif + +typedef unsigned64_t uuid_time_t; +typedef struct { + char nodeID[6]; +} uuid_node_t; + +void get_ieee_node_identifier(uuid_node_t *node); +void get_system_time(uuid_time_t *uuid_time); +void get_random_info(char seed[16]); + + +sysdep.c + +#include "copyrt.h" +#include +#include "sysdep.h" + +/* system dependent call to get IEEE node ID. + This sample implementation generates a random node ID. */ +void get_ieee_node_identifier(uuid_node_t *node) +{ + static inited = 0; + static uuid_node_t saved_node; + char seed[16]; + FILE *fp; + + if (!inited) { + fp = fopen("nodeid", "rb"); + if (fp) { + fread(&saved_node, sizeof saved_node, 1, fp); + fclose(fp); + } + else { + get_random_info(seed); + seed[0] |= 0x01; + memcpy(&saved_node, seed, sizeof saved_node); + fp = fopen("nodeid", "wb"); + if (fp) { + fwrite(&saved_node, sizeof saved_node, 1, fp); + fclose(fp); + } + } + + + +Leach, et al. Standards Track [Page 26] + +RFC 4122 A UUID URN Namespace July 2005 + + + inited = 1; + } + + *node = saved_node; +} + +/* system dependent call to get the current system time. Returned as + 100ns ticks since UUID epoch, but resolution may be less than + 100ns. */ +#ifdef _WINDOWS_ + +void get_system_time(uuid_time_t *uuid_time) +{ + ULARGE_INTEGER time; + + /* NT keeps time in FILETIME format which is 100ns ticks since + Jan 1, 1601. UUIDs use time in 100ns ticks since Oct 15, 1582. + The difference is 17 Days in Oct + 30 (Nov) + 31 (Dec) + + 18 years and 5 leap days. */ + GetSystemTimeAsFileTime((FILETIME *)&time); + time.QuadPart += + + (unsigned __int64) (1000*1000*10) // seconds + * (unsigned __int64) (60 * 60 * 24) // days + * (unsigned __int64) (17+30+31+365*18+5); // # of days + *uuid_time = time.QuadPart; +} + +/* Sample code, not for use in production; see RFC 1750 */ +void get_random_info(char seed[16]) +{ + MD5_CTX c; + struct { + MEMORYSTATUS m; + SYSTEM_INFO s; + FILETIME t; + LARGE_INTEGER pc; + DWORD tc; + DWORD l; + char hostname[MAX_COMPUTERNAME_LENGTH + 1]; + } r; + + MD5Init(&c); + GlobalMemoryStatus(&r.m); + GetSystemInfo(&r.s); + GetSystemTimeAsFileTime(&r.t); + QueryPerformanceCounter(&r.pc); + r.tc = GetTickCount(); + + + +Leach, et al. Standards Track [Page 27] + +RFC 4122 A UUID URN Namespace July 2005 + + + r.l = MAX_COMPUTERNAME_LENGTH + 1; + GetComputerName(r.hostname, &r.l); + MD5Update(&c, &r, sizeof r); + MD5Final(seed, &c); +} + +#else + +void get_system_time(uuid_time_t *uuid_time) +{ + struct timeval tp; + + gettimeofday(&tp, (struct timezone *)0); + + /* Offset between UUID formatted times and Unix formatted times. + UUID UTC base time is October 15, 1582. + Unix base time is January 1, 1970.*/ + *uuid_time = ((unsigned64)tp.tv_sec * 10000000) + + ((unsigned64)tp.tv_usec * 10) + + I64(0x01B21DD213814000); +} + +/* Sample code, not for use in production; see RFC 1750 */ +void get_random_info(char seed[16]) +{ + MD5_CTX c; + struct { + struct sysinfo s; + struct timeval t; + char hostname[257]; + } r; + + MD5Init(&c); + sysinfo(&r.s); + gettimeofday(&r.t, (struct timezone *)0); + gethostname(r.hostname, 256); + MD5Update(&c, &r, sizeof r); + MD5Final(seed, &c); +} + +#endif + +utest.c + +#include "copyrt.h" +#include "sysdep.h" +#include +#include "uuid.h" + + + +Leach, et al. Standards Track [Page 28] + +RFC 4122 A UUID URN Namespace July 2005 + + +uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */ + 0x6ba7b810, + 0x9dad, + 0x11d1, + 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 +}; + +/* puid -- print a UUID */ +void puid(uuid_t u) +{ + int i; + + printf("%8.8x-%4.4x-%4.4x-%2.2x%2.2x-", u.time_low, u.time_mid, + u.time_hi_and_version, u.clock_seq_hi_and_reserved, + u.clock_seq_low); + for (i = 0; i < 6; i++) + printf("%2.2x", u.node[i]); + printf("\n"); +} + +/* Simple driver for UUID generator */ +void main(int argc, char **argv) +{ + uuid_t u; + int f; + + uuid_create(&u); + printf("uuid_create(): "); puid(u); + + f = uuid_compare(&u, &u); + printf("uuid_compare(u,u): %d\n", f); /* should be 0 */ + f = uuid_compare(&u, &NameSpace_DNS); + printf("uuid_compare(u, NameSpace_DNS): %d\n", f); /* s.b. 1 */ + f = uuid_compare(&NameSpace_DNS, &u); + printf("uuid_compare(NameSpace_DNS, u): %d\n", f); /* s.b. -1 */ + uuid_create_md5_from_name(&u, NameSpace_DNS, "www.widgets.com", 15); + printf("uuid_create_md5_from_name(): "); puid(u); +} + +Appendix B. Appendix B - Sample Output of utest + + uuid_create(): 7d444840-9dc0-11d1-b245-5ffdce74fad2 + uuid_compare(u,u): 0 + uuid_compare(u, NameSpace_DNS): 1 + uuid_compare(NameSpace_DNS, u): -1 + uuid_create_md5_from_name(): e902893a-9d22-3c7e-a7b8-d6e313b71d9f + + + + + +Leach, et al. Standards Track [Page 29] + +RFC 4122 A UUID URN Namespace July 2005 + + +Appendix C. Appendix C - Some Name Space IDs + + This appendix lists the name space IDs for some potentially + interesting name spaces, as initialized C structures and in the + string representation defined above. + + /* Name string is a fully-qualified domain name */ + uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */ + 0x6ba7b810, + 0x9dad, + 0x11d1, + 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 + }; + + /* Name string is a URL */ + uuid_t NameSpace_URL = { /* 6ba7b811-9dad-11d1-80b4-00c04fd430c8 */ + 0x6ba7b811, + 0x9dad, + 0x11d1, + 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 + }; + + /* Name string is an ISO OID */ + uuid_t NameSpace_OID = { /* 6ba7b812-9dad-11d1-80b4-00c04fd430c8 */ + 0x6ba7b812, + 0x9dad, + 0x11d1, + 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 + }; + + /* Name string is an X.500 DN (in DER or a text output format) */ + uuid_t NameSpace_X500 = { /* 6ba7b814-9dad-11d1-80b4-00c04fd430c8 */ + 0x6ba7b814, + 0x9dad, + 0x11d1, + 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 + }; + + + + + + + + + + + + + + +Leach, et al. Standards Track [Page 30] + +RFC 4122 A UUID URN Namespace July 2005 + + +Authors' Addresses + + Paul J. Leach + Microsoft + 1 Microsoft Way + Redmond, WA 98052 + US + + Phone: +1 425-882-8080 + EMail: paulle@microsoft.com + + + Michael Mealling + Refactored Networks, LLC + 1635 Old Hwy 41 + Suite 112, Box 138 + Kennesaw, GA 30152 + US + + Phone: +1-678-581-9656 + EMail: michael@refactored-networks.com + URI: http://www.refactored-networks.com + + + Rich Salz + DataPower Technology, Inc. + 1 Alewife Center + Cambridge, MA 02142 + US + + Phone: +1 617-864-0455 + EMail: rsalz@datapower.com + URI: http://www.datapower.com + + + + + + + + + + + + + + + + + + +Leach, et al. Standards Track [Page 31] + +RFC 4122 A UUID URN Namespace July 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Leach, et al. Standards Track [Page 32] + diff --git a/standards/wake-on-lan.pdf b/standards/wake-on-lan.pdf new file mode 100644 index 0000000000..07d97f4439 Binary files /dev/null and b/standards/wake-on-lan.pdf differ diff --git a/systemv/Makefile b/systemv/Makefile index 6a88179782..9cc85ea212 100644 --- a/systemv/Makefile +++ b/systemv/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 5065 2006-02-03 16:55:30Z mike $" +# "$Id: Makefile 5222 2006-03-03 18:57:56Z mike $" # # System V commands makefile for the Common UNIX Printing System (CUPS). # @@ -43,7 +43,7 @@ all: $(TARGETS) # clean: - $(RM) $(OBJS) $(TARGETS) disable enable reject + $(RM) $(OBJS) $(TARGETS) cupsdisable cupsenable reject # @@ -87,10 +87,10 @@ install: all accept: accept.o ../cups/$(LIBCUPS) echo Linking $@... $(CC) $(LDFLAGS) -o accept accept.o $(LIBS) - $(RM) reject enable disable + $(RM) reject cupsenable cupsdisable $(LN) accept reject - $(LN) accept enable - $(LN) accept disable + $(LN) accept cupsenable + $(LN) accept cupsdisable # @@ -191,5 +191,5 @@ include Dependencies # -# End of "$Id: Makefile 5065 2006-02-03 16:55:30Z mike $". +# End of "$Id: Makefile 5222 2006-03-03 18:57:56Z mike $". # diff --git a/templates/Makefile b/templates/Makefile index 1dcfcb2bfa..8eded7d396 100644 --- a/templates/Makefile +++ b/templates/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 5156 2006-02-23 04:24:32Z mike $" +# "$Id: Makefile 5222 2006-03-03 18:57:56Z mike $" # # Template makefile for the Common UNIX Printing System (CUPS). # @@ -50,6 +50,7 @@ FILES = \ error-op.tmpl \ header.tmpl \ help-header.tmpl \ + help-printable.tmpl \ job-cancel.tmpl \ job-hold.tmpl \ job-move.tmpl \ @@ -119,7 +120,7 @@ install: all for lang in $(LANGUAGES); do \ $(INSTALL_DIR) -m 755 $(DATADIR)/templates/$$lang; \ for file in $(FILES); do \ - if test -e $$lang/$$file; then \ + if test -f $$lang/$$file; then \ $(INSTALL_DATA) $$lang/$$file $(DATADIR)/templates/$$lang; \ fi \ done \ @@ -127,5 +128,5 @@ install: all # -# End of "$Id: Makefile 5156 2006-02-23 04:24:32Z mike $". +# End of "$Id: Makefile 5222 2006-03-03 18:57:56Z mike $". # diff --git a/templates/add-class.tmpl b/templates/add-class.tmpl index a1b1689ee9..6a77f2d84b 100644 --- a/templates/add-class.tmpl +++ b/templates/add-class.tmpl @@ -26,7 +26,7 @@
    diff --git a/templates/add-printer.tmpl b/templates/add-printer.tmpl index dd913312fb..cff93eb294 100644 --- a/templates/add-printer.tmpl +++ b/templates/add-printer.tmpl @@ -21,7 +21,7 @@

    diff --git a/templates/admin.tmpl b/templates/admin.tmpl index 989c46be23..0c34c4939b 100644 --- a/templates/admin.tmpl +++ b/templates/admin.tmpl @@ -5,34 +5,34 @@

    Add Printer -Add Printer +Manage Printers {have_samba?Export Printers to Samba:}

    {#device_uri=0?:

    New Printers Found:

      {[device_uri]
    • {device_make_and_model} ({device_info}) Add This Printer
      • }
    }

    Classes

    -Add Class -Manage Classes

    Jobs

    -Manage +<A HREF=Manage Jobs

    @@ -42,16 +42,16 @@ Jobs" CLASS="button">

    Edit Configuration +SRC= View Access Log View Error Log View Page Log

    @@ -66,7 +66,7 @@ CLASS="button"> Allow users to cancel any job (not just their own)
    Save debugging information for troubleshooting

    -

    +

    diff --git a/templates/choose-device.tmpl b/templates/choose-device.tmpl index 440e539f04..6076477e18 100644 --- a/templates/choose-device.tmpl +++ b/templates/choose-device.tmpl @@ -19,7 +19,7 @@ - + diff --git a/templates/choose-make.tmpl b/templates/choose-make.tmpl index 5bc0e67ecf..65e35afdf4 100644 --- a/templates/choose-make.tmpl +++ b/templates/choose-make.tmpl @@ -22,7 +22,7 @@ - + @@ -35,7 +35,7 @@ TYPE="FILE" NAME="PPD_FILE"> - + diff --git a/templates/choose-model.tmpl b/templates/choose-model.tmpl index c0c2ef2c05..aa523080f9 100644 --- a/templates/choose-model.tmpl +++ b/templates/choose-model.tmpl @@ -27,7 +27,7 @@ TYPE="FILE" NAME="PPD_FILE"> - + diff --git a/templates/choose-serial.tmpl b/templates/choose-serial.tmpl index f90dd6a01a..e0bbb1b97d 100644 --- a/templates/choose-serial.tmpl +++ b/templates/choose-serial.tmpl @@ -40,7 +40,7 @@ - + diff --git a/templates/choose-uri.tmpl b/templates/choose-uri.tmpl index ae72d1c173..5124c4ddda 100644 --- a/templates/choose-uri.tmpl +++ b/templates/choose-uri.tmpl @@ -33,7 +33,7 @@ Printers" for the correct URI to use with your printer.

    - + diff --git a/templates/class-confirm.tmpl b/templates/class-confirm.tmpl index 4a9afc6def..b2122929fb 100644 --- a/templates/class-confirm.tmpl +++ b/templates/class-confirm.tmpl @@ -3,5 +3,5 @@

    Delete Class

    diff --git a/templates/classes.tmpl b/templates/classes.tmpl index a69dd7b533..17ee9e4a01 100644 --- a/templates/classes.tmpl +++ b/templates/classes.tmpl @@ -15,38 +15,38 @@

    -Print Test Page +Print Test Page {printer_state=5? -Start Class +Start Class : -Stop Class +Stop Class } {printer_is_accepting_jobs=0? -Accept Jobs +Accept Jobs : -Reject Jobs +Reject Jobs } -Cancel All Jobs +Cancel All Jobs {printer_is_shared=0? -Publish Printer +Publish Printer : -Unpublish Printer +Unpublish Printer } -Modify Class +Modify Class -Delete Class +Delete Class -Set As Default +Set As Default -Set Allowed Users +Set Allowed Users

    diff --git a/templates/edit-config.tmpl.in b/templates/edit-config.tmpl.in index 7ca5da7951..775938cf61 100644 --- a/templates/edit-config.tmpl.in +++ b/templates/edit-config.tmpl.in @@ -22,6 +22,9 @@ function reset_config() "BrowseAllow @LOCAL\\n" + "\\n" + "\\n" + +"# Authenticate against system accounts by default...\\n" + +"DefaultAuthType Basic\\n" + +"\\n" + "# Restrict access to the server...\\n" + "\\n" + " Order allow,deny\\n" + @@ -42,9 +45,6 @@ function reset_config() " Allow localhost\\n" + "\\n" + "\\n" + -"# Authenticate against system accounts by default...\\n" + -"DefaultAuthType Basic\\n" + -"\\n" + "# Set the default printer/job policies...\\n" + "\\n" + " # Job-related operations must be done by the owner or an adminstrator...\\n" + diff --git a/templates/help-header.tmpl b/templates/help-header.tmpl index 21e0ec445b..b1dcc93066 100644 --- a/templates/help-header.tmpl +++ b/templates/help-header.tmpl @@ -4,7 +4,9 @@

    Search in {HELPTITLE?{HELPTITLE}:{TOPIC?{TOPIC}:All Documents}}:

    +TYPE="IMAGE" SRC="/images/button-search.gif" ALT="Search"> +Clear

    @@ -24,5 +26,22 @@ TYPE="IMAGE" SRC="/images/search.gif" ALT="Search">

    {[QTEXT]
  • {QTEXT}{QPTEXT? (in {QPTEXT}):}
    • } {QTEXT?:} :

    No matches found.

    } -{HELPTITLE?
    :}:} -{HELPTITLE?

    {HELPTITLE}

    :} +
    :} +{HELPTITLE?

    {HELPTITLE} +View Printable Version

    :

    CUPS Help Pages

    + +

    This is the CUPS on-line help interface. Enter search words +above or click on any of the documentation links to display +on-line help information.

    + +

    If you are new to CUPS, read the "Overview of CUPS" page. Veteran users +should read the "What's New in CUPS +1.2" page.

    + +

    The CUPS Home Page also +provides many resources including user discussion forums, answers +to frequently-asked questions, and a form for submitting bug +reports and feature requests.

    } diff --git a/templates/help-printable.tmpl b/templates/help-printable.tmpl new file mode 100644 index 0000000000..305112a337 --- /dev/null +++ b/templates/help-printable.tmpl @@ -0,0 +1,11 @@ + + + + + {HELPTITLE} + + + + + +

    {HELPTITLE}

    diff --git a/templates/ja/add-class.tmpl b/templates/ja/add-class.tmpl index 8db1395d2e..eee2ef9937 100644 --- a/templates/ja/add-class.tmpl +++ b/templates/ja/add-class.tmpl @@ -26,7 +26,7 @@ - + diff --git a/templates/ja/add-printer.tmpl b/templates/ja/add-printer.tmpl index 65c09d6c20..aac93808b3 100644 --- a/templates/ja/add-printer.tmpl +++ b/templates/ja/add-printer.tmpl @@ -21,7 +21,7 @@ - + diff --git a/templates/ja/admin.tmpl b/templates/ja/admin.tmpl index 8edfde6981..3d1efb014d 100644 --- a/templates/ja/admin.tmpl +++ b/templates/ja/admin.tmpl @@ -5,34 +5,34 @@

    プリンタの追加 -プリンタの追加 +プリンタの管理 {have_samba?プリンタをSambaにエキスポート:}

    {#device_uri=0?:

    新しいプリンタが見つかりました:

      {[device_uri]
    • {device_make_and_model} ({device_info}) このプリンタを追加
      • }
    }

    クラス

    -クラスの追加 -クラスの管理

    ジョブ

    -ジョブの管理 +ジョブの管理

          @@ -41,15 +41,15 @@ ALT="クラスの管理" CLASS="button">

    設定ファイルの編集 +SRC="/images/button-edit-configuration-file.gif" ALT="設定ファイルの編集" CLASS="button"> アクセスログの表示 エラーログの表示 ページログの表示

    @@ -64,7 +64,7 @@ CLASS="button"> どのジョブであってもキャンセルすることを (たとえ所有者でなくても) ユーザに許可
    トラブルシューティングのためにデバッグ情報を保存

    -

    +

    diff --git a/templates/ja/choose-device.tmpl b/templates/ja/choose-device.tmpl index 022ce5f624..303bf279f7 100644 --- a/templates/ja/choose-device.tmpl +++ b/templates/ja/choose-device.tmpl @@ -19,7 +19,7 @@ - + diff --git a/templates/ja/choose-make.tmpl b/templates/ja/choose-make.tmpl index 4e60161bb6..87cd06fc3b 100644 --- a/templates/ja/choose-make.tmpl +++ b/templates/ja/choose-make.tmpl @@ -22,7 +22,7 @@ - + @@ -35,7 +35,7 @@ TYPE="FILE" NAME="PPD_FILE"> - + diff --git a/templates/ja/choose-model.tmpl b/templates/ja/choose-model.tmpl index 6bc223408a..53bd69b3ed 100644 --- a/templates/ja/choose-model.tmpl +++ b/templates/ja/choose-model.tmpl @@ -27,7 +27,7 @@ TYPE="FILE" NAME="PPD_FILE"> - + diff --git a/templates/ja/choose-serial.tmpl b/templates/ja/choose-serial.tmpl index 7917540dac..e66b52d212 100644 --- a/templates/ja/choose-serial.tmpl +++ b/templates/ja/choose-serial.tmpl @@ -40,7 +40,7 @@ - + diff --git a/templates/ja/choose-uri.tmpl b/templates/ja/choose-uri.tmpl index ca7fa0443e..33dd2f7fdf 100644 --- a/templates/ja/choose-uri.tmpl +++ b/templates/ja/choose-uri.tmpl @@ -34,7 +34,7 @@ - + diff --git a/templates/ja/class-confirm.tmpl b/templates/ja/class-confirm.tmpl index f8eb454d6e..382f1f51fb 100644 --- a/templates/ja/class-confirm.tmpl +++ b/templates/ja/class-confirm.tmpl @@ -3,5 +3,5 @@

    クラスの削除

    diff --git a/templates/ja/classes.tmpl b/templates/ja/classes.tmpl index aeaef9925a..67dcf80488 100644 --- a/templates/ja/classes.tmpl +++ b/templates/ja/classes.tmpl @@ -17,38 +17,38 @@

    -テストページの印刷 +テストページの印刷 {printer_state=5? -クラスを開始 +クラスを開始 : -クラスを停止 +クラスを停止 } {printer_is_accepting_jobs=0? -ジョブを受け付け +ジョブを受け付け : -ジョブを拒否 +ジョブを拒否 } -すべてのジョブをキャンセル +すべてのジョブをキャンセル {printer_is_shared=0? -プリンタを公開 +プリンタを公開 : -プリンタを非公開 +プリンタを非公開 } -クラスの変更 +クラスの変更 -クラスの削除 +クラスの削除 -デフォルトに設定 +デフォルトに設定 -許可するユーザの設定 +許可するユーザの設定

    diff --git a/templates/ja/help-header.tmpl b/templates/ja/help-header.tmpl index 24d67e2675..da92e23206 100644 --- a/templates/ja/help-header.tmpl +++ b/templates/ja/help-header.tmpl @@ -4,7 +4,7 @@

    {HELPTITLE?{HELPTITLE}:{TOPIC?{TOPIC}:すべてのドキュメント}} 内を検索:

    +TYPE="IMAGE" SRC="/images/button-search.gif" ALT="検索">

    diff --git a/templates/ja/job-move.tmpl b/templates/ja/job-move.tmpl index 601e3f9bf1..bfb630e989 100644 --- a/templates/ja/job-move.tmpl +++ b/templates/ja/job-move.tmpl @@ -15,7 +15,7 @@ - + diff --git a/templates/ja/jobs-header.tmpl b/templates/ja/jobs-header.tmpl index 1ed1049ef7..7310f3c9c3 100644 --- a/templates/ja/jobs-header.tmpl +++ b/templates/ja/jobs-header.tmpl @@ -1,15 +1,15 @@

    {?which_jobs=?完了したジョブを表示 +SRC="/images/button-show-completed.gif" CLASS="button" ALT="完了したジョブを表示"> すべてのジョブを表示:{which_jobs=all?:{which_jobs=all?完了したジョブを表示 +SRC="/images/button-show-completed.gif" CLASS="button" ALT="完了したジョブを表示"> アクティブなジョブを表示::アクティブなジョブを表示 +SRC="/images/button-show-active.gif" CLASS="button" ALT="アクティブなジョブを表示"> すべてのジョブを表示}}

    +SRC="/images/button-show-all.gif" CLASS="button" ALT="すべてのジョブを表示">}}

    {total=0?ジョブはありません:{total} 個の{?which_jobs=?アクティブな:{which_jobs=all?:完了した}}ジョブのうち {#job_id} 個を表示中}。

    diff --git a/templates/ja/jobs.tmpl b/templates/ja/jobs.tmpl index 492a9c98ce..371bc30beb 100644 --- a/templates/ja/jobs.tmpl +++ b/templates/ja/jobs.tmpl @@ -23,18 +23,18 @@ {job_preserved>0? -ジョブの再印刷:} +ジョブの再印刷:} {job_state=4? -ジョブを解放:} +ジョブを解放:} {job_state=3? -ジョブをホールド:} +ジョブをホールド:} {job_state<7? -ジョブをキャンセル +ジョブをキャンセル ジョブを移動:} +SRC="/images/button-move-job.gif" ALT="ジョブを移動" CLASS="button">:}   } diff --git a/templates/ja/modify-class.tmpl b/templates/ja/modify-class.tmpl index e3ff08d8c5..11f362d14f 100644 --- a/templates/ja/modify-class.tmpl +++ b/templates/ja/modify-class.tmpl @@ -27,7 +27,7 @@ - + diff --git a/templates/ja/modify-printer.tmpl b/templates/ja/modify-printer.tmpl index 14bab6831f..9fdd15970b 100644 --- a/templates/ja/modify-printer.tmpl +++ b/templates/ja/modify-printer.tmpl @@ -22,7 +22,7 @@ - + diff --git a/templates/ja/option-trailer.tmpl b/templates/ja/option-trailer.tmpl index 82566538fe..f7b1eb714d 100644 --- a/templates/ja/option-trailer.tmpl +++ b/templates/ja/option-trailer.tmpl @@ -1,5 +1,5 @@ - + diff --git a/templates/ja/pager.tmpl b/templates/ja/pager.tmpl index 914d1d6464..13aa874633 100644 --- a/templates/ja/pager.tmpl +++ b/templates/ja/pager.tmpl @@ -1,7 +1,7 @@ - - - + + +
    {PREVURL?前を表示: }{ORDER=dec?昇順にソート:降順にソート}{NEXTURL?次を表示: }{PREVURL?前を表示: }{ORDER=dec?昇順にソート:降順にソート}{NEXTURL?次を表示: }
    diff --git a/templates/ja/printer-confirm.tmpl b/templates/ja/printer-confirm.tmpl index a4eb0e77ff..7a2fe776c5 100644 --- a/templates/ja/printer-confirm.tmpl +++ b/templates/ja/printer-confirm.tmpl @@ -3,5 +3,5 @@

    プリンタの削除

    diff --git a/templates/ja/printers.tmpl b/templates/ja/printers.tmpl index a23959cb5d..f0a39dd64c 100644 --- a/templates/ja/printers.tmpl +++ b/templates/ja/printers.tmpl @@ -17,42 +17,42 @@

    -テストページの印刷 +テストページの印刷 {printer_state=5? -プリタを開始 +プリタを開始 : -プリンタを停止 +プリンタを停止 } {printer_is_accepting_jobs=0? -ジョブを受け付け +ジョブを受け付け : -ジョブを拒否 +ジョブを拒否 } -すべてのジョブの移動 +すべてのジョブの移動 -すべてのジョブをキャンセル +すべてのジョブをキャンセル {printer_is_shared=0? -プリンタを公開 +プリンタを公開 : -プリンタを非公開 +プリンタを非公開 } -プリンタの変更 +プリンタの変更 -プリンタオプションの設定 +プリンタオプションの設定 -プリンタの削除 +プリンタの削除 -デフォルトに設定 +デフォルトに設定 -許可するユーザの設定 +許可するユーザの設定

    diff --git a/templates/ja/samba-export.tmpl b/templates/ja/samba-export.tmpl index 46587f6236..87b84790e9 100644 --- a/templates/ja/samba-export.tmpl +++ b/templates/ja/samba-export.tmpl @@ -48,7 +48,7 @@ onChange="select_printers()"> すべてのプリンタをエキスポート - diff --git a/templates/ja/search.tmpl b/templates/ja/search.tmpl index 04c8e17a55..deaac319b1 100644 --- a/templates/ja/search.tmpl +++ b/templates/ja/search.tmpl @@ -5,6 +5,6 @@

    {SEARCH_DEST?{SEARCH_DEST}:{SECTION=classes?クラス:{SECTION=jobs?ジョブ:プリンタ}}} 内を検索:

    +TYPE="IMAGE" SRC="/images/button-search.gif" ALT="検索">

    diff --git a/templates/ja/users.tmpl b/templates/ja/users.tmpl index fb4e3dde40..ff6ea2fd2d 100644 --- a/templates/ja/users.tmpl +++ b/templates/ja/users.tmpl @@ -18,7 +18,7 @@ - + diff --git a/templates/job-move.tmpl b/templates/job-move.tmpl index 65d8e98211..df2f373481 100644 --- a/templates/job-move.tmpl +++ b/templates/job-move.tmpl @@ -15,7 +15,7 @@ - + diff --git a/templates/jobs-header.tmpl b/templates/jobs-header.tmpl index 45743a18af..5a660611fd 100644 --- a/templates/jobs-header.tmpl +++ b/templates/jobs-header.tmpl @@ -1,15 +1,15 @@

    {?which_jobs=?Show Completed Jobs +SRC="/images/button-show-completed.gif" CLASS="button" ALT="Show Completed Jobs"> Show All Jobs:{which_jobs=all?:{which_jobs=all?Show Completed Jobs +SRC="/images/button-show-completed.gif" CLASS="button" ALT="Show Completed Jobs"> Show Active Jobs::Show Active Jobs +SRC="/images/button-show-active.gif" CLASS="button" ALT="Show Active Jobs"> Show All Jobs}}

    +SRC="/images/button-show-all.gif" CLASS="button" ALT="Show All Jobs">}}

    {total=0?No jobs:Showing {#job_id} of {total} {?which_jobs=?active:{which_jobs=all?:completed}} job{total=1?:s}}.

    diff --git a/templates/jobs.tmpl b/templates/jobs.tmpl index b18604edc7..4f22096f31 100644 --- a/templates/jobs.tmpl +++ b/templates/jobs.tmpl @@ -23,18 +23,18 @@ {job_preserved>0? -Reprint Job:} +Reprint Job:} {job_state=4? -Release Job:} +Release Job:} {job_state=3? -Hold Job:} +Hold Job:} {job_state<7? -Cancel Job +Cancel Job Move Job:} +SRC="/images/button-move-job.gif" ALT="Move Job" CLASS="button">:}   } diff --git a/templates/modify-class.tmpl b/templates/modify-class.tmpl index 4cacc26544..88839ec48f 100644 --- a/templates/modify-class.tmpl +++ b/templates/modify-class.tmpl @@ -27,7 +27,7 @@ - + diff --git a/templates/modify-printer.tmpl b/templates/modify-printer.tmpl index 37847a59ed..af72cf9963 100644 --- a/templates/modify-printer.tmpl +++ b/templates/modify-printer.tmpl @@ -22,7 +22,7 @@ - + diff --git a/templates/option-trailer.tmpl b/templates/option-trailer.tmpl index a8ff4c6fef..d689a442d6 100644 --- a/templates/option-trailer.tmpl +++ b/templates/option-trailer.tmpl @@ -1,5 +1,5 @@ - + diff --git a/templates/pager.tmpl b/templates/pager.tmpl index 4f017c280c..975f5923ac 100644 --- a/templates/pager.tmpl +++ b/templates/pager.tmpl @@ -1,7 +1,7 @@ - - - + + +
    {PREVURL?Show Previous: }{ORDER=dec?Sort Ascending:Sort Descending}{NEXTURL?Show Next: }{PREVURL?Show Previous: }{ORDER=dec?Sort Ascending:Sort Descending}{NEXTURL?Show Next: }
    diff --git a/templates/printer-confirm.tmpl b/templates/printer-confirm.tmpl index 046acb93d8..054d3895f3 100644 --- a/templates/printer-confirm.tmpl +++ b/templates/printer-confirm.tmpl @@ -3,5 +3,5 @@

    Delete Printer

    diff --git a/templates/printers.tmpl b/templates/printers.tmpl index da28244578..79e4ddd812 100644 --- a/templates/printers.tmpl +++ b/templates/printers.tmpl @@ -17,46 +17,46 @@

    -Print Test Page +Print Test Page {?cupscommand=1? -Clean Print Heads +Clean Print Heads -Print Self Test Page:} +Print Self Test Page:} {printer_state=5? -Start Printer +Start Printer : -Stop Printer +Stop Printer } {printer_is_accepting_jobs=0? -Accept Jobs +Accept Jobs : -Reject Jobs +Reject Jobs } -Move All Jobs +Move All Jobs -Cancel All Jobs +Cancel All Jobs {printer_is_shared=0? -Publish Printer +Publish Printer : -Unpublish Printer +Unpublish Printer } -Modify Printer +Modify Printer -Set Printer Options +Set Printer Options -Delete Printer +Delete Printer -Set As Default +Set As Default -Set Allowed Users +Set Allowed Users

    diff --git a/templates/samba-export.tmpl b/templates/samba-export.tmpl index 0510f550c7..426465905a 100644 --- a/templates/samba-export.tmpl +++ b/templates/samba-export.tmpl @@ -47,7 +47,7 @@ onChange="select_printers()"> Export All Printers - diff --git a/templates/search.tmpl b/templates/search.tmpl index 8fc2ac7c65..e1c7c9e748 100644 --- a/templates/search.tmpl +++ b/templates/search.tmpl @@ -5,6 +5,9 @@

    Search in {SEARCH_DEST?{SEARCH_DEST}:{SECTION=classes?Classes:{SECTION=jobs?Jobs:Printers}}}:

    +TYPE="IMAGE" SRC="/images/button-search.gif" ALT="Search"> +Clear

    diff --git a/templates/users.tmpl b/templates/users.tmpl index 61c6e474b7..b2594f0923 100644 --- a/templates/users.tmpl +++ b/templates/users.tmpl @@ -18,7 +18,7 @@ - +