1<!-- 2 Filter and backend programming introduction for CUPS. 3 4 Copyright 2007-2016 by Apple Inc. 5 Copyright 1997-2006 by Easy Software Products, all rights reserved. 6 7 These coded instructions, statements, and computer programs are the 8 property of Apple Inc. and are protected by Federal copyright 9 law. Distribution and use rights are outlined in the file "LICENSE.txt" 10 which should have been included with this file. If this file is 11 file is missing or damaged, see the license at "http://www.cups.org/". 12--> 13 14<h2 class='title'><a name="OVERVIEW">Overview</a></h2> 15 16<p>Filters (which include printer drivers and port monitors) and backends 17are used to convert job files to a printable format and send that data to the 18printer itself. All of these programs use a common interface for processing 19print jobs and communicating status information to the scheduler. Each is run 20with a standard set of command-line arguments:<p> 21 22<dl class="code"> 23 24 <dt>argv[1]</dt> 25 <dd>The job ID</dd> 26 27 <dt>argv[2]</dt> 28 <dd>The user printing the job</dd> 29 30 <dt>argv[3]</dt> 31 <dd>The job name/title</dd> 32 33 <dt>argv[4]</dt> 34 <dd>The number of copies to print</dd> 35 36 <dt>argv[5]</dt> 37 <dd>The options that were provided when the job was submitted</dd> 38 39 <dt>argv[6]</dt> 40 <dd>The file to print (first program only)</dd> 41</dl> 42 43<p>The scheduler runs one or more of these programs to print any given job. The 44first filter reads from the print file and writes to the standard output, while 45the remaining filters read from the standard input and write to the standard 46output. The backend is the last filter in the chain and writes to the 47device.</p> 48 49<p>Filters are always run as a non-privileged user, typically "lp", with no 50connection to the user's desktop. Backends are run either as a non-privileged 51user or as root if the file permissions do not allow user or group execution. 52The <a href="#PERMISSIONS">file permissions</a> section talks about this in 53more detail.</p> 54 55<h3><a name="SECURITY">Security Considerations</a></h3> 56 57<p>It is always important to use security programming practices. Filters and 58most backends are run as a non-privileged user, so the major security 59consideration is resource utilization - filters should not depend on unlimited 60amounts of CPU, memory, or disk space, and should protect against conditions 61that could lead to excess usage of any resource like infinite loops and 62unbounded recursion. In addition, filters must <em>never</em> allow the user to 63specify an arbitrary file path to a separator page, template, or other file 64used by the filter since that can lead to an unauthorized disclosure of 65information. <em>Always</em> treat input as suspect and validate it!</p> 66 67<p>If you are developing a backend that runs as root, make sure to check for 68potential buffer overflows, integer under/overflow conditions, and file 69accesses since these can lead to privilege escalations. When writing files, 70always validate the file path and <em>never</em> allow a user to determine 71where to store a file.</p> 72 73<blockquote><b>Note:</b> 74 75<p><em>Never</em> write files to a user's home directory. Aside from the 76security implications, CUPS is a network print service and as such the network 77user may not be the same as the local user and/or there may not be a local home 78directory to write to.</p> 79 80<p>In addition, some operating systems provide additional security mechanisms 81that further limit file system access, even for backends running as root. On 82macOS, for example, no backend may write to a user's home directory. See the <a href="#SANDBOXING">Sandboxing on macOS</a> section for more information.</p> 83</blockquote> 84 85<h3><a name="SIGNALS">Canceled Jobs and Signal Handling</a></h3> 86 87<p>The scheduler sends <code>SIGTERM</code> when a printing job is canceled or 88held. Filters, backends, and port monitors <em>must</em> catch 89<code>SIGTERM</code> and perform any cleanup necessary to produce a valid output 90file or return the printer to a known good state. The recommended behavior is to 91end the output on the current page, preferably on the current line or object 92being printed.</p> 93 94<p>Filters and backends may also receive <code>SIGPIPE</code> when an upstream or downstream filter/backend exits with a non-zero status. Developers should generally ignore <code>SIGPIPE</code> at the beginning of <code>main()</code> with the following function call:</p> 95 96<pre class="example"> 97#include <signal.h> 98 99... 100 101int 102main(int argc, char *argv[]) 103{ 104 signal(SIGPIPE, SIG_IGN); 105 106 ... 107} 108</pre> 109 110<h3><a name="PERMISSIONS">File Permissions</a></h3> 111 112<p>For security reasons, CUPS will only run filters and backends that are owned 113by root and do not have world or group write permissions. The recommended 114permissions for filters and backends are 0555 - read and execute but no write. 115Backends that must run as root should use permissions of 0500 - read and execute 116by root, no access for other users. Write permissions can be enabled for the 117root user only.</p> 118 119<p>To avoid a warning message, the directory containing your filter(s) must also 120be owned by root and have world and group write disabled - permissions of 0755 121or 0555 are strongly encouraged.</p> 122 123<h3><a name="TEMPFILES">Temporary Files</a></h3> 124 125<p>Temporary files should be created in the directory specified by the 126"TMPDIR" environment variable. The 127<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> function can be 128used to safely create temporary files in this directory.</p> 129 130<h3><a name="COPIES">Copy Generation</a></h3> 131 132<p>The <code>argv[4]</code> argument specifies the number of copies to produce 133of the input file. In general, you should only generate copies if the 134<em>filename</em> argument is supplied. The only exception to this are 135filters that produce device-independent PostScript output, since the PostScript 136filter <var>pstops</var> is responsible for generating copies of PostScript 137files.</p> 138 139<h3><a name="EXITCODES">Exit Codes</a></h3> 140 141<p>Filters must exit with status 0 when they successfully generate print data 142or 1 when they encounter an error. Backends can return any of the 143<a href="#cups_backend_t"><code>cups_backend_t</code></a> constants.</p> 144 145<h3><a name="ENVIRONMENT">Environment Variables</a></h3> 146 147<p>The following environment variables are defined by the printing system 148when running print filters and backends:</p> 149 150<dl class="code"> 151 152 <dt>APPLE_LANGUAGE</dt> 153 <dd>The Apple language identifier associated with the job 154 (macOS only).</dd> 155 156 <dt>CHARSET</dt> 157 <dd>The job character set, typically "utf-8".</dd> 158 159 <dt>CLASS</dt> 160 <dd>When a job is submitted to a printer class, contains the name of 161 the destination printer class. Otherwise this environment 162 variable will not be set.</dd> 163 164 <dt>CONTENT_TYPE</dt> 165 <dd>The MIME type associated with the file (e.g. 166 application/postscript).</dd> 167 168 <dt>CUPS_CACHEDIR</dt> 169 <dd>The directory where cache files can be stored. Cache files can be 170 used to retain information between jobs or files in a job.</dd> 171 172 <dt>CUPS_DATADIR</dt> 173 <dd>The directory where (read-only) CUPS data files can be found.</dd> 174 175 <dt>CUPS_FILETYPE</dt> 176 <dd>The type of file being printed: "job-sheet" for a banner page and 177 "document" for a regular print file.</dd> 178 179 <dt>CUPS_SERVERROOT</dt> 180 <dd>The root directory of the server.</dd> 181 182 <dt>DEVICE_URI</dt> 183 <dd>The device-uri associated with the printer.</dd> 184 185 <dt>FINAL_CONTENT_TYPE</dt> 186 <dd>The MIME type associated with the printer (e.g. 187 application/vnd.cups-postscript).</dd> 188 189 <dt>LANG</dt> 190 <dd>The language locale associated with the job.</dd> 191 192 <dt>PPD</dt> 193 <dd>The full pathname of the PostScript Printer Description (PPD) 194 file for this printer.</dd> 195 196 <dt>PRINTER</dt> 197 <dd>The queue name of the class or printer.</dd> 198 199 <dt>RIP_CACHE</dt> 200 <dd>The recommended amount of memory to use for Raster Image 201 Processors (RIPs).</dd> 202 203 <dt>TMPDIR</dt> 204 <dd>The directory where temporary files should be created.</dd> 205 206</dl> 207 208<h3><a name="MESSAGES">Communicating with the Scheduler</a></h3> 209 210<p>Filters and backends communicate with the scheduler by writing messages 211to the standard error file. The scheduler reads messages from all filters in 212a job and processes the message based on its prefix. For example, the following 213code sets the current printer state message to "Printing page 5":</p> 214 215<pre class="example"> 216int page = 5; 217 218fprintf(stderr, "INFO: Printing page %d\n", page); 219</pre> 220 221<p>Each message is a single line of text starting with one of the following 222prefix strings:</p> 223 224<dl class="code"> 225 226 <dt>ALERT: message</dt> 227 <dd>Sets the printer-state-message attribute and adds the specified 228 message to the current error log file using the "alert" log level.</dd> 229 230 <dt>ATTR: attribute=value [attribute=value]</dt> 231 <dd>Sets the named printer or job attribute(s). Typically this is used 232 to set the <code>marker-colors</code>, <code>marker-high-levels</code>, 233 <code>marker-levels</code>, <code>marker-low-levels</code>, 234 <code>marker-message</code>, <code>marker-names</code>, 235 <code>marker-types</code>, <code>printer-alert</code>, and 236 <code>printer-alert-description</code> printer attributes. Standard 237 <code>marker-types</code> values are listed in <a href='#TABLE1'>Table 238 1</a>. String values need special handling - see <a href="#ATTR_STRINGS">Reporting Attribute String Values</a> below.</dd> 239 240 <dt>CRIT: message</dt> 241 <dd>Sets the printer-state-message attribute and adds the specified 242 message to the current error log file using the "critical" log 243 level.</dd> 244 245 <dt>DEBUG: message</dt> 246 <dd>Sets the printer-state-message attribute and adds the specified 247 message to the current error log file using the "debug" log level.</dd> 248 249 <dt>DEBUG2: message</dt> 250 <dd>Sets the printer-state-message attribute and adds the specified 251 message to the current error log file using the "debug2" log level.</dd> 252 253 <dt>EMERG: message</dt> 254 <dd>Sets the printer-state-message attribute and adds the specified 255 message to the current error log file using the "emergency" log 256 level.</dd> 257 258 <dt>ERROR: message</dt> 259 <dd>Sets the printer-state-message attribute and adds the specified 260 message to the current error log file using the "error" log level. 261 Use "ERROR:" messages for non-persistent processing errors.</dd> 262 263 <dt>INFO: message</dt> 264 <dd>Sets the printer-state-message attribute. If the current log level 265 is set to "debug2", also adds the specified message to the current error 266 log file using the "info" log level.</dd> 267 268 <dt>NOTICE: message</dt> 269 <dd>Sets the printer-state-message attribute and adds the specified 270 message to the current error log file using the "notice" log level.</dd> 271 272 <dt>PAGE: page-number #-copies</dt> 273 <dt>PAGE: total #-pages</dt> 274 <dd>Adds an entry to the current page log file. The first form adds 275 #-copies to the job-media-sheets-completed attribute. The second 276 form sets the job-media-sheets-completed attribute to #-pages.</dd> 277 278 <dt>PPD: keyword=value [keyword=value ...]</dt> 279 <dd>Changes or adds keywords to the printer's PPD file. Typically 280 this is used to update installable options or default media settings 281 based on the printer configuration.</dd> 282 283 <dt>STATE: + printer-state-reason [printer-state-reason ...]</dt> 284 <dt>STATE: - printer-state-reason [printer-state-reason ...]</dt> 285 <dd>Sets or clears printer-state-reason keywords for the current queue. 286 Typically this is used to indicate persistent media, ink, toner, and 287 configuration conditions or errors on a printer. 288 <a href='#TABLE2'>Table 2</a> lists some of the standard "printer-state-reasons" keywords from the <a href="http://www.iana.org/assignments/ipp-registrations/ipp-registrations.xhtml#ipp-registrations-4">IANA IPP Registry</a> - 289 use vendor-prefixed ("com.example.foo") keywords for custom states. See 290 <a href="#MANAGING_STATE">Managing Printer State in a Filter</a> for more 291 information. 292 293 <dt>WARNING: message</dt> 294 <dd>Sets the printer-state-message attribute and adds the specified 295 message to the current error log file using the "warning" log 296 level.</dd> 297 298</dl> 299 300<p>Messages without one of these prefixes are treated as if they began with 301the "DEBUG:" prefix string.</p> 302 303<div class='table'><table width='80%' summary='Table 1: Standard marker-types Values'> 304<caption>Table 1: <a name='TABLE1'>Standard marker-types Values</a></caption> 305<thead> 306<tr> 307 <th>marker-type</th> 308 <th>Description</th> 309</tr> 310</thead> 311<tbody> 312<tr> 313 <td>developer</td> 314 <td>Developer unit</td> 315</tr> 316<tr> 317 <td>fuser</td> 318 <td>Fuser unit</td> 319</tr> 320<tr> 321 <td>fuser-cleaning-pad</td> 322 <td>Fuser cleaning pad</td> 323</tr> 324<tr> 325 <td>fuser-oil</td> 326 <td>Fuser oil</td> 327</tr> 328<tr> 329 <td>ink</td> 330 <td>Ink supply</td> 331</tr> 332<tr> 333 <td>opc</td> 334 <td>Photo conductor</td> 335</tr> 336<tr> 337 <td>solid-wax</td> 338 <td>Wax supply</td> 339</tr> 340<tr> 341 <td>staples</td> 342 <td>Staple supply</td> 343</tr> 344<tr> 345 <td>toner</td> 346 <td>Toner supply</td> 347</tr> 348<tr> 349 <td>transfer-unit</td> 350 <td>Transfer unit</td> 351</tr> 352<tr> 353 <td>waste-ink</td> 354 <td>Waste ink tank</td> 355</tr> 356<tr> 357 <td>waste-toner</td> 358 <td>Waste toner tank</td> 359</tr> 360<tr> 361 <td>waste-wax</td> 362 <td>Waste wax tank</td> 363</tr> 364</tbody> 365</table></div> 366 367<br> 368 369<div class='table'><table width='80%' summary='Table 2: Standard State Keywords'> 370<caption>Table 2: <a name='TABLE2'>Standard State Keywords</a></caption> 371<thead> 372<tr> 373 <th>Keyword</th> 374 <th>Description</th> 375</tr> 376</thead> 377<tbody> 378<tr> 379 <td>connecting-to-device</td> 380 <td>Connecting to printer but not printing yet.</td> 381</tr> 382<tr> 383 <td>cover-open</td> 384 <td>The printer's cover is open.</td> 385</tr> 386<tr> 387 <td>input-tray-missing</td> 388 <td>The paper tray is missing.</td> 389</tr> 390<tr> 391 <td>marker-supply-empty</td> 392 <td>The printer is out of ink.</td> 393</tr> 394<tr> 395 <td>marker-supply-low</td> 396 <td>The printer is almost out of ink.</td> 397</tr> 398<tr> 399 <td>marker-waste-almost-full</td> 400 <td>The printer's waste bin is almost full.</td> 401</tr> 402<tr> 403 <td>marker-waste-full</td> 404 <td>The printer's waste bin is full.</td> 405</tr> 406<tr> 407 <td>media-empty</td> 408 <td>The paper tray (any paper tray) is empty.</td> 409</tr> 410<tr> 411 <td>media-jam</td> 412 <td>There is a paper jam.</td> 413</tr> 414<tr> 415 <td>media-low</td> 416 <td>The paper tray (any paper tray) is almost empty.</td> 417</tr> 418<tr> 419 <td>media-needed</td> 420 <td>The paper tray needs to be filled (for a job that is printing).</td> 421</tr> 422<tr> 423 <td>paused</td> 424 <td>Stop the printer.</td> 425</tr> 426<tr> 427 <td>timed-out</td> 428 <td>Unable to connect to printer.</td> 429</tr> 430<tr> 431 <td>toner-empty</td> 432 <td>The printer is out of toner.</td> 433</tr> 434<tr> 435 <td>toner-low</td> 436 <td>The printer is low on toner.</td> 437</tr> 438</tbody> 439</table></div> 440 441 442<h4><a name="ATTR_STRINGS">Reporting Attribute String Values</a></h4> 443 444<p>When reporting string values using "ATTR:" messages, a filter or backend must take special care to appropriately quote those values. The scheduler uses the CUPS option parsing code for attributes, so the general syntax is:</p> 445 446<pre class="example"> 447name=simple 448name=simple,simple,... 449name='complex value' 450name="complex value" 451name='"complex value"','"complex value"',... 452</pre> 453 454<p>Simple values are strings that do not contain spaces, quotes, backslashes, or the comma and can be placed verbatim in the "ATTR:" message, for example:</p> 455 456<pre class="example"> 457int levels[4] = { 40, 50, 60, 70 }; /* CMYK */ 458 459fputs("ATTR: marker-colors=#00FFFF,#FF00FF,#FFFF00,#000000\n", stderr); 460fputs("ATTR: marker-high-levels=100,100,100,100\n", stderr); 461fprintf(stderr, "ATTR: marker-levels=%d,%d,%d,%d\n", levels[0], levels[1], 462 levels[2], levels[3], levels[4]); 463fputs("ATTR: marker-low-levels=5,5,5,5\n", stderr); 464fputs("ATTR: marker-types=toner,toner,toner,toner\n", stderr); 465</pre> 466 467<p>Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:</p> 468 469<pre class="example"> 470fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr); 471</pre> 472 473<p>When multiple values are reported, each value must be enclosed by a set of single and double quotes:</p> 474 475<pre class="example"> 476fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"'," 477 "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr); 478</pre> 479 480<p>The IPP backend includes a <var>quote_string</var> function that may be used to properly quote a complex value in an "ATTR:" message:</p> 481 482<pre class="example"> 483static const char * /* O - Quoted string */ 484quote_string(const char *s, /* I - String */ 485 char *q, /* I - Quoted string buffer */ 486 size_t qsize) /* I - Size of quoted string buffer */ 487{ 488 char *qptr, /* Pointer into string buffer */ 489 *qend; /* End of string buffer */ 490 491 492 qptr = q; 493 qend = q + qsize - 5; 494 495 if (qend < q) 496 { 497 *q = '\0'; 498 return (q); 499 } 500 501 *qptr++ = '\''; 502 *qptr++ = '\"'; 503 504 while (*s && qptr < qend) 505 { 506 if (*s == '\\' || *s == '\"' || *s == '\'') 507 { 508 if (qptr < (qend - 4)) 509 { 510 *qptr++ = '\\'; 511 *qptr++ = '\\'; 512 *qptr++ = '\\'; 513 } 514 else 515 break; 516 } 517 518 *qptr++ = *s++; 519 } 520 521 *qptr++ = '\"'; 522 *qptr++ = '\''; 523 *qptr = '\0'; 524 525 return (q); 526} 527</pre> 528 529 530<h4><a name="MANAGING_STATE">Managing Printer State in a Filter</a></h4> 531 532<p>Filters are responsible for managing the state keywords they set using 533"STATE:" messages. Typically you will update <em>all</em> of the keywords that 534are used by the filter at startup, for example:</p> 535 536<pre class="example"> 537if (foo_condition != 0) 538 fputs("STATE: +com.example.foo\n", stderr); 539else 540 fputs("STATE: -com.example.foo\n", stderr); 541 542if (bar_condition != 0) 543 fputs("STATE: +com.example.bar\n", stderr); 544else 545 fputs("STATE: -com.example.bar\n", stderr); 546</pre> 547 548<p>Then as conditions change, your filter sends "STATE: +keyword" or "STATE: 549-keyword" messages as necessary to set or clear the corresponding keyword, 550respectively.</p> 551 552<p>State keywords are often used to notify the user of issues that span across 553jobs, for example "media-empty-warning" that indicates one or more paper trays 554are empty. These keywords should not be cleared unless the corresponding issue 555no longer exists.</p> 556 557<p>Filters should clear job-related keywords on startup and exit so that they 558do not remain set between jobs. For example, "connecting-to-device" is a job 559sub-state and not an issue that applies when a job is not printing.</p> 560 561<blockquote><b>Note:</b> 562 563<p>"STATE:" messages often provide visible alerts to the user. For example, 564on macOS setting a printer-state-reason value with an "-error" or 565"-warning" suffix will cause the printer's dock item to bounce if the 566corresponding reason is localized with a cupsIPPReason keyword in the 567printer's PPD file.</p> 568 569<p>When providing a vendor-prefixed keyword, <em>always</em> provide the 570corresponding standard keyword (if any) to allow clients to respond to the 571condition correctly. For example, if you provide a vendor-prefixed keyword 572for a low cyan ink condition ("com.example.cyan-ink-low") you must also set the 573"marker-supply-low-warning" keyword. In such cases you should also refrain 574from localizing the vendor-prefixed keyword in the PPD file - otherwise both 575the generic and vendor-specific keyword will be shown in the user 576interface.</p> 577 578</blockquote> 579 580<h4><a name="REPORTING_SUPPLIES">Reporting Supply Levels</a></h4> 581 582<p>CUPS tracks several "marker-*" attributes for ink/toner supply level 583reporting. These attributes allow applications to display the current supply 584levels for a printer without printer-specific software. <a href="#TABLE3">Table 3</a> lists the marker attributes and what they represent.</p> 585 586<p>Filters set marker attributes by sending "ATTR:" messages to stderr. For 587example, a filter supporting an inkjet printer with black and tri-color ink 588cartridges would use the following to initialize the supply attributes:</p> 589 590<pre class="example"> 591fputs("ATTR: marker-colors=#000000,#00FFFF#FF00FF#FFFF00\n", stderr); 592fputs("ATTR: marker-low-levels=5,10\n", stderr); 593fputs("ATTR: marker-names=Black,Tri-Color\n", stderr); 594fputs("ATTR: marker-types=ink,ink\n", stderr); 595</pre> 596 597<p>Then periodically the filter queries the printer for its current supply 598levels and updates them with a separate "ATTR:" message:</p> 599 600<pre class="example"> 601int black_level, tri_level; 602... 603fprintf(stderr, "ATTR: marker-levels=%d,%d\n", black_level, tri_level); 604</pre> 605 606<div class='table'><table width='80%' summary='Table 3: Supply Level Attributes'> 607<caption>Table 3: <a name='TABLE3'>Supply Level Attributes</a></caption> 608<thead> 609<tr> 610 <th>Attribute</th> 611 <th>Description</th> 612</tr> 613</thead> 614<tbody> 615<tr> 616 <td>marker-colors</td> 617 <td>A list of comma-separated colors; each color is either "none" or one or 618 more hex-encoded sRGB colors of the form "#RRGGBB".</td> 619</tr> 620<tr> 621 <td>marker-high-levels</td> 622 <td>A list of comma-separated "almost full" level values from 0 to 100; a 623 value of 100 should be used for supplies that are consumed/emptied like ink 624 cartridges.</td> 625</tr> 626<tr> 627 <td>marker-levels</td> 628 <td>A list of comma-separated level values for each supply. A value of -1 629 indicates the level is unavailable, -2 indicates unknown, and -3 indicates 630 the level is unknown but has not yet reached capacity. Values from 0 to 100 631 indicate the corresponding percentage.</td> 632</tr> 633<tr> 634 <td>marker-low-levels</td> 635 <td>A list of comma-separated "almost empty" level values from 0 to 100; a 636 value of 0 should be used for supplies that are filled like waste ink 637 tanks.</td> 638</tr> 639<tr> 640 <td>marker-message</td> 641 <td>A human-readable supply status message for the user like "12 pages of 642 ink remaining."</td> 643</tr> 644<tr> 645 <td>marker-names</td> 646 <td>A list of comma-separated supply names like "Cyan Ink", "Fuser", 647 etc.</td> 648</tr> 649<tr> 650 <td>marker-types</td> 651 <td>A list of comma-separated supply types; the types are listed in 652 <a href="#TABLE1">Table 1</a>.</td> 653</tr> 654</tbody> 655</table></div> 656 657<h3><a name="COMMUNICATING_BACKEND">Communicating with the Backend</a></h3> 658 659<p>Filters can communicate with the backend via the 660<a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and 661<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 662functions. The 663<a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> function 664reads data that has been sent back from the device and is typically used to 665obtain status and configuration information. For example, the following code 666polls the backend for back-channel data:</p> 667 668<pre class="example"> 669#include <cups/cups.h> 670 671char buffer[8192]; 672ssize_t bytes; 673 674/* Use a timeout of 0.0 seconds to poll for back-channel data */ 675bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0); 676</pre> 677 678<p>Filters can also use <code>select()</code> or <code>poll()</code> on the 679back-channel file descriptor (3 or <code>CUPS_BC_FD</code>) to read data only 680when it is available.</p> 681 682<p>The 683<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 684function allows you to get out-of-band status information and do synchronization 685with the device. For example, the following code gets the current IEEE-1284 686device ID string from the backend:</p> 687 688<pre class="example"> 689#include <cups/sidechannel.h> 690 691char data[2049]; 692int datalen; 693<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 694 695/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for 696 nul-termination... */ 697datalen = sizeof(data) - 1; 698 699/* Get the IEEE-1284 device ID, waiting for up to 1 second */ 700status = <a href="#cupsSideChannelDoRequest">cupsSideChannelDoRequest</a>(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0); 701 702/* Use the returned value if OK was returned and the length is non-zero */ 703if (status == CUPS_SC_STATUS_OK && datalen > 0) 704 data[datalen] = '\0'; 705else 706 data[0] = '\0'; 707</pre> 708 709<h4><a name="DRAIN_OUTPUT">Forcing All Output to a Printer</a></h4> 710 711<p>The 712<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 713function allows you to tell the backend to send all pending data to the printer. 714This is most often needed when sending query commands to the printer. For example:</p> 715 716<pre class="example"> 717#include <cups/cups.h> 718#include <cups/sidechannel.h> 719 720char data[1024]; 721int datalen = sizeof(data); 722<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 723 724/* Flush pending output to stdout */ 725fflush(stdout); 726 727/* Drain output to backend, waiting for up to 30 seconds */ 728status = <a href="#cupsSideChannelDoRequest">cupsSideChannelDoRequest</a>(CUPS_SC_CMD_DRAIN_OUTPUT, data, &datalen, 30.0); 729 730/* Read the response if the output was sent */ 731if (status == CUPS_SC_STATUS_OK) 732{ 733 ssize_t bytes; 734 735 /* Wait up to 10.0 seconds for back-channel data */ 736 bytes = cupsBackChannelRead(data, sizeof(data), 10.0); 737 /* do something with the data from the printer */ 738} 739</pre> 740 741<h3><a name="COMMUNICATING_FILTER">Communicating with Filters</a></h3> 742 743<p>Backends communicate with filters using the reciprocal functions 744<a href="#cupsBackChannelWrite"><code>cupsBackChannelWrite</code></a>, 745<a href="#cupsSideChannelRead"><code>cupsSideChannelRead</code></a>, and 746<a href="#cupsSideChannelWrite"><code>cupsSideChannelWrite</code></a>. We 747recommend writing back-channel data using a timeout of 1.0 seconds:</p> 748 749<pre class="example"> 750#include <cups/cups.h> 751 752char buffer[8192]; 753ssize_t bytes; 754 755/* Obtain data from printer/device */ 756... 757 758/* Use a timeout of 1.0 seconds to give filters a chance to read */ 759cupsBackChannelWrite(buffer, bytes, 1.0); 760</pre> 761 762<p>The <a href="#cupsSideChannelRead"><code>cupsSideChannelRead</code></a> 763function reads a side-channel command from a filter, driver, or port monitor. 764Backends can either poll for commands using a <code>timeout</code> of 0.0, wait 765indefinitely for commands using a <code>timeout</code> of -1.0 (probably in a 766separate thread for that purpose), or use <code>select</code> or 767<code>poll</code> on the <code>CUPS_SC_FD</code> file descriptor (4) to handle 768input and output on several file descriptors at the same time.</p> 769 770<p>Once a command is processed, the backend uses the 771<a href="#cupsSideChannelWrite"><code>cupsSideChannelWrite</code></a> function 772to send its response. For example, the following code shows how to poll for a 773side-channel command and respond to it:</p> 774 775<pre class="example"> 776#include <cups/sidechannel.h> 777 778<a href="#cups_sc_command_t">cups_sc_command_t</a> command; 779<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 780char data[2048]; 781int datalen = sizeof(data); 782 783/* Poll for a command... */ 784if (!<a href="#cupsSideChannelRead">cupsSideChannelRead</a>(&command, &status, data, &datalen, 0.0)) 785{ 786 switch (command) 787 { 788 /* handle supported commands, fill data/datalen/status with values as needed */ 789 790 default : 791 status = CUPS_SC_STATUS_NOT_IMPLEMENTED; 792 datalen = 0; 793 break; 794 } 795 796 /* Send a response... */ 797 <a href="#cupsSideChannelWrite">cupsSideChannelWrite</a>(command, status, data, datalen, 1.0); 798} 799</pre> 800 801<h3><a name="SNMP">Doing SNMP Queries with Network Printers</a></h3> 802 803<p>The Simple Network Management Protocol (SNMP) allows you to get the current 804status, page counter, and supply levels from most network printers. Every 805piece of information is associated with an Object Identifier (OID), and 806every printer has a <em>community</em> name associated with it. OIDs can be 807queried directly or by "walking" over a range of OIDs with a common prefix.</p> 808 809<p>The two CUPS SNMP functions provide a simple API for querying network 810printers through the side-channel interface. Each accepts a string containing 811an OID like ".1.3.6.1.2.1.43.10.2.1.4.1.1" (the standard page counter OID) 812along with a timeout for the query.</p> 813 814<p>The <a href="#cupsSideChannelSNMPGet"><code>cupsSideChannelSNMPGet</code></a> 815function queries a single OID and returns the value as a string in a buffer 816you supply:</p> 817 818<pre class="example"> 819#include <cups/sidechannel.h> 820 821char data[512]; 822int datalen = sizeof(data); 823 824if (<a href="#cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a>(".1.3.6.1.2.1.43.10.2.1.4.1.1", data, &datalen, 5.0) 825 == CUPS_SC_STATUS_OK) 826{ 827 /* Do something with the value */ 828 printf("Page counter is: %s\n", data); 829} 830</pre> 831 832<p>The 833<a href="#cupsSideChannelSNMPWalk"><code>cupsSideChannelSNMPWalk</code></a> 834function allows you to query a whole group of OIDs, calling a function of your 835choice for each OID that is found:</p> 836 837<pre class="example"> 838#include <cups/sidechannel.h> 839 840void 841my_callback(const char *oid, const char *data, int datalen, void *context) 842{ 843 /* Do something with the value */ 844 printf("%s=%s\n", oid, data); 845} 846 847... 848 849void *my_data; 850 851<a href="#cupsSideChannelSNMPWalk">cupsSNMPSideChannelWalk</a>(".1.3.6.1.2.1.43", 5.0, my_callback, my_data); 852</pre> 853 854<h2><a name="SANDBOXING">Sandboxing on macOS</a></h2> 855 856<p>Starting with macOS 10.6, filters and backends are run inside a security "sandbox" which further limits (beyond the normal UNIX user/group permissions) what a filter or backend can do. This helps to both secure the printing system from malicious software and enforce the functional separation of components in the CUPS filter chain. What follows is a list of actions that are explicitly allowed for all filters and backends:</p> 857 858<ol> 859 860 <li>Reading of files: pursuant to normal UNIX file permissions, filters and backends can read files for the current job from the <var>/private/var/spool/cups</var> directory and other files on mounted filesystems <em>except</em> for user home directories under <var>/Users</var>.</li> 861 862 <li>Writing of files: pursuant to normal UNIX file permissions, filters and backends can read/write files to the cache directory specified by the <code>CUPS_CACHEDIR</code> environment variable, to the state directory specified by the <code>CUPS_STATEDIR</code> environment variable, to the temporary directory specified by the <code>TMPDIR</code> environment variable, and under the <var>/private/var/db</var>, <var>/private/var/folders</var>, <var>/private/var/lib</var>, <var>/private/var/mysql</var>, <var>/private/var/run</var>, <var>/private/var/spool</var> (except <var>/private/var/spool/cups</var>), <var>/Library/Application Support</var>, <var>/Library/Caches</var>, <var>/Library/Logs</var>, <var>/Library/Preferences</var>, <var>/Library/WebServer</var>, and <var>/Users/Shared</var> directories.</li> 863 864 <li>Execution of programs: pursuant to normal UNIX file permissions, filters and backends can execute any program not located under the <var>/Users</var> directory. Child processes inherit the sandbox and are subject to the same restrictions as the parent.</li> 865 866 <li>Bluetooth and USB: backends can access Bluetooth and USB printers through IOKit. <em>Filters cannot access Bluetooth and USB printers directly.</em></li> 867 868 <li>Network: filters and backends can access UNIX domain sockets under the <var>/private/tmp</var>, <var>/private/var/run</var>, and <var>/private/var/tmp</var> directories. Backends can also create IPv4 and IPv6 TCP (outgoing) and UDP (incoming and outgoing) socket, and bind to local source ports. <em>Filters cannot directly create IPv4 and IPv6 TCP or UDP sockets.</em></li> 869 870 <li>Notifications: filters and backends can send notifications via the Darwin <code>notify_post()</code> API.</li> 871 872</ol> 873 874<blockquote><b>Note:</b> The sandbox profile used in CUPS 2.0 still allows some actions that are not listed above - these privileges will be removed over time until the profile matches the list above.</blockquote> 875