Load cups into easysw/current.

[thirdparty/cups.git] / doc / help / api-cups.html

diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html
index 42ffa2d1cb9eb2fd8ec4ab8c493bc5a7308e5d75..7466fa32221a0473e16579066e5a1025ab1e690c 100644 (file)
--- a/doc/help/api-cups.html
+++ b/doc/help/api-cups.html
@@ -176,8 +176,16 @@ CUPS 1.1 or higher.</p>
 <h4>Description</h4>
 <p>Add a destination to the list of destinations.
 
-Use the cupsSaveDests() function to save the updated list of destinations
-to the user's lpoptions file.</p>
+This function cannot be used to add a new class or printer queue,
+it only adds a new container of saved options for the named
+destination or instance.
+
+If the named destination already exists, the destination list is
+returned unchanged.  Adding a new instance of a destination creates
+a copy of that destination's options.
+
+Use the cupsSaveDests() function to save the updated list of
+destinations to the user's lpoptions file.</p>
 <h4>Syntax</h4>
 <pre>
 int
@@ -191,8 +199,8 @@ cupsAddDest(
 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 <tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination or NULL for none/primary</td></tr>
+<tr><td><tt>name</tt></td><td>Destination name</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL for none/primary</td></tr>
 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 </tbody></table></div>
@@ -412,8 +420,8 @@ cupsGetDest(
 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 <tbody>
-<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
-<tr><td><tt>instance</tt></td><td>Instance of destination</td></tr>
+<tr><td><tt>name</tt></td><td>Destination name or NULL for the default destination</td></tr>
+<tr><td><tt>instance</tt></td><td>Instance name or NULL</td></tr>
 <tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
 <tr><td><tt>dests</tt></td><td>Destinations</td></tr>
 </tbody></table></div>
@@ -427,7 +435,10 @@ cupsGetDest(
 Starting with CUPS 1.2, the returned list of destinations include the
 printer-info, printer-is-accepting-jobs, printer-is-shared,
 printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.</p>
+printer-state-reasons, and printer-type attributes as options.
+
+Use the cupsFreeDests() function to free the destination list and
+the cupsGetDest() function to find a particular destination.</p>
 <h4>Syntax</h4>
 <pre>
 int
@@ -452,6 +463,9 @@ printer-info, printer-is-accepting-jobs, printer-is-shared,
 printer-make-and-model, printer-state, printer-state-change-time,
 printer-state-reasons, and printer-type attributes as options.
 
+Use the cupsFreeDests() function to free the destination list and
+the cupsGetDest() function to find a particular destination.
+
 </p>
 <h4>Syntax</h4>
 <pre>
@@ -1192,9 +1206,10 @@ cupsSetUser(
 <!-- NEW PAGE -->
 <h3 class='title'><a name='cupsTempFd'>cupsTempFd()</a></h3>
 <h4>Description</h4>
-<p>Create a temporary file.
+<p>Creates a temporary file.
 
-The temporary filename is stored in the filename buffer.</p>
+The temporary filename is returned in the filename buffer.
+The temporary file is opened for reading and writing.</p>
 <h4>Syntax</h4>
 <pre>
 int
@@ -1210,13 +1225,13 @@ cupsTempFd(
 <tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
 </tbody></table></div>
 <h4>Returns</h4>
-<p>New file descriptor</p>
+<p>New file descriptor or -1 on error</p>
 <!-- NEW PAGE -->
 <h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsTempFile'>cupsTempFile()</a></h3>
 <h4>Description</h4>
-<p>Generate a temporary filename.
+<p>Generates a temporary filename.
 
-The temporary filename is stored in the filename buffer.
+The temporary filename is returned in the filename buffer.
 This function is deprecated - use cupsTempFd() or cupsTempFile2()
 instead.
 
@@ -1236,13 +1251,14 @@ cupsTempFile(
 <tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
 </tbody></table></div>
 <h4>Returns</h4>
-<p>Filename</p>
+<p>Filename or NULL on error</p>
 <!-- NEW PAGE -->
 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsTempFile2'>cupsTempFile2()</a></h3>
 <h4>Description</h4>
-<p>Create a temporary CUPS file.
+<p>Creates a temporary CUPS file.
 
-The temporary filename is stored in the filename buffer.
+The temporary filename is returned in the filename buffer.
+The temporary file is opened for writing.
 
 </p>
 <h4>Syntax</h4>