1filter(7) OpenPrinting filter(7)
2
6 filter - cups file conversion filter interface
7
9 filter job user title num-copies options [ filename ]
10 #include <cups/cups.h>
12 ssize_t cupsBackChannelRead(char *buffer, size_t bytes,
14 double timeout);
15 cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
17 char *data, int *datalen,
18 double timeout);
19 #include <cups/ppd.h>
21 const char *cupsGetOption(const char *name, int num_options,
23 cups_option_t *options);
24 int cupsMarkOptions(ppd_file_t *ppd, int num_options,
26 cups_option_t *options);
27 int cupsParseOptions(const char *arg, int num_options,
29 cups_option_t **options);
30 ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
32 void ppdMarkDefaults(ppd_file_t *ppd);
34 ppd_file_t *ppdOpenFile(const char *filename);
36
38 The CUPS filter interface provides a standard method for adding support
39 for new document types or printers to CUPS. Each filter is capable of
40 converting from one or more input formats to another format that can
41 either be printed directly or piped into another filter to get it to a
42 printable format.
43 Filters MUST be capable of reading from a filename on the command-line
45 or from the standard input, copying the standard input to a temporary
46 file as required by the file format. All output MUST be sent to the
47 standard output. Filters MUST NOT attempt to communicate directly with
48 the printer, other processes, or other services.
49 The command name (argv[0]) is set to the name of the destination
51 printer but is also available in the PRINTER environment variable.
52
54 Options are passed in argv[5] and are encoded from the corresponding
55 IPP attributes used when the job was submitted. Use the cupsParseOp‐
56 tions() function to load the options into a cups_option_t array and the
57 cupsGetOption() function to get the value of a specific attribute. Be
58 careful to look for common aliases of IPP attributes such as "land‐
59 scape" for the IPP "orientation-requested" attribute.
60 Options passed on the command-line typically do not include the default
62 choices the printer's PPD file. Use the ppdMarkDefaults() and cups‐
63 MarkOptions() functions in the CUPS library to apply the options to the
64 PPD defaults and map any IPP attributes to the corresponding PPD op‐
65 tions. Use ppdFindMarkedChoice() to get the user-selected choice for a
66 PPD option. For example, a filter might use the following code to de‐
67 termine the current value of the Duplex PPD option:
68 ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
70 cups_option_t *options = NULL;
71 int num_options = cupsParseOptions(argv[5], 0, &options);
72 ppdMarkDefaults(ppd);
74 cupsMarkOptions(ppd, num_options, options);
75 ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex");
77 Raster filters should use option choices set through the raster page
79 header, as those reflect the options in effect for a given page. Op‐
80 tions specified on the command-line determine the default values for
81 the entire job, which can be overridden on a per-page basis.
82
84 Messages sent to the standard error are generally stored in the
85 printer's "printer-state-message" attribute and the current ErrorLog
86 file. Each line begins with a standard prefix:
87 ALERT: message
89 Sets the "printer-state-message" attribute and adds the specified
90 message to the current ErrorLog using the "alert" log level.
91 ATTR: attribute=value [ ... attribute=value]
93 Sets the named job or printer attribute(s). The following job at‐
94 tributes can be set: "job-media-progress". The following printer
95 attributes can be set: "auth-info-required", "marker-colors",
96 "marker-high-levels", "marker-levels", "marker-low-levels",
97 "marker-message", "marker-names", "marker-types", "printer-alert",
98 and "printer-alert-description".
99 CRIT: message
101 Sets the "printer-state-message" attribute and adds the specified
102 message to the current ErrorLog using the "critical" log level.
103 DEBUG: message
105 Adds the specified message to the current ErrorLog using the "de‐
106 bug" log level. DEBUG messages are never stored in the "printer-
107 state-message" attribute.
108 DEBUG2: message
110 Adds the specified message to the current ErrorLog using the "de‐
111 bug2" log level. DEBUG2 messages are never stored in the
112 "printer-state-message" attribute.
113 EMERG: message
115 Sets the "printer-state-message" attribute and adds the specified
116 message to the current ErrorLog using the "emergency" log level.
117 ERROR: message
119 Sets the "printer-state-message" attribute and adds the specified
120 message to the current ErrorLog using the "error" log level.
121 INFO: message
123 Sets the "printer-state-message" attribute. If the current
124 LogLevel is set to "debug2", also adds the specified message to
125 the current ErrorLog using the "info" log level.
126 NOTICE: message
128 Sets the "printer-state-message" attribute and adds the specified
129 message to the current ErrorLog using the "notice" log level.
130 PAGE: page-number #-copies
132 PAGE: total #-pages
134 Adds an entry to the current PageLog. The first form adds #-copies
135 to the "job-media-sheets-completed" attribute. The second form
136 sets the "job-media-sheets-completed" attribute to #-pages.
137 PPD: Keyword=Value [ ... KeywordN=Value ]
139 Sets the named keywords in the printer's PPD file. This is typi‐
140 cally used to update default option keywords such as DefaultPage‐
141 Size and the various installable options in the PPD file.
142 STATE: printer-state-reason [ ... printer-state-reason ]
144 STATE: + printer-state-reason [ ... printer-state-reason ]
146 STATE: - printer-state-reason [ ... printer-state-reason ]
148 Sets, adds, or removes "printer-state-reason" keywords for the
149 current queue. Typically this is used to indicate media, ink, and
150 toner conditions on a printer.
151 WARNING: message
153 Sets the "printer-state-message" attribute and adds the specified
154 message to the current ErrorLog using the "warning" log level.
155
157 The following environment variables are defined by the CUPS server when
158 executing the filter:
159 CHARSET
161 The default text character set, typically "utf-8".
162 CLASS
164 When a job is submitted to a printer class, contains the name of
165 the destination printer class. Otherwise this environment variable
166 will not be set.
167 CONTENT_TYPE
169 The MIME media type associated with the submitted job file, for
170 example "application/postscript".
171 CUPS_CACHEDIR
173 The directory where semi-persistent cache files can be found and
174 stored.
175 CUPS_DATADIR
177 The directory where data files can be found.
178 CUPS_FILETYPE
180 The type of file being printed: "job-sheet" for a banner page and
181 "document" for a regular print file.
182 CUPS_MAX_MESSAGE
184 The maximum size of a message sent to stderr, including any lead‐
185 ing prefix and the trailing newline.
186 CUPS_SERVERROOT
188 The root directory of the server.
189 FINAL_CONTENT_TYPE
191 The MIME media type associated with the output destined for the
192 printer, for example "application/vnd.cups-postscript".
193 LANG The default language locale (typically C or en).
195 PATH The standard execution path for external programs that may be run
197 by the filter.
198 PPD The full pathname of the PostScript Printer Description (PPD) file
200 for this printer.
201 PRINTER
203 The name of the printer.
204 RIP_CACHE
206 The recommended amount of memory to use for Raster Image Proces‐
207 sors (RIPs).
208 SOFTWARE
210 The name and version number of the server (typically CUPS/ma‐
211 jor.minor).
212 TZ The timezone of the server.
214 USER The user executing the filter, typically "lp" or "root"; consult
216 the cups-files.conf file for the current setting.
217
219 While the filter interface is compatible with System V interface
220 scripts, CUPS does not support System V interface scripts.
221
223 CUPS printer drivers and backends are deprecated and will no longer be
224 supported in a future feature release of CUPS. Printers that do not
225 support IPP can be supported using applications such as
226 ippeveprinter(1).
227 CUPS filters are not meant to be run directly by the user. Aside from
229 the legacy System V interface issues (argv[0] is the printer name),
230 CUPS filters also expect specific environment variables and file de‐
231 scriptors, and typically run in a user session that (on macOS) has ad‐
232 ditional restrictions that affect how it runs. Unless you are a devel‐
233 oper and know what you are doing, please do not run filters directly.
234 Instead, use the cupsfilter(8) program to use the appropriate filters
235 to do the conversions you need.
236
238 backend(7), cups(1), cups-files.conf(5), cupsd(8), cupsfilter(8),
239 CUPS Online Help (http://localhost:631/help)
240
242 Copyright © 2021-2022 by OpenPrinting.
2432021-02-28 CUPS filter(7)