|
Packit |
2fc92b |
.\"
|
|
Packit |
2fc92b |
.\" filter man page for CUPS.
|
|
Packit |
2fc92b |
.\"
|
|
Packit |
2fc92b |
.\" Copyright 2007-2015 by Apple Inc.
|
|
Packit |
2fc92b |
.\" Copyright 1997-2007 by Easy Software Products.
|
|
Packit |
2fc92b |
.\"
|
|
Packit |
2fc92b |
.\" These coded instructions, statements, and computer programs are the
|
|
Packit |
2fc92b |
.\" property of Apple Inc. and are protected by Federal copyright
|
|
Packit |
2fc92b |
.\" law. Distribution and use rights are outlined in the file "LICENSE.txt"
|
|
Packit |
2fc92b |
.\" which should have been included with this file. If this file is
|
|
Packit |
2fc92b |
.\" file is missing or damaged, see the license at "http://www.cups.org/".
|
|
Packit |
2fc92b |
.\"
|
|
Packit |
2fc92b |
.TH filter 7 "CUPS" "19 October 2015" "Apple Inc."
|
|
Packit |
2fc92b |
.SH NAME
|
|
Packit |
2fc92b |
filter \- cups file conversion filter interface
|
|
Packit |
2fc92b |
.SH SYNOPSIS
|
|
Packit |
2fc92b |
.B filter
|
|
Packit |
2fc92b |
.I job
|
|
Packit |
2fc92b |
.I user
|
|
Packit |
2fc92b |
.I title
|
|
Packit |
2fc92b |
.I num-copies
|
|
Packit |
2fc92b |
.I options
|
|
Packit |
2fc92b |
[
|
|
Packit |
2fc92b |
.I filename
|
|
Packit |
2fc92b |
]
|
|
Packit |
2fc92b |
.nf
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fB#include <cups/cups.h>\fR
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBssize_t cupsBackChannelRead\fR(\fBchar *\fIbuffer\fR, \fBsize_t \fIbytes\fR,
|
|
Packit |
2fc92b |
\fBdouble \fItimeout\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBcups_sc_status_t cupsSideChannelDoRequest\fR(\fBcups_sc_command_t \fIcommand\fR,
|
|
Packit |
2fc92b |
\fBchar *\fIdata\fR, \fBint *\fIdatalen\fR,
|
|
Packit |
2fc92b |
\fBdouble \fItimeout\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fB#include <cups/ppd.h>\fR
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBconst char *cupsGetOption\fR(\fBconst char *\fIname\fR, \fBint \fInum_options\fR,
|
|
Packit |
2fc92b |
\fBcups_option_t *\fIoptions\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBint cupsMarkOptions\fR(\fBppd_file_t *\fIppd\fR, \fBint \fInum_options\fR,
|
|
Packit |
2fc92b |
\fBcups_option_t *\fIoptions\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBint cupsParseOptions\fR(\fBconst char *\fIarg\fR, \fBint \fInum_options\fR,
|
|
Packit |
2fc92b |
\fBcups_option_t **\fIoptions\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBppd_choice_t *ppdFindMarkedChoice\fR(\fBppd_file_t *\fIppd\fR, \fBconst char *\fIkeyword\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBvoid ppdMarkDefaults\fR(\fBppd_file_t *\fIppd\fR);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
\fBppd_file_t *ppdOpenFile\fR(\fBconst char *\fIfilename\fR);
|
|
Packit |
2fc92b |
.fi
|
|
Packit |
2fc92b |
.SH DESCRIPTION
|
|
Packit |
2fc92b |
The CUPS filter interface provides a standard method for adding support for new document types or printers to CUPS.
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.LP
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
All output \fBMUST\fR be sent to the standard output.
|
|
Packit |
2fc92b |
Filters \fBMUST NOT\fR attempt to communicate directly with the printer, other processes, or other services.
|
|
Packit |
2fc92b |
.LP
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.SH OPTIONS
|
|
Packit |
2fc92b |
Options are passed in \fIargv[5]\fR and are encoded from the corresponding IPP attributes used when the job was submitted. Use the
|
|
Packit |
2fc92b |
.BR cupsParseOptions ()
|
|
Packit |
2fc92b |
function to load the options into a \fBcups_option_t\fR array and the
|
|
Packit |
2fc92b |
.BR cupsGetOption ()
|
|
Packit |
2fc92b |
function to get the value of a specific attribute.
|
|
Packit |
2fc92b |
Be careful to look for common aliases of IPP attributes such as "landscape" for the IPP "orientation-requested" attribute.
|
|
Packit |
2fc92b |
.LP
|
|
Packit |
2fc92b |
Options passed on the command-line typically do not include the default choices the printer's PPD file. Use the
|
|
Packit |
2fc92b |
.BR ppdMarkDefaults ()
|
|
Packit |
2fc92b |
and
|
|
Packit |
2fc92b |
.BR cupsMarkOptions ()
|
|
Packit |
2fc92b |
functions in the CUPS library to apply the options to the PPD defaults and map any IPP attributes to the corresponding PPD options.
|
|
Packit |
2fc92b |
Use
|
|
Packit |
2fc92b |
.BR ppdFindMarkedChoice ()
|
|
Packit |
2fc92b |
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:
|
|
Packit |
2fc92b |
.nf
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
|
|
Packit |
2fc92b |
cups_option_t *options = NULL;
|
|
Packit |
2fc92b |
int num_options = cupsParseOptions(argv[5], 0, &options);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
ppdMarkDefaults(ppd);
|
|
Packit |
2fc92b |
cupsMarkOptions(ppd, num_options, options);
|
|
Packit |
2fc92b |
|
|
Packit |
2fc92b |
ppd_choice_t *choice = ppdFindMarkedChoice(ppd, "Duplex");
|
|
Packit |
2fc92b |
.fi
|
|
Packit |
2fc92b |
.LP
|
|
Packit |
2fc92b |
Raster filters should use option choices set through the raster page header, as those reflect the options in effect for a given page.
|
|
Packit |
2fc92b |
Options specified on the command-line determine the default values for the entire job, which can be overridden on a per-page basis.
|
|
Packit |
2fc92b |
.SH LOG MESSAGES
|
|
Packit |
2fc92b |
Messages sent to the standard error are generally stored in the printer's "printer-state-message" attribute and the current \fBErrorLog\fR file.
|
|
Packit |
2fc92b |
Each line begins with a standard prefix:
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBALERT: \fImessage\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "alert" log level.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBATTR: \fIattribute=value \fR[ \fI... attribute=value\fR]
|
|
Packit |
2fc92b |
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:
|
|
Packit |
2fc92b |
"auth-info-required", "marker-colors", "marker-high-levels", "marker-levels",
|
|
Packit |
2fc92b |
"marker-low-levels", "marker-message", "marker-names", "marker-types",
|
|
Packit |
2fc92b |
"printer-alert", and "printer-alert-description".
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBCRIT: \fImessage\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "critical" log level.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBDEBUG: \fImessage\fR
|
|
Packit |
2fc92b |
Adds the specified message to the current \fBErrorLog\fR using the "debug" log level.
|
|
Packit |
2fc92b |
\fBDEBUG\fR messages are never stored in the "printer-state-message" attribute.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBDEBUG2: \fImessage\fR
|
|
Packit |
2fc92b |
.br
|
|
Packit |
2fc92b |
Adds the specified message to the current \fBErrorLog\fR using the "debug2" log level.
|
|
Packit |
2fc92b |
\fBDEBUG2\fR messages are never stored in the "printer-state-message" attribute.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBEMERG: \fImessage\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "emergency" log level.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBERROR:\fI message\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "error" log level.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBINFO:\fI message\fR
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBNOTICE:\fI message\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "notice" log level.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBPAGE:\fI page-number #-copies\fR
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBPAGE:\fI total #-pages\fR
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBPPD:\fI Keyword=Value\fR [ \fI... KeywordN=Value\fR ]
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBSTATE:\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ]
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBSTATE: +\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ]
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBSTATE: -\fI printer-state-reason \fR[ \fI... printer-state-reason\fR ]
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
\fBWARNING:\fI message\fR
|
|
Packit |
2fc92b |
Sets the "printer-state-message" attribute and adds the specified message to the current \fBErrorLog\fR using the "warning" log level.
|
|
Packit |
2fc92b |
.SH ENVIRONMENT VARIABLES
|
|
Packit |
2fc92b |
The following environment variables are defined by the CUPS
|
|
Packit |
2fc92b |
server when executing the filter:
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CHARSET
|
|
Packit |
2fc92b |
The default text character set, typically "utf-8".
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CLASS
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CONTENT_TYPE
|
|
Packit |
2fc92b |
The MIME media type associated with the submitted job file, for example "application/postscript".
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CUPS_CACHEDIR
|
|
Packit |
2fc92b |
The directory where semi-persistent cache files can be found and stored.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CUPS_DATADIR
|
|
Packit |
2fc92b |
The directory where data files can be found.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CUPS_FILETYPE
|
|
Packit |
2fc92b |
The type of file being printed: "job-sheet" for a banner page and "document"
|
|
Packit |
2fc92b |
for a regular print file.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CUPS_MAX_MESSAGE
|
|
Packit |
2fc92b |
The maximum size of a message sent to \fIstderr\fR, including any leading prefix and the trailing newline.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B CUPS_SERVERROOT
|
|
Packit |
2fc92b |
The root directory of the server.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B FINAL_CONTENT_TYPE
|
|
Packit |
2fc92b |
The MIME media type associated with the output destined for the printer, for example "application/vnd.cups-postscript".
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B LANG
|
|
Packit |
2fc92b |
The default language locale (typically C or en).
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B PATH
|
|
Packit |
2fc92b |
The standard execution path for external programs that may be run by the filter.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B PPD
|
|
Packit |
2fc92b |
The full pathname of the PostScript Printer Description (PPD) file for this printer.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B PRINTER
|
|
Packit |
2fc92b |
The name of the printer.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B RIP_CACHE
|
|
Packit |
2fc92b |
The recommended amount of memory to use for Raster Image Processors (RIPs).
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B SOFTWARE
|
|
Packit |
2fc92b |
The name and version number of the server (typically CUPS/\fImajor.minor\fR).
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B TZ
|
|
Packit |
2fc92b |
The timezone of the server.
|
|
Packit |
2fc92b |
.TP 5
|
|
Packit |
2fc92b |
.B USER
|
|
Packit |
2fc92b |
The user executing the filter, typically "lp" or "root"; consult the \fIcups-files.conf\fR file for the current setting.
|
|
Packit |
2fc92b |
.SH CONFORMING TO
|
|
Packit |
2fc92b |
While the filter interface is compatible with System V interface scripts, CUPS does not support System V interface scripts.
|
|
Packit |
2fc92b |
.SH NOTES
|
|
Packit |
2fc92b |
CUPS filters are not meant to be run directly by the user.
|
|
Packit |
2fc92b |
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.
|
|
Packit |
2fc92b |
Unless you are a developer and know what you are doing, please do not run filters directly.
|
|
Packit |
2fc92b |
Instead, use the
|
|
Packit |
2fc92b |
.BR cupsfilter (8)
|
|
Packit |
2fc92b |
program to use the appropriate filters to do the conversions you need.
|
|
Packit |
2fc92b |
.SH SEE ALSO
|
|
Packit |
2fc92b |
.BR backend (7),
|
|
Packit |
2fc92b |
.BR cups (1),
|
|
Packit |
2fc92b |
.BR cups-files.conf (5),
|
|
Packit |
2fc92b |
.BR cupsd (8),
|
|
Packit |
2fc92b |
.BR cupsfilter (8),
|
|
Packit |
2fc92b |
.br
|
|
Packit |
2fc92b |
CUPS Online Help (http://localhost:631/help)
|
|
Packit |
2fc92b |
.SH COPYRIGHT
|
|
Packit |
2fc92b |
Copyright \[co] 2007-2017 by Apple Inc.
|