1backend(7)                        Apple Inc.                        backend(7)
2
3
4

NAME

6       backend - cups backend transmission interfaces
7

SYNOPSIS

9       backend
10       backend job user title num-copies options [ filename ]
11
12       #include <cups/cups.h>
13
14       const char *cupsBackendDeviceURI(char **argv);
15
16       void cupsBackendReport(const char *device_scheme,
17                              const char *device_uri,
18                              const char *device_make_and_model,
19                              const char *device_info,
20                              const char *device_id,
21                              const char *device_location);
22
23       ssize_t cupsBackChannelWrite(const char *buffer,
24                                    size_t bytes, double timeout);
25
26       int cupsSideChannelRead(cups_sc_command_t *command,
27                               cups_sc_status_t *status, char *data,
28                               int *datalen, double timeout);
29
30       int cupsSideChannelWrite(cups_sc_command_t command,
31                                cups_sc_status_t status, const char *data,
32                                int datalen, double timeout);
33

DESCRIPTION

35       Backends  are  a  special type of filter(7) which is used to send print
36       data to and discover different devices on the system.
37
38       Like filters, backends must be capable of reading from  a  filename  on
39       the command-line or from the standard input, copying the standard input
40       to a temporary file as required by the physical interface.
41
42       The command name (argv[0]) is set to the device URI of the  destination
43       printer.   Authentication information in argv[0] is removed, so backend
44       developers are urged to use the DEVICE_URI environment  variable  when‐
45       ever authentication information is required. The cupsBackendDeviceURI()
46       function may be used to retrieve the correct device URI.
47
48       Back-channel data from the device should be relayed to the job  filters
49       using the cupsBackChannelWrite function.
50
51       Backends  are  responsible  for reading side-channel requests using the
52       cupsSideChannelRead() function and responding with the cupsSideChannel‐
53       Write()  function.  The CUPS_SC_FD constant defines the file descriptor
54       that should be monitored for incoming requests.
55
56   DEVICE DISCOVERY
57       When run with no arguments, the backend should  list  the  devices  and
58       schemes it supports or is advertising to the standard output.  The out‐
59       put consists of zero or more lines consisting of any of  the  following
60       forms:
61
62           device-class scheme "Unknown" "device-info"
63           device-class device-uri "device-make-and-model" "device-info"
64           device-class device-uri "device-make-and-model" "device-info" "device-id"
65           device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location"
66
67       The  cupsBackendReport()  function  can be used to generate these lines
68       and handle any necessary escaping of characters in the various strings.
69
70       The device-class field is one of the following values:
71
72       direct
73            The device-uri refers to a specific direct-access device  with  no
74            options, such as a parallel, USB, or SCSI device.
75
76       file The device-uri refers to a file on disk.
77
78       network
79            The  device-uri  refers  to a networked device and conforms to the
80            general form for network URIs.
81
82       serial
83            The device-uri refers to a serial device  with  configurable  baud
84            rate  and other options.  If the device-uri contains a baud value,
85            it represents the maximum baud rate supported by the device.
86
87       The scheme field provides the URI scheme that is supported by the back‐
88       end.   Backends should use this form only when the backend supports any
89       URI using that scheme.  The device-uri field specifies the full URI  to
90       use when communicating with the device.
91
92       The  device-make-and-model  field  specifies  the make and model of the
93       device, e.g. "Example Foojet 2000".  If  the  make  and  model  is  not
94       known, you must report "Unknown".
95
96       The  device-info  field  specifies  additional  information  about  the
97       device.  Typically this includes the make and model along with the port
98       number or network address, e.g. "Example Foojet 2000 USB #1".
99
100       The  optional  device-id field specifies the IEEE-1284 device ID string
101       for the device, which is used to select a matching driver.
102
103       The optional device-location field specifies the physical  location  of
104       the  device,  which  is often used to pre-populate the printer-location
105       attribute when adding a printer.
106
107   PERMISSIONS
108       Backends without world read and execute permissions are run as the root
109       user.   Otherwise,  the  backend  is  run  using  an  unprivileged user
110       account, typically "lp".
111

EXIT STATUS

113       The following exit codes are defined for backends:
114
115       CUPS_BACKEND_OK
116            The print file was  successfully  transmitted  to  the  device  or
117            remote server.
118
119       CUPS_BACKEND_FAILED
120            The  print  file was not successfully transmitted to the device or
121            remote server.  The scheduler will respond to  this  by  canceling
122            the  job, retrying the job, or stopping the queue depending on the
123            state of the printer-error-policy attribute.
124
125       CUPS_BACKEND_AUTH_REQUIRED
126            The print file was  not  successfully  transmitted  because  valid
127            authentication   information  is  required.   The  scheduler  will
128            respond to this by holding the job and adding the  'cups-held-for-
129            authentication'  keyword  to  the  "job-reasons"  Job  Description
130            attribute.
131
132       CUPS_BACKEND_HOLD
133            The print file was not successfully transmitted because it  cannot
134            be  printed  at  this time.  The scheduler will respond to this by
135            holding the job.
136
137       CUPS_BACKEND_STOP
138            The print file was not successfully transmitted because it  cannot
139            be  printed  at  this time.  The scheduler will respond to this by
140            stopping the queue.
141
142       CUPS_BACKEND_CANCEL
143            The print file was not successfully  transmitted  because  one  or
144            more  attributes  are not supported or the job was canceled at the
145            printer.  The scheduler will respond to this by canceling the job.
146
147       CUPS_BACKEND_RETRY
148            The print file was not successfully transmitted because of a  tem‐
149            porary issue.  The scheduler will retry the job at a future time -
150            other jobs may print before this one.
151
152       CUPS_BACKEND_RETRY_CURRENT
153            The print file was not successfully transmitted because of a  tem‐
154            porary  issue.  The scheduler will retry the job immediately with‐
155            out allowing intervening jobs.
156
157       All other exit code values are reserved.
158

ENVIRONMENT

160       In addition to the environment variables listed  in  cups(1)  and  fil‐
161       ter(7), CUPS backends can expect the following environment variable:
162
163       DEVICE_URI
164            The device URI associated with the printer.
165

FILES

167       /etc/cups/cups-files.conf
168

NOTES

170       CUPS  backends  are  not  generally  designed to be run directly by the
171       user.  Aside from the device URI issue ( argv[0] and  DEVICE_URI  envi‐
172       ronment  variable  contain  the  device URI), CUPS backends also expect
173       specific environment variables and file descriptors, and typically  run
174       in  a  user  session  that  (on macOS) has additional restrictions that
175       affect how it runs.  Backends can also  be  installed  with  restricted
176       permissions  (0500  or 0700) that tell the scheduler to run them as the
177       "root" user instead of an unprivileged user  (typically  "lp")  on  the
178       system.
179
180       Unless  you  are a developer and know what you are doing, please do not
181       run backends directly.  Instead, use the lp(1) or  lpr(1)  programs  to
182       send  print jobs or lpinfo(8) to query for available printers using the
183       backend.  The one exception is the SNMP backend - see cups-snmp(8)  for
184       more information.
185

NOTES

187       CUPS  printer drivers and backends are deprecated and will no longer be
188       supported in a future feature release of CUPS.  Printers  that  do  not
189       support   IPP   can   be   supported   using   applications   such   as
190       ippeveprinter(1).
191

SEE ALSO

193       cups(1), cups-files.conf(5), cups-snmp(8), cupsd(8), filter(7),  lp(1),
194       lpinfo(8), lpr(1),
195       CUPS Online Help (http://localhost:631/help)
196
198       Copyright © 2007-2019 by Apple Inc.
199
200
201
20226 April 2019                        CUPS                           backend(7)
Impressum