1filter(7)                        OpenPrinting                        filter(7)
2
3
4

NAME

6       filter - cups file conversion filter interface
7

SYNOPSIS

9       filter job user title num-copies options [ filename ]
10
11       #include <cups/cups.h>
12
13       ssize_t cupsBackChannelRead(char *buffer, size_t bytes,
14                                   double timeout);
15
16       cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
17                                                 char *data, int *datalen,
18                                                 double timeout);
19
20       #include <cups/ppd.h>
21
22       const char *cupsGetOption(const char *name, int num_options,
23                        cups_option_t *options);
24
25       int cupsMarkOptions(ppd_file_t *ppd, int num_options,
26                           cups_option_t *options);
27
28       int cupsParseOptions(const char *arg, int num_options,
29                            cups_option_t **options);
30
31       ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
32
33       void ppdMarkDefaults(ppd_file_t *ppd);
34
35       ppd_file_t *ppdOpenFile(const char *filename);
36

DESCRIPTION

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
44       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
50       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

OPTIONS

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
61       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
69           ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
70           cups_option_t *options = NULL;
71           int num_options = cupsParseOptions(argv[5], 0, &options);
72
73           ppdMarkDefaults(ppd);
74           cupsMarkOptions(ppd, num_options, options);
75
76           ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex");
77
78       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

LOG MESSAGES

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
88       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
92       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
100       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
104       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
109       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
114       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
118       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
122       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
127       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
131       PAGE: page-number #-copies
132
133       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
138       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
143       STATE: printer-state-reason [ ... printer-state-reason ]
144
145       STATE: + printer-state-reason [ ... printer-state-reason ]
146
147       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
152       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

ENVIRONMENT VARIABLES

157       The following environment variables are defined by the CUPS server when
158       executing the filter:
159
160       CHARSET
161            The default text character set, typically "utf-8".
162
163       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
168       CONTENT_TYPE
169            The MIME media type associated with the submitted  job  file,  for
170            example "application/postscript".
171
172       CUPS_CACHEDIR
173            The  directory  where semi-persistent cache files can be found and
174            stored.
175
176       CUPS_DATADIR
177            The directory where data files can be found.
178
179       CUPS_FILETYPE
180            The type of file being printed: "job-sheet" for a banner page  and
181            "document" for a regular print file.
182
183       CUPS_MAX_MESSAGE
184            The  maximum size of a message sent to stderr, including any lead‐
185            ing prefix and the trailing newline.
186
187       CUPS_SERVERROOT
188            The root directory of the server.
189
190       FINAL_CONTENT_TYPE
191            The MIME media type associated with the output  destined  for  the
192            printer, for example "application/vnd.cups-postscript".
193
194       LANG The default language locale (typically C or en).
195
196       PATH The  standard execution path for external programs that may be run
197            by the filter.
198
199       PPD  The full pathname of the PostScript Printer Description (PPD) file
200            for this printer.
201
202       PRINTER
203            The name of the printer.
204
205       RIP_CACHE
206            The  recommended  amount of memory to use for Raster Image Proces‐
207            sors (RIPs).
208
209       SOFTWARE
210            The name and version number  of  the  server  (typically  CUPS/ma‐
211            jor.minor).
212
213       TZ   The timezone of the server.
214
215       USER The  user  executing the filter, typically "lp" or "root"; consult
216            the cups-files.conf file for the current setting.
217

CONFORMING TO

219       While the filter  interface  is  compatible  with  System  V  interface
220       scripts, CUPS does not support System V interface scripts.
221

NOTES

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
228       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

SEE ALSO

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-2023 by OpenPrinting.
243
244
245
2462021-02-28                           CUPS                            filter(7)
Impressum