File: idd.shtml

package info (click to toggle)
cupsys 1.2.7-4%2Betch9
links: PTS
area: main
in suites: etch
size: 20,436 kB
ctags: 10,404
sloc: ansic: 97,130; cpp: 49,167; java: 6,199; sh: 4,723; makefile: 1,918; lisp: 232; perl: 145; python: 119; php: 28
file content (1445 lines) | stat: -rw-r--r-- 39,483 bytes
parent folder | download | duplicates (2)
<HTML>
<HEAD>
	<META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
	<META NAME="DOCNUMBER" CONTENT="CUPS-IDD-1.2">
	<META NAME="Author" CONTENT="Easy Software Products">
	<TITLE>CUPS Interface Design Description</TITLE>
</HEAD>
<BODY>

<H1>Scope</H1>

<H2>Identification</H2>

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

<EMBED SRC="system-overview.shtml">

<H2>Document Overview</H2>

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

<UL>
	<LI>1 - Scope
	<LI>2 - References
	<LI>3 - Internal Interfaces
	<LI>4 - External Interfaces
	<LI>5 - Directories
	<LI>A - Glossary
</UL>

<EMBED SRC="references.shtml">

<H1>Internal Interfaces</H1>

<H2>Character Set Files</H2>

<P>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 <TT>#</TT> character in the first column
of a line.

<H3>8-Bit Character Set Files</H3>

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

<UL><PRE>
charset 8bit
</PRE></UL>

<P>Following this are lines that define the font information:

<UL><PRE>
first last direction width normal bold italic bold-italic
</PRE></UL>

<P><VAR>First</VAR> and <VAR>last</VAR> 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.

<P><VAR>Direction</VAR> is the string "ltor", "rtol", or "rtola" indicating
left-to-right, right-to-left, or right-to-left Arabic text.

<P><VAR>Width</VAR> is the string "single" or "double"; double means that the
glyphs are twice as wide as ASCII characters in the Courier typeface.

<P><VAR>Normal, bold, italic</VAR>, and <VAR>bold-italic</VAR> 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.

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

<UL><PRE>
xx yyyy
</PRE></UL>

<H3>Unicode Character Set Files</H3>

<P>Unicode character set files start with a line reading:

<UL><PRE>
charset encoding
</PRE></UL>

<P><VAR>Encoding</VAR> is the encoding to use for the text; currently only
the string "utf8" is supported.

<P>Following this are lines defining the font information:

<UL><PRE>
first last direction width normal bold italic bold-italic
</PRE></UL>

<P><VAR>First</VAR> and <VAR>last</VAR> 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.

<P><VAR>Direction</VAR> is the string "ltor", "rtol", or "rtola" indicating
left-to-right, right-to-left, or right-to-left Arabic text.

<P><VAR>Width</VAR> is the string "single" or "double"; double means that the
glyphs are twice as wide as ASCII characters in the Courier typeface.

<P><VAR>Normal, bold, italic</VAR>, and <VAR>bold-italic</VAR> 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.

<H2>Language Files</H2>

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

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

<UL>
	<LI>iso-8859-1
	<LI>iso-8859-2
	<LI>iso-8859-3
	<LI>iso-8859-4
	<LI>iso-8859-5
	<LI>iso-8859-6
	<LI>iso-8859-7
	<LI>iso-8859-8
	<LI>iso-8859-9
	<LI>iso-8859-10
	<LI>iso-8859-13
	<LI>iso-8859-14
	<LI>iso-8859-15
	<LI>us-ascii
	<LI>utf-8
	<LI>windows-874
	<LI>windows-1250
	<LI>windows-1251
	<LI>windows-1252
	<LI>windows-1253
	<LI>windows-1254
	<LI>windows-1255
	<LI>windows-1256
	<LI>windows-1257
	<LI>windows-1258
	<LI>koi8-r
	<LI>koi8-u
</UL>

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

<H2>MIME Files</H2>

<P>CUPS uses two MIME files in its standard configuration.

<H3>mime.types</H3>

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

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

<UL><PRE>
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 ]
</PRE></UL>

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

<H3>mime.convs</H3>

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

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

<UL><PRE>
super/type SP super/type2 SP cost SP program
</PRE></UL>

<H2>Option Files</H2>

<P>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 (<CODE>/etc/cups/lpoptions</CODE>) are loaded first,
followed by the user option file (<CODE>$HOME/.lpoptions</CODE>).
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:

<UL><PRE>
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
</PRE></UL>

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

<P><VAR>Name</VAR> is the name of a printer known to the local server.

<P><VAR>Instance</VAR> can be any string of letters, numbers, and the underscore
up to 127 characters in length.

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

<H2>PostScript Printer Description Files</H2>

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

<H3>PPD Specification</H3>

<P>The PPD file format is described in
<A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
Adobe TechNote #5003: PostScript Printer Description File Format
Specification Version 4.3</A>.

<H3>CUPS Extensions to PPD Files</H3>

<P>CUPS adds several new attributes that are described below.

<H4>cupsFilter</H4>

<P>This string attribute provides a conversion rule of the form:

<UL><PRE>
source/type cost program
</PRE></UL>

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

<H4>cupsFlipDuplex</H4>

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

<H4>cupsManualCopies</H4>

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

<H4>cupsModelNumber</H4>

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

<H4>cupsProfile</H4>

<P>This string attribute specifies a color profile of the form:

<UL><PRE>
resolution/type density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22
</PRE></UL>

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

<P>The <I>density</I> and <I>gamma</I> values define gamma and density
adjustment function such that:

<UL><PRE>
f(x) = density * x<SUP>gamma</SUP>
</PRE></UL>

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

<H4>cupsProtocol</H4>

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

<H4>cupsVersion</H4>

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

<H2>Scheduler Configuration Files</H2>

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

<DL>

	<DT>classes.conf
	<DD>This file defines all of the printer classes known to the
	system.

	<DT>cupsd.conf
	<DD>This file defines the files, directories, passwords, etc.
	used by the scheduler.

	<DT>printers.conf
	<DD>This file defines all of the printers known to the system.

</DL>

<H3>classes.conf</H3>

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

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

<CENTER><TABLE WIDTH="90%" BORDER="1">
<TR>
	<TH WIDTH="25%">Directive</TH>
	<TH>Description</TH>
</TR>
<TR>
	<TD>&lt;Class name&gt;<BR>
	&lt;/Class&gt;</TD>
	<TD>Surrounds a class definition.</TD>
</TR>
<TR>
	<TD>&lt;DefaultClass name&gt;<BR>
	&lt;/Class&gt;</TD>
	<TD>Surrounds a class definition for the default destination.</TD>
</TR>
<TR>
	<TD>Accepting</TD>
	<TD>Specifies whether the class is accepting new jobs. May be
	the names "Yes" or "No".</TD>
</TR>
<TR>
	<TD>AllowUsers</TD>
	<TD>Specifies a list of users that are allowed to access the class.</TD>
</TR>
<TR>
	<TD>BannerStart</TD>
	<TD>Specifies the banner that is printed before other files in a
	job.</TD>
</TR>
<TR>
	<TD>BannerEnd</TD>
	<TD>Specifies the banner that is printed after other files in a
	job.</TD>
</TR>
<TR>
	<TD>DenyUsers</TD>
	<TD>Specifies a list of users that are not allowed to access the
	class.</TD>
</TR>
<TR>
	<TD>Info</TD>
	<TD>A textual description of the class.</TD>
</TR>
<TR>
	<TD>Location</TD>
	<TD>A textual location of the class.</TD>
</TR>
<TR>
	<TD>Printer</TD>
	<TD>Specifies a printer that is a member of the class.</TD>
</TR>
<TR>
	<TD>State</TD>
	<TD>Specifies the initial state of the class; can be "Idle" or
	"Stopped".</TD>
</TR>
<TR>
	<TD>StateMessage</TD>
	<TD>Specifies a textual message for the current class state.</TD>
</TR>
</TABLE></CENTER>

<H3>cupsd.conf</H3>

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

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

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

<H3>printers.conf</H3>

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

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

<CENTER><TABLE WIDTH="90%" BORDER="1">
<TR>
	<TH WIDTH="25%">Directive</TH>
	<TH>Description</TH>
</TR>
<TR>
	<TD>Accepting</TD>
	<TD>Specifies whether the printer is accepting new jobs. May be
	the names "Yes" or "No".</TD>
</TR>
<TR>
	<TD>&lt;DefaultPrinter name&gt;<BR>
	&lt;/Printer&gt;</TD>
	<TD>Surrounds the printer definition for a default destination.</TD>
</TR>
<TR>
	<TD>AllowUsers</TD>
	<TD>Specifies a list of users that are allowed to access the printer.</TD>
</TR>
<TR>
	<TD>BannerStart</TD>
	<TD>Specifies the banner that is printed before other files in a
	job.</TD>
</TR>
<TR>
	<TD>BannerEnd</TD>
	<TD>Specifies the banner that is printed after other files in a
	job.</TD>
</TR>
<TR>
	<TD>DenyUsers</TD>
	<TD>Specifies a list of users that are not allowed to access the
	printer.</TD>
</TR>
<TR>
	<TD>DeviceURI</TD>
	<TD>Specifies the device-uri attribute for the printer.</TD>
</TR>
<TR>
	<TD>Info</TD>
	<TD>A textual description of the printer.</TD>
</TR>
<TR>
	<TD>Location</TD>
	<TD>A textual location of the printer.</TD>
</TR>
<TR>
	<TD>&lt;Printer name&gt;<BR>
	&lt;/Printer&gt;</TD>
	<TD>Surrounds the printer definition.</TD>
</TR>
<TR>
	<TD>State</TD>
	<TD>Specifies the initial state of the printer; can be "Idle" or
	"Stopped".</TD>
</TR>
<TR>
	<TD>StateMessage</TD>
	<TD>Specifies a textual message for the current printer state.</TD>
</TR>
</TABLE></CENTER>

<H1>External Interfaces</H1>

<H2>AppSocket Protocol</H2>

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

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

<H2>CUPS Browsing Protocol</H2>

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

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

<UL><PRE>
type SP state SP uri SP "location" SP "info" SP "make-and-model" NL
</PRE></UL>

<P><VAR>State, uri, location, info</VAR>, and <VAR>make-and-model</VAR>,
correspond to the IPP <CODE>printer-state</CODE>,
<CODE>printer-uri-supported</CODE>, <CODE>printer-location</CODE>,
<CODE>printer-info</CODE>, and <CODE>printer-make-and-model</CODE>
attributes.

<P><VAR>Type</VAR> is a hexadecimal number string representing
capability/type bits:

<CENTER><TABLE WIDTH="40%" BORDER="1">
<TR>
	<TH WIDTH="8%">Bit</TH>
	<TH>Description</TH>
</TR>
<TR>
	<TD>0</TD>
	<TD>0 = printer<BR>
	1 = class</TD>
</TR>
<TR>
	<TD>1</TD>
	<TD>0 = local<BR>
	1 = remote<BR>
	(always 1)</TD>
</TR>
<TR>
	<TD>2</TD>
	<TD>1 = can print B&W</TD>
</TR>
<TR>
	<TD>3</TD>
	<TD>1 = can print color</TD>
</TR>
<TR>
	<TD>4</TD>
	<TD>1 = can duplex</TD>
</TR>
<TR>
	<TD>5</TD>
	<TD>1 = can staple</TD>
</TR>
<TR>
	<TD>6</TD>
	<TD>1 = can do fast copies</TD>
</TR>
<TR>
	<TD>7</TD>
	<TD>1 = can do fast collating</TD>
</TR>
<TR>
	<TD>8</TD>
	<TD>1 = can punch holes</TD>
</TR>
<TR>
	<TD>9</TD>
	<TD>1 = can cover</TD>
</TR>
<TR>
	<TD>10</TD>
	<TD>1 = can bind</TD>
</TR>
<TR>
	<TD>11</TD>
	<TD>1 = can sort</TD>
</TR>
<TR>
	<TD>12</TD>
	<TD>1 = can print up to 9x14 inches</TD>
</TR>
<TR>
	<TD>13</TD>
	<TD>1 = can print up to 18x24 inches</TD>
</TR>
<TR>
	<TD>14</TD>
	<TD>1 = can print up to 36x48 inches</TD>
</TR>
<TR>
	<TD>15</TD>
	<TD>1 = can print variable sizes</TD>
</TR>
</TABLE></CENTER>

<H2>CUPS Form File</H2>

<P>CUPS Form files are XML files used by the CUPS <CODE>formtops</CODE>
filter to produce dynamic banner pages and support preprinted forms.

<P>The MIME type for CUPS Form files is
<CODE>application/vnd.cups-form</CODE>.

<H3>CUPS Form DTD</H3>

<P>The following DTD describes the available elements and attributes in
a CUPS Form file:

<CENTER><TABLE BORDER>
<TR>
<TD><PRE>
&lt;!ENTITY % Angle "CDATA" -- angle in degrees -->

&lt;!ENTITY % Color "CDATA" -- a color using sRGB: #RRGGBB as Hex values -->

&lt;!ENTITY % Length "CDATA" -- nn for pixels or nn% for percentage length -->

&lt;!ENTITY % Lengths "CDATA" -- comma-separated Length values -->

&lt;!ENTITY % Text "CDATA">

&lt;!ENTITY % heading "H1|H2|H3|H4|H5|H6">

&lt;!ENTITY % preformatted "PRE">

&lt;!ENTITY % i18n
 "lang        %LanguageCode; #IMPLIED  -- language code --
  dir         (ltr|rtl)      #IMPLIED  -- direction for weak/neutral text --"
  >

&lt;!ENTITY % attrs "%i18n;">

&lt;!ENTITY % fontstyle
 "B | FONT | I | TT">

&lt;!ENTITY % graphics
 "BOX | RECT | LINE | POLY | ARC | PIE | TEXT">

&lt;!ENTITY % insert
 "IMG | VAR">

&lt;!-- %inline; covers inline or "text-level" elements -->
&lt;!ENTITY % inline "#PCDATA | %fontstyle; | %graphics; | %insert;">

&lt;!ELEMENT (%fontstyle;) - - (%inline;)*>
&lt;!ATTLIST (%fontstyle;)
  %attrs;                              -- %i18n --
  >

&lt;!ELEMENT BR - O EMPTY                 -- forced line break -->
&lt;!ATTLIST BR
  %attrs;                              -- %i18n --
  >

&lt;!ENTITY % block
     "P | %heading; | %preformatted;">

&lt;!ENTITY % flow "%block; | %inline;">

&lt;!ELEMENT PAGE O O (%flow;)+           -- document body -->
&lt;!ATTLIST PAGE
  %attrs;                              -- %i18n --
  align       (left|center|right) #IMPLIED -- horizontal alignment --
  valign      (top|middle|center|bottom) #IMPLIED -- vertical alignment --
  >

&lt;!ELEMENT P - O (%inline;)*            -- paragraph -->
&lt;!ATTLIST P
  %attrs;                              -- %i18n --
  align       (left|center|right) #IMPLIED -- horizontal alignment --
  >

&lt;!ELEMENT (%heading;)  - - (%inline;)* -- heading -->
&lt;!ATTLIST (%heading;)
  %attrs;                              -- %i18n --
  align       (left|center|right) #IMPLIED -- horizontal alignment --
  >

&lt;!ELEMENT PRE - - (%inline;)*          -- preformatted text -->
&lt;!ATTLIST PRE
  %attrs;                              -- %i18n --
  align       (left|center|right) #IMPLIED -- horizontal alignment --
  >

&lt;!ELEMENT BOX - O EMPTY                -- unfilled box -->
&lt;!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 --
  >

&lt;!ELEMENT RECT - O EMPTY               -- filled box -->
&lt;!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 --
  >

&lt;!ELEMENT LINE - O EMPTY               -- polyline -->
&lt;!ATTLIST LINE
  color       %Color;        #IMPLIED  -- override color --
  thickness   %Length;       #IMPLIED  -- override line thickness --
  x           %Lengths;      #REQUIRED -- horizontal positions --
  y           %Lengths;      #REQUIRED -- vertical positions --
  >

&lt;!ELEMENT POLY - O EMPTY               -- polygon (filled) -->
&lt;!ATTLIST POLY
  color       %Color;        #IMPLIED  -- override color --
  x           %Lengths;      #REQUIRED -- horizontal positions --
  y           %Lengths;      #REQUIRED -- vertical positions --
  >

&lt;!ELEMENT ARC - O EMPTY                -- unfilled arc -->
&lt;!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 --
  >

&lt;!ELEMENT PIE - O EMPTY                -- filled arc -->
&lt;!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 --
  >

&lt;!ELEMENT TEXT - - (%flow;)*           -- text box -->
&lt;!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 --
  >


&lt;!ELEMENT IMG - O EMPTY                -- Embedded image -->
&lt;!ATTLIST IMG
  %attrs;                              -- %coreattrs, %i18n, %events --
  src         %URI;          #REQUIRED -- URI of image to embed --
  height      %Length;       #IMPLIED  -- override height --
  width       %Length;       #IMPLIED  -- override width --
  >

&lt;!ELEMENT HEAD O O (DEFVAR)*           -- document head -->
&lt;!ATTLIST HEAD
  %i18n;                               -- lang, dir --
  >

&lt;!ELEMENT DEFVAR - O EMPTY             -- variable definition -->
&lt;!ATTLIST DEFVAR
  name        CDATA          #REQUIRED -- name
  value       CDATA          #REQUIRED -- value
  >


&lt;!ENTITY % html.content "HEAD, PAGE">

&lt;!ELEMENT CUPSFORM - - (HEAD) (PAGE)+  -- document root element -->
&lt;!ATTLIST CUPSFORM
  %i18n;                               -- lang, dir --
  >
</PRE></TD>
</TR>
</TABLE></CENTER>

<H2>CUPS PostScript File</H2>

<P>CUPS PostScript files are device-dependent Adobe PostScript program files.
The PostScript language is described in the
<A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf">
Adobe PostScript Language Reference Manual, Third Edition</A>.

<P>The MIME type for CUPS PostScript files is
<CODE>application/vnd.cups-postscript</CODE>.

<H2>CUPS Raster File</H2>

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

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

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

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

<P>The MIME type for CUPS Raster files is
<CODE>application/vnd.cups-raster</CODE>.

<H2>CUPS Raw Files</H2>

<P>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 <CODE>application/vnd.cups-raw</CODE>.

<H2>Internet Printing Protocol</H2>

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

<H2>Line Printer Daemon Protocol</H2>

<P>The Line Printer Daemon (LPD) protocol is described by
<A HREF="http://www.ietf.org/rfc/rfc1179.txt">RFC 1179: Line Printer Daemon
Protocol</A>.

<P>The URI method name for LPD is "lpd".

<H2>Server Message Block Protocol</H2>

<P>The Server Message Block (SMB) and related Common Internet File
System (CIFS) protocols are described at
<A HREF="http://anu.samba.org/cifs">http://anu.samba.org/cifs</A>.

<P>The URI method name for SMB is "smb". Support for this protocol is
provided via the SAMBA <CODE>smbspool(1)</CODE> program provided with
SAMBA 2.0.6 and higher.

<H1>Directories</H1>

<DL>

	<DT>/etc/cups
	<DD>The scheduler configuration and MIME files reside here.

	<DT>/etc/cups/certs
	<DD>The authentication certificates reside here.

	<DT>/etc/cups/interfaces
	<DD>System V interface scripts reside here.

	<DT>/etc/cups/ppd
	<DD>This directory contains PPD files for each printer.

	<DT>/usr/bin
	<DD>The <CODE>cancel</CODE>, <CODE>lp</CODE>, <CODE>lpq</CODE>,
	<CODE>lpr</CODE>, <CODE>lprm</CODE>, and <CODE>lpstat</CODE> commands
	reside here.

	<DT>/usr/lib, /usr/lib32
	<DD>The shared libraries (DSOs) reside here.

	<DT>/usr/lib/cups/backend
	<DD>The backend filters reside here.

	<DT>/usr/lib/cups/cgi-bin
	<DD>The CGI programs reside here.

	<DT>/usr/lib/cups/daemon
	<DD>The polling and LPD daemons reside here.

	<DT>/usr/lib/cups/filter
	<DD>The file filters reside here.

	<DT>/usr/sbin
	<DD>The <CODE>accept</CODE>, <CODE>cupsd</CODE>,
	<CODE>lpadmin</CODE>, <CODE>lpc</CODE>, and <CODE>reject</CODE>
	commands reside here.

	<DT>/usr/share/cups
	<DD>This is the root directory of the CUPS static data.

	<DT>/usr/share/cups/charsets
	<DD>The character set files reside here.

	<DT>/usr/share/cups/data
	<DD>The filter data files reside here.

	<DT>/usr/share/cups/fonts
	<DD>The <CODE>pstoraster</CODE> font files reside here.

	<DT>/usr/share/cups/model
	<DD>The sample PPD files reside here.

	<DT>/usr/share/cups/pstoraster
	<DD>The <CODE>pstoraster</CODE> data files reside here.

	<DT>/usr/share/doc/cups
	<DD>The scheduler documentation files reside here.

	<DT>/var/log/cups
	<DD>The <CODE>access_log</CODE>, <CODE>error_log</CODE>, and
	<CODE>page_log</CODE> files reside here.

	<DT>/var/spool/cups
	<DD>This directory contains print job files.

</DL>

<EMBED SRC="glossary.shtml">

</BODY>
</HTML>