[thirdparty/cups.git] / doc / help / spec-design.html

<HTML>
<!-- SECTION: Specifications -->
<HEAD>
	<TITLE>CUPS Design Description</TITLE>
</HEAD>
<BODY>

<P><EM>This document is still being updated for CUPS
1.2...</EM></P>

<P>This design description documents the overall organization of
the Common UNIX Printing System. The purpose is not to provide a
line-by-line description of the CUPS source code, but rather to
describe the overall architecture and location of key pieces so
that developers can more easily understand the underlying
operation of CUPS.</P>

<H2 CLASS="title"><A NAME="INTRO">Introduction</A></H2>

<P>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. <A
HREF="#FIGURE1">Figure 1</A> shows the basic organization of
CUPS.</P>

<H3>Scheduler</H3>

<P>The scheduler is a HTTP/1.1 and IPP/1.1 server application
manages HTTP and IPP requests, printers, classes, jobs,
subscriptions, and notifications on the system. HTTP is used for
normal web browser services as well as IPP operation messages
passed via HTTP POST requests with the
<CODE>application/ipp</CODE> content type. The scheduler uses a
series of helper Common Gateway Interface ("CGI") applications to
provide dynamic web interfaces, and can be configured to run
additional, site-specific programs or scripts for the web
interface.</P>

<P>The scheduler is designed as a traditional monolithic,
single-threaded server process which runs external processes to
do longer-term operations such as printing, notification,
device/driver enumeration, and remote printer monitoring. While
this design does limit the maximum number of simultaneous clients
that can be supported on a typical system, it also keep resource
utilization to a minimum and greatly simplifies the scheduler's
logic.</P>

<DIV CLASS="figure"><TABLE SUMMARY="CUPS Block Diagram">
<CAPTION>Figure 1: <A NAME="FIGURE1">CUPS Block Diagram</A></CAPTION>
<TR><TD ALIGN="CENTER"><IMG SRC="../images/cups-block-diagram.gif"
WIDTH="768" HEIGHT="768" ALT="CUPS Block Diagram"/></TD></TR>
</TABLE></DIV>

<H4>Job Files</H4>

<P>The scheduler stores job files in a <EM>spool directory</EM>,
typically <VAR>/var/spool/cups</VAR>. Two types of files will be
found in the spool directory: <EM>control files</EM> starting
with the letter "c" ("c00001", "c99999", "c100000", etc.) and
<EM>data files</EM> starting with the letter "d" ("d00001-001",
"d99999-001", "d100000-001", etc.) Control files are IPP messages
based on the original IPP Print-Job or Create-Job messages, while
data files are the original print files that were submitted for
printing. There is one control file for every job known to the
system and 0 or more data files for each job. Data files are
normally removed after a job has successfully printed, however
this behavior can be configured.</P>

<H4>Log Files</H4>

<P>The scheduler keeps three kinds of log files which are
normally stored in the <VAR>/var/log/cups</VAR> directory. The <A
HREF="ref-access_log.html">access_log</A> file lists every HTTP
and IPP request that is processed by the scheduler. The <A
HREF="ref-error_log.html">error_log</A> file contains messages
from the scheduler and its helper applications that can be used
to track down problems. The <A
HREF="ref-page_log.html">page_log</A> file lists every page that
is printed, allowing for simple print accounting.</P>

<P>Log files are rotated automatically by the scheduler when they
reach the configured size limit, by default 1MB. If the limit is
set to 0 then no rotation is performed in the scheduler - this
mode is often used by Linux distributions so they can use the
<B>logrotated(8)</B> program to rotate them instead.</P>

<H4>Config Files</H4>

<P>The scheduler uses several configuration files to store the
server settings (<A HREF="ref-cupsd-conf.html">cupsd.conf</A>),
available classes (<A
HREF="ref-classes-conf.html">classes.conf</A>), available
printers (<A HREF="ref-printers-conf.html">printers.conf</A>),
current notification subscriptions (<A
HREF="ref-subscriptions-conf.html">subscriptions.conf</A>), and
supported file types and filters (<A
HREF="man-mime.types.html">mime.types</A>, <A
HREF="man-mime.convs.html">mime.convs</A>). In addition,
PostScript Printer Description ("PPD") files or interface scripts
are associated with each printer, and the scheduler has cache
files for remote printers, PPD files, and current jobs to
optimize the scheduler's startup speed and availability.</P>

<H3>Berkeley Commands</H3>

<P>CUPS provides the Berkeley <A HREF="man-lpc.html">lpc(8)</A>,
<A HREF="man-lpq.html">lpq(1)</A>, <A
HREF="man-lpr.html">lpr(1)</A>, and <A
HREF="man-lprm.html">lprm(1)</A> commands. In general, they
function identically to the original Berkeley commands with the
following exceptions:</P>

<OL>

	<LI>The <B>lpc</B> command currently only supports the
	"status" sub-command.</LI>

	<LI>The <B>lpr</B> command does not support the format
	modifier options "1" (TROFF font set 1), "2" (TROFF font
	set 2), "3" (TROFF font set 3), "4" (TROFF font set 4),
	"c" (CIFPLOT), "d" (DVI), "f" (FORTRAN), "g" (GNU plot),
	"i" (indentation), "n" (Ditroff), "r" (Sun raster), "t"
	(Troff), or "w" (width), as they do not map to the IPP
	MIME media type based document formats.</LI>

</OL>

<H3>System V Commands</H3>

<P>CUPS provides the System V <A
HREF="man-accept.html">accept(8)</A>, <A
HREF="man-cancel.html">cancel(1)</A>, <A
HREF="man-lp.html">lp(1)</A>, <A
HREF="man-lpadmin.html">lpadmin(8)</A>, <A
HREF="man-lpmove.html">lpmove(8)</A>, <A
HREF="man-lpstat.html">lpstat(1)</A>, and <A
HREF="man-accept.html">reject(8)</A> commands. In general, they
function identically to the original System V commands with the
following exceptions:</P>

<OL>

	<LI>All commands may ask for a password; the System V
	print spooler requires root access to perform
	administration tasks, while CUPS allows for more flexible
	configurations.</LI>

	<LI>The <B>lpadmin</B> command does not implement the
	Solaris "-A" (alert), "-F" (fault recovery), "-M" (mount
	form/wheel), "-P" (paper list), "-S" (print wheels), "-T"
	(type list), "-U" (dialer info), "-W" (wait), "-f" (form
	name), "-l" (content-type list), "-s" (remote printer),
	or "-t" (number of trays) options.</LI>

</OL>

<H3>CUPS Commands</H3>

<P>CUPS provides the <A
HREF="man-cupsaddsmb.html">cupsaddsmb(8)</A>, <A
HREF="man-cupsenable.html">cupsdisable(8)</A>, <A
HREF="man-cupsenable.html">cupsenable(8)</A>, <A
HREF="man-cupstestppd.html">cupstestppd(1)</A>, <A
HREF="man-lpinfo.html">lpinfo(8)</A>, and <A
HREF="man-lppasswd.html">lppasswd(1)</A> commands. The
<B>cupsdisable</B> and <B>cupsenable</B> commands correspond to
the System V <B>disable</B> and <B>enable</B> commands but have
been renamed to avoid conflicts with the <B>bash(1)</B> internal
commands of the same name.</P>

<H3>LPD Support</H3>

<P>LPD client support is provided via the <A
HREF="man-cups-lpd.html">cups-lpd(8)</A> program. Incoming LPD
requests are accepted on TCP port 515 by the local
<B>inetd(8)</B>, <B>launchd(8)</B>, or <B>xinetd(8)</B> process
and forwarded to the <B>cups-lpd</B> program for conversion to
the corresponding IPP request(s).</P>

<P>The <B>cups-lpd</B> program conforms, for the most part, to
RFC 1179: Line Printer Daemon Protocol, but does not enforce the
privileged source port restriction specified in that document. In
addition, the banner page and output format options are usually
overridden via command-line options to the <B>cups-lpd</B>
program when it is invoked by the corresponding super-daemon
program.</P>

<H3>Web Interface</H3>

<P>The web interface is supported by five CGI programs. Table 1
describes the purpose of each of the programs.</P>

<DIV CLASS="table"><TABLE SUMMARY="CGI Programs">
<CAPTION>Table 1: <A NAME="TABLE1">CGI Programs</A></CAPTION>
<THEAD>
<TR>
	<TH>Program</TH>
	<TH>Location</TH>
	<TH>Description</TH>
</TR>
</THEAD>
<TBODY>
<TR>
	<TD>admin.cgi</TD>
	<TD>/admin</TD>
	<TD>Provides all of the administrative functions</TD>
</TR>
<TR>
	<TD>classes.cgi</TD>
	<TD>/classes</TD>
	<TD>Lists classes and provides class management functions</TD>
</TR>
<TR>
	<TD>help.cgi</TD>
	<TD>/help</TD>
	<TD>Provides access to on-line help documents</TD>
</TR>
<TR>
	<TD>jobs.cgi</TD>
	<TD>/jobs</TD>
	<TD>Lists jobs and provides job management functions</TD>
</TR>
<TR>
	<TD>printers.cgi</TD>
	<TD>/printers</TD>
	<TD>Lists printers and provides printer management functions</TD>
</TR>
</TBODY>
</TABLE></DIV>

<H3>Notifiers</H3>

<P>Notifiers provide the means for sending event notifications
from the scheduler. Notifiers are executed with the recipient
information on the command-line and the event data on the
standard input.</P>

<P>The <B>mailto</B> notifier is the only notifier included with
CUPS 1.2 and handles email notifications for the scheduler.
Additional notifiers can be added as needed without additional
configuration.</P>

<H3>Filters</H3>

<P>Filters convert job files into a printable format. Multiple
filters are run, as needed, to convert from the job file format
to the printable format. 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.</P>

<P>CUPS provides filters for printing text, PostScript, PDF,
HP-GL/2, and many types of image files. CUPS also provides
printer driver filters for HP-PCL, ESC/P, and several types of
label printers. Additional filters can be added through the use
of mime.convs and PPD files.</P>

<H3>Port Monitors</H3>

<P>Port monitors handle the device- and channel-specific data
formatting for a printer. Port monitors use the same interface as
filters.</P>

<P>CUPS includes two port monitors: the <B>bcp</B> port monitor
which supports the PostScript Binary Communications Protocol
("BCP") and the <b>tbcp</b> port monitor which supports the
PostScript Tagged Binary Communications Protocol ("TBCP").
Additional port monitors can be added through PPD files.</P>

<H3>Backends</H3>

<P>Backends send print data to the printer and enumerate
available printers/devices as needed. Backends use the same
interface as filters.</P>

<P>CUPS includes backends for parallel, serial, SCSI, USB, LPD,
IPP, and AppSocket (JetDirect) connections. Additional backends
can be added as needed without additional configuration.</P>

<H2 CLASS="title"><A NAME="PROGRAMMING">Programming Interfaces</A></H2>

<P>CUPS makes use of two general-purpose libraries to provide its
printing services. The CUPS library provides the general
communications and management infrastructure while the CUPS
imaging library provides the image file and raster data
support.</P>

<H3>CUPS Libary</H3>

<P>The CUPS library 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.</P>

<H3>CUPS Imaging Library</H3>

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

<!--<H2 CLASS="title">Network Printing</H2>

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

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

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

<P>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!</P>

<H3>Scheduler</H3>

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

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

<H3>Configuration Files</H3>

<P>The configuration files consist of:</P>

<ul>

	<LI>The HTTP server configuration file.</LI>

	<LI>Printer and class definition files.</LI>

	<LI>MIME type and conversion rule files.</LI>

	<LI>PostScript Printer Description (PPD) files.</LI>

</ul>

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

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

<P>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 <tt>Content-Type</tt> field for
<tt>GET</tt> and <tt>HEAD</tt> requests and by the IPP request
handler to determine the file type when a <tt>Print-Job</tt> or
<tt>Send-File</tt> request is received with a
<tt>document-format</tt> of
<tt>application/octet-stream</tt>.</P>

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

<P>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 <tt>cupsFilter</tt> attributes to support
printer drivers.</P>
-->

</BODY>
</HTML>
Commit	Line	Data
4744bd90	1	<HTML>
	2	<!-- SECTION: Specifications -->
	3	<HEAD>
	4	<TITLE>CUPS Design Description</TITLE>
	5	</HEAD>
	6	<BODY>
	7
e1d6a774	8	<P><EM>This document is still being updated for CUPS
	9	1.2...</EM></P>
	10
	11	<P>This design description documents the overall organization of
	12	the Common UNIX Printing System. The purpose is not to provide a
	13	line-by-line description of the CUPS source code, but rather to
	14	describe the overall architecture and location of key pieces so
	15	that developers can more easily understand the underlying
	16	operation of CUPS.</P>
	17
	18	<H2 CLASS="title"><A NAME="INTRO">Introduction</A></H2>
	19
4744bd90	20	<P>Like most printing systems, CUPS is designed around a central
	21	print scheduling process that dispatches print jobs, processes
	22	administrative commands, provides printer status information to
e1d6a774	23	local and remote programs, and informs users as needed. <A
	24	HREF="#FIGURE1">Figure 1</A> shows the basic organization of
	25	CUPS.</P>
	26
	27	<H3>Scheduler</H3>
	28
	29	<P>The scheduler is a HTTP/1.1 and IPP/1.1 server application
	30	manages HTTP and IPP requests, printers, classes, jobs,
	31	subscriptions, and notifications on the system. HTTP is used for
	32	normal web browser services as well as IPP operation messages
	33	passed via HTTP POST requests with the
	34	<CODE>application/ipp</CODE> content type. The scheduler uses a
	35	series of helper Common Gateway Interface ("CGI") applications to
	36	provide dynamic web interfaces, and can be configured to run
	37	additional, site-specific programs or scripts for the web
	38	interface.</P>
	39
	40	<P>The scheduler is designed as a traditional monolithic,
	41	single-threaded server process which runs external processes to
	42	do longer-term operations such as printing, notification,
	43	device/driver enumeration, and remote printer monitoring. While
	44	this design does limit the maximum number of simultaneous clients
	45	that can be supported on a typical system, it also keep resource
	46	utilization to a minimum and greatly simplifies the scheduler's
	47	logic.</P>
	48
	49	<DIV CLASS="figure"><TABLE SUMMARY="CUPS Block Diagram">
	50	<CAPTION>Figure 1: <A NAME="FIGURE1">CUPS Block Diagram</A></CAPTION>
	51	<TR><TD ALIGN="CENTER"><IMG SRC="../images/cups-block-diagram.gif"
	52	WIDTH="768" HEIGHT="768" ALT="CUPS Block Diagram"/></TD></TR>
	53	</TABLE></DIV>
	54
	55	<H4>Job Files</H4>
	56
	57	<P>The scheduler stores job files in a <EM>spool directory</EM>,
	58	typically <VAR>/var/spool/cups</VAR>. Two types of files will be
	59	found in the spool directory: <EM>control files</EM> starting
	60	with the letter "c" ("c00001", "c99999", "c100000", etc.) and
	61	<EM>data files</EM> starting with the letter "d" ("d00001-001",
	62	"d99999-001", "d100000-001", etc.) Control files are IPP messages
	63	based on the original IPP Print-Job or Create-Job messages, while
	64	data files are the original print files that were submitted for
	65	printing. There is one control file for every job known to the
	66	system and 0 or more data files for each job. Data files are
	67	normally removed after a job has successfully printed, however
	68	this behavior can be configured.</P>
	69
	70	<H4>Log Files</H4>
	71
	72	<P>The scheduler keeps three kinds of log files which are
	73	normally stored in the <VAR>/var/log/cups</VAR> directory. The <A
	74	HREF="ref-access_log.html">access_log</A> file lists every HTTP
	75	and IPP request that is processed by the scheduler. The <A
	76	HREF="ref-error_log.html">error_log</A> file contains messages
	77	from the scheduler and its helper applications that can be used
	78	to track down problems. The <A
	79	HREF="ref-page_log.html">page_log</A> file lists every page that
	80	is printed, allowing for simple print accounting.</P>
	81
	82	<P>Log files are rotated automatically by the scheduler when they
	83	reach the configured size limit, by default 1MB. If the limit is
	84	set to 0 then no rotation is performed in the scheduler - this
	85	mode is often used by Linux distributions so they can use the
	86	<B>logrotated(8)</B> program to rotate them instead.</P>
87
88	<H4>Config Files</H4>
89
90	<P>The scheduler uses several configuration files to store the
91	server settings (<A HREF="ref-cupsd-conf.html">cupsd.conf</A>),
92	available classes (<A
93	HREF="ref-classes-conf.html">classes.conf</A>), available
94	printers (<A HREF="ref-printers-conf.html">printers.conf</A>),
95	current notification subscriptions (<A
96	HREF="ref-subscriptions-conf.html">subscriptions.conf</A>), and
97	supported file types and filters (<A
98	HREF="man-mime.types.html">mime.types</A>, <A
99	HREF="man-mime.convs.html">mime.convs</A>). In addition,
100	PostScript Printer Description ("PPD") files or interface scripts
101	are associated with each printer, and the scheduler has cache
102	files for remote printers, PPD files, and current jobs to
103	optimize the scheduler's startup speed and availability.</P>
104
105	<H3>Berkeley Commands</H3>
106
107	<P>CUPS provides the Berkeley <A HREF="man-lpc.html">lpc(8)</A>,
108	<A HREF="man-lpq.html">lpq(1)</A>, <A
109	HREF="man-lpr.html">lpr(1)</A>, and <A
110	HREF="man-lprm.html">lprm(1)</A> commands. In general, they
111	function identically to the original Berkeley commands with the
112	following exceptions:</P>
113
114	<OL>
115
116	<LI>The <B>lpc</B> command currently only supports the
117	"status" sub-command.</LI>
118
119	<LI>The <B>lpr</B> command does not support the format
120	modifier options "1" (TROFF font set 1), "2" (TROFF font
121	set 2), "3" (TROFF font set 3), "4" (TROFF font set 4),
122	"c" (CIFPLOT), "d" (DVI), "f" (FORTRAN), "g" (GNU plot),
123	"i" (indentation), "n" (Ditroff), "r" (Sun raster), "t"
124	(Troff), or "w" (width), as they do not map to the IPP
125	MIME media type based document formats.</LI>
126
127	</OL>
128
129	<H3>System V Commands</H3>
130
131	<P>CUPS provides the System V <A
132	HREF="man-accept.html">accept(8)</A>, <A
133	HREF="man-cancel.html">cancel(1)</A>, <A
134	HREF="man-lp.html">lp(1)</A>, <A
135	HREF="man-lpadmin.html">lpadmin(8)</A>, <A
136	HREF="man-lpmove.html">lpmove(8)</A>, <A
137	HREF="man-lpstat.html">lpstat(1)</A>, and <A
138	HREF="man-accept.html">reject(8)</A> commands. In general, they
139	function identically to the original System V commands with the
140	following exceptions:</P>
141
142	<OL>
143
144	<LI>All commands may ask for a password; the System V
145	print spooler requires root access to perform
146	administration tasks, while CUPS allows for more flexible
147	configurations.</LI>
148
149	<LI>The <B>lpadmin</B> command does not implement the
150	Solaris "-A" (alert), "-F" (fault recovery), "-M" (mount
151	form/wheel), "-P" (paper list), "-S" (print wheels), "-T"
152	(type list), "-U" (dialer info), "-W" (wait), "-f" (form
153	name), "-l" (content-type list), "-s" (remote printer),
154	or "-t" (number of trays) options.</LI>
155
156	</OL>
157
158	<H3>CUPS Commands</H3>
159
160	<P>CUPS provides the <A
161	HREF="man-cupsaddsmb.html">cupsaddsmb(8)</A>, <A
162	HREF="man-cupsenable.html">cupsdisable(8)</A>, <A
163	HREF="man-cupsenable.html">cupsenable(8)</A>, <A
164	HREF="man-cupstestppd.html">cupstestppd(1)</A>, <A
165	HREF="man-lpinfo.html">lpinfo(8)</A>, and <A
166	HREF="man-lppasswd.html">lppasswd(1)</A> commands. The
167	<B>cupsdisable</B> and <B>cupsenable</B> commands correspond to
168	the System V <B>disable</B> and <B>enable</B> commands but have
169	been renamed to avoid conflicts with the <B>bash(1)</B> internal
170	commands of the same name.</P>
171
172	<H3>LPD Support</H3>
173
174	<P>LPD client support is provided via the <A
175	HREF="man-cups-lpd.html">cups-lpd(8)</A> program. Incoming LPD
176	requests are accepted on TCP port 515 by the local
177	<B>inetd(8)</B>, <B>launchd(8)</B>, or <B>xinetd(8)</B> process
178	and forwarded to the <B>cups-lpd</B> program for conversion to
179	the corresponding IPP request(s).</P>
180
181	<P>The <B>cups-lpd</B> program conforms, for the most part, to
182	RFC 1179: Line Printer Daemon Protocol, but does not enforce the
183	privileged source port restriction specified in that document. In
184	addition, the banner page and output format options are usually
185	overridden via command-line options to the <B>cups-lpd</B>
186	program when it is invoked by the corresponding super-daemon
187	program.</P>
188
189	<H3>Web Interface</H3>
190
191	<P>The web interface is supported by five CGI programs. Table 1
192	describes the purpose of each of the programs.</P>
193
194	<DIV CLASS="table"><TABLE SUMMARY="CGI Programs">
195	<CAPTION>Table 1: <A NAME="TABLE1">CGI Programs</A></CAPTION>
196	<THEAD>
197	<TR>
198	<TH>Program</TH>
199	<TH>Location</TH>
200	<TH>Description</TH>
201	</TR>
202	</THEAD>
203	<TBODY>
204	<TR>
205	<TD>admin.cgi</TD>
206	<TD>/admin</TD>
207	<TD>Provides all of the administrative functions</TD>
208	</TR>
209	<TR>
210	<TD>classes.cgi</TD>
211	<TD>/classes</TD>
212	<TD>Lists classes and provides class management functions</TD>
213	</TR>
214	<TR>
215	<TD>help.cgi</TD>
216	<TD>/help</TD>
217	<TD>Provides access to on-line help documents</TD>
218	</TR>
219	<TR>
220	<TD>jobs.cgi</TD>
221	<TD>/jobs</TD>
222	<TD>Lists jobs and provides job management functions</TD>
223	</TR>
224	<TR>
225	<TD>printers.cgi</TD>
226	<TD>/printers</TD>
227	<TD>Lists printers and provides printer management functions</TD>
228	</TR>
229	</TBODY>
230	</TABLE></DIV>
231
232	<H3>Notifiers</H3>
233
234	<P>Notifiers provide the means for sending event notifications
235	from the scheduler. Notifiers are executed with the recipient
236	information on the command-line and the event data on the
237	standard input.</P>
238
239	<P>The <B>mailto</B> notifier is the only notifier included with
240	CUPS 1.2 and handles email notifications for the scheduler.
241	Additional notifiers can be added as needed without additional
242	configuration.</P>
243
244	<H3>Filters</H3>
245
246	<P>Filters convert job files into a printable format. Multiple
247	filters are run, as needed, to convert from the job file format
248	to the printable format. A filter program reads from the standard
249	input or from a file if a filename is supplied. All filters must
250	support a common set of options including printer name, job ID,
251	username, job title, number of copies, and job options. All
252	output is sent to the standard output.</P>
253
254	<P>CUPS provides filters for printing text, PostScript, PDF,
255	HP-GL/2, and many types of image files. CUPS also provides
256	printer driver filters for HP-PCL, ESC/P, and several types of
257	label printers. Additional filters can be added through the use
258	of mime.convs and PPD files.</P>
259
260	<H3>Port Monitors</H3>
261
262	<P>Port monitors handle the device- and channel-specific data
263	formatting for a printer. Port monitors use the same interface as
264	filters.</P>
265
266	<P>CUPS includes two port monitors: the <B>bcp</B> port monitor
267	which supports the PostScript Binary Communications Protocol
268	("BCP") and the <b>tbcp</b> port monitor which supports the
269	PostScript Tagged Binary Communications Protocol ("TBCP").
270	Additional port monitors can be added through PPD files.</P>
271
272	<H3>Backends</H3>
273
274	<P>Backends send print data to the printer and enumerate
275	available printers/devices as needed. Backends use the same
276	interface as filters.</P>
277
278	<P>CUPS includes backends for parallel, serial, SCSI, USB, LPD,
279	IPP, and AppSocket (JetDirect) connections. Additional backends
280	can be added as needed without additional configuration.</P>
281
282	<H2 CLASS="title"><A NAME="PROGRAMMING">Programming Interfaces</A></H2>
283
284	<P>CUPS makes use of two general-purpose libraries to provide its
285	printing services. The CUPS library provides the general
286	communications and management infrastructure while the CUPS
287	imaging library provides the image file and raster data
288	support.</P>
289
290	<H3>CUPS Libary</H3>
291
292	<P>The CUPS library contains CUPS-specific convenience functions
293	for queuing print jobs, getting printer information, accessing
294	resources via HTTP and IPP, and manipulating PPD files. Unlike
295	the rest of CUPS, the CUPS API is provided under the terms of the
296	GNU LGPL so it may be used by non-GPL applications.</P>
297
298	<H3>CUPS Imaging Library</H3>
299
300	<P>The CUPS imaging library provides functions for managing large
301	images, doing colorspace conversion and color management, scaling
302	images for printing, and managing raster page streams. It is used
303	by the CUPS image file filters, the PostScript RIP, and all
304	raster printers drivers.</P>
305
306	<!--<H2 CLASS="title">Network Printing</H2>
307
308	<P>Traditionally, network printing has been one of the hardest
309	things to get working under UNIX. One reason is because each
310	vendor added their own extensions to the LPD protocol (the
311	previous standard for network printing), making cross-platform
312	printing difficult if not impossible.</P>
313
314	<P>Another reason is that you have to administer every network
315	printer on every client machine. In some cases you can "clone'
316	the printer configuration from a "master' client to each of the
317	others, but even that can be time-consuming and error-prone.
318	Something better is needed.</P>
319
320	<P>CUPS provides "printer browsing", which allows clients to
321	automatically see and use printers from any server on a LAN.
322	This means that you only need to configure the server and the
323	clients will automatically see the printers and classes on
324	it.</P>
325
326	<P>In addition, CUPS can automatically merge multiple identical
327	network printers into "implicit classes". This allows clients to
328	send jobs to the implicit class and have them print on the first
329	available printer or server. In addition, failsafe and
330	load-balancing functions are enabled simply by defining the same
331	printer on multiple servers!</P>
4744bd90	332
	333	<H3>Scheduler</H3>
	334
	335	<P>The scheduler is a HTTP/1.1 server application that handles
	336	HTTP requests. Besides handling printer requests via IPP POST
	337	requests, the scheduler also acts as a full-featured web server
	338	for documentation, status monitoring, and administration.</P>
	339
	340	<P>The scheduler also manages a list of available printers on
	341	the LAN and dispatches print jobs as needed using the
	342	appropriate filters and backends.</P>
	343
	344	<H3>Configuration Files</H3>
	345
	346	<P>The configuration files consist of:</P>
	347
	348	<ul>
	349
	350	<LI>The HTTP server configuration file.</LI>
	351
	352	<LI>Printer and class definition files.</LI>
	353
	354	<LI>MIME type and conversion rule files.</LI>
	355
	356	<LI>PostScript Printer Description (PPD) files.</LI>
	357
	358	</ul>
	359
	360	<P>The HTTP server configuration file is purposely similar to
	361	the Apache server configuration file and defines all of the
	362	access control properties for the server.</P>
	363
	364	<P>The printer and class definition files list the available
	365	printer queues and classes. Printer classes are collections of
	366	printers. Jobs sent to a class are forwarded to the first
	367	available printer in the class, round-robin fashion.</P>
	368
	369	<P>The MIME type files list the supported MIME types
	370	(text/plain, application/postscript, etc.) and "magic' rules for
	371	automatically detecting the format of a file. These are used by
	372	the HTTP server to determine the <tt>Content-Type</tt> field for
	373	<tt>GET</tt> and <tt>HEAD</tt> requests and by the IPP request
	374	handler to determine the file type when a <tt>Print-Job</tt> or
	375	<tt>Send-File</tt> request is received with a
	376	<tt>document-format</tt> of
	377	<tt>application/octet-stream</tt>.</P>
	378
	379	<P>The MIME conversion rule files list the available filters.
	380	The filters are used when a job is dispatched so that an
	381	application can send a convenient file format to the printing
	382	system which then converts the document into a printable format
	383	as needed. Each filter has a relative cost associated with it,
	384	and the filtering algorithm chooses the set of filters that will
	385	convert the file to the needed format with the lowest total
	386	"cost".</P>
	387
	388	<P>The PPD files describe the capabilities of all printers, not
	389	just PostScript printers. There is one PPD file for each
	390	printer. PPD files for non-PostScript printers define additional
	391	filters through <tt>cupsFilter</tt> attributes to support
	392	printer drivers.</P>
e1d6a774	393	-->
4744bd90	394
	395	</BODY>
	396	</HTML>