man/backend.man

   1 .\"
   2 .\" "$Id: backend.man 177 2006-06-21 00:20:03Z jlovell $"
   3 .\"
   4 .\"   Backend man page for the Common UNIX Printing System (CUPS).
   5 .\"
   6 .\"   Copyright 1997-2006 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 7 "Common UNIX Printing System" "20 March 2006" "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 Backends are a special type of \fIfilter(7)\fR which is used to
  39 send print data to and discover different devices on the system.
  40
  41 .LP
  42 Like filters, backends must be capable of reading from a filename
  43 on the command-line or from the standard input, copying the
  44 standard input to a temporary file as required by the physical
  45 interface.
  46
  47 .LP
  48 The command name (argv[0]) is set to the device URI of the
  49 destination printer. Starting with CUPS 1.1.22, any
  50 authentication information in argv[0] is removed, so
  51 backend developers are urged to use the DEVICE_URI environment
  52 variable whenever authentication information is required. The
  53 CUPS API includes a \fIcupsBackendDeviceURI\fR function for
  54 retrieving the correct device URI.
  55
  56 .LP
  57 Back-channel data from the device should be relayed to the job
  58 filters by writing to file descriptor 3. The CUPS API includes
  59 the \fIcupsBackChannelWrite\fR function for this purpose.
  60
  61 .SH DEVICE DISCOVERY
  62 When run with no arguments, the backend should list the devices
  63 and schemes it supports or is advertising to stdout. The output
  64 consists of zero or more lines consisting of any of the following
  65 forms:
  66
  67 .nf
  68     device-class scheme "Unknown" "device-info"
  69     device-class device-uri "device-make-and-model" "device-info"
  70     device-class device-uri "device-make-and-model" "device-info" "device-id"
  71 .fi
  72
  73 .LP
  74 The \fIdevice-class\fR field is one of the following values:
  75
  76 .TP 5
  77 direct
  78 .br
  79 The device-uri refers to a specific direct-access device with no
  80 options, such as a parallel, USB, or SCSI device.
  81
  82 .TP 5
  83 file
  84 .br
  85 The device-uri refers to a file on disk.
  86
  87 .TP 5
  88 network
  89 .br
  90 The device-uri refers to a networked device and conforms to the
  91 general form for network URIs.
  92
  93 .TP 5
  94 serial
  95 .br
  96 The device-uri refers to a serial device with configurable baud
  97 rate and other options. If the device-uri contains a baud value,
  98 it represents the maximum baud rate supported by the device.
  99
 100 .LP
 101 The \fIscheme\fR field provides the URI scheme that is supported
 102 by the backend. Backends should use this form only when the
 103 backend supports any URI using that scheme. The \fIdevice-uri\fR
 104 field specifies the full URI to use when communicating with the
 105 device.
 106
 107 .LP
 108 The \fIdevice-make-and-model\fR field specifies the make and
 109 model of the device, e.g. "Acme Foojet 2000". If the make and
 110 model is not known, you must report "Unknown".
 111
 112 .LP
 113 The \fIdevice-info\fR field specifies additional information
 114 about the device. Typically this includes the make and model
 115 along with the port number or network address, e.g. "Acme Foojet
 116 2000 USB #1".
 117
 118 .LP
 119 The optional \fIdevice-id\fR field specifies the IEEE-1284 device
 120 ID string for the device, which is used to select a matching
 121 driver.
 122
 123 .SH PERMISSIONS
 124 Backends without world execute permissions are run as the root
 125 user. Otherwise, the backend is run using the unprivileged user
 126 account, typically "lp".
 127
 128 .SH EXIT CODES
 129 The following exit codes are defined for backends; C API
 130 constants defined in the <cups/backend.h> header file are defined
 131 in parenthesis:
 132
 133 .TP 5
 134 0 (CUPS_BACKEND_OK)
 135 .br
 136 The print file was successfully transmitted to the device or
 137 remote server.
 138
 139 .TP 5
 140 1 (CUPS_BACKEND_FAILED)
 141 .br
 142 The print file was not successfully transmitted to the device or
 143 remote server. The scheduler will respond to this by canceling
 144 the job, retrying the job, or stopping the queue depending on the
 145 state of the error-policy attribute.
 146
 147 .TP 5
 148 2 (CUPS_BACKEND_AUTH_REQUIRED)
 149 .br
 150 The print file was not successfully transmitted because valid
 151 authentication information is required. The scheduler will
 152 respond to this by holding the job and adding the
 153 authentication-required job-reasons keyword.
 154
 155 .TP 5
 156 3 (CUPS_BACKEND_HOLD)
 157 .br
 158 The print file was not successfully transmitted because it cannot
 159 be printed at this time. The scheduler will respond to this by
 160 holding the job.
 161
 162 .TP 5
 163 4 (CUPS_BACKEND_STOP)
 164 .br
 165 The print file was not successfully transmitted because it cannot
 166 be printed at this time. The scheduler will respond to this by
 167 stopping the queue.
 168
 169 .TP 5
 170 5 (CUPS_BACKEND_CANCEL)
 171 .br
 172 The print file was not successfully transmitted because one or
 173 more attributes are not supported. The scheduler will respond to
 174 this by canceling the job.
 175
 176 .PP
 177 All other exit code values are reserved.
 178
 179 .SH SEE ALSO
 180 \fIcupsd(8)\fR, \fIcupsd.conf(5)\fR, \fIfilter(7)\fR
 181 .br
 182 http://localhost:631/help
 183
 184 .SH COPYRIGHT
 185 Copyright 1997-2006 by Easy Software Products, All Rights Reserved.
 186 .\"
 187 .\" End of "$Id: backend.man 177 2006-06-21 00:20:03Z jlovell $".
 188 .\"