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