]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
75bd9771 | 2 | .\" "$Id: filter.man 7600 2008-05-20 21:06:23Z mike $" |
ef416fc2 | 3 | .\" |
321d8d57 | 4 | .\" filter man page for CUPS. |
ef416fc2 | 5 | .\" |
321d8d57 | 6 | .\" Copyright 2007-2011 by Apple Inc. |
bc44d920 | 7 | .\" Copyright 1997-2007 by Easy Software Products. |
ef416fc2 | 8 | .\" |
9 | .\" These coded instructions, statements, and computer programs are the | |
bc44d920 | 10 | .\" property of Apple Inc. and are protected by Federal copyright |
11 | .\" law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
12 | .\" which should have been included with this file. If this file is | |
13 | .\" file is missing or damaged, see the license at "http://www.cups.org/". | |
ef416fc2 | 14 | .\" |
178cb736 | 15 | .TH filter 7 "CUPS" "13 May 2009" "Apple Inc." |
ef416fc2 | 16 | .SH NAME |
bd7854cb | 17 | filter \- cups file conversion filter interface |
ef416fc2 | 18 | .SH SYNOPSIS |
19 | .B filter | |
20 | job user title num-copies options [ | |
21 | .I filename | |
22 | ] | |
23 | .SH DESCRIPTION | |
24 | The CUPS filter interface provides a standard method for adding support for | |
25 | new document types to CUPS. Each filter is capable of converting from one | |
26 | or more input formats to another format that can either be printed directly | |
27 | or piped into another filter to get it to a printable format. | |
28 | .LP | |
bd7854cb | 29 | Filters \fBmust\fR be capable of reading from a filename on the command-line |
ef416fc2 | 30 | or from the standard input, copying the standard input to a temporary |
bd7854cb | 31 | file as required by the file format. All output \fBmust\fR be sent to the |
ef416fc2 | 32 | standard output. |
33 | .LP | |
178cb736 MS |
34 | The command name (argv[0]) is set to the name of the destination printer but is |
35 | also available in the PRINTER environment variable. | |
36 | ||
37 | .SH OPTIONS | |
38 | Options passed on the command-line typically do not include the default choices | |
39 | the printer's PPD file. In addition, some options may be specified in multiple | |
40 | ways - "landscape" is a synonym for "orientation-requested=4", "media" is a | |
41 | synonym for "PageSize", "PageRegion", "InputSlot", and "MediaType", and "sides" | |
42 | is a synonym for the various "Duplex" options. Non-raster filters \fBmust\fR | |
43 | support both explicit and implicit specification of PPD options - use the | |
44 | ppdMarkDefaults and cupsMarkOptions functions in the CUPS library to use the | |
45 | correct mapping, and ppdFindMarkedChoice to get the user-selected choice. | |
46 | .LP | |
47 | Raster filters should use option choices set through the raster page header, as | |
48 | those reflect the options in effect for a given page. Options specified on the | |
49 | command-line determine the default values for the entire job, which can be | |
50 | overridden on a per-page basis. | |
51 | ||
bd7854cb | 52 | .SH LOG MESSAGES |
53 | Messages sent to stderr are generally logged to | |
54 | printer-state-message attribute and the current \fIErrorLog\fR. | |
55 | Each line begins with a standard prefix: | |
56 | ||
57 | .TP 5 | |
58 | ALERT: message | |
59 | .br | |
60 | Sets the printer-state-message attribute and adds the specified | |
61 | message to the current \fIErrorLog\fR using the "alert" log level. | |
62 | ||
63 | .TP 5 | |
64 | ATTR: attribute=value [attribute=value] | |
65 | .br | |
66 | Sets the named job attribute(s). Typically this will be used to | |
67 | set the job-remote-id attribute. | |
68 | ||
69 | .TP 5 | |
70 | CRIT: message | |
71 | .br | |
72 | Sets the printer-state-message attribute and adds the specified | |
73 | message to the current \fIErrorLog\fR using the "critical" log level. | |
74 | ||
75 | .TP 5 | |
76 | DEBUG: message | |
77 | .br | |
78 | Sets the printer-state-message attribute and adds the specified | |
79 | message to the current \fIErrorLog\fR using the "debug" log level. | |
80 | ||
81 | .TP 5 | |
82 | DEBUG2: message | |
83 | .br | |
84 | Sets the printer-state-message attribute and adds the specified | |
85 | message to the current \fIErrorLog\fR using the "debug2" log level. | |
86 | ||
87 | .TP 5 | |
88 | EMERG: message | |
89 | .br | |
90 | Sets the printer-state-message attribute and adds the specified | |
91 | message to the current \fIErrorLog\fR using the "emergency" log level. | |
92 | ||
93 | .TP 5 | |
94 | ERROR: message | |
95 | .br | |
96 | Sets the printer-state-message attribute and adds the specified | |
97 | message to the current \fIErrorLog\fR using the "error" log level. | |
98 | ||
99 | .TP 5 | |
100 | INFO: message | |
101 | .br | |
102 | Sets the printer-state-message attribute. If the current \fILogLevel\fR | |
103 | is set to "debug2", also adds the specified message to the | |
104 | current \fIErrorLog\fR using the "info" log level. | |
105 | ||
106 | .TP 5 | |
107 | NOTICE: message | |
108 | .br | |
109 | Sets the printer-state-message attribute and adds the specified | |
110 | message to the current \fIErrorLog\fR using the "notice" log level. | |
111 | ||
112 | .TP 5 | |
113 | PAGE: page-number #-copies | |
114 | .TP 5 | |
bc44d920 | 115 | PAGE: total #-pages |
bd7854cb | 116 | .br |
117 | Adds an entry to the current \fIPageLog\fR. The first form adds | |
118 | #-copies to the job-media-sheets-completed attribute. The second | |
119 | form sets the job-media-sheets-completed attribute to #-pages. | |
120 | ||
c9fc04c6 MS |
121 | .TP 5 |
122 | PPD: Keyword=Value ... KeywordN=Value | |
123 | .br | |
124 | Sets the named keywords in the printer's PPD file. This is typically | |
125 | used to update default option keywords such as DefaultPageSize and | |
126 | the various installable options in the PPD file. | |
127 | ||
bd7854cb | 128 | .TP 5 |
129 | STATE: printer-state-reason [printer-state-reason ...] | |
130 | .TP 5 | |
131 | STATE: + printer-state-reason [printer-state-reason ...] | |
132 | .TP 5 | |
133 | STATE: - printer-state-reason [printer-state-reason ...] | |
134 | .br | |
135 | Sets, adds, or removes printer-state-reason keywords to the | |
136 | current queue. Typically this is used to indicate media, ink, and | |
137 | toner conditions on a printer. | |
138 | ||
139 | .TP 5 | |
140 | WARNING: message | |
141 | .br | |
142 | Sets the printer-state-message attribute and adds the specified | |
143 | message to the current \fIErrorLog\fR using the "warning" log level. | |
144 | ||
ef416fc2 | 145 | .SH ENVIRONMENT VARIABLES |
bd7854cb | 146 | The following environment variables are defined by the CUPS |
80ca4592 | 147 | server when executing the filter: |
bd7854cb | 148 | |
ef416fc2 | 149 | .TP 5 |
150 | CHARSET | |
151 | .br | |
bd7854cb | 152 | The default text character set, typically utf-8. |
153 | ||
ef416fc2 | 154 | .TP 5 |
155 | CLASS | |
156 | .br | |
157 | When a job is submitted to a printer class, contains the name of | |
158 | the destination printer class. Otherwise this environment | |
159 | variable will not be set. | |
bd7854cb | 160 | |
ef416fc2 | 161 | .TP 5 |
162 | CONTENT_TYPE | |
163 | .br | |
bd7854cb | 164 | The MIME type associated with the file (e.g. |
165 | application/postscript). | |
166 | ||
0af14961 MS |
167 | .TP 5 |
168 | CUPS_CACHEDIR | |
169 | .br | |
170 | The directory for semi-persistent cache files can be found. | |
171 | ||
ef416fc2 | 172 | .TP 5 |
173 | CUPS_DATADIR | |
174 | .br | |
175 | The directory where data files can be found. | |
bd7854cb | 176 | |
0af14961 MS |
177 | .TP 5 |
178 | CUPS_FILETYPE | |
179 | .br | |
180 | The type of file being printed: "job-sheet" for a banner page and "document" | |
181 | for a regular print file. | |
182 | ||
ef416fc2 | 183 | .TP 5 |
184 | CUPS_SERVERROOT | |
185 | .br | |
186 | The root directory of the server. | |
bd7854cb | 187 | |
ef416fc2 | 188 | .TP 5 |
189 | DEVICE_URI | |
190 | .br | |
80ca4592 | 191 | The device-uri associated with the printer. |
bd7854cb | 192 | |
193 | .TP 5 | |
194 | FINAL_CONTENT_TYPE | |
195 | .br | |
196 | The MIME type associated with the printer (e.g. | |
197 | application/vnd.cups-postscript). | |
198 | ||
ef416fc2 | 199 | .TP 5 |
200 | LANG | |
201 | .br | |
202 | The default language locale (typically C or en). | |
bd7854cb | 203 | |
ef416fc2 | 204 | .TP 5 |
205 | PATH | |
206 | .br | |
bd7854cb | 207 | The standard execution path for external programs that may be run by |
80ca4592 | 208 | the filter. |
bd7854cb | 209 | |
ef416fc2 | 210 | .TP 5 |
211 | PPD | |
212 | .br | |
bd7854cb | 213 | The full pathname of the PostScript Printer Description (PPD) |
214 | file for this printer. | |
215 | ||
ef416fc2 | 216 | .TP 5 |
217 | PRINTER | |
218 | .br | |
bd7854cb | 219 | The name of the printer. |
220 | ||
ef416fc2 | 221 | .TP 5 |
222 | RIP_CACHE | |
223 | .br | |
bd7854cb | 224 | The recommended amount of memory to use for Raster Image |
225 | Processors (RIPs). | |
226 | ||
ef416fc2 | 227 | .TP 5 |
228 | SOFTWARE | |
229 | .br | |
bd7854cb | 230 | The name and version number of the server (typically CUPS/1.2). |
231 | ||
ef416fc2 | 232 | .TP 5 |
233 | TZ | |
234 | .br | |
235 | The timezone of the server. | |
bd7854cb | 236 | |
ef416fc2 | 237 | .TP 5 |
238 | USER | |
239 | .br | |
80ca4592 | 240 | The user executing the filter, typically "lp" or "root"; consult the |
bd7854cb | 241 | \fIcupsd.conf(5)\fR file for the current setting. |
242 | ||
ef416fc2 | 243 | .SH COMPATIBILITY |
244 | While the filter interface is compatible with System V interface | |
245 | scripts, it will only work with the System V interface script as the | |
246 | only filter. Typically the interface script will be provided via the | |
bd7854cb | 247 | \fIlpadmin(8)\fR command using the \fI-i\fR option. |
ef416fc2 | 248 | .SH SEE ALSO |
178cb736 | 249 | \fIbackend(7)\fR, \fIcupsd(8)\fR, |
bd7854cb | 250 | .br |
251 | http://localhost:631/help | |
ef416fc2 | 252 | .SH COPYRIGHT |
321d8d57 | 253 | Copyright 2007-2011 by Apple Inc. |
ef416fc2 | 254 | .\" |
75bd9771 | 255 | .\" End of "$Id: filter.man 7600 2008-05-20 21:06:23Z mike $". |
ef416fc2 | 256 | .\" |