1filter(7) Apple Inc. filter(7)
2
6 filter - cups file conversion filter interface
7
9 filter job user title num-copies options [ filename ]
10
12 The CUPS filter interface provides a standard method for adding support
13 for new document types to CUPS. Each filter is capable of converting
14 from one or more input formats to another format that can either be
15 printed directly or piped into another filter to get it to a printable
16 format.
17 Filters must be capable of reading from a filename on the command-line
19 or from the standard input, copying the standard input to a temporary
20 file as required by the file format. All output must be sent to the
21 standard output.
22 The command name (argv[0]) is set to the name of the destination
24 printer but is also available in the PRINTER environment variable.
25
27 CUPS filters are not meant to be run directly by the user. Aside from
28 the legacy System V interface issues (argv[0] is the printer name),
29 CUPS filters also expect specific environment variables and file
30 descriptors, and typically run in a user session that (on OS X) has
31 additional restrictions that affect how it runs. Unless you are a
32 developer and know what you are doing, please do not run filters
33 directly. Instead, use the cupsfilter(8) program to use the appropriate
34 filters to do the conversions you need.
35
37 Options passed on the command-line typically do not include the default
38 choices the printer's PPD file. In addition, some options may be speci‐
39 fied in multiple ways - "landscape" is a synonym for "orientation-
40 requested=4", "media" is a synonym for "PageSize", "PageRegion",
41 "InputSlot", and "MediaType", and "sides" is a synonym for the various
42 "Duplex" options. Non-raster filters must support both explicit and
43 implicit specification of PPD options - use the ppdMarkDefaults and
44 cupsMarkOptions functions in the CUPS library to use the correct map‐
45 ping, and ppdFindMarkedChoice to get the user-selected choice.
46 Raster filters should use option choices set through the raster page
48 header, as those reflect the options in effect for a given page.
49 Options specified on the command-line determine the default values for
50 the entire job, which can be overridden on a per-page basis.
51
53 Messages sent to stderr are generally logged to printer-state-message
54 attribute and the current ErrorLog. Each line begins with a standard
55 prefix:
56 ALERT: message
58 Sets the printer-state-message attribute and adds the specified
59 message to the current ErrorLog using the "alert" log level.
60 ATTR: attribute=value [attribute=value]
62 Sets the named job or printer attribute(s). The following job
63 attributes can be set: "job-media-progress". The following printer
64 attributes can be set: "auth-info-required", "marker-colors",
65 "marker-high-levels", "marker-levels", "marker-low-levels",
66 "marker-message", "marker-names", "marker-types", "printer-alert",
67 and "printer-alert-description".
68 CRIT: message
70 Sets the printer-state-message attribute and adds the specified
71 message to the current ErrorLog using the "critical" log level.
72 DEBUG: message
74 Sets the printer-state-message attribute and adds the specified
75 message to the current ErrorLog using the "debug" log level.
76 DEBUG2: message
78 Sets the printer-state-message attribute and adds the specified
79 message to the current ErrorLog using the "debug2" log level.
80 EMERG: message
82 Sets the printer-state-message attribute and adds the specified
83 message to the current ErrorLog using the "emergency" log level.
84 ERROR: message
86 Sets the printer-state-message attribute and adds the specified
87 message to the current ErrorLog using the "error" log level.
88 INFO: message
90 Sets the printer-state-message attribute. If the current LogLevel
91 is set to "debug2", also adds the specified message to the current
92 ErrorLog using the "info" log level.
93 NOTICE: message
95 Sets the printer-state-message attribute and adds the specified
96 message to the current ErrorLog using the "notice" log level.
97 PAGE: page-number #-copies
99 PAGE: total #-pages
101 Adds an entry to the current PageLog. The first form adds #-copies
102 to the job-media-sheets-completed attribute. The second form sets
103 the job-media-sheets-completed attribute to #-pages.
104 PPD: Keyword=Value ... KeywordN=Value
106 Sets the named keywords in the printer's PPD file. This is typi‐
107 cally used to update default option keywords such as DefaultPage‐
108 Size and the various installable options in the PPD file.
109 STATE: printer-state-reason [printer-state-reason ...]
111 STATE: + printer-state-reason [printer-state-reason ...]
113 STATE: - printer-state-reason [printer-state-reason ...]
115 Sets, adds, or removes printer-state-reason keywords to the cur‐
116 rent queue. Typically this is used to indicate media, ink, and
117 toner conditions on a printer.
118 WARNING: message
120 Sets the printer-state-message attribute and adds the specified
121 message to the current ErrorLog using the "warning" log level.
122
124 The following environment variables are defined by the CUPS server when
125 executing the filter:
126 CHARSET
128 The default text character set, typically utf-8.
129 CLASS
131 When a job is submitted to a printer class, contains the name of
132 the destination printer class. Otherwise this environment variable
133 will not be set.
134 CONTENT_TYPE
136 The MIME type associated with the file (e.g. application/post‐
137 script).
138 CUPS_CACHEDIR
140 The directory for semi-persistent cache files can be found.
141 CUPS_DATADIR
143 The directory where data files can be found.
144 CUPS_FILETYPE
146 The type of file being printed: "job-sheet" for a banner page and
147 "document" for a regular print file.
148 CUPS_MAX_MESSAGE
150 The maximum size of a message sent to stderr, including any lead‐
151 ing prefix and the trailing newline.
152 CUPS_SERVERROOT
154 The root directory of the server.
155 DEVICE_URI
157 The device-uri associated with the printer.
158 FINAL_CONTENT_TYPE
160 The MIME type associated with the printer (e.g. applica‐
161 tion/vnd.cups-postscript).
162 LANG
164 The default language locale (typically C or en).
165 PATH
167 The standard execution path for external programs that may be run
168 by the filter.
169 PPD
171 The full pathname of the PostScript Printer Description (PPD) file
172 for this printer.
173 PRINTER
175 The name of the printer.
176 RIP_CACHE
178 The recommended amount of memory to use for Raster Image Proces‐
179 sors (RIPs).
180 SOFTWARE
182 The name and version number of the server (typically CUPS/1.2).
183 TZ
185 The timezone of the server.
186 USER
188 The user executing the filter, typically "lp" or "root"; consult
189 the cupsd.conf(5) file for the current setting.
190
192 While the filter interface is compatible with System V interface
193 scripts, it will only work with the System V interface script as the
194 only filter. Typically the interface script will be provided via the
195 lpadmin(8) command using the -i option.
196
198 backend(7), cupsd(8), cupsfilter(8),
199 http://localhost:631/help
200
202 Copyright 2007-2013 by Apple Inc.
20318 May 2012 CUPS filter(7)