]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
f7faf1f5 | 2 | .\" "$Id: backend.man 5313 2006-03-20 15:29:09Z mike $" |
ef416fc2 | 3 | .\" |
4 | .\" Backend man page for the Common UNIX Printing System (CUPS). | |
5 | .\" | |
bd7854cb | 6 | .\" Copyright 1997-2006 by Easy Software Products. |
ef416fc2 | 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 | .\" | |
e1d6a774 | 24 | .TH backend 7 "Common UNIX Printing System" "20 March 2006" "Easy Software Products" |
ef416fc2 | 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 | |
bd7854cb | 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. | |
ef416fc2 | 40 | |
41 | .LP | |
bd7854cb | 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. | |
ef416fc2 | 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 | |
bd7854cb | 50 | authentication information in argv[0] is removed, so |
ef416fc2 | 51 | backend developers are urged to use the DEVICE_URI environment |
bd7854cb | 52 | variable whenever authentication information is required. The |
53 | CUPS API includes a \fIcupsBackendDeviceURI\fR function for | |
54 | retrieving the correct device URI. | |
ef416fc2 | 55 | |
56 | .LP | |
bd7854cb | 57 | Back-channel data from the device should be relayed to the job |
ef416fc2 | 58 | filters by writing to file descriptor 3. The CUPS API includes |
bd7854cb | 59 | the \fIcupsBackChannelWrite\fR function for this purpose. |
ef416fc2 | 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 | |
bd7854cb | 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" | |
ef416fc2 | 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 | ||
bd7854cb | 123 | .SH PERMISSIONS |
124 | Backends without world execute permissions are run as the root | |
e1d6a774 | 125 | user. Otherwise, the backend is run using the unprivileged user |
bd7854cb | 126 | account, typically "lp". |
127 | ||
ef416fc2 | 128 | .SH EXIT CODES |
bd7854cb | 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: | |
ef416fc2 | 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 | |
bd7854cb | 148 | 2 (CUPS_BACKEND_AUTH_REQUIRED) |
ef416fc2 | 149 | .br |
bd7854cb | 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. | |
ef416fc2 | 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 | |
bd7854cb | 170 | 5 (CUPS_BACKEND_CANCEL) |
ef416fc2 | 171 | .br |
bd7854cb | 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. | |
ef416fc2 | 175 | |
176 | .PP | |
177 | All other exit code values are reserved. | |
178 | ||
ef416fc2 | 179 | .SH SEE ALSO |
bd7854cb | 180 | \fIcupsd(8)\fR, \fIcupsd.conf(5)\fR, \fIfilter(7)\fR |
ef416fc2 | 181 | .br |
182 | http://localhost:631/help | |
183 | ||
184 | .SH COPYRIGHT | |
bd7854cb | 185 | Copyright 1997-2006 by Easy Software Products, All Rights Reserved. |
ef416fc2 | 186 | .\" |
f7faf1f5 | 187 | .\" End of "$Id: backend.man 5313 2006-03-20 15:29:09Z mike $". |
ef416fc2 | 188 | .\" |