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