mirror of https://gitee.com/openkylin/cups.git
190 lines
11 KiB
HTML
190 lines
11 KiB
HTML
|
<!DOCTYPE HTML>
|
||
|
|
<html>
|
||
|
|
<!-- SECTION: Man Pages -->
|
||
|
|
<head>
|
||
|
|
<link rel="stylesheet" type="text/css" href="../cups-printable.css">
|
||
|
|
<title>filter(7)</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<h1 class="title">filter(7)</h1>
|
||
|
|
<h2 class="title"><a name="NAME">Name</a></h2>
|
||
|
|
filter - cups file conversion filter interface
|
||
|
|
<h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2>
|
||
|
|
<b>filter</b>
|
||
|
|
<i>job</i>
|
||
|
|
<i>user</i>
|
||
|
|
<i>title</i>
|
||
|
|
<i>num-copies</i>
|
||
|
|
<i>options</i>
|
||
|
|
[
|
||
|
|
<i>filename</i>
|
||
|
|
]
|
||
|
|
<pre class="man">
|
||
|
|
|
||
|
|
<b>#include <cups/cups.h></b>
|
||
|
|
|
||
|
|
<b>ssize_t cupsBackChannelRead</b>(<b>char *</b><i>buffer</i>, <b>size_t </b><i>bytes</i>,
|
||
|
|
<b>double </b><i>timeout</i>);
|
||
|
|
|
||
|
|
<b>cups_sc_status_t cupsSideChannelDoRequest</b>(<b>cups_sc_command_t </b><i>command</i>,
|
||
|
|
<b>char *</b><i>data</i>, <b>int *</b><i>datalen</i>,
|
||
|
|
<b>double </b><i>timeout</i>);
|
||
|
|
|
||
|
|
<b>#include <cups/ppd.h></b>
|
||
|
|
|
||
|
|
<b>const char *cupsGetOption</b>(<b>const char *</b><i>name</i>, <b>int </b><i>num_options</i>,
|
||
|
|
<b>cups_option_t *</b><i>options</i>);
|
||
|
|
|
||
|
|
<b>int cupsMarkOptions</b>(<b>ppd_file_t *</b><i>ppd</i>, <b>int </b><i>num_options</i>,
|
||
|
|
<b>cups_option_t *</b><i>options</i>);
|
||
|
|
|
||
|
|
<b>int cupsParseOptions</b>(<b>const char *</b><i>arg</i>, <b>int </b><i>num_options</i>,
|
||
|
|
<b>cups_option_t **</b><i>options</i>);
|
||
|
|
|
||
|
|
<b>ppd_choice_t *ppdFindMarkedChoice</b>(<b>ppd_file_t *</b><i>ppd</i>, <b>const char *</b><i>keyword</i>);
|
||
|
|
|
||
|
|
<b>void ppdMarkDefaults</b>(<b>ppd_file_t *</b><i>ppd</i>);
|
||
|
|
|
||
|
|
<b>ppd_file_t *ppdOpenFile</b>(<b>const char *</b><i>filename</i>);
|
||
|
|
</pre>
|
||
|
|
<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
|
||
|
|
The CUPS filter interface provides a standard method for adding support for new document types or printers to CUPS.
|
||
|
|
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.
|
||
|
|
<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.
|
||
|
|
All output <b>MUST</b> be sent to the standard output.
|
||
|
|
Filters <b>MUST NOT</b> attempt to communicate directly with the printer, other processes, or other services.
|
||
|
|
<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.
|
||
|
|
</i><h2 class="title"><a name="OPTIONS">Options</a></h2>
|
||
|
|
Options are passed in <i>argv[5]</i> and are encoded from the corresponding IPP attributes used when the job was submitted. Use the
|
||
|
|
<b>cupsParseOptions</b>()
|
||
|
|
function to load the options into a <b>cups_option_t</b> array and the
|
||
|
|
<b>cupsGetOption</b>()
|
||
|
|
function to get the value of a specific attribute.
|
||
|
|
Be careful to look for common aliases of IPP attributes such as "landscape" for the IPP "orientation-requested" attribute.
|
||
|
|
<p>Options passed on the command-line typically do not include the default choices the printer's PPD file. Use the
|
||
|
|
<b>ppdMarkDefaults</b>()
|
||
|
|
and
|
||
|
|
<b>cupsMarkOptions</b>()
|
||
|
|
functions in the CUPS library to apply the options to the PPD defaults and map any IPP attributes to the corresponding PPD options.
|
||
|
|
Use
|
||
|
|
<b>ppdFindMarkedChoice</b>()
|
||
|
|
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:
|
||
|
|
<pre class="man">
|
||
|
|
|
||
|
|
ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
|
||
|
|
cups_option_t *options = NULL;
|
||
|
|
int num_options = cupsParseOptions(argv[5], 0, &options);
|
||
|
|
|
||
|
|
ppdMarkDefaults(ppd);
|
||
|
|
cupsMarkOptions(ppd, num_options, options);
|
||
|
|
|
||
|
|
ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex");
|
||
|
|
</pre>
|
||
|
|
<p>Raster filters should use option choices set through the raster page header, as those reflect the options in effect for a given page.
|
||
|
|
Options specified on the command-line determine the default values for the entire job, which can be overridden on a per-page basis.
|
||
|
|
<h2 class="title"><a name="LOG_MESSAGES">Log Messages</a></h2>
|
||
|
|
Messages sent to the standard error are generally stored in the printer's "printer-state-message" attribute and the current <b>ErrorLog</b> file.
|
||
|
|
Each line begins with a standard prefix:
|
||
|
|
<dl class="man">
|
||
|
|
<dt><b>ALERT: </b><i>message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>ATTR: </b><i>attribute=value </i>[ <i>... attribute=value</i>]
|
||
|
|
<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:
|
||
|
|
"auth-info-required", "marker-colors", "marker-high-levels", "marker-levels",
|
||
|
|
"marker-low-levels", "marker-message", "marker-names", "marker-types",
|
||
|
|
"printer-alert", and "printer-alert-description".
|
||
|
|
<dt><b>CRIT: </b><i>message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>DEBUG: </b><i>message</i>
|
||
|
|
<dd style="margin-left: 5.0em">Adds the specified message to the current <b>ErrorLog</b> using the "debug" log level.
|
||
|
|
<b>DEBUG</b> messages are never stored in the "printer-state-message" attribute.
|
||
|
|
<dt><b>DEBUG2: </b><i>message</i>
|
||
|
|
<dd style="margin-left: 5.0em"><br>
|
||
|
|
Adds the specified message to the current <b>ErrorLog</b> using the "debug2" log level.
|
||
|
|
<b>DEBUG2</b> messages are never stored in the "printer-state-message" attribute.
|
||
|
|
<dt><b>EMERG: </b><i>message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>ERROR:</b><i> message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>INFO:</b><i> message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>NOTICE:</b><i> message</i>
|
||
|
|
<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.
|
||
|
|
<dt><b>PAGE:</b><i> page-number #-copies</i>
|
||
|
|
<dd style="margin-left: 5.0em"><dt><b>PAGE:</b><i> total #-pages</i>
|
||
|
|
<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>.
|
||
|
|
<dt><b>PPD:</b><i> Keyword=Value</i> [ <i>... KeywordN=Value</i> ]
|
||
|
|
<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.
|
||
|
|
<dt><b>STATE:</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ]
|
||
|
|
<dd style="margin-left: 5.0em"><dt><b>STATE: +</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ]
|
||
|
|
<dd style="margin-left: 5.0em"><dt><b>STATE: -</b><i> printer-state-reason </i>[ <i>... printer-state-reason</i> ]
|
||
|
|
<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.
|
||
|
|
<dt><b>WARNING:</b><i> message</i>
|
||
|
|
<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.
|
||
|
|
</dl>
|
||
|
|
<h2 class="title"><a name="ENVIRONMENT_VARIABLES">Environment Variables</a></h2>
|
||
|
|
The following environment variables are defined by the CUPS
|
||
|
|
server when executing the filter:
|
||
|
|
<dl class="man">
|
||
|
|
<dt><b>CHARSET</b>
|
||
|
|
<dd style="margin-left: 5.0em">The default text character set, typically "utf-8".
|
||
|
|
<dt><b>CLASS</b>
|
||
|
|
<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.
|
||
|
|
<dt><b>CONTENT_TYPE</b>
|
||
|
|
<dd style="margin-left: 5.0em">The MIME media type associated with the submitted job file, for example "application/postscript".
|
||
|
|
<dt><b>CUPS_CACHEDIR</b>
|
||
|
|
<dd style="margin-left: 5.0em">The directory where semi-persistent cache files can be found and stored.
|
||
|
|
<dt><b>CUPS_DATADIR</b>
|
||
|
|
<dd style="margin-left: 5.0em">The directory where data files can be found.
|
||
|
|
<dt><b>CUPS_FILETYPE</b>
|
||
|
|
<dd style="margin-left: 5.0em">The type of file being printed: "job-sheet" for a banner page and "document"
|
||
|
|
for a regular print file.
|
||
|
|
<dt><b>CUPS_MAX_MESSAGE</b>
|
||
|
|
<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.
|
||
|
|
<dt><b>CUPS_SERVERROOT</b>
|
||
|
|
<dd style="margin-left: 5.0em">The root directory of the server.
|
||
|
|
<dt><b>FINAL_CONTENT_TYPE</b>
|
||
|
|
<dd style="margin-left: 5.0em">The MIME media type associated with the output destined for the printer, for example "application/vnd.cups-postscript".
|
||
|
|
<dt><b>LANG</b>
|
||
|
|
<dd style="margin-left: 5.0em">The default language locale (typically C or en).
|
||
|
|
<dt><b>PATH</b>
|
||
|
|
<dd style="margin-left: 5.0em">The standard execution path for external programs that may be run by the filter.
|
||
|
|
<dt><b>PPD</b>
|
||
|
|
<dd style="margin-left: 5.0em">The full pathname of the PostScript Printer Description (PPD) file for this printer.
|
||
|
|
<dt><b>PRINTER</b>
|
||
|
|
<dd style="margin-left: 5.0em">The name of the printer.
|
||
|
|
<dt><b>RIP_CACHE</b>
|
||
|
|
<dd style="margin-left: 5.0em">The recommended amount of memory to use for Raster Image Processors (RIPs).
|
||
|
|
<dt><b>SOFTWARE</b>
|
||
|
|
<dd style="margin-left: 5.0em">The name and version number of the server (typically CUPS/<i>major.minor</i>).
|
||
|
|
<dt><b>TZ</b>
|
||
|
|
<dd style="margin-left: 5.0em">The timezone of the server.
|
||
|
|
<dt><b>USER</b>
|
||
|
|
<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.
|
||
|
|
</dl>
|
||
|
|
<h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2>
|
||
|
|
While the filter interface is compatible with System V interface scripts, CUPS does not support System V interface scripts.
|
||
|
|
<h2 class="title"><a name="NOTES">Notes</a></h2>
|
||
|
|
CUPS printer drivers and backends are deprecated and will no longer be supported in a future feature release of CUPS.
|
||
|
|
Printers that do not support IPP can be supported using applications such as
|
||
|
|
<b>ippeveprinter</b>(1).
|
||
|
|
<p>CUPS filters are not meant to be run directly by the user.
|
||
|
|
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 macOS) has additional restrictions that affect how it runs.
|
||
|
|
Unless you are a developer and know what you are doing, please do not run filters directly.
|
||
|
|
Instead, use the
|
||
|
|
<b>cupsfilter</b>(8)
|
||
|
|
program to use the appropriate filters to do the conversions you need.
|
||
|
|
<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
|
||
|
|
<b>backend</b>(7),
|
||
|
|
<b>cups</b>(1),
|
||
|
|
<b>cups-files.conf</b>(5),
|
||
|
|
<b>cupsd</b>(8),
|
||
|
|
<b>cupsfilter</b>(8),
|
||
|
|
<br>
|
||
|
|
CUPS Online Help (<a href="http://localhost:631/help">http://localhost:631/help</a>)
|
||
|
|
<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
|
||
|
|
Copyright © 2007-2019 by Apple Inc.
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|