1*5e7646d2SAndroid Build Coastguard Worker<!DOCTYPE HTML> 2*5e7646d2SAndroid Build Coastguard Worker<html> 3*5e7646d2SAndroid Build Coastguard Worker<!-- SECTION: Man Pages --> 4*5e7646d2SAndroid Build Coastguard Worker<head> 5*5e7646d2SAndroid Build Coastguard Worker <link rel="stylesheet" type="text/css" href="../cups-printable.css"> 6*5e7646d2SAndroid Build Coastguard Worker <title>backend(7)</title> 7*5e7646d2SAndroid Build Coastguard Worker</head> 8*5e7646d2SAndroid Build Coastguard Worker<body> 9*5e7646d2SAndroid Build Coastguard Worker<h1 class="title">backend(7)</h1> 10*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="NAME">Name</a></h2> 11*5e7646d2SAndroid Build Coastguard Workerbackend - cups backend transmission interfaces 12*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2> 13*5e7646d2SAndroid Build Coastguard Worker<b>backend</b> 14*5e7646d2SAndroid Build Coastguard Worker<br> 15*5e7646d2SAndroid Build Coastguard Worker<b>backend</b> 16*5e7646d2SAndroid Build Coastguard Worker<i>job</i> 17*5e7646d2SAndroid Build Coastguard Worker<i>user</i> 18*5e7646d2SAndroid Build Coastguard Worker<i>title</i> 19*5e7646d2SAndroid Build Coastguard Worker<i>num-copies</i> 20*5e7646d2SAndroid Build Coastguard Worker<i>options</i> 21*5e7646d2SAndroid Build Coastguard Worker[ 22*5e7646d2SAndroid Build Coastguard Worker<i>filename</i> 23*5e7646d2SAndroid Build Coastguard Worker] 24*5e7646d2SAndroid Build Coastguard Worker<pre class="man"> 25*5e7646d2SAndroid Build Coastguard Worker 26*5e7646d2SAndroid Build Coastguard Worker<b>#include <cups/cups.h></b> 27*5e7646d2SAndroid Build Coastguard Worker 28*5e7646d2SAndroid Build Coastguard Worker<b>const char *cupsBackendDeviceURI</b>(<b>char **</b><i>argv</i>); 29*5e7646d2SAndroid Build Coastguard Worker 30*5e7646d2SAndroid Build Coastguard Worker<b>void cupsBackendReport</b>(<b>const char *</b><i>device_scheme</i>, 31*5e7646d2SAndroid Build Coastguard Worker <b>const char *</b><i>device_uri</i>, 32*5e7646d2SAndroid Build Coastguard Worker <b>const char *</b><i>device_make_and_model</i>, 33*5e7646d2SAndroid Build Coastguard Worker <b>const char *</b><i>device_info</i>, 34*5e7646d2SAndroid Build Coastguard Worker <b>const char *</b><i>device_id</i>, 35*5e7646d2SAndroid Build Coastguard Worker <b>const char *</b><i>device_location</i>); 36*5e7646d2SAndroid Build Coastguard Worker 37*5e7646d2SAndroid Build Coastguard Worker<b>ssize_t cupsBackChannelWrite</b>(<b>const char *</b><i>buffer</i>, 38*5e7646d2SAndroid Build Coastguard Worker <b>size_t </b><i>bytes</i>, <b>double </b><i>timeout</i>); 39*5e7646d2SAndroid Build Coastguard Worker 40*5e7646d2SAndroid Build Coastguard Worker<b>int cupsSideChannelRead</b>(<b>cups_sc_command_t *</b><i>command</i>, 41*5e7646d2SAndroid Build Coastguard Worker <b>cups_sc_status_t *</b><i>status</i>, <b>char *</b><i>data</i>, 42*5e7646d2SAndroid Build Coastguard Worker <b>int *</b><i>datalen</i>, <b>double </b><i>timeout</i>); 43*5e7646d2SAndroid Build Coastguard Worker 44*5e7646d2SAndroid Build Coastguard Worker<b>int cupsSideChannelWrite</b>(<b>cups_sc_command_t </b><i>command</i>, 45*5e7646d2SAndroid Build Coastguard Worker <b>cups_sc_status_t </b><i>status</i>, <b>const char *</b><i>data</i>, 46*5e7646d2SAndroid Build Coastguard Worker <b>int </b><i>datalen</i>, <b>double </b><i>timeout</i>); 47*5e7646d2SAndroid Build Coastguard Worker</pre> 48*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="DESCRIPTION">Description</a></h2> 49*5e7646d2SAndroid Build Coastguard WorkerBackends are a special type of 50*5e7646d2SAndroid Build Coastguard Worker<b>filter</b>(7) 51*5e7646d2SAndroid Build Coastguard Workerwhich is used to send print data to and discover different devices on the system. 52*5e7646d2SAndroid Build Coastguard Worker<p>Like filters, backends must be capable of reading from a filename on the command-line or from the standard input, copying the standard input to a temporary file as required by the physical interface. 53*5e7646d2SAndroid Build Coastguard Worker<p>The command name (<i>argv[0]</i>) is set to the device URI of the destination printer. 54*5e7646d2SAndroid Build Coastguard WorkerAuthentication information in 55*5e7646d2SAndroid Build Coastguard Worker<i>argv[0]</i> 56*5e7646d2SAndroid Build Coastguard Workeris removed, so backend developers are urged to use the 57*5e7646d2SAndroid Build Coastguard Worker<b>DEVICE_URI</b> 58*5e7646d2SAndroid Build Coastguard Workerenvironment variable whenever authentication information is required. The 59*5e7646d2SAndroid Build Coastguard Worker<b>cupsBackendDeviceURI</b>() 60*5e7646d2SAndroid Build Coastguard Workerfunction may be used to retrieve the correct device URI. 61*5e7646d2SAndroid Build Coastguard Worker<p>Back-channel data from the device should be relayed to the job filters using the <i>cupsBackChannelWrite</i> function. 62*5e7646d2SAndroid Build Coastguard Worker<p>Backends are responsible for reading side-channel requests using the 63*5e7646d2SAndroid Build Coastguard Worker<b>cupsSideChannelRead</b>() 64*5e7646d2SAndroid Build Coastguard Workerfunction and responding with the 65*5e7646d2SAndroid Build Coastguard Worker<b>cupsSideChannelWrite</b>() 66*5e7646d2SAndroid Build Coastguard Workerfunction. The 67*5e7646d2SAndroid Build Coastguard Worker<b>CUPS_SC_FD</b> 68*5e7646d2SAndroid Build Coastguard Workerconstant defines the file descriptor that should be monitored for incoming requests. 69*5e7646d2SAndroid Build Coastguard Worker<h3><a name="DEVICE_DISCOVERY">Device Discovery</a></h3> 70*5e7646d2SAndroid Build Coastguard WorkerWhen run with no arguments, the backend should list the devices and schemes it supports or is advertising to the standard output. 71*5e7646d2SAndroid Build Coastguard WorkerThe output consists of zero or more lines consisting of any of the following forms: 72*5e7646d2SAndroid Build Coastguard Worker<pre class="man"> 73*5e7646d2SAndroid Build Coastguard Worker 74*5e7646d2SAndroid Build Coastguard Worker device-class scheme "Unknown" "device-info" 75*5e7646d2SAndroid Build Coastguard Worker device-class device-uri "device-make-and-model" "device-info" 76*5e7646d2SAndroid Build Coastguard Worker device-class device-uri "device-make-and-model" "device-info" "device-id" 77*5e7646d2SAndroid Build Coastguard Worker device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location" 78*5e7646d2SAndroid Build Coastguard Worker</pre> 79*5e7646d2SAndroid Build Coastguard Worker<p>The 80*5e7646d2SAndroid Build Coastguard Worker<b>cupsBackendReport</b>() 81*5e7646d2SAndroid Build Coastguard Workerfunction can be used to generate these lines and handle any necessary escaping of characters in the various strings. 82*5e7646d2SAndroid Build Coastguard Worker<p>The 83*5e7646d2SAndroid Build Coastguard Worker<i>device-class</i> 84*5e7646d2SAndroid Build Coastguard Workerfield is one of the following values: 85*5e7646d2SAndroid Build Coastguard Worker<dl class="man"> 86*5e7646d2SAndroid Build Coastguard Worker<dt><b>direct</b> 87*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The device-uri refers to a specific direct-access device with no options, such as a parallel, USB, or SCSI device. 88*5e7646d2SAndroid Build Coastguard Worker<dt><b>file</b> 89*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The device-uri refers to a file on disk. 90*5e7646d2SAndroid Build Coastguard Worker<dt><b>network</b> 91*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The device-uri refers to a networked device and conforms to the general form for 92*5e7646d2SAndroid Build Coastguard Workernetwork URIs. 93*5e7646d2SAndroid Build Coastguard Worker<dt><b>serial</b> 94*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The device-uri refers to a serial device with configurable baud rate and other options. 95*5e7646d2SAndroid Build Coastguard WorkerIf the device-uri contains a baud value, it represents the maximum baud rate supported by the device. 96*5e7646d2SAndroid Build Coastguard Worker</dl> 97*5e7646d2SAndroid Build Coastguard Worker<p>The 98*5e7646d2SAndroid Build Coastguard Worker<i>scheme</i> 99*5e7646d2SAndroid Build Coastguard Workerfield provides the URI scheme that is supported by the backend. 100*5e7646d2SAndroid Build Coastguard WorkerBackends should use this form only when the backend supports any URI using that scheme. 101*5e7646d2SAndroid Build Coastguard WorkerThe 102*5e7646d2SAndroid Build Coastguard Worker<i>device-uri</i> 103*5e7646d2SAndroid Build Coastguard Workerfield specifies the full URI to use when communicating with the device. 104*5e7646d2SAndroid Build Coastguard Worker<p>The 105*5e7646d2SAndroid Build Coastguard Worker<i>device-make-and-model</i> 106*5e7646d2SAndroid Build Coastguard Workerfield specifies the make and model of the device, e.g. "Example Foojet 2000". 107*5e7646d2SAndroid Build Coastguard WorkerIf the make and model is not known, you must report "Unknown". 108*5e7646d2SAndroid Build Coastguard Worker<p>The 109*5e7646d2SAndroid Build Coastguard Worker<i>device-info</i> 110*5e7646d2SAndroid Build Coastguard Workerfield specifies additional information about the device. 111*5e7646d2SAndroid Build Coastguard WorkerTypically this includes the make and model along with the port number or network address, e.g. "Example Foojet 2000 USB #1". 112*5e7646d2SAndroid Build Coastguard Worker<p>The optional 113*5e7646d2SAndroid Build Coastguard Worker<i>device-id</i> 114*5e7646d2SAndroid Build Coastguard Workerfield specifies the IEEE-1284 device ID string for the device, which is used to select a matching driver. 115*5e7646d2SAndroid Build Coastguard Worker<p>The optional 116*5e7646d2SAndroid Build Coastguard Worker<i>device-location</i> 117*5e7646d2SAndroid Build Coastguard Workerfield specifies the physical location of the device, which is often used to pre-populate the printer-location attribute when adding a printer. 118*5e7646d2SAndroid Build Coastguard Worker<h3><a name="PERMISSIONS">Permissions</a></h3> 119*5e7646d2SAndroid Build Coastguard WorkerBackends without world read and execute permissions are run as the root user. 120*5e7646d2SAndroid Build Coastguard WorkerOtherwise, the backend is run using an unprivileged user account, typically "lp". 121*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="EXIT_STATUS">Exit Status</a></h2> 122*5e7646d2SAndroid Build Coastguard WorkerThe following exit codes are defined for backends: 123*5e7646d2SAndroid Build Coastguard Worker<dl class="man"> 124*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_OK</b> 125*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was successfully transmitted to the device or remote server. 126*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_FAILED</b> 127*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em"><br> 128*5e7646d2SAndroid Build Coastguard WorkerThe print file was not successfully transmitted to the device or remote server. 129*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will respond to this by canceling the job, retrying the job, or stopping the queue depending on the state of the 130*5e7646d2SAndroid Build Coastguard Worker<i>printer-error-policy</i> 131*5e7646d2SAndroid Build Coastguard Workerattribute. 132*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_AUTH_REQUIRED</b> 133*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because valid authentication information is required. 134*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will respond to this by holding the job and adding the 'cups-held-for-authentication' keyword to the "job-reasons" Job Description attribute. 135*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_HOLD</b> 136*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because it cannot be printed at this time. 137*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will respond to this by holding the job. 138*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_STOP</b> 139*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because it cannot be printed at this time. 140*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will respond to this by stopping the queue. 141*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_CANCEL</b> 142*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because one or more attributes are not supported or the job was canceled at the printer. 143*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will respond to this by canceling the job. 144*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_RETRY</b> 145*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because of a temporary issue. 146*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will retry the job at a future time - other jobs may print before this one. 147*5e7646d2SAndroid Build Coastguard Worker<dt><b>CUPS_BACKEND_RETRY_CURRENT</b> 148*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The print file was not successfully transmitted because of a temporary issue. 149*5e7646d2SAndroid Build Coastguard WorkerThe scheduler will retry the job immediately without allowing intervening jobs. 150*5e7646d2SAndroid Build Coastguard Worker</dl> 151*5e7646d2SAndroid Build Coastguard Worker<p>All other exit code values are reserved. 152*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="ENVIRONMENT">Environment</a></h2> 153*5e7646d2SAndroid Build Coastguard WorkerIn addition to the environment variables listed in 154*5e7646d2SAndroid Build Coastguard Worker<b>cups</b>(1) 155*5e7646d2SAndroid Build Coastguard Workerand 156*5e7646d2SAndroid Build Coastguard Worker<b>filter</b>(7), 157*5e7646d2SAndroid Build Coastguard WorkerCUPS backends can expect the following environment variable: 158*5e7646d2SAndroid Build Coastguard Worker<dl class="man"> 159*5e7646d2SAndroid Build Coastguard Worker<dt><b>DEVICE_URI</b> 160*5e7646d2SAndroid Build Coastguard Worker<dd style="margin-left: 5.0em">The device URI associated with the printer. 161*5e7646d2SAndroid Build Coastguard Worker</dl> 162*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="FILES">Files</a></h2> 163*5e7646d2SAndroid Build Coastguard Worker<i>/etc/cups/cups-files.conf</i> 164*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="NOTES">Notes</a></h2> 165*5e7646d2SAndroid Build Coastguard WorkerCUPS backends are not generally designed to be run directly by the user. 166*5e7646d2SAndroid Build Coastguard WorkerAside from the device URI issue ( 167*5e7646d2SAndroid Build Coastguard Worker<i>argv[0]</i> 168*5e7646d2SAndroid Build Coastguard Workerand 169*5e7646d2SAndroid Build Coastguard Worker<b>DEVICE_URI</b> 170*5e7646d2SAndroid Build Coastguard Workerenvironment variable contain the device URI), CUPS backends also expect specific environment variables and file descriptors, and typically run in a user session that (on macOS) has additional restrictions that affect how it runs. 171*5e7646d2SAndroid Build Coastguard WorkerBackends can also be installed with restricted permissions (0500 or 0700) that tell the scheduler to run them as the "root" user instead of an unprivileged user (typically "lp") on the system. 172*5e7646d2SAndroid Build Coastguard Worker<p>Unless you are a developer and know what you are doing, please do not run backends directly. 173*5e7646d2SAndroid Build Coastguard WorkerInstead, use the 174*5e7646d2SAndroid Build Coastguard Worker<b>lp</b>(1) 175*5e7646d2SAndroid Build Coastguard Workeror 176*5e7646d2SAndroid Build Coastguard Worker<b>lpr</b>(1) 177*5e7646d2SAndroid Build Coastguard Workerprograms to send print jobs or 178*5e7646d2SAndroid Build Coastguard Worker<b>lpinfo</b>(8) 179*5e7646d2SAndroid Build Coastguard Workerto query for available printers using the backend. 180*5e7646d2SAndroid Build Coastguard WorkerThe one exception is the SNMP backend - see 181*5e7646d2SAndroid Build Coastguard Worker<b>cups-snmp</b>(8) 182*5e7646d2SAndroid Build Coastguard Workerfor more information. 183*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="NOTES">Notes</a></h2> 184*5e7646d2SAndroid Build Coastguard WorkerCUPS printer drivers and backends are deprecated and will no longer be supported in a future feature release of CUPS. 185*5e7646d2SAndroid Build Coastguard WorkerPrinters that do not support IPP can be supported using applications such as 186*5e7646d2SAndroid Build Coastguard Worker<b>ippeveprinter</b>(1). 187*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="SEE_ALSO">See Also</a></h2> 188*5e7646d2SAndroid Build Coastguard Worker<i>cups</i>(1), 189*5e7646d2SAndroid Build Coastguard Worker<i>cups-files.conf</i>(5), 190*5e7646d2SAndroid Build Coastguard Worker<i>cups-snmp</i>(8), 191*5e7646d2SAndroid Build Coastguard Worker<i>cupsd</i>(8), 192*5e7646d2SAndroid Build Coastguard Worker<i>filter</i>(7), 193*5e7646d2SAndroid Build Coastguard Worker<i>lp</i>(1), 194*5e7646d2SAndroid Build Coastguard Worker<i>lpinfo</i>(8), 195*5e7646d2SAndroid Build Coastguard Worker<i>lpr</i>(1), 196*5e7646d2SAndroid Build Coastguard Worker<br> 197*5e7646d2SAndroid Build Coastguard WorkerCUPS Online Help (<a href="http://localhost:631/help">http://localhost:631/help</a>) 198*5e7646d2SAndroid Build Coastguard Worker<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> 199*5e7646d2SAndroid Build Coastguard WorkerCopyright © 2007-2019 by Apple Inc. 200*5e7646d2SAndroid Build Coastguard Worker 201*5e7646d2SAndroid Build Coastguard Worker</body> 202*5e7646d2SAndroid Build Coastguard Worker</html> 203