filter(7)

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

DESCRIPTION

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
18       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
23       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
26

OPTIONS

28       Options passed on the command-line typically do not include the default
29       choices the printer's PPD file. In addition, some options may be speci‐
30       fied  in  multiple  ways  -  "landscape" is a synonym for "orientation-
31       requested=4",  "media"  is  a  synonym  for  "PageSize",  "PageRegion",
32       "InputSlot",  and "MediaType", and "sides" is a synonym for the various
33       "Duplex" options. Non-raster filters must  support  both  explicit  and
34       implicit  specification  of  PPD  options - use the ppdMarkDefaults and
35       cupsMarkOptions functions in the CUPS library to use the  correct  map‐
36       ping, and ppdFindMarkedChoice to get the user-selected choice.
37
38       Raster  filters  should  use option choices set through the raster page
39       header, as those reflect the  options  in  effect  for  a  given  page.
40       Options  specified on the command-line determine the default values for
41       the entire job, which can be overridden on a per-page basis.
42
43

LOG MESSAGES

45       Messages sent to stderr are generally logged  to  printer-state-message
46       attribute  and  the current ErrorLog.  Each line begins with a standard
47       prefix:
48
49
50       ALERT: message
51            Sets the printer-state-message attribute and  adds  the  specified
52            message to the current ErrorLog using the "alert" log level.
53
54
55       ATTR: attribute=value [attribute=value]
56            Sets  the  named  job attribute(s). Typically this will be used to
57            set the job-remote-id attribute.
58
59
60       CRIT: message
61            Sets the printer-state-message attribute and  adds  the  specified
62            message to the current ErrorLog using the "critical" log level.
63
64
65       DEBUG: message
66            Sets  the  printer-state-message  attribute and adds the specified
67            message to the current ErrorLog using the "debug" log level.
68
69
70       DEBUG2: message
71            Sets the printer-state-message attribute and  adds  the  specified
72            message to the current ErrorLog using the "debug2" log level.
73
74
75       EMERG: message
76            Sets  the  printer-state-message  attribute and adds the specified
77            message to the current ErrorLog using the "emergency" log level.
78
79
80       ERROR: message
81            Sets the printer-state-message attribute and  adds  the  specified
82            message to the current ErrorLog using the "error" log level.
83
84
85       INFO: message
86            Sets  the printer-state-message attribute. If the current LogLevel
87            is set to "debug2", also adds the specified message to the current
88            ErrorLog using the "info" log level.
89
90
91       NOTICE: message
92            Sets  the  printer-state-message  attribute and adds the specified
93            message to the current ErrorLog using the "notice" log level.
94
95
96       PAGE: page-number #-copies
97
98       PAGE: total #-pages
99            Adds an entry to the current PageLog. The first form adds #-copies
100            to  the job-media-sheets-completed attribute. The second form sets
101            the job-media-sheets-completed attribute to #-pages.
102
103
104       PPD: Keyword=Value ... KeywordN=Value
105            Sets the named keywords in the printer's PPD file. This  is  typi‐
106            cally  used to update default option keywords such as DefaultPage‐
107            Size and the various installable options in the PPD file.
108
109
110       STATE: printer-state-reason [printer-state-reason ...]
111
112       STATE: + printer-state-reason [printer-state-reason ...]
113
114       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
119
120       WARNING: message
121            Sets the printer-state-message attribute and  adds  the  specified
122            message to the current ErrorLog using the "warning" log level.
123
124

ENVIRONMENT VARIABLES

126       The following environment variables are defined by the CUPS server when
127       executing the filter:
128
129
130       CHARSET
131            The default text character set, typically utf-8.
132
133
134       CLASS
135            When a job is submitted to a printer class, contains the  name  of
136            the destination printer class. Otherwise this environment variable
137            will not be set.
138
139
140       CONTENT_TYPE
141            The MIME type associated with the  file  (e.g.   application/post‐
142            script).
143
144
145       CUPS_CACHEDIR
146            The directory for semi-persistent cache files can be found.
147
148
149       CUPS_DATADIR
150            The directory where data files can be found.
151
152
153       CUPS_FILETYPE
154            The  type of file being printed: "job-sheet" for a banner page and
155            "document" for a regular print file.
156
157
158       CUPS_SERVERROOT
159            The root directory of the server.
160
161
162       DEVICE_URI
163            The device-uri associated with the printer.
164
165
166       FINAL_CONTENT_TYPE
167            The  MIME  type  associated  with  the  printer  (e.g.    applica‐
168            tion/vnd.cups-postscript).
169
170
171       LANG
172            The default language locale (typically C or en).
173
174
175       PATH
176            The  standard execution path for external programs that may be run
177            by the filter.
178
179
180       PPD
181            The full pathname of the PostScript Printer Description (PPD) file
182            for this printer.
183
184
185       PRINTER
186            The name of the printer.
187
188
189       RIP_CACHE
190            The  recommended  amount of memory to use for Raster Image Proces‐
191            sors (RIPs).
192
193
194       SOFTWARE
195            The name and version number of the server (typically CUPS/1.2).
196
197
198       TZ
199            The timezone of the server.
200
201
202       USER
203            The user executing the filter, typically "lp" or  "root";  consult
204            the cupsd.conf(5) file for the current setting.
205
206

COMPATIBILITY

208       While  the  filter  interface  is  compatible  with  System V interface
209       scripts, it will only work with the System V interface  script  as  the
210       only  filter.   Typically the interface script will be provided via the
211       lpadmin(8) command using the -i option.
212

COPYRIGHT

218       Copyright 2007-2009 by Apple Inc.
219
220
221
22213 May 2009                          CUPS                            filter(7)