]>
Commit | Line | Data |
---|---|---|
c277f98c | 1 | <!DOCTYPE HTML> |
94436c5a MS |
2 | <html> |
3 | <!-- SECTION: Man Pages --> | |
4 | <head> | |
5 | <link rel="stylesheet" type="text/css" href="../cups-printable.css"> | |
6 | <title>filter(7)</title> | |
7 | </head> | |
8 | <body> | |
9 | <h1 class="title">filter(7)</h1> | |
10 | <h2 class="title"><a name="NAME">Name</a></h2> | |
11 | filter - cups file conversion filter interface | |
12 | <h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2> | |
c277f98c | 13 | <b>filter</b> |
bfbd0197 MS |
14 | <i>job</i> |
15 | <i>user</i> | |
16 | <i>title</i> | |
17 | <i>num-copies</i> | |
18 | <i>options</i> | |
19 | [ | |
c277f98c MS |
20 | <i>filename</i> |
21 | ] | |
2909c66c | 22 | <pre class="man"> |
bfbd0197 MS |
23 | |
24 | <b>#include <cups/cups.h></b> | |
25 | ||
26 | <b>ssize_t cupsBackChannelRead</b>(<b>char *</b><i>buffer</i>, <b>size_t </b><i>bytes</i>, | |
27 | <b>double </b><i>timeout</i>); | |
28 | ||
29 | <b>cups_sc_status_t cupsSideChannelDoRequest</b>(<b>cups_sc_command_t </b><i>command</i>, | |
30 | <b>char *</b><i>data</i>, <b>int *</b><i>datalen</i>, | |
31 | <b>double </b><i>timeout</i>); | |
32 | ||
33 | <b>#include <cups/ppd.h></b> | |
34 | ||
35 | <b>const char *cupsGetOption</b>(<b>const char *</b><i>name</i>, <b>int </b><i>num_options</i>, | |
36 | <b>cups_option_t *</b><i>options</i>); | |
37 | ||
38 | <b>int cupsMarkOptions</b>(<b>ppd_file_t *</b><i>ppd</i>, <b>int </b><i>num_options</i>, | |
39 | <b>cups_option_t *</b><i>options</i>); | |
40 | ||
41 | <b>int cupsParseOptions</b>(<b>const char *</b><i>arg</i>, <b>int </b><i>num_options</i>, | |
42 | <b>cups_option_t **</b><i>options</i>); | |
43 | ||
44 | <b>ppd_choice_t *ppdFindMarkedChoice</b>(<b>ppd_file_t *</b><i>ppd</i>, <b>const char *</b><i>keyword</i>); | |
45 | ||
46 | <b>void ppdMarkDefaults</b>(<b>ppd_file_t *</b><i>ppd</i>); | |
47 | ||
48 | <b>ppd_file_t *ppdOpenFile</b>(<b>const char *</b><i>filename</i>); | |
49 | </pre> | |
94436c5a | 50 | <h2 class="title"><a name="DESCRIPTION">Description</a></h2> |
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. | |
53 | <p>Filters <b>MUST</b> 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. | |
54 | All output <b>MUST</b> be sent to the standard output. | |
55 | Filters <b>MUST NOT</b> attempt to communicate directly with the printer, other processes, or other services. | |
56 | <p>The command name (<i>argv[0]</i>) is set to the name of the destination printer but is also available in the <b>PRINTER</b><i> environment variable. | |
57 | </i><h2 class="title"><a name="OPTIONS">Options</a></h2> | |
58 | Options are passed in <i>argv[5]</i> and are encoded from the corresponding IPP attributes used when the job was submitted. Use the | |
59 | <b>cupsParseOptions</b>() | |
60 | function to load the options into a <b>cups_option_t</b> array and the | |
61 | <b>cupsGetOption</b>() | |
62 | function to get the value of a specific attribute. | |
dd3fdd2c | 63 | Be careful to look for common aliases of IPP attributes such as "landscape" for the IPP "orientation-requested" attribute. |
bfbd0197 MS |
64 | <p>Options passed on the command-line typically do not include the default choices the printer's PPD file. Use the |
65 | <b>ppdMarkDefaults</b>() | |
66 | and | |
67 | <b>cupsMarkOptions</b>() | |
68 | functions in the CUPS library to apply the options to the PPD defaults and map any IPP attributes to the corresponding PPD options. | |
69 | Use | |
70 | <b>ppdFindMarkedChoice</b>() | |
71 | 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 <b>Duplex</b> PPD option: | |
2909c66c | 72 | <pre class="man"> |
bfbd0197 MS |
73 | |
74 | ppd_file_t *ppd = ppdOpenFile(getenv("PPD")); | |
75 | cups_option_t *options = NULL; | |
76 | int num_options = cupsParseOptions(argv[5], 0, &options); | |
77 | ||
78 | ppdMarkDefaults(ppd); | |
79 | cupsMarkOptions(ppd, num_options, options); | |
80 | ||
81 | ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex"); | |
82 | </pre> | |
83 | <p>Raster filters should use option choices set through the raster page header, as those reflect the options in effect for a given page. | |
84 | Options specified on the command-line determine the default values for the entire job, which can be overridden on a per-page basis. | |
94436c5a | 85 | <h2 class="title"><a name="LOG_MESSAGES">Log Messages</a></h2> |
bfbd0197 | 86 | Messages sent to the standard error are generally stored in the printer's "printer-state-message" attribute and the current <b>ErrorLog</b> file. |
94436c5a | 87 | Each line begins with a standard prefix: |
2909c66c MS |
88 | <dl class="man"> |
89 | <dt><b>ALERT: </b><i>message</i> | |
90 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "alert" log level. | |
91 | <dt><b>ATTR: </b><i>attribute=value </i>[ <i>... attribute=value</i>] | |
92 | <dd style="margin-left: 5.0em">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: | |
94436c5a MS |
93 | "auth-info-required", "marker-colors", "marker-high-levels", "marker-levels", |
94 | "marker-low-levels", "marker-message", "marker-names", "marker-types", | |
95 | "printer-alert", and "printer-alert-description". | |
2909c66c MS |
96 | <dt><b>CRIT: </b><i>message</i> |
97 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "critical" log level. | |
98 | <dt><b>DEBUG: </b><i>message</i> | |
99 | <dd style="margin-left: 5.0em">Adds the specified message to the current <b>ErrorLog</b> using the "debug" log level. | |
bfbd0197 | 100 | <b>DEBUG</b> messages are never stored in the "printer-state-message" attribute. |
2909c66c MS |
101 | <dt><b>DEBUG2: </b><i>message</i> |
102 | <dd style="margin-left: 5.0em"><br> | |
bfbd0197 MS |
103 | Adds the specified message to the current <b>ErrorLog</b> using the "debug2" log level. |
104 | <b>DEBUG2</b> messages are never stored in the "printer-state-message" attribute. | |
2909c66c MS |
105 | <dt><b>EMERG: </b><i>message</i> |
106 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "emergency" log level. | |
107 | <dt><b>ERROR:</b><i> message</i> | |
108 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "error" log level. | |
109 | <dt><b>INFO:</b><i> message</i> | |
110 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute. If the current <b>LogLevel</b> is set to "debug2", also adds the specified message to the current <b>ErrorLog</b> using the "info" log level. | |
111 | <dt><b>NOTICE:</b><i> message</i> | |
112 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "notice" log level. | |
113 | <dt><b>PAGE:</b><i> page-number #-copies</i> | |
114 | <dd style="margin-left: 5.0em"><dt><b>PAGE:</b><i> total #-pages</i> | |
115 | <dd style="margin-left: 5.0em">Adds an entry to the current <b>PageLog</b>. The first form adds <i>#-copies</i> to the "job-media-sheets-completed" attribute. The second form sets the "job-media-sheets-completed" attribute to <i>#-pages</i>. | |
116 | <dt><b>PPD:</b><i> Keyword=Value</i> [ <i>... KeywordN=Value</i> ] | |
117 | <dd style="margin-left: 5.0em">Sets the named keywords in the printer's PPD file. This is typically used to update default option keywords such as <b>DefaultPageSize</b> and the various installable options in the PPD file. | |
118 | <dt><b>STATE:</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ] | |
119 | <dd style="margin-left: 5.0em"><dt><b>STATE: +</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ] | |
120 | <dd style="margin-left: 5.0em"><dt><b>STATE: -</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ] | |
121 | <dd style="margin-left: 5.0em">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. | |
122 | <dt><b>WARNING:</b><i> message</i> | |
123 | <dd style="margin-left: 5.0em">Sets the "printer-state-message" attribute and adds the specified message to the current <b>ErrorLog</b> using the "warning" log level. | |
124 | </dl> | |
94436c5a MS |
125 | <h2 class="title"><a name="ENVIRONMENT_VARIABLES">Environment Variables</a></h2> |
126 | The following environment variables are defined by the CUPS | |
127 | server when executing the filter: | |
2909c66c MS |
128 | <dl class="man"> |
129 | <dt><b>CHARSET</b> | |
130 | <dd style="margin-left: 5.0em">The default text character set, typically "utf-8". | |
131 | <dt><b>CLASS</b> | |
132 | <dd style="margin-left: 5.0em">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. | |
133 | <dt><b>CONTENT_TYPE</b> | |
134 | <dd style="margin-left: 5.0em">The MIME media type associated with the submitted job file, for example "application/postscript". | |
135 | <dt><b>CUPS_CACHEDIR</b> | |
136 | <dd style="margin-left: 5.0em">The directory where semi-persistent cache files can be found and stored. | |
137 | <dt><b>CUPS_DATADIR</b> | |
138 | <dd style="margin-left: 5.0em">The directory where data files can be found. | |
139 | <dt><b>CUPS_FILETYPE</b> | |
140 | <dd style="margin-left: 5.0em">The type of file being printed: "job-sheet" for a banner page and "document" | |
bfbd0197 | 141 | for a regular print file. |
2909c66c MS |
142 | <dt><b>CUPS_MAX_MESSAGE</b> |
143 | <dd style="margin-left: 5.0em">The maximum size of a message sent to <i>stderr</i>, including any leading prefix and the trailing newline. | |
144 | <dt><b>CUPS_SERVERROOT</b> | |
145 | <dd style="margin-left: 5.0em">The root directory of the server. | |
146 | <dt><b>FINAL_CONTENT_TYPE</b> | |
147 | <dd style="margin-left: 5.0em">The MIME media type associated with the output destined for the printer, for example "application/vnd.cups-postscript". | |
148 | <dt><b>LANG</b> | |
149 | <dd style="margin-left: 5.0em">The default language locale (typically C or en). | |
150 | <dt><b>PATH</b> | |
151 | <dd style="margin-left: 5.0em">The standard execution path for external programs that may be run by the filter. | |
152 | <dt><b>PPD</b> | |
153 | <dd style="margin-left: 5.0em">The full pathname of the PostScript Printer Description (PPD) file for this printer. | |
154 | <dt><b>PRINTER</b> | |
155 | <dd style="margin-left: 5.0em">The name of the printer. | |
156 | <dt><b>RIP_CACHE</b> | |
157 | <dd style="margin-left: 5.0em">The recommended amount of memory to use for Raster Image Processors (RIPs). | |
158 | <dt><b>SOFTWARE</b> | |
159 | <dd style="margin-left: 5.0em">The name and version number of the server (typically CUPS/<i>major.minor</i>). | |
160 | <dt><b>TZ</b> | |
161 | <dd style="margin-left: 5.0em">The timezone of the server. | |
162 | <dt><b>USER</b> | |
163 | <dd style="margin-left: 5.0em">The user executing the filter, typically "lp" or "root"; consult the <i>cups-files.conf</i> file for the current setting. | |
164 | </dl> | |
bfbd0197 | 165 | <h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2> |
e67e2f9e | 166 | While the filter interface is compatible with System V interface scripts, CUPS does not support System V interface scripts. |
bfbd0197 MS |
167 | <h2 class="title"><a name="NOTES">Notes</a></h2> |
168 | CUPS filters are not meant to be run directly by the user. | |
169 | Aside from the legacy System V interface issues (<i>argv[0]</i> 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. | |
170 | Unless you are a developer and know what you are doing, please do not run filters directly. | |
171 | Instead, use the | |
172 | <a href="man-cupsfilter.html?TOPIC=Man+Pages"><b>cupsfilter</b>(8)</a> | |
173 | program to use the appropriate filters to do the conversions you need. | |
94436c5a | 174 | <h2 class="title"><a name="SEE_ALSO">See Also</a></h2> |
bfbd0197 MS |
175 | <a href="man-backend.html?TOPIC=Man+Pages"><b>backend</b>(7),</a> |
176 | <a href="man-cups.html?TOPIC=Man+Pages"><b>cups</b>(1),</a> | |
177 | <a href="man-cups-files.conf.html?TOPIC=Man+Pages"><b>cups-files.conf</b>(5),</a> | |
178 | <a href="man-cupsd.html?TOPIC=Man+Pages"><b>cupsd</b>(8),</a> | |
179 | <a href="man-cupsfilter.html?TOPIC=Man+Pages"><b>cupsfilter</b>(8),</a> | |
94436c5a | 180 | <br> |
bfbd0197 | 181 | CUPS Online Help (<a href="http://localhost:631/help">http://localhost:631/help</a>) |
94436c5a | 182 | <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> |
d58c2629 | 183 | Copyright © 2007-2016 by Apple Inc. |
94436c5a MS |
184 | |
185 | </body> | |
186 | </html> |