]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
75bd9771 | 2 | .\" "$Id: backend.man 7600 2008-05-20 21:06:23Z mike $" |
ef416fc2 | 3 | .\" |
4 | .\" Backend man page for the Common UNIX Printing System (CUPS). | |
5 | .\" | |
bc44d920 | 6 | .\" Copyright 2007 by Apple Inc. |
bd7854cb | 7 | .\" Copyright 1997-2006 by Easy Software Products. |
ef416fc2 | 8 | .\" |
9 | .\" These coded instructions, statements, and computer programs are the | |
bc44d920 | 10 | .\" property of Apple Inc. and are protected by Federal copyright |
11 | .\" law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
12 | .\" which should have been included with this file. If this file is | |
13 | .\" file is missing or damaged, see the license at "http://www.cups.org/". | |
ef416fc2 | 14 | .\" |
bc44d920 | 15 | .TH backend 7 "Common UNIX Printing System" "20 March 2006" "Apple Inc." |
ef416fc2 | 16 | |
17 | .SH NAME | |
18 | backend \- cups backend transmission interfaces | |
19 | ||
20 | .SH SYNOPSIS | |
21 | .B backend | |
22 | .br | |
23 | .B backend | |
24 | job user title num-copies options [ | |
25 | .I filename | |
26 | ] | |
27 | ||
28 | .SH DESCRIPTION | |
bd7854cb | 29 | Backends are a special type of \fIfilter(7)\fR which is used to |
30 | send print data to and discover different devices on the system. | |
ef416fc2 | 31 | |
32 | .LP | |
bd7854cb | 33 | Like filters, backends must be capable of reading from a filename |
34 | on the command-line or from the standard input, copying the | |
35 | standard input to a temporary file as required by the physical | |
36 | interface. | |
ef416fc2 | 37 | |
38 | .LP | |
39 | The command name (argv[0]) is set to the device URI of the | |
40 | destination printer. Starting with CUPS 1.1.22, any | |
bd7854cb | 41 | authentication information in argv[0] is removed, so |
ef416fc2 | 42 | backend developers are urged to use the DEVICE_URI environment |
bd7854cb | 43 | variable whenever authentication information is required. The |
44 | CUPS API includes a \fIcupsBackendDeviceURI\fR function for | |
45 | retrieving the correct device URI. | |
ef416fc2 | 46 | |
47 | .LP | |
bd7854cb | 48 | Back-channel data from the device should be relayed to the job |
ef416fc2 | 49 | filters by writing to file descriptor 3. The CUPS API includes |
bd7854cb | 50 | the \fIcupsBackChannelWrite\fR function for this purpose. |
ef416fc2 | 51 | |
52 | .SH DEVICE DISCOVERY | |
53 | When run with no arguments, the backend should list the devices | |
54 | and schemes it supports or is advertising to stdout. The output | |
55 | consists of zero or more lines consisting of any of the following | |
56 | forms: | |
57 | ||
58 | .nf | |
bd7854cb | 59 | device-class scheme "Unknown" "device-info" |
60 | device-class device-uri "device-make-and-model" "device-info" | |
61 | device-class device-uri "device-make-and-model" "device-info" "device-id" | |
ef416fc2 | 62 | .fi |
63 | ||
64 | .LP | |
65 | The \fIdevice-class\fR field is one of the following values: | |
66 | ||
67 | .TP 5 | |
68 | direct | |
69 | .br | |
70 | The device-uri refers to a specific direct-access device with no | |
71 | options, such as a parallel, USB, or SCSI device. | |
72 | ||
73 | .TP 5 | |
74 | file | |
75 | .br | |
76 | The device-uri refers to a file on disk. | |
77 | ||
78 | .TP 5 | |
79 | network | |
80 | .br | |
81 | The device-uri refers to a networked device and conforms to the | |
82 | general form for network URIs. | |
83 | ||
84 | .TP 5 | |
85 | serial | |
86 | .br | |
87 | The device-uri refers to a serial device with configurable baud | |
88 | rate and other options. If the device-uri contains a baud value, | |
89 | it represents the maximum baud rate supported by the device. | |
90 | ||
91 | .LP | |
92 | The \fIscheme\fR field provides the URI scheme that is supported | |
93 | by the backend. Backends should use this form only when the | |
94 | backend supports any URI using that scheme. The \fIdevice-uri\fR | |
95 | field specifies the full URI to use when communicating with the | |
96 | device. | |
97 | ||
98 | .LP | |
99 | The \fIdevice-make-and-model\fR field specifies the make and | |
100 | model of the device, e.g. "Acme Foojet 2000". If the make and | |
101 | model is not known, you must report "Unknown". | |
102 | ||
103 | .LP | |
104 | The \fIdevice-info\fR field specifies additional information | |
105 | about the device. Typically this includes the make and model | |
106 | along with the port number or network address, e.g. "Acme Foojet | |
107 | 2000 USB #1". | |
108 | ||
109 | .LP | |
110 | The optional \fIdevice-id\fR field specifies the IEEE-1284 device | |
111 | ID string for the device, which is used to select a matching | |
112 | driver. | |
113 | ||
bd7854cb | 114 | .SH PERMISSIONS |
115 | Backends without world execute permissions are run as the root | |
e1d6a774 | 116 | user. Otherwise, the backend is run using the unprivileged user |
bd7854cb | 117 | account, typically "lp". |
118 | ||
ef416fc2 | 119 | .SH EXIT CODES |
bd7854cb | 120 | The following exit codes are defined for backends; C API |
121 | constants defined in the <cups/backend.h> header file are defined | |
122 | in parenthesis: | |
ef416fc2 | 123 | |
124 | .TP 5 | |
125 | 0 (CUPS_BACKEND_OK) | |
126 | .br | |
127 | The print file was successfully transmitted to the device or | |
128 | remote server. | |
129 | ||
130 | .TP 5 | |
131 | 1 (CUPS_BACKEND_FAILED) | |
132 | .br | |
133 | The print file was not successfully transmitted to the device or | |
134 | remote server. The scheduler will respond to this by canceling | |
135 | the job, retrying the job, or stopping the queue depending on the | |
136 | state of the error-policy attribute. | |
137 | ||
138 | .TP 5 | |
bd7854cb | 139 | 2 (CUPS_BACKEND_AUTH_REQUIRED) |
ef416fc2 | 140 | .br |
bd7854cb | 141 | The print file was not successfully transmitted because valid |
142 | authentication information is required. The scheduler will | |
143 | respond to this by holding the job and adding the | |
144 | authentication-required job-reasons keyword. | |
ef416fc2 | 145 | |
146 | .TP 5 | |
147 | 3 (CUPS_BACKEND_HOLD) | |
148 | .br | |
149 | The print file was not successfully transmitted because it cannot | |
150 | be printed at this time. The scheduler will respond to this by | |
151 | holding the job. | |
152 | ||
153 | .TP 5 | |
154 | 4 (CUPS_BACKEND_STOP) | |
155 | .br | |
156 | The print file was not successfully transmitted because it cannot | |
157 | be printed at this time. The scheduler will respond to this by | |
158 | stopping the queue. | |
159 | ||
160 | .TP 5 | |
bd7854cb | 161 | 5 (CUPS_BACKEND_CANCEL) |
ef416fc2 | 162 | .br |
bd7854cb | 163 | The print file was not successfully transmitted because one or |
164 | more attributes are not supported. The scheduler will respond to | |
165 | this by canceling the job. | |
ef416fc2 | 166 | |
167 | .PP | |
168 | All other exit code values are reserved. | |
169 | ||
ef416fc2 | 170 | .SH SEE ALSO |
bd7854cb | 171 | \fIcupsd(8)\fR, \fIcupsd.conf(5)\fR, \fIfilter(7)\fR |
ef416fc2 | 172 | .br |
173 | http://localhost:631/help | |
174 | ||
175 | .SH COPYRIGHT | |
bc44d920 | 176 | Copyright 2007 by Apple Inc. |
ef416fc2 | 177 | .\" |
75bd9771 | 178 | .\" End of "$Id: backend.man 7600 2008-05-20 21:06:23Z mike $". |
ef416fc2 | 179 | .\" |