]>
Commit | Line | Data |
---|---|---|
c277f98c | 1 | <!DOCTYPE HTML> |
94436c5a MS |
2 | <html> |
3 | <!-- SECTION: Man Pages --> | |
4 | <head> | |
5 | <link rel="stylesheet" type="text/css" href="../cups-printable.css"> | |
6 | <title>filter(7)</title> | |
7 | </head> | |
8 | <body> | |
9 | <h1 class="title">filter(7)</h1> | |
10 | <h2 class="title"><a name="NAME">Name</a></h2> | |
11 | filter - cups file conversion filter interface | |
12 | <h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2> | |
c277f98c MS |
13 | <b>filter</b> |
14 | job user title num-copies options [ | |
15 | <i>filename</i> | |
16 | ] | |
94436c5a MS |
17 | <h2 class="title"><a name="DESCRIPTION">Description</a></h2> |
18 | The CUPS filter interface provides a standard method for adding support for | |
19 | new document types to CUPS. Each filter is capable of converting from one | |
20 | or more input formats to another format that can either be printed directly | |
21 | or piped into another filter to get it to a printable format. | |
22 | <p>Filters <b>must</b> be capable of reading from a filename on the command-line | |
23 | or from the standard input, copying the standard input to a temporary | |
24 | file as required by the file format. All output <b>must</b> be sent to the | |
25 | standard output. | |
26 | <p>The command name (argv[0]) is set to the name of the destination printer but is | |
27 | also available in the PRINTER environment variable. | |
28 | <h2 class="title"><a name="WARNING">Warning</a></h2> | |
29 | CUPS filters are not meant to be run directly by the user. Aside from the legacy | |
30 | System V interface issues (argv[0] is the printer name), CUPS filters also | |
31 | expect specific environment variables and file descriptors, and typically run in | |
32 | a user session that (on OS X) has additional restrictions that affect how it | |
33 | runs. Unless you are a developer and know what you are doing, please do not run | |
c277f98c | 34 | filters directly. Instead, use the <i>cupsfilter(8)</i> program to use the |
94436c5a MS |
35 | appropriate filters to do the conversions you need. |
36 | <h2 class="title"><a name="OPTIONS">Options</a></h2> | |
37 | Options passed on the command-line typically do not include the default choices | |
38 | the printer's PPD file. In addition, some options may be specified in multiple | |
39 | ways - "landscape" is a synonym for "orientation-requested=4", "media" is a | |
40 | synonym for "PageSize", "PageRegion", "InputSlot", and "MediaType", and "sides" | |
41 | is a synonym for the various "Duplex" options. Non-raster filters <b>must</b> | |
42 | support both explicit and implicit specification of PPD options - use the | |
43 | ppdMarkDefaults and cupsMarkOptions functions in the CUPS library to use the | |
44 | correct mapping, and ppdFindMarkedChoice to get the user-selected choice. | |
45 | <p>Raster filters should use option choices set through the raster page header, as | |
46 | those reflect the options in effect for a given page. Options specified on the | |
47 | command-line determine the default values for the entire job, which can be | |
48 | overridden on a per-page basis. | |
49 | <h2 class="title"><a name="LOG_MESSAGES">Log Messages</a></h2> | |
50 | Messages sent to stderr are generally logged to | |
51 | printer-state-message attribute and the current <i>ErrorLog</i>. | |
52 | Each line begins with a standard prefix: | |
c277f98c MS |
53 | <p style="margin-left: 5.0em; text-indent: -5.0em">ALERT: message |
54 | <br> | |
55 | <br> | |
56 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 57 | message to the current <i>ErrorLog</i> using the "alert" log level. |
c277f98c MS |
58 | <p style="margin-left: 5.0em; text-indent: -5.0em">ATTR: attribute=value [attribute=value] |
59 | <br> | |
60 | <br> | |
61 | Sets the named job or printer attribute(s). The following job attributes can be | |
94436c5a MS |
62 | set: "job-media-progress". The following printer attributes can be set: |
63 | "auth-info-required", "marker-colors", "marker-high-levels", "marker-levels", | |
64 | "marker-low-levels", "marker-message", "marker-names", "marker-types", | |
65 | "printer-alert", and "printer-alert-description". | |
c277f98c MS |
66 | <p style="margin-left: 5.0em; text-indent: -5.0em">CRIT: message |
67 | <br> | |
68 | <br> | |
69 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 70 | message to the current <i>ErrorLog</i> using the "critical" log level. |
c277f98c MS |
71 | <p style="margin-left: 5.0em; text-indent: -5.0em">DEBUG: message |
72 | <br> | |
73 | <br> | |
74 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 75 | message to the current <i>ErrorLog</i> using the "debug" log level. |
c277f98c MS |
76 | <p style="margin-left: 5.0em; text-indent: -5.0em">DEBUG2: message |
77 | <br> | |
78 | <br> | |
79 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 80 | message to the current <i>ErrorLog</i> using the "debug2" log level. |
c277f98c MS |
81 | <p style="margin-left: 5.0em; text-indent: -5.0em">EMERG: message |
82 | <br> | |
83 | <br> | |
84 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 85 | message to the current <i>ErrorLog</i> using the "emergency" log level. |
c277f98c MS |
86 | <p style="margin-left: 5.0em; text-indent: -5.0em">ERROR: message |
87 | <br> | |
88 | <br> | |
89 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 90 | message to the current <i>ErrorLog</i> using the "error" log level. |
c277f98c MS |
91 | <p style="margin-left: 5.0em; text-indent: -5.0em">INFO: message |
92 | <br> | |
93 | <br> | |
94 | Sets the printer-state-message attribute. If the current <i>LogLevel</i> | |
94436c5a MS |
95 | is set to "debug2", also adds the specified message to the |
96 | current <i>ErrorLog</i> using the "info" log level. | |
c277f98c MS |
97 | <p style="margin-left: 5.0em; text-indent: -5.0em">NOTICE: message |
98 | <br> | |
99 | <br> | |
100 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 101 | message to the current <i>ErrorLog</i> using the "notice" log level. |
c277f98c MS |
102 | <p style="margin-left: 5.0em; text-indent: -5.0em">PAGE: page-number #-copies |
103 | <br> | |
104 | <p style="margin-left: 5.0em; text-indent: -5.0em">PAGE: total #-pages | |
105 | <br> | |
106 | <br> | |
107 | Adds an entry to the current <i>PageLog</i>. The first form adds | |
94436c5a MS |
108 | #-copies to the job-media-sheets-completed attribute. The second |
109 | form sets the job-media-sheets-completed attribute to #-pages. | |
c277f98c MS |
110 | <p style="margin-left: 5.0em; text-indent: -5.0em">PPD: Keyword=Value ... KeywordN=Value |
111 | <br> | |
112 | <br> | |
113 | Sets the named keywords in the printer's PPD file. This is typically | |
94436c5a MS |
114 | used to update default option keywords such as DefaultPageSize and |
115 | the various installable options in the PPD file. | |
c277f98c MS |
116 | <p style="margin-left: 5.0em; text-indent: -5.0em">STATE: printer-state-reason [printer-state-reason ...] |
117 | <br> | |
118 | <p style="margin-left: 5.0em; text-indent: -5.0em">STATE: + printer-state-reason [printer-state-reason ...] | |
119 | <br> | |
120 | <p style="margin-left: 5.0em; text-indent: -5.0em">STATE: - printer-state-reason [printer-state-reason ...] | |
121 | <br> | |
122 | <br> | |
123 | Sets, adds, or removes printer-state-reason keywords to the | |
94436c5a MS |
124 | current queue. Typically this is used to indicate media, ink, and |
125 | toner conditions on a printer. | |
c277f98c MS |
126 | <p style="margin-left: 5.0em; text-indent: -5.0em">WARNING: message |
127 | <br> | |
128 | <br> | |
129 | Sets the printer-state-message attribute and adds the specified | |
94436c5a | 130 | message to the current <i>ErrorLog</i> using the "warning" log level. |
94436c5a MS |
131 | <h2 class="title"><a name="ENVIRONMENT_VARIABLES">Environment Variables</a></h2> |
132 | The following environment variables are defined by the CUPS | |
133 | server when executing the filter: | |
c277f98c MS |
134 | <p style="margin-left: 5.0em; text-indent: -5.0em">CHARSET |
135 | <br> | |
136 | <br> | |
137 | The default text character set, typically utf-8. | |
138 | <p style="margin-left: 5.0em; text-indent: -5.0em">CLASS | |
139 | <br> | |
140 | <br> | |
141 | When a job is submitted to a printer class, contains the name of | |
94436c5a MS |
142 | the destination printer class. Otherwise this environment |
143 | variable will not be set. | |
c277f98c MS |
144 | <p style="margin-left: 5.0em; text-indent: -5.0em">CONTENT_TYPE |
145 | <br> | |
146 | <br> | |
147 | The MIME type associated with the file (e.g. | |
94436c5a | 148 | application/postscript). |
c277f98c MS |
149 | <p style="margin-left: 5.0em; text-indent: -5.0em">CUPS_CACHEDIR |
150 | <br> | |
151 | <br> | |
152 | The directory for semi-persistent cache files can be found. | |
153 | <p style="margin-left: 5.0em; text-indent: -5.0em">CUPS_DATADIR | |
154 | <br> | |
155 | <br> | |
156 | The directory where data files can be found. | |
157 | <p style="margin-left: 5.0em; text-indent: -5.0em">CUPS_FILETYPE | |
158 | <br> | |
159 | <br> | |
160 | The type of file being printed: "job-sheet" for a banner page and "document" | |
94436c5a | 161 | for a regular print file. |
c277f98c MS |
162 | <p style="margin-left: 5.0em; text-indent: -5.0em">CUPS_MAX_MESSAGE |
163 | <br> | |
164 | <br> | |
165 | The maximum size of a message sent to stderr, including any leading prefix and | |
94436c5a | 166 | the trailing newline. |
c277f98c MS |
167 | <p style="margin-left: 5.0em; text-indent: -5.0em">CUPS_SERVERROOT |
168 | <br> | |
169 | <br> | |
170 | The root directory of the server. | |
171 | <p style="margin-left: 5.0em; text-indent: -5.0em">DEVICE_URI | |
172 | <br> | |
173 | <br> | |
174 | The device-uri associated with the printer. | |
175 | <p style="margin-left: 5.0em; text-indent: -5.0em">FINAL_CONTENT_TYPE | |
176 | <br> | |
177 | <br> | |
178 | The MIME type associated with the printer (e.g. | |
94436c5a | 179 | application/vnd.cups-postscript). |
c277f98c MS |
180 | <p style="margin-left: 5.0em; text-indent: -5.0em">LANG |
181 | <br> | |
182 | <br> | |
183 | The default language locale (typically C or en). | |
184 | <p style="margin-left: 5.0em; text-indent: -5.0em">PATH | |
185 | <br> | |
186 | <br> | |
187 | The standard execution path for external programs that may be run by | |
94436c5a | 188 | the filter. |
c277f98c MS |
189 | <p style="margin-left: 5.0em; text-indent: -5.0em">PPD |
190 | <br> | |
191 | <br> | |
192 | The full pathname of the PostScript Printer Description (PPD) | |
94436c5a | 193 | file for this printer. |
c277f98c MS |
194 | <p style="margin-left: 5.0em; text-indent: -5.0em">PRINTER |
195 | <br> | |
196 | <br> | |
197 | The name of the printer. | |
198 | <p style="margin-left: 5.0em; text-indent: -5.0em">RIP_CACHE | |
199 | <br> | |
200 | <br> | |
201 | The recommended amount of memory to use for Raster Image | |
94436c5a | 202 | Processors (RIPs). |
c277f98c MS |
203 | <p style="margin-left: 5.0em; text-indent: -5.0em">SOFTWARE |
204 | <br> | |
205 | <br> | |
206 | The name and version number of the server (typically CUPS/1.2). | |
207 | <p style="margin-left: 5.0em; text-indent: -5.0em">TZ | |
208 | <br> | |
209 | <br> | |
210 | The timezone of the server. | |
211 | <p style="margin-left: 5.0em; text-indent: -5.0em">USER | |
212 | <br> | |
213 | <br> | |
214 | The user executing the filter, typically "lp" or "root"; consult the | |
215 | <i>cupsd.conf(5)</i> file for the current setting. | |
94436c5a MS |
216 | <h2 class="title"><a name="COMPATIBILITY">Compatibility</a></h2> |
217 | While the filter interface is compatible with System V interface | |
218 | scripts, it will only work with the System V interface script as the | |
219 | only filter. Typically the interface script will be provided via the | |
c277f98c | 220 | <i>lpadmin(8)</i> command using the <i>-i</i> option. |
94436c5a | 221 | <h2 class="title"><a name="SEE_ALSO">See Also</a></h2> |
c277f98c | 222 | <i>backend(7)</i>, <i>cupsd(8)</i>, <i>cupsfilter(8)</i>, |
94436c5a | 223 | <br> |
c277f98c | 224 | <a href="http://localhost:631/help">http://localhost:631/help</a> |
94436c5a MS |
225 | <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> |
226 | Copyright 2007-2013 by Apple Inc. | |
227 | ||
228 | </body> | |
229 | </html> |