1filter(7)                         Apple Inc.                         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
65       options.  Use ppdFindMarkedChoice() to get the user-selected choice for
66       a PPD option. For example, a filter might use  the  following  code  to
67       determine 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.
80       Options  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
94            attributes 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
106            "debug" log  level.   DEBUG  messages  are  never  stored  in  the
107            "printer-state-message" attribute.
108
109       DEBUG2: message
110            Adds  the  specified  message  to  the  current ErrorLog using the
111            "debug2" 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
211            CUPS/major.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  filters are not meant to be run directly by the user.  Aside from
224       the legacy System V interface issues (argv[0]  is  the  printer  name),
225       CUPS  filters  also  expect  specific  environment  variables  and file
226       descriptors, and typically run in a user session that  (on  macOS)  has
227       additional  restrictions  that  affect  how  it runs.  Unless you are a
228       developer and know what you  are  doing,  please  do  not  run  filters
229       directly.   Instead, use the cupsfilter(8) program to use the appropri‐
230       ate filters to do the conversions you need.
231

SEE ALSO

233       backend(7), cups(1), cups-files.conf(5), cupsd(8), cupsfilter(8),
234       CUPS Online Help (http://localhost:631/help)
235
237       Copyright © 2007-2017 by Apple Inc.
238
239
240
24119 October 2015                      CUPS                            filter(7)
Impressum