man/filter.man

   1 .\"
   2 .\" "$Id: filter.man 7600 2008-05-20 21:06:23Z mike $"
   3 .\"
   4 .\"   filter man page for the Common UNIX Printing System (CUPS).
   5 .\"
   6 .\"   Copyright 2007-2009 by Apple Inc.
   7 .\"   Copyright 1997-2007 by Easy Software Products.
   8 .\"
   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/".
  14 .\"
  15 .TH filter 7 "CUPS" "13 May 2009" "Apple Inc."
  16 .SH NAME
  17 filter \- cups file conversion filter interface
  18 .SH SYNOPSIS
  19 .B filter
  20 job user title num-copies options [
  21 .I filename
  22 ]
  23 .SH DESCRIPTION
  24 The CUPS filter interface provides a standard method for adding support for
  25 new document types to CUPS. Each filter is capable of converting from one
  26 or more input formats to another format that can either be printed directly
  27 or piped into another filter to get it to a printable format.
  28 .LP
  29 Filters \fBmust\fR be capable of reading from a filename on the command-line
  30 or from the standard input, copying the standard input to a temporary
  31 file as required by the file format. All output \fBmust\fR be sent to the
  32 standard output.
  33 .LP
  34 The command name (argv[0]) is set to the name of the destination printer but is
  35 also available in the PRINTER environment variable.
  36
  37 .SH OPTIONS
  38 Options passed on the command-line typically do not include the default choices
  39 the printer's PPD file. In addition, some options may be specified in multiple
  40 ways - "landscape" is a synonym for "orientation-requested=4", "media" is a
  41 synonym for "PageSize", "PageRegion", "InputSlot", and "MediaType", and "sides"
  42 is a synonym for the various "Duplex" options. Non-raster filters \fBmust\fR
  43 support both explicit and implicit specification of PPD options - use the
  44 ppdMarkDefaults and cupsMarkOptions functions in the CUPS library to use the
  45 correct mapping, and ppdFindMarkedChoice to get the user-selected choice.
  46 .LP
  47 Raster filters should use option choices set through the raster page header, as
  48 those reflect the options in effect for a given page. Options specified on the
  49 command-line determine the default values for the entire job, which can be
  50 overridden on a per-page basis.
  51
  52 .SH LOG MESSAGES
  53 Messages sent to stderr are generally logged to
  54 printer-state-message attribute and the current \fIErrorLog\fR.
  55 Each line begins with a standard prefix:
  56
  57 .TP 5
  58 ALERT: message
  59 .br
  60 Sets the printer-state-message attribute and adds the specified
  61 message to the current \fIErrorLog\fR using the "alert" log level.
  62
  63 .TP 5
  64 ATTR: attribute=value [attribute=value]
  65 .br
  66 Sets the named job attribute(s). Typically this will be used to
  67 set the job-remote-id attribute.
  68
  69 .TP 5
  70 CRIT: message
  71 .br
  72 Sets the printer-state-message attribute and adds the specified
  73 message to the current \fIErrorLog\fR using the "critical" log level.
  74
  75 .TP 5
  76 DEBUG: message
  77 .br
  78 Sets the printer-state-message attribute and adds the specified
  79 message to the current \fIErrorLog\fR using the "debug" log level.
  80
  81 .TP 5
  82 DEBUG2: message
  83 .br
  84 Sets the printer-state-message attribute and adds the specified
  85 message to the current \fIErrorLog\fR using the "debug2" log level.
  86
  87 .TP 5
  88 EMERG: message
  89 .br
  90 Sets the printer-state-message attribute and adds the specified
  91 message to the current \fIErrorLog\fR using the "emergency" log level.
  92
  93 .TP 5
  94 ERROR: message
  95 .br
  96 Sets the printer-state-message attribute and adds the specified
  97 message to the current \fIErrorLog\fR using the "error" log level.
  98
  99 .TP 5
 100 INFO: message
 101 .br
 102 Sets the printer-state-message attribute. If the current \fILogLevel\fR
 103 is set to "debug2", also adds the specified message to the
 104 current \fIErrorLog\fR using the "info" log level.
 105
 106 .TP 5
 107 NOTICE: message
 108 .br
 109 Sets the printer-state-message attribute and adds the specified
 110 message to the current \fIErrorLog\fR using the "notice" log level.
 111
 112 .TP 5
 113 PAGE: page-number #-copies
 114 .TP 5
 115 PAGE: total #-pages
 116 .br
 117 Adds an entry to the current \fIPageLog\fR. The first form adds
 118 #-copies to the job-media-sheets-completed attribute. The second
 119 form sets the job-media-sheets-completed attribute to #-pages.
 120
 121 .TP 5
 122 PPD: Keyword=Value ... KeywordN=Value
 123 .br
 124 Sets the named keywords in the printer's PPD file. This is typically
 125 used to update default option keywords such as DefaultPageSize and
 126 the various installable options in the PPD file.
 127
 128 .TP 5
 129 STATE: printer-state-reason [printer-state-reason ...]
 130 .TP 5
 131 STATE: + printer-state-reason [printer-state-reason ...]
 132 .TP 5
 133 STATE: - printer-state-reason [printer-state-reason ...]
 134 .br
 135 Sets, adds, or removes printer-state-reason keywords to the
 136 current queue. Typically this is used to indicate media, ink, and
 137 toner conditions on a printer.
 138
 139 .TP 5
 140 WARNING: message
 141 .br
 142 Sets the printer-state-message attribute and adds the specified
 143 message to the current \fIErrorLog\fR using the "warning" log level.
 144
 145 .SH ENVIRONMENT VARIABLES
 146 The following environment variables are defined by the CUPS
 147 server when executing the filter:
 148
 149 .TP 5
 150 CHARSET
 151 .br
 152 The default text character set, typically utf-8.
 153
 154 .TP 5
 155 CLASS
 156 .br
 157 When a job is submitted to a printer class, contains the name of
 158 the destination printer class. Otherwise this environment
 159 variable will not be set.
 160
 161 .TP 5
 162 CONTENT_TYPE
 163 .br
 164 The MIME type associated with the file (e.g.
 165 application/postscript).
 166
 167 .TP 5
 168 CUPS_CACHEDIR
 169 .br
 170 The directory for semi-persistent cache files can be found.
 171
 172 .TP 5
 173 CUPS_DATADIR
 174 .br
 175 The directory where data files can be found.
 176
 177 .TP 5
 178 CUPS_FILETYPE
 179 .br
 180 The type of file being printed: "job-sheet" for a banner page and "document"
 181 for a regular print file.
 182
 183 .TP 5
 184 CUPS_SERVERROOT
 185 .br
 186 The root directory of the server.
 187
 188 .TP 5
 189 DEVICE_URI
 190 .br
 191 The device-uri associated with the printer.
 192
 193 .TP 5
 194 FINAL_CONTENT_TYPE
 195 .br
 196 The MIME type associated with the printer (e.g.
 197 application/vnd.cups-postscript).
 198
 199 .TP 5
 200 LANG
 201 .br
 202 The default language locale (typically C or en).
 203
 204 .TP 5
 205 PATH
 206 .br
 207 The standard execution path for external programs that may be run by
 208 the filter.
 209
 210 .TP 5
 211 PPD
 212 .br
 213 The full pathname of the PostScript Printer Description (PPD)
 214 file for this printer.
 215
 216 .TP 5
 217 PRINTER
 218 .br
 219 The name of the printer.
 220
 221 .TP 5
 222 RIP_CACHE
 223 .br
 224 The recommended amount of memory to use for Raster Image
 225 Processors (RIPs).
 226
 227 .TP 5
 228 SOFTWARE
 229 .br
 230 The name and version number of the server (typically CUPS/1.2).
 231
 232 .TP 5
 233 TZ
 234 .br
 235 The timezone of the server.
 236
 237 .TP 5
 238 USER
 239 .br
 240 The user executing the filter, typically "lp" or "root"; consult the
 241 \fIcupsd.conf(5)\fR file for the current setting.
 242
 243 .SH COMPATIBILITY
 244 While the filter interface is compatible with System V interface
 245 scripts, it will only work with the System V interface script as the
 246 only filter.  Typically the interface script will be provided via the
 247 \fIlpadmin(8)\fR command using the \fI-i\fR option.
 248 .SH SEE ALSO
 249 \fIbackend(7)\fR, \fIcupsd(8)\fR,
 250 .br
 251 http://localhost:631/help
 252 .SH COPYRIGHT
 253 Copyright 2007-2009 by Apple Inc.
 254 .\"
 255 .\" End of "$Id: filter.man 7600 2008-05-20 21:06:23Z mike $".
 256 .\"