man/backend.man

   1 .\"
   2 .\" "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $"
   3 .\"
   4 .\"   Backend man page for the Common UNIX Printing System (CUPS).
   5 .\"
   6 .\"   Copyright 1997-2005 by Easy Software Products.
   7 .\"
   8 .\"   These coded instructions, statements, and computer programs are the
   9 .\"   property of Easy Software Products and are protected by Federal
  10 .\"   copyright law.  Distribution and use rights are outlined in the file
  11 .\"   "LICENSE.txt" which should have been included with this file.  If this
  12 .\"   file is missing or damaged please contact Easy Software Products
  13 .\"   at:
  14 .\"
  15 .\"       Attn: CUPS Licensing Information
  16 .\"       Easy Software Products
  17 .\"       44141 Airport View Drive, Suite 204
  18 .\"       Hollywood, Maryland 20636 USA
  19 .\"
  20 .\"       Voice: (301) 373-9600
  21 .\"       EMail: cups-info@cups.org
  22 .\"         WWW: http://www.cups.org
  23 .\"
  24 .TH backend 1 "Common UNIX Printing System" "15 December 2005" "Easy Software Products"
  25
  26 .SH NAME
  27 backend \- cups backend transmission interfaces
  28
  29 .SH SYNOPSIS
  30 .B backend
  31 .br
  32 .B backend
  33 job user title num-copies options [
  34 .I filename
  35 ]
  36
  37 .SH DESCRIPTION
  38 The CUPS backend interface provides a standard method for sending
  39 document files to different physical interfaces.
  40
  41 .LP
  42 Backends must be capable of reading from a filename on the
  43 command-line or from the standard input, copying the standard
  44 input to a temporary file if required by the physical interface.
  45
  46 .LP
  47 The command name (argv[0]) is set to the device URI of the
  48 destination printer. Starting with CUPS 1.1.22, any
  49 authentication information in argv[0] will be removed, so
  50 backend developers are urged to use the DEVICE_URI environment
  51 variable whenever authentication information is required.
  52
  53 .LP
  54 Backchannel data from the device should be relayed to the job
  55 filters by writing to file descriptor 3. The CUPS API includes
  56 the \fIcupsBackchannelWrite\fR function for this purpose.
  57
  58 .SH DEVICE DISCOVERY
  59 When run with no arguments, the backend should list the devices
  60 and schemes it supports or is advertising to stdout. The output
  61 consists of zero or more lines consisting of any of the following
  62 forms:
  63
  64 .nf
  65 device-class scheme "Unknown" "device-info"
  66 device-class device-uri "device-make-and-model" "device-info"
  67 device-class device-uri "device-make-and-model" "device-info" "device-id"
  68 .fi
  69
  70 .LP
  71 The \fIdevice-class\fR field is one of the following values:
  72
  73 .TP 5
  74 direct
  75 .br
  76 The device-uri refers to a specific direct-access device with no
  77 options, such as a parallel, USB, or SCSI device.
  78
  79 .TP 5
  80 file
  81 .br
  82 The device-uri refers to a file on disk.
  83
  84 .TP 5
  85 network
  86 .br
  87 The device-uri refers to a networked device and conforms to the
  88 general form for network URIs.
  89
  90 .TP 5
  91 serial
  92 .br
  93 The device-uri refers to a serial device with configurable baud
  94 rate and other options. If the device-uri contains a baud value,
  95 it represents the maximum baud rate supported by the device.
  96
  97 .LP
  98 The \fIscheme\fR field provides the URI scheme that is supported
  99 by the backend. Backends should use this form only when the
 100 backend supports any URI using that scheme. The \fIdevice-uri\fR
 101 field specifies the full URI to use when communicating with the
 102 device.
 103
 104 .LP
 105 The \fIdevice-make-and-model\fR field specifies the make and
 106 model of the device, e.g. "Acme Foojet 2000". If the make and
 107 model is not known, you must report "Unknown".
 108
 109 .LP
 110 The \fIdevice-info\fR field specifies additional information
 111 about the device. Typically this includes the make and model
 112 along with the port number or network address, e.g. "Acme Foojet
 113 2000 USB #1".
 114
 115 .LP
 116 The optional \fIdevice-id\fR field specifies the IEEE-1284 device
 117 ID string for the device, which is used to select a matching
 118 driver.
 119
 120 .SH EXIT CODES
 121 The following exit codes are defined for backends:
 122
 123 .TP 5
 124 0 (CUPS_BACKEND_OK)
 125 .br
 126 The print file was successfully transmitted to the device or
 127 remote server.
 128
 129 .TP 5
 130 1 (CUPS_BACKEND_FAILED)
 131 .br
 132 The print file was not successfully transmitted to the device or
 133 remote server. The scheduler will respond to this by canceling
 134 the job, retrying the job, or stopping the queue depending on the
 135 state of the error-policy attribute.
 136
 137 .TP 5
 138 2 (CUPS_BACKEND_CANCEL)
 139 .br
 140 The print file was not successfully transmitted because one or
 141 more attributes are not supported. The scheduler will respond to
 142 this by canceling the job.
 143
 144 .TP 5
 145 3 (CUPS_BACKEND_HOLD)
 146 .br
 147 The print file was not successfully transmitted because it cannot
 148 be printed at this time. The scheduler will respond to this by
 149 holding the job.
 150
 151 .TP 5
 152 4 (CUPS_BACKEND_STOP)
 153 .br
 154 The print file was not successfully transmitted because it cannot
 155 be printed at this time. The scheduler will respond to this by
 156 stopping the queue.
 157
 158 .TP 5
 159 5 (CUPS_BACKEND_AUTH_REQUIRED)
 160 .br
 161 The print file was not successfully transmitted because valid
 162 authentication information is required. The scheduler will
 163 respond to this by holding the job and adding the
 164 authentication-required job-reasons keyword.
 165
 166 .PP
 167 All other exit code values are reserved.
 168
 169 .SH LOG MESSAGES
 170 Messages sent to stderr are generally logged to
 171 printer-state-message attribute and the current ErrorLog. Each
 172 line begins with a standard prefix:
 173
 174 .TP 5
 175 ALERT: message
 176 .br
 177 Sets the printer-state-message attribute and adds the specified
 178 message to the current ErrorLog using the "alert" log level.
 179
 180 .TP 5
 181 ATTR: attribute=value [attribute=value]
 182 .br
 183 Sets the named job attribute(s). Typically this will be used to
 184 set the job-remote-id attribute.
 185
 186 .TP 5
 187 CRIT: message
 188 .br
 189 Sets the printer-state-message attribute and adds the specified
 190 message to the current ErrorLog using the "critical" log level.
 191
 192 .TP 5
 193 DEBUG: message
 194 .br
 195 Sets the printer-state-message attribute and adds the specified
 196 message to the current ErrorLog using the "debug" log level.
 197
 198 .TP 5
 199 DEBUG2: message
 200 .br
 201 Sets the printer-state-message attribute and adds the specified
 202 message to the current ErrorLog using the "debug2" log level.
 203
 204 .TP 5
 205 EMERG: message
 206 .br
 207 Sets the printer-state-message attribute and adds the specified
 208 message to the current ErrorLog using the "emergency" log level.
 209
 210 .TP 5
 211 ERROR: message
 212 .br
 213 Sets the printer-state-message attribute and adds the specified
 214 message to the current ErrorLog using the "error" log level.
 215
 216 .TP 5
 217 INFO: message
 218 .br
 219 Sets the printer-state-message attribute. If the current LogLevel
 220 is set to "debug2", also adds the specified message to the
 221 current ErrorLog using the "info" log level.
 222
 223 .TP 5
 224 NOTICE: message
 225 .br
 226 Sets the printer-state-message attribute and adds the specified
 227 message to the current ErrorLog using the "notice" log level.
 228
 229 .TP 5
 230 PAGE: page-number #-copies
 231 .TP 5
 232 PAGE: #-pages total
 233 .br
 234 Adds an entry to the current PageLog. The first form adds
 235 #-copies to the job-media-sheets-completed attribute. The second
 236 form sets the job-media-sheets-completed attribute to #-pages.
 237
 238 .TP 5
 239 STATE: printer-state-reason [printer-state-reason ...]
 240 .TP 5
 241 STATE: + printer-state-reason [printer-state-reason ...]
 242 .TP 5
 243 STATE: - printer-state-reason [printer-state-reason ...]
 244 .br
 245 Sets, adds, or removes printer-state-reason keywords to the
 246 current queue. Typically this is used to indicate media, ink, and
 247 toner conditions on a printer.
 248
 249 .TP 5
 250 WARNING: message
 251 .br
 252 Sets the printer-state-message attribute and adds the specified
 253 message to the current ErrorLog using the "warning" log level.
 254
 255 .SH ENVIRONMENT VARIABLES
 256 The following environment variables are defined by the CUPS
 257 server when executing the backend:
 258
 259 .TP 5
 260 CHARSET
 261 .br
 262 The default text character set, typically utf-8.
 263
 264 .TP 5
 265 CLASS
 266 .br
 267 When a job is submitted to a printer class, contains the name of
 268 the destination printer class. Otherwise this environment
 269 variable will not be set.
 270
 271 .TP 5
 272 CONTENT_TYPE
 273 .br
 274 The MIME type associated with the file (e.g.
 275 application/postscript).
 276
 277 .TP 5
 278 CUPS_DATADIR
 279 .br
 280 The directory where data files can be found.
 281
 282 .TP 5
 283 CUPS_SERVERROOT
 284 .br
 285 The root directory of the server.
 286
 287 .TP 5
 288 DEVICE_URI
 289 .br
 290 The device-uri associated with the printer; this is provided for
 291 shell scripts which may not be able to get the passed argv[0]
 292 string and for backends that require any authentication
 293 information which is not included in argv[0].
 294
 295 .TP 5
 296 LANG
 297 .br
 298 The default language locale (typically C or en).
 299
 300 .TP 5
 301 PATH
 302 .br
 303 The standard execution path for external programs that may be run by
 304 the backend.
 305
 306 .TP 5
 307 PPD
 308 .br
 309 The full pathname of the PostScript Printer Description (PPD)
 310 file for this printer.
 311
 312 .TP 5
 313 PRINTER
 314 .br
 315 The name of the printer.
 316
 317 .TP 5
 318 RIP_CACHE
 319 .br
 320 The recommended amount of memory to use for Raster Image
 321 Processors (RIPs).
 322
 323 .TP 5
 324 SOFTWARE
 325 .br
 326 The name and version number of the server (typically CUPS/1.1).
 327
 328 .TP 5
 329 TZ
 330 .br
 331 The timezone of the server.
 332
 333 .TP 5
 334 USER
 335 .br
 336 The user executing the backend, typically root; consult the
 337 cupsd.conf file for the current setting.
 338
 339 .SH SEE ALSO
 340 cupsd(8), filter(1)
 341 .br
 342 http://localhost:631/help
 343
 344 .SH COPYRIGHT
 345 Copyright 1993-2005 by Easy Software Products, All Rights Reserved.
 346 .\"
 347 .\" End of "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $".
 348 .\"