1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 3<html> 4 <head> 5 <meta name="generator" content="HTML Tidy, see www.w3.org"> 6 <title>Filter Command Line Options and Environment 7 Variables</title> 8 <meta name="GENERATOR" content= 9 "Modular DocBook HTML Stylesheet Version 1.7"> 10 <link rel="HOME" title=" LPRng Reference Manual" href= 11 "index.htm"> 12 <link rel="UP" title="Filters " href="filters.htm"> 13 <link rel="PREVIOUS" title="Chaining Filters " href= 14 "chainingfilters.htm"> 15 <link rel="NEXT" title="LPRng Supported Filters" href= 16 "x8397.htm"> 17 </head> 18 19 <body class="SECT1" bgcolor="#FFFFFF" text="#000000" link= 20 "#0000FF" vlink="#840084" alink="#0000FF"> 21 <div class="NAVHEADER"> 22 <table summary="Header navigation table" width="100%" border= 23 "0" cellpadding="0" cellspacing="0"> 24 <tr> 25 <th colspan="3" align="center">LPRng Reference Manual: 5 26 Sep 2003 (For LPRng-3.8.22)</th> 27 </tr> 28 29 <tr> 30 <td width="10%" align="left" valign="bottom"><a href= 31 "chainingfilters.htm" accesskey="P">Prev</a></td> 32 33 <td width="80%" align="center" valign="bottom">Chapter 34 16. Filters</td> 35 36 <td width="10%" align="right" valign="bottom"><a href= 37 "x8397.htm" accesskey="N">Next</a></td> 38 </tr> 39 </table> 40 <hr align="LEFT" width="100%"> 41 </div> 42 43 <div class="SECT1"> 44 <h1 class="SECT1"><a name="FILTEROPTIONS">16.8. Filter 45 Command Line Options and Environment Variables</a></h1> 46 47 <p>Options used:</p> 48 49 <ul> 50 <li> 51 <p><var class="LITERAL">bk_filter_options=</var><span 52 class="emphasis"><i class="EMPHASIS">Backwards Compatible 53 Filter options</i></span></p> 54 </li> 55 56 <li> 57 <p><var class="LITERAL">bk_of_filter_options=</var><span 58 class="emphasis"><i class="EMPHASIS">Backwards Compatible 59 OF Filter options</i></span></p> 60 </li> 61 62 <li> 63 <p><var class="LITERAL">bkf</var> FLAG <span class= 64 "emphasis"><i class="EMPHASIS">Backwards Compatible 65 Filters</i></span></p> 66 </li> 67 68 <li> 69 <p><var class="LITERAL">filter_ld_path=</var><span class= 70 "emphasis"><i class="EMPHASIS">Filter LD_LIBRARY_PATH 71 environment</i></span></p> 72 </li> 73 74 <li> 75 <p><var class="LITERAL">filter_options=</var><span class= 76 "emphasis"><i class="EMPHASIS">Filter 77 options</i></span></p> 78 </li> 79 80 <li> 81 <p><var class="LITERAL">filter_path=</var><span class= 82 "emphasis"><i class="EMPHASIS">Filter PATH 83 environment</i></span></p> 84 </li> 85 86 <li> 87 <p><var class="LITERAL">of_filter_options=</var><span 88 class="emphasis"><i class="EMPHASIS">OF Filter 89 options</i></span></p> 90 </li> 91 92 <li> 93 <p><var class="LITERAL">pass_env=</var><span class= 94 "emphasis"><i class="EMPHASIS">Environment variables to 95 copy to Filter environment</i></span></p> 96 </li> 97 98 <li> 99 <p><var class="LITERAL">pl=</var><span class= 100 "emphasis"><i class="EMPHASIS">line count for 101 page</i></span></p> 102 </li> 103 104 <li> 105 <p><var class="LITERAL">pw=</var><span class= 106 "emphasis"><i class="EMPHASIS">column count for 107 page</i></span></p> 108 </li> 109 110 <li> 111 <p><var class="LITERAL">px=</var><span class= 112 "emphasis"><i class="EMPHASIS">pixel width for 113 page</i></span></p> 114 </li> 115 116 <li> 117 <p><var class="LITERAL">py=</var><span class= 118 "emphasis"><i class="EMPHASIS">pixel length for 119 page</i></span></p> 120 </li> 121 </ul> 122 <br> 123 <br> 124 125 <p>A filter (or program) specification in the <b class= 126 "APPLICATION">LPRng</b> printcap database has the form:</p> 127 128 <div class="INFORMALEXAMPLE"> 129 <a name="AEN8055"></a> 130<pre class="SCREEN"> 131 :option=| [flags] /path [argument | "argument" | 'argument' ]* 132 :option=[flags] /path [argument | "argument" | 'argument' ]* 133</pre> 134 </div> 135 <br> 136 <br> 137 138 <p>The first case is used where the option value can be a 139 string or filter, and the second where a program is always 140 expected. The following procedure is used to run a filter 141 program. Arguments in single or double quotes are passed as a 142 single value, as for a shell.</p> 143 144 <p>The sequence of operations to run a filter is as 145 follows:</p> 146 147 <ol type="1"> 148 <li> 149 <p>The program must be specified with an absolute path 150 name.</p> 151 </li> 152 153 <li> 154 <p>By default, the program is run as the user if invoked 155 from a client program such as <b class= 156 "APPLICATION">lpr</b>, <b class="APPLICATION">lpc</b>, 157 etc. If invoked from <b class="APPLICATION">lpd</b>, it 158 is run as the user ID specified by the <var class= 159 "LITERAL">:user</var> (default <var class= 160 "LITERAL">daemon</var>) configuration entry.</p> 161 </li> 162 163 <li> 164 <p>The <var class="LITERAL">filter_path</var> (default 165 <var class="LITERAL">/bin:/usr/bin:/usr/local/bin</var>, 166 and <var class="LITERAL">filter_ld_path</var> (default 167 <var class="LITERAL">/lib:/usr/lib:/usr/local/lib</var>, 168 configuration options specifies the value of the <var 169 class="LITERAL">PATH</var> and <var class= 170 "LITERAL">LD_LIBRARY_PATH</var> environment 171 variables.</p> 172 </li> 173 174 <li> 175 <p>The <var class="LITERAL">filter_path</var> (default 176 <var class="LITERAL">/bin:/usr/bin:/usr/local/bin</var>, 177 and <var class="LITERAL">filter_ld_path</var> (default 178 <var class="LITERAL">/lib:/usr/lib:/usr/local/lib</var>, 179 configuration option specifies the value of the <var 180 class="LITERAL">PATH</var> and <var class= 181 "LITERAL">LD_LIBRARY_PATH</var> environment variables. 182 The other enviroment variables are described in <a href= 183 "filteroptions.htm#FILTERENV"><b class= 184 "APPLICATION">LPRng</b> ftp mirror sites Filter 185 Environment Variables</a></p> 186 </li> 187 188 <li> 189 <p><acronym class="ACRONYM">ROOT</acronym> Flag. If the 190 ROOT flag is specified the filter is executed with Userid 191 and Effective Userid ROOT (User ID 0). By default it is 192 executed with the <var class="LITERAL">user</var> and 193 <var class="LITERAL">group</var> configuration option 194 user and group ids. Running a filter as ROOT is extremely 195 dangerous, and should only be used for programs that 196 require root permissions to open files or make network 197 connections from privileged ports.</p> 198 </li> 199 200 <li> 201 <p><var class="LITERAL">$-</var> or <var class= 202 "LITERAL">-$</var> Flag. This flag suppresses appending 203 options to the filter command line. If the <span class= 204 "emphasis"><i class="EMPHASIS">$-</i></span> or <var 205 class="LITERAL">-$</var> flag is not present, the <var 206 class="LITERAL">:filter_options</var> or <var class= 207 "LITERAL">:of_filter_options</var> for the <var class= 208 "OPTION">:of</var> filter values are appended to the 209 filter command line. If the <var class= 210 "LITERAL">:bkf</var> (Berkeley <b class= 211 "APPLICATION">lpd</b> filter compatible flag) is <var 212 class="LITERAL">TRUE</var> then the <var class= 213 "LITERAL">:bk_filter_options</var> and <var class= 214 "LITERAL">:bk_of_filter_options</var> values are used 215 instead of the <var class="LITERAL">:filter_options</var> 216 and <var class="LITERAL">:of_filter_options</var> 217 values.</p> 218 219 <div class="TABLE"> 220 <a name="PRINTFILTERCOMMAND"></a> 221 222 <p><b>Table 16-1. Print Filter Command Line 223 Options</b></p> 224 225 <table border="1" class="CALSTABLE"> 226 <col> 227 <col> 228 229 <thead> 230 <tr> 231 <th>Option</th> 232 233 <th>DefaultValue</th> 234 </tr> 235 </thead> 236 237 <tbody> 238 <tr> 239 <td>Option</td> 240 241 <td>DefaultValue</td> 242 </tr> 243 244 <tr> 245 <td><var class= 246 "LITERAL">filter_options</var></td> 247 248 <td>$C $F $H $J $L $P $Q $R $Z $a $c $d $e $f $h 249 $i $j $k $l $n $p$r $s $w $x $y $-a</td> 250 </tr> 251 252 <tr> 253 <td><var class= 254 "LITERAL">of_filter_options</var></td> 255 256 <td>(same as <var class= 257 "LITERAL">filter_options</var>)</td> 258 </tr> 259 260 <tr> 261 <td><var class= 262 "LITERAL">bk_filter_options</var></td> 263 264 <td>$P $w $l $x $y $F $c $L $i $J $C $0n $0h 265 $-a</td> 266 </tr> 267 268 <tr> 269 <td><var class= 270 "LITERAL">bk_of_filter_options</var></td> 271 272 <td>$w $l $x $y</td> 273 </tr> 274 </tbody> 275 </table> 276 </div> 277 </li> 278 279 <li> 280 <p>By default, for programs that are not being invoked as 281 print job file filters, the <var class= 282 "LITERAL">filter_options</var> arguments are added. For 283 print job filters, if the <var class="LITERAL">:bkf</var> 284 flag is set, then the <var class= 285 "LITERAL">bk_filter_options</var> and <var class= 286 "LITERAL">bk_of_filter_options</var> entries are used. 287 The default <var class="LITERAL">bk</var> filter options 288 are the same as originally used with the BSD <b class= 289 "APPLICATION">lpr</b> filters. For the <var class= 290 "LITERAL">:of</var> filter, either the <var class= 291 "LITERAL">of_filter_options</var> or <var class= 292 "LITERAL">bk_of_filter_options</var> arguments will be 293 added.</p> 294 </li> 295 296 <li> 297 <p>The program arguments will then be scanned and 298 interpreted. Arguments of the form <var class= 299 "LITERAL">$</var><var class="LITERAL">letter</var> will 300 be translated into values from the print job control file 301 and/or printcap entry. The letters have the following 302 meaning:</p> 303 304 <div class="TABLE"> 305 <a name="FILTEROPTIONFLAGS"></a> 306 307 <p><b>Table 16-2. Filter Command Line Options and 308 Values</b></p> 309 310 <table border="1" class="CALSTABLE"> 311 <col> 312 <col> 313 314 <thead> 315 <tr> 316 <th>Option</th> 317 318 <th>Purpose or Value</th> 319 </tr> 320 </thead> 321 322 <tbody> 323 <tr> 324 <td><var class="LITERAL">a</var> </td> 325 326 <td>printcap <var class="LITERAL">af</var> 327 (accounting file name)</td> 328 </tr> 329 330 <tr> 331 <td><var class="LITERAL">b</var> </td> 332 333 <td>job size (in K bytes)</td> 334 </tr> 335 336 <tr> 337 <td><var class="LITERAL">c</var> </td> 338 339 <td>binary file (<var class="LITERAL">l</var> 340 format for print file)</td> 341 </tr> 342 343 <tr> 344 <td><var class="LITERAL">d</var> </td> 345 346 <td>printcap <var class="LITERAL">cd</var> or 347 <var class="LITERAL">sd</var> entry</td> 348 </tr> 349 350 <tr> 351 <td><var class="LITERAL">e</var> </td> 352 353 <td>print job data file name (currently being 354 processed)</td> 355 </tr> 356 357 <tr> 358 <td><var class="LITERAL">f</var> </td> 359 360 <td>print job original name when spooled for 361 printing (N info from control file)</td> 362 </tr> 363 364 <tr> 365 <td><var class="LITERAL">h</var> </td> 366 367 <td>print job originating host (H info from 368 control file)</td> 369 </tr> 370 371 <tr> 372 <td><var class="LITERAL">i</var> </td> 373 374 <td>indent request (I info from control 375 file)</td> 376 </tr> 377 378 <tr> 379 <td><var class="LITERAL">j</var> </td> 380 381 <td>job number in spool queue</td> 382 </tr> 383 384 <tr> 385 <td><var class="LITERAL">k</var> </td> 386 387 <td>print job control file name</td> 388 </tr> 389 390 <tr> 391 <td><var class="LITERAL">l</var> </td> 392 393 <td>printcap <var class="LITERAL">pl</var> (page 394 length)</td> 395 </tr> 396 397 <tr> 398 <td><var class="LITERAL">m</var> </td> 399 400 <td>printcap <var class="LITERAL">co</var></td> 401 </tr> 402 403 <tr> 404 <td><var class="LITERAL">n</var> </td> 405 406 <td>user name (L info from control file)</td> 407 </tr> 408 409 <tr> 410 <td><var class="LITERAL">p</var> </td> 411 412 <td>remote printer (when processing for bounce 413 queue)</td> 414 </tr> 415 416 <tr> 417 <td><var class="LITERAL">r</var> </td> 418 419 <td>remote host (when processing for bounce 420 queue)</td> 421 </tr> 422 423 <tr> 424 <td><var class="LITERAL">s</var> </td> 425 426 <td>printcap <var class="LITERAL">sf</var> 427 (status file)</td> 428 </tr> 429 430 <tr> 431 <td><var class="LITERAL">t</var> </td> 432 433 <td>time in common UNIX format</td> 434 </tr> 435 436 <tr> 437 <td><var class="LITERAL">w</var> </td> 438 439 <td>printcap <var class="LITERAL">pw</var> (page 440 width)</td> 441 </tr> 442 443 <tr> 444 <td><var class="LITERAL">x</var> </td> 445 446 <td>printcap <var class="LITERAL">px</var> (page 447 x dimension)</td> 448 </tr> 449 450 <tr> 451 <td><var class="LITERAL">y</var> </td> 452 453 <td>printcap <var class="LITERAL">py</var> (page 454 y dimension)</td> 455 </tr> 456 457 <tr> 458 <td><var class="LITERAL">F</var> </td> 459 460 <td>print file format</td> 461 </tr> 462 463 <tr> 464 <td><var class="LITERAL">P</var> </td> 465 466 <td>printer name</td> 467 </tr> 468 469 <tr> 470 <td><var class="LITERAL">S</var> </td> 471 472 <td>printcap <var class="LITERAL">cm</var> 473 (comment field)</td> 474 </tr> 475 476 <tr> 477 <td>Capital letter</td> 478 479 <td>Corresponding line from control file</td> 480 </tr> 481 482 <tr> 483 <td>{key}</td> 484 485 <td>printcap value for <var class= 486 "LITERAL">key</var></td> 487 </tr> 488 </tbody> 489 </table> 490 </div> 491 <br> 492 <br> 493 </li> 494 495 <li> 496 <p>If there is no value for the specified argument, then 497 the argument is removed from the list. If there is a 498 value, the actual form of the substitution is controlled 499 by additional flags as follows.</p> 500 501 <div class="TABLE"> 502 <a name="AEN8271"></a> 503 504 <p><b>Table 16-3. Filter Command Line Option 505 Format</b></p> 506 507 <table border="1" frame="border" rules="all" class= 508 "CALSTABLE"> 509 <col> 510 <col> 511 512 <thead> 513 <tr> 514 <th>Form</th> 515 516 <th>TranslatedValue</th> 517 </tr> 518 </thead> 519 520 <tbody> 521 <tr> 522 <td><var class="LITERAL">$x</var> </td> 523 524 <td><var class="LITERAL">'-x</var><var class= 525 "REPLACEABLE">value</var><var class= 526 "LITERAL">'</var></td> 527 </tr> 528 529 <tr> 530 <td><var class="LITERAL">$-x</var> </td> 531 532 <td><var class="LITERAL">'</var><var class= 533 "REPLACEABLE">value</var><var class= 534 "LITERAL">'</var></td> 535 </tr> 536 537 <tr> 538 <td><var class="LITERAL">$0x</var> </td> 539 540 <td><var class="LITERAL">-x '</var><var class= 541 "REPLACEABLE">value</var><var class= 542 "LITERAL">'</var></td> 543 </tr> 544 545 <tr> 546 <td><var class="LITERAL">$'x</var> </td> 547 548 <td><var class="LITERAL">-x</var> <var class= 549 "REPLACEABLE">value</var></td> 550 </tr> 551 </tbody> 552 </table> 553 </div> 554 <br> 555 <br> 556 557 <p>Each entry in quotes is treated as a single value, as 558 in /bin/sh. The <var class="LITERAL">$'x</var> does not 559 quote the value. Combinations of the various flags are 560 allowed. For example, <var class="LITERAL">$-x</var> 561 would simply substitute the value for <var class= 562 "LITERAL">x</var>, and then pass the whitespace separated 563 components as individual arguments. This last form is 564 useful for adding in additional flags on the command 565 line.</p> 566 </li> 567 568 <li> 569 <p>The command line is parsed, metacharacters are 570 ruthlessly stripped from all arguments and pathnames and 571 replaced by <var class="LITERAL">_</var> (underscores), 572 and an argument list suitable for the <var class= 573 "LITERAL">execve</var> system call is formed.</p> 574 </li> 575 576 <li> 577 <p>A sanitized environment is set up for the program 578 execution, with the following environment variables.</p> 579 580 <div class="TABLE"> 581 <a name="FILTERENV"></a> 582 583 <p><b>Table 16-4. Filter Environment Variables</b></p> 584 585 <table border="1" frame="border" rules="all" class= 586 "CALSTABLE"> 587 <col> 588 <col> 589 590 <thead> 591 <tr> 592 <th>Variable Name</th> 593 594 <th>Meaning</th> 595 </tr> 596 </thead> 597 598 <tbody> 599 <tr> 600 <td><var class="LITERAL">CONTROL</var> </td> 601 602 <td>control file name</td> 603 </tr> 604 605 <tr> 606 <td><var class="LITERAL">DATAFILES</var> </td> 607 608 <td>list of data file names</td> 609 </tr> 610 611 <tr> 612 <td><var class="LITERAL">HOME</var> </td> 613 614 <td>Home directory (client only)</td> 615 </tr> 616 617 <tr> 618 <td><var class="LITERAL">IFS</var> </td> 619 620 <td><var class="LITERAL">" \t"</var></td> 621 </tr> 622 623 <tr> 624 <td><var class="LITERAL">LD_LIBRARY_PATH</var> 625 </td> 626 627 <td><var class="LITERAL">:filter_ld_path</var> 628 configuration information</td> 629 </tr> 630 631 <tr> 632 <td><var class="LITERAL">LOGDIR</var> </td> 633 634 <td>Home directory (client only)</td> 635 </tr> 636 637 <tr> 638 <td><var class="LITERAL">LOGNAME</var> </td> 639 640 <td><var class="LITERAL">L</var> control file 641 line</td> 642 </tr> 643 644 <tr> 645 <td><var class="LITERAL">PATH</var> </td> 646 647 <td><var class="LITERAL">filter_path</var> 648 configuration information</td> 649 </tr> 650 651 <tr> 652 <td><var class="LITERAL">PRINTCAP_ENTRY</var> 653 </td> 654 655 <td>printcap information</td> 656 </tr> 657 658 <tr> 659 <td><var class="LITERAL">SHELL</var> </td> 660 661 <td><var class="OPTION">:sh</var> configuration 662 information (default <tt class= 663 "FILENAME">/bin/sh</tt>)</td> 664 </tr> 665 666 <tr> 667 <td><var class="LITERAL">SPOOL_DIR</var> </td> 668 669 <td><var class="LITERAL">:sd</var> printcap 670 information</td> 671 </tr> 672 673 <tr> 674 <td><var class="LITERAL">TZ</var> </td> 675 676 <td>Time zone</td> 677 </tr> 678 679 <tr> 680 <td><var class="LITERAL">USER</var> </td> 681 682 <td>User name (client only)</td> 683 </tr> 684 </tbody> 685 </table> 686 </div> 687 <br> 688 <br> 689 </li> 690 691 <li> 692 <p>If the filter is to be run by a client program such as 693 <b class="APPLICATION">lpr</b>, then the environment 694 variables specified by the <var class= 695 "LITERAL">pass_env</var> configuration or printcap option 696 will be extracted from the environment, have any 697 metacharacters removed, and then placed in the 698 environment variable list. Commonly, the <acronym class= 699 "ACRONYM">PGPPASS</acronym>, <acronym class= 700 "ACRONYM">PGPPASSFD</acronym>, and <acronym class= 701 "ACRONYM">PGPPATH</acronym> are specified.</p> 702 </li> 703 704 <li> 705 <p>The program is started, with <acronym class= 706 "ACRONYM">STDIN</acronym>, <acronym class= 707 "ACRONYM">STDOUT</acronym>, and <acronym class= 708 "ACRONYM">STDERR</acronym> attached to the appropriate 709 files or file descriptors. If none is specified, then 710 they are attached to <tt class= 711 "FILENAME">/dev/null</tt>.</p> 712 </li> 713 </ol> 714 <br> 715 <br> 716 </div> 717 718 <div class="NAVFOOTER"> 719 <hr align="LEFT" width="100%"> 720 721 <table summary="Footer navigation table" width="100%" border= 722 "0" cellpadding="0" cellspacing="0"> 723 <tr> 724 <td width="33%" align="left" valign="top"><a href= 725 "chainingfilters.htm" accesskey="P">Prev</a></td> 726 727 <td width="34%" align="center" valign="top"><a href= 728 "index.htm" accesskey="H">Home</a></td> 729 730 <td width="33%" align="right" valign="top"><a href= 731 "x8397.htm" accesskey="N">Next</a></td> 732 </tr> 733 734 <tr> 735 <td width="33%" align="left" valign="top">Chaining 736 Filters</td> 737 738 <td width="34%" align="center" valign="top"><a href= 739 "filters.htm" accesskey="U">Up</a></td> 740 741 <td width="33%" align="right" valign="top"><b class= 742 "APPLICATION">LPRng</b> Supported Filters</td> 743 </tr> 744 </table> 745 </div> 746 </body> 747</html> 748 749