man/filter.man

   1 .\"
   2 .\" "$Id: filter.man 6649 2007-07-11 21:46:42Z mike $"
   3 .\"
   4 .\"   filter man page for the Common UNIX Printing System (CUPS).
   5 .\"
   6 .\"   Copyright 2007 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 "Common UNIX Printing System" "6 July 2007" "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.
  35 .SH LOG MESSAGES
  36 Messages sent to stderr are generally logged to
  37 printer-state-message attribute and the current \fIErrorLog\fR.
  38 Each line begins with a standard prefix:
  39
  40 .TP 5
  41 ALERT: message
  42 .br
  43 Sets the printer-state-message attribute and adds the specified
  44 message to the current \fIErrorLog\fR using the "alert" log level.
  45
  46 .TP 5
  47 ATTR: attribute=value [attribute=value]
  48 .br
  49 Sets the named job attribute(s). Typically this will be used to
  50 set the job-remote-id attribute.
  51
  52 .TP 5
  53 CRIT: message
  54 .br
  55 Sets the printer-state-message attribute and adds the specified
  56 message to the current \fIErrorLog\fR using the "critical" log level.
  57
  58 .TP 5
  59 DEBUG: message
  60 .br
  61 Sets the printer-state-message attribute and adds the specified
  62 message to the current \fIErrorLog\fR using the "debug" log level.
  63
  64 .TP 5
  65 DEBUG2: message
  66 .br
  67 Sets the printer-state-message attribute and adds the specified
  68 message to the current \fIErrorLog\fR using the "debug2" log level.
  69
  70 .TP 5
  71 EMERG: message
  72 .br
  73 Sets the printer-state-message attribute and adds the specified
  74 message to the current \fIErrorLog\fR using the "emergency" log level.
  75
  76 .TP 5
  77 ERROR: message
  78 .br
  79 Sets the printer-state-message attribute and adds the specified
  80 message to the current \fIErrorLog\fR using the "error" log level.
  81
  82 .TP 5
  83 INFO: message
  84 .br
  85 Sets the printer-state-message attribute. If the current \fILogLevel\fR
  86 is set to "debug2", also adds the specified message to the
  87 current \fIErrorLog\fR using the "info" log level.
  88
  89 .TP 5
  90 NOTICE: message
  91 .br
  92 Sets the printer-state-message attribute and adds the specified
  93 message to the current \fIErrorLog\fR using the "notice" log level.
  94
  95 .TP 5
  96 PAGE: page-number #-copies
  97 .TP 5
  98 PAGE: total #-pages
  99 .br
 100 Adds an entry to the current \fIPageLog\fR. The first form adds
 101 #-copies to the job-media-sheets-completed attribute. The second
 102 form sets the job-media-sheets-completed attribute to #-pages.
 103
 104 .TP 5
 105 STATE: printer-state-reason [printer-state-reason ...]
 106 .TP 5
 107 STATE: + printer-state-reason [printer-state-reason ...]
 108 .TP 5
 109 STATE: - printer-state-reason [printer-state-reason ...]
 110 .br
 111 Sets, adds, or removes printer-state-reason keywords to the
 112 current queue. Typically this is used to indicate media, ink, and
 113 toner conditions on a printer.
 114
 115 .TP 5
 116 WARNING: message
 117 .br
 118 Sets the printer-state-message attribute and adds the specified
 119 message to the current \fIErrorLog\fR using the "warning" log level.
 120
 121 .SH ENVIRONMENT VARIABLES
 122 The following environment variables are defined by the CUPS
 123 server when executing the filter:
 124
 125 .TP 5
 126 CHARSET
 127 .br
 128 The default text character set, typically utf-8.
 129
 130 .TP 5
 131 CLASS
 132 .br
 133 When a job is submitted to a printer class, contains the name of
 134 the destination printer class. Otherwise this environment
 135 variable will not be set.
 136
 137 .TP 5
 138 CONTENT_TYPE
 139 .br
 140 The MIME type associated with the file (e.g.
 141 application/postscript).
 142
 143 .TP 5
 144 CUPS_DATADIR
 145 .br
 146 The directory where data files can be found.
 147
 148 .TP 5
 149 CUPS_SERVERROOT
 150 .br
 151 The root directory of the server.
 152
 153 .TP 5
 154 DEVICE_URI
 155 .br
 156 The device-uri associated with the printer.
 157
 158 .TP 5
 159 FINAL_CONTENT_TYPE
 160 .br
 161 The MIME type associated with the printer (e.g.
 162 application/vnd.cups-postscript).
 163
 164 .TP 5
 165 LANG
 166 .br
 167 The default language locale (typically C or en).
 168
 169 .TP 5
 170 PATH
 171 .br
 172 The standard execution path for external programs that may be run by
 173 the filter.
 174
 175 .TP 5
 176 PPD
 177 .br
 178 The full pathname of the PostScript Printer Description (PPD)
 179 file for this printer.
 180
 181 .TP 5
 182 PRINTER
 183 .br
 184 The name of the printer.
 185
 186 .TP 5
 187 RIP_CACHE
 188 .br
 189 The recommended amount of memory to use for Raster Image
 190 Processors (RIPs).
 191
 192 .TP 5
 193 SOFTWARE
 194 .br
 195 The name and version number of the server (typically CUPS/1.2).
 196
 197 .TP 5
 198 TZ
 199 .br
 200 The timezone of the server.
 201
 202 .TP 5
 203 USER
 204 .br
 205 The user executing the filter, typically "lp" or "root"; consult the
 206 \fIcupsd.conf(5)\fR file for the current setting.
 207
 208 .SH COMPATIBILITY
 209 While the filter interface is compatible with System V interface
 210 scripts, it will only work with the System V interface script as the
 211 only filter.  Typically the interface script will be provided via the
 212 \fIlpadmin(8)\fR command using the \fI-i\fR option.
 213 .SH SEE ALSO
 214 \fIbackend(1)\fR, \fIcupsd(8)\fR,
 215 .br
 216 http://localhost:631/help
 217 .SH COPYRIGHT
 218 Copyright 2007 by Apple Inc.
 219 .\"
 220 .\" End of "$Id: filter.man 6649 2007-07-11 21:46:42Z mike $".
 221 .\"