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