-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML>
<html>
<!-- SECTION: Man Pages -->
<head>
<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>job user title num-copies options [
-<i>filename
-</i>]
+<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 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.
-<p>The command name (argv[0]) is set to the name of the destination printer but is
-also available in the PRINTER environment variable.
-<h2 class="title"><a name="WARNING">Warning</a></h2>
-CUPS filters are not meant to be run directly by the user. Aside from the legacy
-System V interface issues (argv[0] 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. Unless you are a developer and know what you are doing, please do not run
-filters directly. Instead, use the <a href='man-cupsfilter.html?TOPIC=Man+Pages'>cupsfilter(8)</a> program to use the
-appropriate filters to do the conversions you need.
-<h2 class="title"><a name="OPTIONS">Options</a></h2>
-Options passed on the command-line typically do not include the default choices
-the printer's PPD file. In addition, some options may be specified in multiple
-ways - "landscape" is a synonym for "orientation-requested=4", "media" is a
-synonym for "PageSize", "PageRegion", "InputSlot", and "MediaType", and "sides"
-is a synonym for the various "Duplex" options. Non-raster filters <b>must</b>
-support both explicit and implicit specification of PPD options - use the
-ppdMarkDefaults and cupsMarkOptions functions in the CUPS library to use the
-correct mapping, and ppdFindMarkedChoice to get the user-selected choice.
-<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.
+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 stderr are generally logged to
-printer-state-message attribute and the current <i>ErrorLog</i>.
+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>
-<dt>ALERT: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "alert" log level.
-</dd>
-<dt>ATTR: attribute=value [attribute=value]
-</dt>
-<dd></dd>
-<dd>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:
+<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".
-</dd>
-<dt>CRIT: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "critical" log level.
-</dd>
-<dt>DEBUG: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "debug" log level.
-</dd>
-<dt>DEBUG2: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "debug2" log level.
-</dd>
-<dt>EMERG: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "emergency" log level.
-</dd>
-<dt>ERROR: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "error" log level.
-</dd>
-<dt>INFO: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute. If the current <i>LogLevel</i>
-is set to "debug2", also adds the specified message to the
-current <i>ErrorLog</i> using the "info" log level.
-</dd>
-<dt>NOTICE: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "notice" log level.
-</dd>
-<dt>PAGE: page-number #-copies
-</dt>
-<dd></dd>
-<dt>PAGE: total #-pages
-</dt>
-<dd></dd>
-<dd>Adds an entry to the current <i>PageLog</i>. The first form adds
-#-copies to the job-media-sheets-completed attribute. The second
-form sets the job-media-sheets-completed attribute to #-pages.
-</dd>
-<dt>PPD: Keyword=Value ... KeywordN=Value
-</dt>
-<dd></dd>
-<dd>Sets the named keywords in the printer's PPD file. This is typically
-used to update default option keywords such as DefaultPageSize and
-the various installable options in the PPD file.
-</dd>
-<dt>STATE: printer-state-reason [printer-state-reason ...]
-</dt>
-<dd></dd>
-<dt>STATE: + printer-state-reason [printer-state-reason ...]
-</dt>
-<dd></dd>
-<dt>STATE: - printer-state-reason [printer-state-reason ...]
-</dt>
-<dd></dd>
-<dd>Sets, adds, or removes printer-state-reason keywords to the
-current queue. Typically this is used to indicate media, ink, and
-toner conditions on a printer.
-</dd>
-<dt>WARNING: message
-</dt>
-<dd></dd>
-<dd>Sets the printer-state-message attribute and adds the specified
-message to the current <i>ErrorLog</i> using the "warning" log level.
-</dd>
+<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>
-<dt>CHARSET
-</dt>
-<dd></dd>
-<dd>The default text character set, typically utf-8.
-</dd>
-<dt>CLASS
-</dt>
-<dd></dd>
-<dd>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.
-</dd>
-<dt>CONTENT_TYPE
-</dt>
-<dd></dd>
-<dd>The MIME type associated with the file (e.g.
-application/postscript).
-</dd>
-<dt>CUPS_CACHEDIR
-</dt>
-<dd></dd>
-<dd>The directory for semi-persistent cache files can be found.
-</dd>
-<dt>CUPS_DATADIR
-</dt>
-<dd></dd>
-<dd>The directory where data files can be found.
-</dd>
-<dt>CUPS_FILETYPE
-</dt>
-<dd></dd>
-<dd>The type of file being printed: "job-sheet" for a banner page and "document"
+<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.
-</dd>
-<dt>CUPS_MAX_MESSAGE
-</dt>
-<dd></dd>
-<dd>The maximum size of a message sent to stderr, including any leading prefix and
-the trailing newline.
-</dd>
-<dt>CUPS_SERVERROOT
-</dt>
-<dd></dd>
-<dd>The root directory of the server.
-</dd>
-<dt>DEVICE_URI
-</dt>
-<dd></dd>
-<dd>The device-uri associated with the printer.
-</dd>
-<dt>FINAL_CONTENT_TYPE
-</dt>
-<dd></dd>
-<dd>The MIME type associated with the printer (e.g.
-application/vnd.cups-postscript).
-</dd>
-<dt>LANG
-</dt>
-<dd></dd>
-<dd>The default language locale (typically C or en).
-</dd>
-<dt>PATH
-</dt>
-<dd></dd>
-<dd>The standard execution path for external programs that may be run by
-the filter.
-</dd>
-<dt>PPD
-</dt>
-<dd></dd>
-<dd>The full pathname of the PostScript Printer Description (PPD)
-file for this printer.
-</dd>
-<dt>PRINTER
-</dt>
-<dd></dd>
-<dd>The name of the printer.
-</dd>
-<dt>RIP_CACHE
-</dt>
-<dd></dd>
-<dd>The recommended amount of memory to use for Raster Image
-Processors (RIPs).
-</dd>
-<dt>SOFTWARE
-</dt>
-<dd></dd>
-<dd>The name and version number of the server (typically CUPS/1.2).
-</dd>
-<dt>TZ
-</dt>
-<dd></dd>
-<dd>The timezone of the server.
-</dd>
-<dt>USER
-</dt>
-<dd></dd>
-<dd>The user executing the filter, typically "lp" or "root"; consult the
-<a href='man-cupsd.conf.html?TOPIC=Man+Pages'>cupsd.conf(5)</a> file for the current setting.
-</dd>
+<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="COMPATIBILITY">Compatibility</a></h2>
-While the filter interface is compatible with System V interface
-scripts, it will only work with the System V interface script as the
-only filter. Typically the interface script will be provided via the
-<a href='man-lpadmin.html?TOPIC=Man+Pages'>lpadmin(8)</a> command using the <i>-i</i> option.
+<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>
-<a href='man-backend.html?TOPIC=Man+Pages'>backend(7)</a>, <a href='man-cupsd.html?TOPIC=Man+Pages'>cupsd(8)</a>, <a href='man-cupsfilter.html?TOPIC=Man+Pages'>cupsfilter(8)</a>,
+<b>backend</b>(7),
+<b>cups</b>(1),
+<b>cups-files.conf</b>(5),
+<b>cupsd</b>(8),
+<b>cupsfilter</b>(8),
<br>
-<a href='http://localhost:631/help'>http://localhost:631/help</a>
+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-2013 by Apple Inc.
+Copyright © 2007-2019 by Apple Inc.
</body>
</html>
projects / thirdparty / cups.git / blobdiff