]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
bfbd0197 | 2 | .\" filter man page for CUPS. |
ef416fc2 | 3 | .\" |
dd3fdd2c | 4 | .\" Copyright 2007-2015 by Apple Inc. |
bfbd0197 | 5 | .\" Copyright 1997-2007 by Easy Software Products. |
ef416fc2 | 6 | .\" |
bfbd0197 MS |
7 | .\" These coded instructions, statements, and computer programs are the |
8 | .\" property of Apple Inc. and are protected by Federal copyright | |
9 | .\" law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
10 | .\" which should have been included with this file. If this file is | |
11 | .\" file is missing or damaged, see the license at "http://www.cups.org/". | |
ef416fc2 | 12 | .\" |
e67e2f9e | 13 | .TH filter 7 "CUPS" "19 October 2015" "Apple Inc." |
ef416fc2 | 14 | .SH NAME |
bd7854cb | 15 | filter \- cups file conversion filter interface |
ef416fc2 | 16 | .SH SYNOPSIS |
17 | .B filter | |
bfbd0197 MS |
18 | .I job |
19 | .I user | |
20 | .I title | |
21 | .I num-copies | |
22 | .I options | |
23 | [ | |
ef416fc2 | 24 | .I filename |
25 | ] | |
bfbd0197 MS |
26 | .nf |
27 | ||
28 | \fB#include <cups/cups.h>\fR | |
29 | ||
30 | \fBssize_t cupsBackChannelRead\fR(\fBchar *\fIbuffer\fR, \fBsize_t \fIbytes\fR, | |
31 | \fBdouble \fItimeout\fR); | |
32 | ||
33 | \fBcups_sc_status_t cupsSideChannelDoRequest\fR(\fBcups_sc_command_t \fIcommand\fR, | |
34 | \fBchar *\fIdata\fR, \fBint *\fIdatalen\fR, | |
35 | \fBdouble \fItimeout\fR); | |
36 | ||
37 | \fB#include <cups/ppd.h>\fR | |
38 | ||
39 | \fBconst char *cupsGetOption\fR(\fBconst char *\fIname\fR, \fBint \fInum_options\fR, | |
40 | \fBcups_option_t *\fIoptions\fR); | |
41 | ||
42 | \fBint cupsMarkOptions\fR(\fBppd_file_t *\fIppd\fR, \fBint \fInum_options\fR, | |
43 | \fBcups_option_t *\fIoptions\fR); | |
44 | ||
45 | \fBint cupsParseOptions\fR(\fBconst char *\fIarg\fR, \fBint \fInum_options\fR, | |
46 | \fBcups_option_t **\fIoptions\fR); | |
47 | ||
48 | \fBppd_choice_t *ppdFindMarkedChoice\fR(\fBppd_file_t *\fIppd\fR, \fBconst char *\fIkeyword\fR); | |
49 | ||
50 | \fBvoid ppdMarkDefaults\fR(\fBppd_file_t *\fIppd\fR); | |
51 | ||
52 | \fBppd_file_t *ppdOpenFile\fR(\fBconst char *\fIfilename\fR); | |
53 | .fi | |
ef416fc2 | 54 | .SH DESCRIPTION |
bfbd0197 MS |
55 | The CUPS filter interface provides a standard method for adding support for new document types or printers to CUPS. |
56 | Each filter is capable of converting from one or more input formats to another format that can either be printed directly or piped into another filter to get it to a printable format. | |
ef416fc2 | 57 | .LP |
bfbd0197 MS |
58 | Filters \fBMUST\fR be capable of reading from a filename on the command-line or from the standard input, copying the standard input to a temporary file as required by the file format. |
59 | All output \fBMUST\fR be sent to the standard output. | |
60 | Filters \fBMUST NOT\fR attempt to communicate directly with the printer, other processes, or other services. | |
ef416fc2 | 61 | .LP |
bfbd0197 | 62 | The command name (\fIargv[0]\fR) is set to the name of the destination printer but is also available in the \fBPRINTER\fI environment variable. |
178cb736 | 63 | .SH OPTIONS |
bfbd0197 MS |
64 | Options are passed in \fIargv[5]\fR and are encoded from the corresponding IPP attributes used when the job was submitted. Use the |
65 | .BR cupsParseOptions () | |
66 | function to load the options into a \fBcups_option_t\fR array and the | |
67 | .BR cupsGetOption () | |
68 | function to get the value of a specific attribute. | |
dd3fdd2c | 69 | Be careful to look for common aliases of IPP attributes such as "landscape" for the IPP "orientation-requested" attribute. |
178cb736 | 70 | .LP |
bfbd0197 MS |
71 | Options passed on the command-line typically do not include the default choices the printer's PPD file. Use the |
72 | .BR ppdMarkDefaults () | |
73 | and | |
74 | .BR cupsMarkOptions () | |
75 | functions in the CUPS library to apply the options to the PPD defaults and map any IPP attributes to the corresponding PPD options. | |
76 | Use | |
77 | .BR ppdFindMarkedChoice () | |
78 | to get the user-selected choice for a PPD option. For example, a filter might use the following code to determine the current value of the \fBDuplex\fR PPD option: | |
79 | .nf | |
80 | ||
81 | ppd_file_t *ppd = ppdOpenFile(getenv("PPD")); | |
82 | cups_option_t *options = NULL; | |
83 | int num_options = cupsParseOptions(argv[5], 0, &options); | |
84 | ||
85 | ppdMarkDefaults(ppd); | |
86 | cupsMarkOptions(ppd, num_options, options); | |
87 | ||
88 | ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex"); | |
89 | .fi | |
90 | .LP | |
91 | Raster filters should use option choices set through the raster page header, as those reflect the options in effect for a given page. | |
92 | Options specified on the command-line determine the default values for the entire job, which can be overridden on a per-page basis. | |
bd7854cb | 93 | .SH LOG MESSAGES |
bfbd0197 | 94 | Messages sent to the standard error are generally stored in the printer's "printer-state-message" attribute and the current \fBErrorLog\fR file. |
bd7854cb | 95 | Each line begins with a standard prefix: |
bd7854cb | 96 | .TP 5 |
bfbd0197 MS |
97 | \fBALERT: \fImessage\fR |
98 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "alert" log level. | |
bd7854cb | 99 | .TP 5 |
bfbd0197 MS |
100 | \fBATTR: \fIattribute=value \fR[ \fI... attribute=value\fR] |
101 | Sets the named job or printer attribute(s). The following job attributes can be set: "job-media-progress". The following printer attributes can be set: | |
f3c17241 MS |
102 | "auth-info-required", "marker-colors", "marker-high-levels", "marker-levels", |
103 | "marker-low-levels", "marker-message", "marker-names", "marker-types", | |
104 | "printer-alert", and "printer-alert-description". | |
bd7854cb | 105 | .TP 5 |
bfbd0197 MS |
106 | \fBCRIT: \fImessage\fR |
107 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "critical" log level. | |
bd7854cb | 108 | .TP 5 |
bfbd0197 MS |
109 | \fBDEBUG: \fImessage\fR |
110 | Adds the specified message to the current \fBErrorLog\fR using the "debug" log level. | |
111 | \fBDEBUG\fR messages are never stored in the "printer-state-message" attribute. | |
bd7854cb | 112 | .TP 5 |
bfbd0197 | 113 | \fBDEBUG2: \fImessage\fR |
bd7854cb | 114 | .br |
bfbd0197 MS |
115 | Adds the specified message to the current \fBErrorLog\fR using the "debug2" log level. |
116 | \fBDEBUG2\fR messages are never stored in the "printer-state-message" attribute. | |
bd7854cb | 117 | .TP 5 |
bfbd0197 MS |
118 | \fBEMERG: \fImessage\fR |
119 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "emergency" log level. | |
bd7854cb | 120 | .TP 5 |
bfbd0197 MS |
121 | \fBERROR:\fI message\fR |
122 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "error" log level. | |
bd7854cb | 123 | .TP 5 |
bfbd0197 MS |
124 | \fBINFO:\fI message\fR |
125 | Sets the "printer-state-message" attribute. If the current \fBLogLevel\fR is set to "debug2", also adds the specified message to the current \fBErrorLog\fR using the "info" log level. | |
bd7854cb | 126 | .TP 5 |
bfbd0197 MS |
127 | \fBNOTICE:\fI message\fR |
128 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "notice" log level. | |
bd7854cb | 129 | .TP 5 |
bfbd0197 | 130 | \fBPAGE:\fI page-number #-copies\fR |
bd7854cb | 131 | .TP 5 |
bfbd0197 MS |
132 | \fBPAGE:\fI total #-pages\fR |
133 | Adds an entry to the current \fBPageLog\fR. The first form adds \fI#-copies\fR to the "job-media-sheets-completed" attribute. The second form sets the "job-media-sheets-completed" attribute to \fI#-pages\fR. | |
c9fc04c6 | 134 | .TP 5 |
bfbd0197 MS |
135 | \fBPPD:\fI Keyword=Value\fR [ \fI... KeywordN=Value\fR ] |
136 | Sets the named keywords in the printer's PPD file. This is typically used to update default option keywords such as \fBDefaultPageSize\fR and the various installable options in the PPD file. | |
bd7854cb | 137 | .TP 5 |
bfbd0197 | 138 | \fBSTATE:\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ] |
bd7854cb | 139 | .TP 5 |
bfbd0197 | 140 | \fBSTATE: +\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ] |
bd7854cb | 141 | .TP 5 |
bfbd0197 MS |
142 | \fBSTATE: -\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ] |
143 | Sets, adds, or removes "printer-state-reason" keywords for the current queue. Typically this is used to indicate media, ink, and toner conditions on a printer. | |
bd7854cb | 144 | .TP 5 |
bfbd0197 MS |
145 | \fBWARNING:\fI message\fR |
146 | Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "warning" log level. | |
ef416fc2 | 147 | .SH ENVIRONMENT VARIABLES |
bd7854cb | 148 | The following environment variables are defined by the CUPS |
80ca4592 | 149 | server when executing the filter: |
ef416fc2 | 150 | .TP 5 |
bfbd0197 MS |
151 | .B CHARSET |
152 | The default text character set, typically "utf-8". | |
ef416fc2 | 153 | .TP 5 |
bfbd0197 MS |
154 | .B CLASS |
155 | When a job is submitted to a printer class, contains the name of the destination printer class. Otherwise this environment variable will not be set. | |
ef416fc2 | 156 | .TP 5 |
bfbd0197 MS |
157 | .B CONTENT_TYPE |
158 | The MIME media type associated with the submitted job file, for example "application/postscript". | |
0af14961 | 159 | .TP 5 |
bfbd0197 MS |
160 | .B CUPS_CACHEDIR |
161 | The directory where semi-persistent cache files can be found and stored. | |
ef416fc2 | 162 | .TP 5 |
bfbd0197 | 163 | .B CUPS_DATADIR |
ef416fc2 | 164 | The directory where data files can be found. |
0af14961 | 165 | .TP 5 |
bfbd0197 | 166 | .B CUPS_FILETYPE |
0af14961 MS |
167 | The type of file being printed: "job-sheet" for a banner page and "document" |
168 | for a regular print file. | |
ef416fc2 | 169 | .TP 5 |
bfbd0197 MS |
170 | .B CUPS_MAX_MESSAGE |
171 | The maximum size of a message sent to \fIstderr\fR, including any leading prefix and the trailing newline. | |
a29fd7dd | 172 | .TP 5 |
bfbd0197 | 173 | .B CUPS_SERVERROOT |
ef416fc2 | 174 | The root directory of the server. |
175 | .TP 5 | |
bfbd0197 MS |
176 | .B FINAL_CONTENT_TYPE |
177 | The MIME media type associated with the output destined for the printer, for example "application/vnd.cups-postscript". | |
ef416fc2 | 178 | .TP 5 |
bfbd0197 | 179 | .B LANG |
ef416fc2 | 180 | The default language locale (typically C or en). |
181 | .TP 5 | |
bfbd0197 MS |
182 | .B PATH |
183 | The standard execution path for external programs that may be run by the filter. | |
ef416fc2 | 184 | .TP 5 |
bfbd0197 MS |
185 | .B PPD |
186 | The full pathname of the PostScript Printer Description (PPD) file for this printer. | |
ef416fc2 | 187 | .TP 5 |
bfbd0197 | 188 | .B PRINTER |
bd7854cb | 189 | The name of the printer. |
ef416fc2 | 190 | .TP 5 |
bfbd0197 MS |
191 | .B RIP_CACHE |
192 | The recommended amount of memory to use for Raster Image Processors (RIPs). | |
ef416fc2 | 193 | .TP 5 |
bfbd0197 MS |
194 | .B SOFTWARE |
195 | The name and version number of the server (typically CUPS/\fImajor.minor\fR). | |
ef416fc2 | 196 | .TP 5 |
bfbd0197 | 197 | .B TZ |
ef416fc2 | 198 | The timezone of the server. |
199 | .TP 5 | |
bfbd0197 MS |
200 | .B USER |
201 | The user executing the filter, typically "lp" or "root"; consult the \fIcups-files.conf\fR file for the current setting. | |
202 | .SH CONFORMING TO | |
e67e2f9e | 203 | While the filter interface is compatible with System V interface scripts, CUPS does not support System V interface scripts. |
bfbd0197 MS |
204 | .SH NOTES |
205 | CUPS filters are not meant to be run directly by the user. | |
8072030b | 206 | Aside from the legacy System V interface issues (\fIargv[0]\fR is the printer name), CUPS filters also expect specific environment variables and file descriptors, and typically run in a user session that (on macOS) has additional restrictions that affect how it runs. |
bfbd0197 MS |
207 | Unless you are a developer and know what you are doing, please do not run filters directly. |
208 | Instead, use the | |
209 | .BR cupsfilter (8) | |
210 | program to use the appropriate filters to do the conversions you need. | |
ef416fc2 | 211 | .SH SEE ALSO |
bfbd0197 MS |
212 | .BR backend (7), |
213 | .BR cups (1), | |
214 | .BR cups-files.conf (5), | |
215 | .BR cupsd (8), | |
216 | .BR cupsfilter (8), | |
bd7854cb | 217 | .br |
bfbd0197 | 218 | CUPS Online Help (http://localhost:631/help) |
ef416fc2 | 219 | .SH COPYRIGHT |
bd5a2f28 | 220 | Copyright \[co] 2007-2017 by Apple Inc. |