]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
e4e5666b | 2 | .\" "$Id$" |
ef416fc2 | 3 | .\" |
321d8d57 | 4 | .\" filter man page for CUPS. |
ef416fc2 | 5 | .\" |
0fa6c7fa | 6 | .\" Copyright 2007-2013 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 | .\" |
a29fd7dd | 15 | .TH filter 7 "CUPS" "18 May 2012" "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. | |
f3c17241 MS |
36 | .SH WARNING |
37 | CUPS filters are not meant to be run directly by the user. Aside from the legacy | |
38 | System V interface issues (argv[0] is the printer name), CUPS filters also | |
39 | expect specific environment variables and file descriptors, and typically run in | |
40 | a user session that (on OS X) has additional restrictions that affect how it | |
41 | runs. Unless you are a developer and know what you are doing, please do not run | |
42 | filters directly. Instead, use the \fIcupsfilter(8)\fR program to use the | |
43 | appropriate filters to do the conversions you need. | |
178cb736 MS |
44 | .SH OPTIONS |
45 | Options passed on the command-line typically do not include the default choices | |
46 | the printer's PPD file. In addition, some options may be specified in multiple | |
47 | ways - "landscape" is a synonym for "orientation-requested=4", "media" is a | |
48 | synonym for "PageSize", "PageRegion", "InputSlot", and "MediaType", and "sides" | |
49 | is a synonym for the various "Duplex" options. Non-raster filters \fBmust\fR | |
50 | support both explicit and implicit specification of PPD options - use the | |
51 | ppdMarkDefaults and cupsMarkOptions functions in the CUPS library to use the | |
52 | correct mapping, and ppdFindMarkedChoice to get the user-selected choice. | |
53 | .LP | |
54 | Raster filters should use option choices set through the raster page header, as | |
55 | those reflect the options in effect for a given page. Options specified on the | |
56 | command-line determine the default values for the entire job, which can be | |
57 | overridden on a per-page basis. | |
bd7854cb | 58 | .SH LOG MESSAGES |
59 | Messages sent to stderr are generally logged to | |
60 | printer-state-message attribute and the current \fIErrorLog\fR. | |
61 | Each line begins with a standard prefix: | |
bd7854cb | 62 | .TP 5 |
63 | ALERT: message | |
64 | .br | |
65 | Sets the printer-state-message attribute and adds the specified | |
66 | message to the current \fIErrorLog\fR using the "alert" log level. | |
bd7854cb | 67 | .TP 5 |
68 | ATTR: attribute=value [attribute=value] | |
69 | .br | |
f3c17241 MS |
70 | Sets the named job or printer attribute(s). The following job attributes can be |
71 | set: "job-media-progress". The following printer attributes can be set: | |
72 | "auth-info-required", "marker-colors", "marker-high-levels", "marker-levels", | |
73 | "marker-low-levels", "marker-message", "marker-names", "marker-types", | |
74 | "printer-alert", and "printer-alert-description". | |
bd7854cb | 75 | .TP 5 |
76 | CRIT: message | |
77 | .br | |
78 | Sets the printer-state-message attribute and adds the specified | |
79 | message to the current \fIErrorLog\fR using the "critical" log level. | |
bd7854cb | 80 | .TP 5 |
81 | DEBUG: message | |
82 | .br | |
83 | Sets the printer-state-message attribute and adds the specified | |
84 | message to the current \fIErrorLog\fR using the "debug" log level. | |
bd7854cb | 85 | .TP 5 |
86 | DEBUG2: message | |
87 | .br | |
88 | Sets the printer-state-message attribute and adds the specified | |
89 | message to the current \fIErrorLog\fR using the "debug2" log level. | |
bd7854cb | 90 | .TP 5 |
91 | EMERG: message | |
92 | .br | |
93 | Sets the printer-state-message attribute and adds the specified | |
94 | message to the current \fIErrorLog\fR using the "emergency" log level. | |
bd7854cb | 95 | .TP 5 |
96 | ERROR: message | |
97 | .br | |
98 | Sets the printer-state-message attribute and adds the specified | |
99 | message to the current \fIErrorLog\fR using the "error" log level. | |
bd7854cb | 100 | .TP 5 |
101 | INFO: message | |
102 | .br | |
103 | Sets the printer-state-message attribute. If the current \fILogLevel\fR | |
104 | is set to "debug2", also adds the specified message to the | |
105 | current \fIErrorLog\fR using the "info" log level. | |
bd7854cb | 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. | |
bd7854cb | 111 | .TP 5 |
112 | PAGE: page-number #-copies | |
113 | .TP 5 | |
bc44d920 | 114 | PAGE: total #-pages |
bd7854cb | 115 | .br |
116 | Adds an entry to the current \fIPageLog\fR. The first form adds | |
117 | #-copies to the job-media-sheets-completed attribute. The second | |
118 | form sets the job-media-sheets-completed attribute to #-pages. | |
c9fc04c6 MS |
119 | .TP 5 |
120 | PPD: Keyword=Value ... KeywordN=Value | |
121 | .br | |
122 | Sets the named keywords in the printer's PPD file. This is typically | |
123 | used to update default option keywords such as DefaultPageSize and | |
124 | the various installable options in the PPD file. | |
bd7854cb | 125 | .TP 5 |
126 | STATE: printer-state-reason [printer-state-reason ...] | |
127 | .TP 5 | |
128 | STATE: + printer-state-reason [printer-state-reason ...] | |
129 | .TP 5 | |
130 | STATE: - printer-state-reason [printer-state-reason ...] | |
131 | .br | |
132 | Sets, adds, or removes printer-state-reason keywords to the | |
133 | current queue. Typically this is used to indicate media, ink, and | |
134 | toner conditions on a printer. | |
bd7854cb | 135 | .TP 5 |
136 | WARNING: message | |
137 | .br | |
138 | Sets the printer-state-message attribute and adds the specified | |
139 | message to the current \fIErrorLog\fR using the "warning" log level. | |
ef416fc2 | 140 | .SH ENVIRONMENT VARIABLES |
bd7854cb | 141 | The following environment variables are defined by the CUPS |
80ca4592 | 142 | server when executing the filter: |
ef416fc2 | 143 | .TP 5 |
144 | CHARSET | |
145 | .br | |
bd7854cb | 146 | The default text character set, typically utf-8. |
ef416fc2 | 147 | .TP 5 |
148 | CLASS | |
149 | .br | |
150 | When a job is submitted to a printer class, contains the name of | |
151 | the destination printer class. Otherwise this environment | |
152 | variable will not be set. | |
153 | .TP 5 | |
154 | CONTENT_TYPE | |
155 | .br | |
bd7854cb | 156 | The MIME type associated with the file (e.g. |
157 | application/postscript). | |
0af14961 MS |
158 | .TP 5 |
159 | CUPS_CACHEDIR | |
160 | .br | |
161 | The directory for semi-persistent cache files can be found. | |
ef416fc2 | 162 | .TP 5 |
163 | CUPS_DATADIR | |
164 | .br | |
165 | The directory where data files can be found. | |
0af14961 MS |
166 | .TP 5 |
167 | CUPS_FILETYPE | |
168 | .br | |
169 | The type of file being printed: "job-sheet" for a banner page and "document" | |
170 | for a regular print file. | |
ef416fc2 | 171 | .TP 5 |
a29fd7dd MS |
172 | CUPS_MAX_MESSAGE |
173 | .br | |
174 | The maximum size of a message sent to stderr, including any leading prefix and | |
175 | the trailing newline. | |
176 | .TP 5 | |
ef416fc2 | 177 | CUPS_SERVERROOT |
178 | .br | |
179 | The root directory of the server. | |
180 | .TP 5 | |
181 | DEVICE_URI | |
182 | .br | |
80ca4592 | 183 | The device-uri associated with the printer. |
bd7854cb | 184 | .TP 5 |
185 | FINAL_CONTENT_TYPE | |
186 | .br | |
187 | The MIME type associated with the printer (e.g. | |
188 | application/vnd.cups-postscript). | |
ef416fc2 | 189 | .TP 5 |
190 | LANG | |
191 | .br | |
192 | The default language locale (typically C or en). | |
193 | .TP 5 | |
194 | PATH | |
195 | .br | |
bd7854cb | 196 | The standard execution path for external programs that may be run by |
80ca4592 | 197 | the filter. |
ef416fc2 | 198 | .TP 5 |
199 | PPD | |
200 | .br | |
bd7854cb | 201 | The full pathname of the PostScript Printer Description (PPD) |
202 | file for this printer. | |
ef416fc2 | 203 | .TP 5 |
204 | PRINTER | |
205 | .br | |
bd7854cb | 206 | The name of the printer. |
ef416fc2 | 207 | .TP 5 |
208 | RIP_CACHE | |
209 | .br | |
bd7854cb | 210 | The recommended amount of memory to use for Raster Image |
211 | Processors (RIPs). | |
ef416fc2 | 212 | .TP 5 |
213 | SOFTWARE | |
214 | .br | |
bd7854cb | 215 | The name and version number of the server (typically CUPS/1.2). |
ef416fc2 | 216 | .TP 5 |
217 | TZ | |
218 | .br | |
219 | The timezone of the server. | |
220 | .TP 5 | |
221 | USER | |
222 | .br | |
80ca4592 | 223 | The user executing the filter, typically "lp" or "root"; consult the |
bd7854cb | 224 | \fIcupsd.conf(5)\fR file for the current setting. |
ef416fc2 | 225 | .SH COMPATIBILITY |
226 | While the filter interface is compatible with System V interface | |
227 | scripts, it will only work with the System V interface script as the | |
228 | only filter. Typically the interface script will be provided via the | |
bd7854cb | 229 | \fIlpadmin(8)\fR command using the \fI-i\fR option. |
ef416fc2 | 230 | .SH SEE ALSO |
f3c17241 | 231 | \fIbackend(7)\fR, \fIcupsd(8)\fR, \fIcupsfilter(8)\fR, |
bd7854cb | 232 | .br |
233 | http://localhost:631/help | |
ef416fc2 | 234 | .SH COPYRIGHT |
0fa6c7fa | 235 | Copyright 2007-2013 by Apple Inc. |
ef416fc2 | 236 | .\" |
e4e5666b | 237 | .\" End of "$Id$". |
ef416fc2 | 238 | .\" |