]>
Commit | Line | Data |
---|---|---|
94436c5a MS |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
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> | |
14 | <b>backend | |
15 | </b><br> | |
16 | <b>backend | |
17 | </b>job user title num-copies options [ | |
18 | <i>filename | |
19 | </i>] | |
20 | <h2 class="title"><a name="DESCRIPTION">Description</a></h2> | |
21 | Backends are a special type of <a href='man-filter.html?TOPIC=Man+Pages'>filter(7)</a> which is used to send print data | |
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 | |
44 | backends directly. Instead, use the <a href='man-lp.html?TOPIC=Man+Pages'>lp(1)</a> or <a href='man-lpr.html?TOPIC=Man+Pages'>lpr(1)</a> programs to send | |
45 | a print job or <a href='man-lpinfo.html?TOPIC=Man+Pages'>lpinfo(8)</a> program to query for available printers using the | |
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: | |
60 | <dl> | |
61 | <dt>direct | |
62 | </dt> | |
63 | <dd></dd> | |
64 | <dd>The device-uri refers to a specific direct-access device with no options, such | |
65 | as a parallel, USB, or SCSI device. | |
66 | </dd> | |
67 | <dt>file | |
68 | </dt> | |
69 | <dd></dd> | |
70 | <dd>The device-uri refers to a file on disk. | |
71 | </dd> | |
72 | <dt>network | |
73 | </dt> | |
74 | <dd></dd> | |
75 | <dd>The device-uri refers to a networked device and conforms to the general form for | |
76 | network URIs. | |
77 | </dd> | |
78 | <dt>serial | |
79 | </dt> | |
80 | <dd></dd> | |
81 | <dd>The device-uri refers to a serial device with configurable baud rate and other | |
82 | options. If the device-uri contains a baud value, it represents the maximum baud | |
83 | rate supported by the device. | |
84 | </dd> | |
85 | </dl> | |
86 | <p>The <i>scheme</i> field provides the URI scheme that is supported by the backend. | |
87 | Backends should use this form only when the backend supports any URI using that | |
88 | scheme. The <i>device-uri</i> field specifies the full URI to use when | |
89 | communicating with the device. | |
90 | <p>The <i>device-make-and-model</i> field specifies the make and model of the | |
91 | device, e.g. "Example Foojet 2000". If the make and model is not known, you must | |
92 | report "Unknown". | |
93 | <p>The <i>device-info</i> field specifies additional information about the device. | |
94 | Typically this includes the make and model along with the port number or network | |
95 | address, e.g. "Example Foojet 2000 USB #1". | |
96 | <p>The optional <i>device-id</i> field specifies the IEEE-1284 device ID string for | |
97 | the device, which is used to select a matching driver. | |
98 | <p>The optional <i>device-location</i> field specifies the physical location of | |
99 | the device, which is often used to pre-populate the printer-location attribute | |
100 | when adding a printer. | |
101 | <h2 class="title"><a name="PERMISSIONS">Permissions</a></h2> | |
102 | Backends without world execute permissions are run as the root user. Otherwise, | |
103 | the backend is run using an unprivileged user account, typically "lp". | |
104 | <h2 class="title"><a name="EXIT_CODES">Exit Codes</a></h2> | |
105 | The following exit codes are defined for backends; C API constants defined in | |
106 | the <cups/backend.h> header file are defined in parenthesis: | |
107 | <dl> | |
108 | <dt>0 (CUPS_BACKEND_OK) | |
109 | </dt> | |
110 | <dd></dd> | |
111 | <dd>The print file was successfully transmitted to the device or remote server. | |
112 | </dd> | |
113 | <dt>1 (CUPS_BACKEND_FAILED) | |
114 | </dt> | |
115 | <dd></dd> | |
116 | <dd>The print file was not successfully transmitted to the device or remote server. | |
117 | The scheduler will respond to this by canceling the job, retrying the job, or | |
118 | stopping the queue depending on the state of the error-policy attribute. | |
119 | </dd> | |
120 | <dt>2 (CUPS_BACKEND_AUTH_REQUIRED) | |
121 | </dt> | |
122 | <dd></dd> | |
123 | <dd>The print file was not successfully transmitted because valid authentication | |
124 | information is required. The scheduler will respond to this by holding the job | |
125 | and adding the "cups-held-for-authentication" keyword to the "job-reasons" | |
126 | attribute. | |
127 | </dd> | |
128 | <dt>3 (CUPS_BACKEND_HOLD) | |
129 | </dt> | |
130 | <dd></dd> | |
131 | <dd>The print file was not successfully transmitted because it cannot be printed at | |
132 | this time. The scheduler will respond to this by holding the job. | |
133 | </dd> | |
134 | <dt>4 (CUPS_BACKEND_STOP) | |
135 | </dt> | |
136 | <dd></dd> | |
137 | <dd>The print file was not successfully transmitted because it cannot be printed at | |
138 | this time. The scheduler will respond to this by stopping the queue. | |
139 | </dd> | |
140 | <dt>5 (CUPS_BACKEND_CANCEL) | |
141 | </dt> | |
142 | <dd></dd> | |
143 | <dd>The print file was not successfully transmitted because one or more attributes | |
144 | are not supported or the job was canceled at the printer. The scheduler will | |
145 | respond to this by canceling the job. | |
146 | </dd> | |
147 | <dt>6 (CUPS_BACKEND_RETRY) | |
148 | </dt> | |
149 | <dd></dd> | |
150 | <dd>The print file was not successfully transmitted because of a temporary issue. | |
151 | The scheduler will retry the job at a future time - other jobs may print before | |
152 | this one. | |
153 | </dd> | |
154 | <dt>7 (CUPS_BACKEND_RETRY_CURRENT) | |
155 | </dt> | |
156 | <dd></dd> | |
157 | <dd>The print file was not successfully transmitted because of a temporary issue. | |
158 | The scheduler will retry the job immediately without allowing intervening jobs. | |
159 | </dd> | |
160 | </dl> | |
161 | <p>All other exit code values are reserved. | |
162 | <h2 class="title"><a name="SEE_ALSO">See Also</a></h2> | |
163 | <a href='man-cups-snmp.html?TOPIC=Man+Pages'>cups-snmp(8)</a>, <a href='man-cupsd.html?TOPIC=Man+Pages'>cupsd(8)</a>, <a href='man-cupsd.conf.html?TOPIC=Man+Pages'>cupsd.conf(5)</a>, <a href='man-filter.html?TOPIC=Man+Pages'>filter(7)</a>, | |
164 | <a href='man-lpinfo.html?TOPIC=Man+Pages'>lpinfo(8)</a>, | |
165 | <br> | |
166 | <a href='http://localhost:631/help'>http://localhost:631/help</a> | |
167 | <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> | |
168 | Copyright 2007-2013 by Apple Inc. | |
169 | ||
170 | </body> | |
171 | </html> |