]>
Commit | Line | Data |
---|---|---|
c277f98c | 1 | <!DOCTYPE HTML> |
94436c5a MS |
2 | <html> |
3 | <!-- SECTION: Man Pages --> | |
4 | <head> | |
5 | <link rel="stylesheet" type="text/css" href="../cups-printable.css"> | |
6 | <title>backend(7)</title> | |
7 | </head> | |
8 | <body> | |
9 | <h1 class="title">backend(7)</h1> | |
10 | ||
11 | <h2 class="title"><a name="NAME">Name</a></h2> | |
12 | backend - cups backend transmission interfaces | |
13 | <h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2> | |
c277f98c MS |
14 | <b>backend</b> |
15 | <br> | |
16 | <b>backend</b> | |
17 | job user title num-copies options [ | |
18 | <i>filename</i> | |
19 | ] | |
94436c5a | 20 | <h2 class="title"><a name="DESCRIPTION">Description</a></h2> |
c277f98c | 21 | Backends are a special type of <i>filter(7)</i> which is used to send print data |
94436c5a MS |
22 | to and discover different devices on the system. |
23 | <p>Like filters, backends must be capable of reading from a filename on the | |
24 | command-line or from the standard input, copying the standard input to a | |
25 | temporary file as required by the physical interface. | |
26 | <p>The command name (argv[0]) is set to the device URI of the destination printer. | |
27 | Starting with CUPS 1.1.22, any authentication information in argv[0] is removed, | |
28 | so backend developers are urged to use the DEVICE_URI environment variable | |
29 | whenever authentication information is required. The CUPS API includes a | |
30 | <i>cupsBackendDeviceURI</i> function for retrieving the correct device URI. | |
31 | <p>Back-channel data from the device should be relayed to the job | |
32 | filters by writing to file descriptor 3. The CUPS API includes | |
33 | the <i>cupsBackChannelWrite</i> function for this purpose. | |
34 | <h2 class="title"><a name="WARNING">Warning</a></h2> | |
35 | CUPS backends are not generally design to be run directly by the user. Aside | |
36 | from the device URI issue (argv[0] and DEVICE_URI environment variable contain | |
37 | the device URI), CUPS backends also expect specific environment variables and | |
38 | file descriptors, and typically run in a user session that (on OS X) has | |
39 | additional restrictions that affect how it runs. Backends can also be installed | |
40 | with restricted permissions (0500 or 0700) that tell the scheduler to run them | |
41 | as the "root" user instead of an unprivileged user (typically "lp") on the | |
42 | system. | |
43 | <p>Unless you are a developer and know what you are doing, please do not run | |
c277f98c MS |
44 | backends directly. Instead, use the <i>lp(1)</i> or <i>lpr(1)</i> programs to send |
45 | a print job or <i>lpinfo(8)</i> program to query for available printers using the | |
94436c5a MS |
46 | backend. The one exception is the SNMP backend - see <i>snmpbackend(8)</i> for |
47 | more information. | |
48 | <h2 class="title"><a name="DEVICE_DISCOVERY">Device Discovery</a></h2> | |
49 | When run with no arguments, the backend should list the devices and schemes it | |
50 | supports or is advertising to stdout. The output consists of zero or more lines | |
51 | consisting of any of the following forms: | |
52 | ||
53 | <pre> | |
54 | device-class scheme "Unknown" "device-info" | |
55 | device-class device-uri "device-make-and-model" "device-info" | |
56 | device-class device-uri "device-make-and-model" "device-info" "device-id" | |
57 | device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location" | |
58 | </pre> | |
59 | <p>The <i>device-class</i> field is one of the following values: | |
c277f98c MS |
60 | <p style="margin-left: 5.0em; text-indent: -5.0em">direct |
61 | <br> | |
62 | <br> | |
63 | The device-uri refers to a specific direct-access device with no options, such | |
94436c5a | 64 | as a parallel, USB, or SCSI device. |
c277f98c MS |
65 | <p style="margin-left: 5.0em; text-indent: -5.0em">file |
66 | <br> | |
67 | <br> | |
68 | The device-uri refers to a file on disk. | |
69 | <p style="margin-left: 5.0em; text-indent: -5.0em">network | |
70 | <br> | |
71 | <br> | |
72 | The device-uri refers to a networked device and conforms to the general form for | |
94436c5a | 73 | network URIs. |
c277f98c MS |
74 | <p style="margin-left: 5.0em; text-indent: -5.0em">serial |
75 | <br> | |
76 | <br> | |
77 | The device-uri refers to a serial device with configurable baud rate and other | |
94436c5a MS |
78 | options. If the device-uri contains a baud value, it represents the maximum baud |
79 | rate supported by the device. | |
94436c5a MS |
80 | <p>The <i>scheme</i> field provides the URI scheme that is supported by the backend. |
81 | Backends should use this form only when the backend supports any URI using that | |
82 | scheme. The <i>device-uri</i> field specifies the full URI to use when | |
83 | communicating with the device. | |
84 | <p>The <i>device-make-and-model</i> field specifies the make and model of the | |
85 | device, e.g. "Example Foojet 2000". If the make and model is not known, you must | |
86 | report "Unknown". | |
87 | <p>The <i>device-info</i> field specifies additional information about the device. | |
88 | Typically this includes the make and model along with the port number or network | |
89 | address, e.g. "Example Foojet 2000 USB #1". | |
90 | <p>The optional <i>device-id</i> field specifies the IEEE-1284 device ID string for | |
91 | the device, which is used to select a matching driver. | |
92 | <p>The optional <i>device-location</i> field specifies the physical location of | |
93 | the device, which is often used to pre-populate the printer-location attribute | |
94 | when adding a printer. | |
95 | <h2 class="title"><a name="PERMISSIONS">Permissions</a></h2> | |
96 | Backends without world execute permissions are run as the root user. Otherwise, | |
97 | the backend is run using an unprivileged user account, typically "lp". | |
98 | <h2 class="title"><a name="EXIT_CODES">Exit Codes</a></h2> | |
99 | The following exit codes are defined for backends; C API constants defined in | |
100 | the <cups/backend.h> header file are defined in parenthesis: | |
c277f98c MS |
101 | <p style="margin-left: 5.0em; text-indent: -5.0em">0 (CUPS_BACKEND_OK) |
102 | <br> | |
103 | <br> | |
104 | The print file was successfully transmitted to the device or remote server. | |
105 | <p style="margin-left: 5.0em; text-indent: -5.0em">1 (CUPS_BACKEND_FAILED) | |
106 | <br> | |
107 | <br> | |
108 | The print file was not successfully transmitted to the device or remote server. | |
94436c5a MS |
109 | The scheduler will respond to this by canceling the job, retrying the job, or |
110 | stopping the queue depending on the state of the error-policy attribute. | |
c277f98c MS |
111 | <p style="margin-left: 5.0em; text-indent: -5.0em">2 (CUPS_BACKEND_AUTH_REQUIRED) |
112 | <br> | |
113 | <br> | |
114 | The print file was not successfully transmitted because valid authentication | |
94436c5a MS |
115 | information is required. The scheduler will respond to this by holding the job |
116 | and adding the "cups-held-for-authentication" keyword to the "job-reasons" | |
117 | attribute. | |
c277f98c MS |
118 | <p style="margin-left: 5.0em; text-indent: -5.0em">3 (CUPS_BACKEND_HOLD) |
119 | <br> | |
120 | <br> | |
121 | The print file was not successfully transmitted because it cannot be printed at | |
94436c5a | 122 | this time. The scheduler will respond to this by holding the job. |
c277f98c MS |
123 | <p style="margin-left: 5.0em; text-indent: -5.0em">4 (CUPS_BACKEND_STOP) |
124 | <br> | |
125 | <br> | |
126 | The print file was not successfully transmitted because it cannot be printed at | |
94436c5a | 127 | this time. The scheduler will respond to this by stopping the queue. |
c277f98c MS |
128 | <p style="margin-left: 5.0em; text-indent: -5.0em">5 (CUPS_BACKEND_CANCEL) |
129 | <br> | |
130 | <br> | |
131 | The print file was not successfully transmitted because one or more attributes | |
94436c5a MS |
132 | are not supported or the job was canceled at the printer. The scheduler will |
133 | respond to this by canceling the job. | |
c277f98c MS |
134 | <p style="margin-left: 5.0em; text-indent: -5.0em">6 (CUPS_BACKEND_RETRY) |
135 | <br> | |
136 | <br> | |
137 | The print file was not successfully transmitted because of a temporary issue. | |
94436c5a MS |
138 | The scheduler will retry the job at a future time - other jobs may print before |
139 | this one. | |
c277f98c MS |
140 | <p style="margin-left: 5.0em; text-indent: -5.0em">7 (CUPS_BACKEND_RETRY_CURRENT) |
141 | <br> | |
142 | <br> | |
143 | The print file was not successfully transmitted because of a temporary issue. | |
94436c5a | 144 | The scheduler will retry the job immediately without allowing intervening jobs. |
94436c5a MS |
145 | <p>All other exit code values are reserved. |
146 | <h2 class="title"><a name="SEE_ALSO">See Also</a></h2> | |
c277f98c MS |
147 | <i>cups-snmp(8)</i>, <i>cupsd(8)</i>, <i>cupsd.conf(5)</i>, <i>filter(7)</i>, |
148 | <i>lpinfo(8)</i>, | |
94436c5a | 149 | <br> |
c277f98c | 150 | <a href="http://localhost:631/help">http://localhost:631/help</a> |
94436c5a MS |
151 | <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> |
152 | Copyright 2007-2013 by Apple Inc. | |
153 | ||
154 | </body> | |
155 | </html> |