From: mike <mike@7a7537e8-13f0-0310-91df-b6672ffda945>
Date: Fri, 22 Apr 2011 20:10:04 +0000 (+0000)
Subject: Update filter documentation to talk a little about signal handling.
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7be32d5877fc3fd04094089546490d99d0fb6e0a;p=thirdparty%2Fcups.git

Update filter documentation to talk a little about signal handling.


git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@9714 7a7537e8-13f0-0310-91df-b6672ffda945
---

diff --git a/cups/api-filter.shtml b/cups/api-filter.shtml
index 6dfad329d5..319d1324b3 100644
--- a/cups/api-filter.shtml
+++ b/cups/api-filter.shtml
@@ -1,10 +1,9 @@
 <!--
   "$Id$"
 
-  Filter and backend programming introduction for the Common UNIX Printing
-  System (CUPS).
+  Filter and backend programming introduction for CUPS.
 
-  Copyright 2007-2009 by Apple Inc.
+  Copyright 2007-2011 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -85,6 +84,14 @@ that further limit file system access, even for backends running as root. On
 Mac OS X, for example, no backend may write to a user's home directory.</p>
 </blockquote>
 
+<h3><a name="SIGNALS">Signal Handling</a><h3>
+
+<p>The scheduler sends <code>SIGTERM</code> when a printing job is canceled or
+held. Filters, backends, and port monitors <em>must</em> catch
+<code>SIGTERM</code> and perform any cleanup necessary to produce a valid output
+file or return the printer to a known good state. The recommended behavior is to
+end the output on the current page.</p>
+
 <h3><a name="PERMISSIONS">File Permissions</a></h3>
 
 <p>For security reasons, CUPS will only run filters and backends that are owned
@@ -424,7 +431,7 @@ the "DEBUG:" prefix string.</p>
 <p>Filters can communicate with the backend via the
 <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and
 <a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a>
-functions. The 
+functions. The
 <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> function
 reads data that has been sent back from the device and is typically used to
 obtain status and configuration information. For example, the following code
diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html
index a4cde044e9..45f5e33fca 100644
--- a/doc/help/api-filedir.html
+++ b/doc/help/api-filedir.html
@@ -390,7 +390,7 @@ div.contents ul.subcontents li {
 	<li><a href="#cupsFileFind" title="Find a file using the specified path.">cupsFileFind</a></li>
 	<li><a href="#cupsFileFlush" title="Flush pending output.">cupsFileFlush</a></li>
 	<li><a href="#cupsFileGetChar" title="Get a single character from a file.">cupsFileGetChar</a></li>
-	<li><a href="#cupsFileGetConf" title="Get a line from a configuration file...">cupsFileGetConf</a></li>
+	<li><a href="#cupsFileGetConf" title="Get a line from a configuration file.">cupsFileGetConf</a></li>
 	<li><a href="#cupsFileGetLine" title="Get a CR and/or LF-terminated line that may
 contain binary data.">cupsFileGetLine</a></li>
 	<li><a href="#cupsFileGets" title="Get a CR and/or LF-terminated line.">cupsFileGets</a></li>
@@ -602,7 +602,7 @@ int cupsFileGetChar (<br>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Character or -1 on end of file</p>
 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileGetConf">cupsFileGetConf</a></h3>
-<p class="description">Get a line from a configuration file...</p>
+<p class="description">Get a line from a configuration file.</p>
 <p class="code">
 char *cupsFileGetConf (<br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html
index d6e4dc8be2..904926fe24 100644
--- a/doc/help/api-filter.html
+++ b/doc/help/api-filter.html
@@ -386,7 +386,7 @@ div.contents ul.subcontents li {
 <ul class="contents">
 <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 	<li><a href="#SECURITY">Security Considerations</a></li>
-	<li><a href="#PERMISSIONS">File Permissions</a></li>
+	<li><a href="#SIGNALS">Signal Handling</a></li>
 	<li><a href="#TEMPFILES">Temporary Files</a></li>
 	<li><a href="#COPIES">Copy Generation</a></li>
 	<li><a href="#EXITCODES">Exit Codes</a></li>
@@ -428,10 +428,9 @@ div.contents ul.subcontents li {
 <!--
   "$Id$"
 
-  Filter and backend programming introduction for the Common UNIX Printing
-  System (CUPS).
+  Filter and backend programming introduction for CUPS.
 
-  Copyright 2007-2009 by Apple Inc.
+  Copyright 2007-2011 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -512,6 +511,14 @@ that further limit file system access, even for backends running as root. On
 Mac OS X, for example, no backend may write to a user's home directory.</p>
 </blockquote>
 
+<h3><a name="SIGNALS">Signal Handling</a><h3>
+
+<p>The scheduler sends <code>SIGTERM</code> when a printing job is canceled or
+held. Filters, backends, and port monitors <em>must</em> catch
+<code>SIGTERM</code> and perform any cleanup necessary to produce a valid output
+file or return the printer to a known good state. The recommended behavior is to
+end the output on the current page.</p>
+
 <h3><a name="PERMISSIONS">File Permissions</a></h3>
 
 <p>For security reasons, CUPS will only run filters and backends that are owned
@@ -851,7 +858,7 @@ the "DEBUG:" prefix string.</p>
 <p>Filters can communicate with the backend via the
 <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and
 <a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a>
-functions. The 
+functions. The
 <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> function
 reads data that has been sent back from the device and is typically used to
 obtain status and configuration information. For example, the following code
@@ -1352,6 +1359,10 @@ typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datal
 <dd class="description">Job failed, hold job</dd>
 <dt>CUPS_BACKEND_OK </dt>
 <dd class="description">Job completed successfully</dd>
+<dt>CUPS_BACKEND_RETRY </dt>
+<dd class="description">Job failed, retry this job later</dd>
+<dt>CUPS_BACKEND_RETRY_CURRENT </dt>
+<dd class="description">Job failed, retry this job immediately</dd>
 <dt>CUPS_BACKEND_STOP </dt>
 <dd class="description">Job failed, stop queue</dd>
 </dl>
diff --git a/doc/help/api-mime.html b/doc/help/api-mime.html
index 30682c8d12..7631e6a7d9 100644
--- a/doc/help/api-mime.html
+++ b/doc/help/api-mime.html
@@ -396,7 +396,7 @@ including file size.">mimeFilter2</a></li>
 	<li><a href="#mimeLoadTypes" title="Load type definitions from disk.">mimeLoadTypes</a></li>
 	<li><a href="#mimeNextFilter" title="Get the next filter in the MIME database.">mimeNextFilter</a></li>
 	<li><a href="#mimeNextType" title="Get the next type in the MIME database.">mimeNextType</a></li>
-	<li><a href="#mimeNumFilters" title="MIME database">mimeNumFilters</a></li>
+	<li><a href="#mimeNumFilters" title="Next type">mimeNumFilters</a></li>
 	<li><a href="#mimeNumTypes" title="MIME database">mimeNumTypes</a></li>
 	<li><a href="#mimeType" title="Lookup a file type.">mimeType</a></li>
 </ul></li>
@@ -727,7 +727,7 @@ Use <a href="#mimeLoadFilters"><code>mimeLoadFilters</code></a> to load all filt
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Type or NULL</p>
 <h3 class="function"><a name="mimeNumFilters">mimeNumFilters</a></h3>
-<p class="description">MIME database</p>
+<p class="description">Next type</p>
 <p class="code">
 int mimeNumFilters (<br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#mime_t">mime_t</a> *mime<br>