]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | .\" |
e4e5666b | 2 | .\" "$Id$" |
ef416fc2 | 3 | .\" |
22c9029b | 4 | .\" Backend man page for CUPS. |
ef416fc2 | 5 | .\" |
0fa6c7fa | 6 | .\" Copyright 2007-2013 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 | .\" |
f3c17241 | 15 | .TH backend 7 "CUPS" "23 April 2012" "Apple Inc." |
ef416fc2 | 16 | |
17 | .SH NAME | |
18 | backend \- cups backend transmission interfaces | |
ef416fc2 | 19 | .SH SYNOPSIS |
20 | .B backend | |
21 | .br | |
22 | .B backend | |
23 | job user title num-copies options [ | |
24 | .I filename | |
25 | ] | |
ef416fc2 | 26 | .SH DESCRIPTION |
f3c17241 MS |
27 | Backends are a special type of \fIfilter(7)\fR which is used to send print data |
28 | to and discover different devices on the system. | |
ef416fc2 | 29 | .LP |
f3c17241 MS |
30 | Like filters, backends must be capable of reading from a filename on the |
31 | command-line or from the standard input, copying the standard input to a | |
32 | temporary file as required by the physical interface. | |
ef416fc2 | 33 | .LP |
178cb736 MS |
34 | The command name (argv[0]) is set to the device URI of the destination printer. |
35 | Starting with CUPS 1.1.22, any authentication information in argv[0] is removed, | |
36 | so backend developers are urged to use the DEVICE_URI environment variable | |
37 | whenever authentication information is required. The CUPS API includes a | |
38 | \fIcupsBackendDeviceURI\fR function for retrieving the correct device URI. | |
ef416fc2 | 39 | .LP |
bd7854cb | 40 | Back-channel data from the device should be relayed to the job |
ef416fc2 | 41 | filters by writing to file descriptor 3. The CUPS API includes |
bd7854cb | 42 | the \fIcupsBackChannelWrite\fR function for this purpose. |
f3c17241 MS |
43 | .SH WARNING |
44 | CUPS backends are not generally design to be run directly by the user. Aside | |
45 | from the device URI issue (argv[0] and DEVICE_URI environment variable contain | |
46 | the device URI), CUPS backends also expect specific environment variables and | |
47 | file descriptors, and typically run in a user session that (on OS X) has | |
48 | additional restrictions that affect how it runs. Backends can also be installed | |
49 | with restricted permissions (0500 or 0700) that tell the scheduler to run them | |
50 | as the "root" user instead of an unprivileged user (typically "lp") on the | |
51 | system. | |
52 | .LP | |
53 | Unless you are a developer and know what you are doing, please do not run | |
54 | backends directly. Instead, use the \fIlp(1)\fR or \fIlpr(1)\fR programs to send | |
55 | a print job or \fIlpinfo(8)\fR program to query for available printers using the | |
56 | backend. The one exception is the SNMP backend - see \fIsnmpbackend(8)\fR for | |
57 | more information. | |
ef416fc2 | 58 | .SH DEVICE DISCOVERY |
f3c17241 MS |
59 | When run with no arguments, the backend should list the devices and schemes it |
60 | supports or is advertising to stdout. The output consists of zero or more lines | |
61 | consisting of any of the following forms: | |
ef416fc2 | 62 | |
63 | .nf | |
bd7854cb | 64 | device-class scheme "Unknown" "device-info" |
65 | device-class device-uri "device-make-and-model" "device-info" | |
66 | device-class device-uri "device-make-and-model" "device-info" "device-id" | |
749b1e90 | 67 | device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location" |
ef416fc2 | 68 | .fi |
ef416fc2 | 69 | .LP |
70 | The \fIdevice-class\fR field is one of the following values: | |
ef416fc2 | 71 | .TP 5 |
72 | direct | |
73 | .br | |
f3c17241 MS |
74 | The device-uri refers to a specific direct-access device with no options, such |
75 | as a parallel, USB, or SCSI device. | |
ef416fc2 | 76 | .TP 5 |
77 | file | |
78 | .br | |
79 | The device-uri refers to a file on disk. | |
ef416fc2 | 80 | .TP 5 |
81 | network | |
82 | .br | |
f3c17241 MS |
83 | The device-uri refers to a networked device and conforms to the general form for |
84 | network URIs. | |
ef416fc2 | 85 | .TP 5 |
86 | serial | |
87 | .br | |
f3c17241 MS |
88 | The device-uri refers to a serial device with configurable baud rate and other |
89 | options. If the device-uri contains a baud value, it represents the maximum baud | |
90 | rate supported by the device. | |
ef416fc2 | 91 | .LP |
f3c17241 MS |
92 | The \fIscheme\fR field provides the URI scheme that is supported by the backend. |
93 | Backends should use this form only when the backend supports any URI using that | |
94 | scheme. The \fIdevice-uri\fR field specifies the full URI to use when | |
95 | communicating with the device. | |
ef416fc2 | 96 | .LP |
f3c17241 MS |
97 | The \fIdevice-make-and-model\fR field specifies the make and model of the |
98 | device, e.g. "Example Foojet 2000". If the make and model is not known, you must | |
99 | report "Unknown". | |
ef416fc2 | 100 | .LP |
f3c17241 MS |
101 | The \fIdevice-info\fR field specifies additional information about the device. |
102 | Typically this includes the make and model along with the port number or network | |
103 | address, e.g. "Example Foojet 2000 USB #1". | |
ef416fc2 | 104 | .LP |
f3c17241 MS |
105 | The optional \fIdevice-id\fR field specifies the IEEE-1284 device ID string for |
106 | the device, which is used to select a matching driver. | |
749b1e90 MS |
107 | .LP |
108 | The optional \fIdevice-location\fR field specifies the physical location of | |
109 | the device, which is often used to pre-populate the printer-location attribute | |
110 | when adding a printer. | |
bd7854cb | 111 | .SH PERMISSIONS |
f3c17241 MS |
112 | Backends without world execute permissions are run as the root user. Otherwise, |
113 | the backend is run using an unprivileged user account, typically "lp". | |
ef416fc2 | 114 | .SH EXIT CODES |
f3c17241 MS |
115 | The following exit codes are defined for backends; C API constants defined in |
116 | the <cups/backend.h> header file are defined in parenthesis: | |
ef416fc2 | 117 | .TP 5 |
118 | 0 (CUPS_BACKEND_OK) | |
119 | .br | |
f3c17241 | 120 | The print file was successfully transmitted to the device or remote server. |
ef416fc2 | 121 | .TP 5 |
122 | 1 (CUPS_BACKEND_FAILED) | |
123 | .br | |
f3c17241 MS |
124 | The print file was not successfully transmitted to the device or remote server. |
125 | The scheduler will respond to this by canceling the job, retrying the job, or | |
126 | stopping the queue depending on the state of the error-policy attribute. | |
ef416fc2 | 127 | .TP 5 |
bd7854cb | 128 | 2 (CUPS_BACKEND_AUTH_REQUIRED) |
ef416fc2 | 129 | .br |
f3c17241 MS |
130 | The print file was not successfully transmitted because valid authentication |
131 | information is required. The scheduler will respond to this by holding the job | |
132 | and adding the "cups-held-for-authentication" keyword to the "job-reasons" | |
133 | attribute. | |
ef416fc2 | 134 | .TP 5 |
135 | 3 (CUPS_BACKEND_HOLD) | |
136 | .br | |
f3c17241 MS |
137 | The print file was not successfully transmitted because it cannot be printed at |
138 | this time. The scheduler will respond to this by holding the job. | |
ef416fc2 | 139 | .TP 5 |
140 | 4 (CUPS_BACKEND_STOP) | |
141 | .br | |
f3c17241 MS |
142 | The print file was not successfully transmitted because it cannot be printed at |
143 | this time. The scheduler will respond to this by stopping the queue. | |
ef416fc2 | 144 | .TP 5 |
bd7854cb | 145 | 5 (CUPS_BACKEND_CANCEL) |
ef416fc2 | 146 | .br |
f3c17241 MS |
147 | The print file was not successfully transmitted because one or more attributes |
148 | are not supported or the job was canceled at the printer. The scheduler will | |
149 | respond to this by canceling the job. | |
22c9029b MS |
150 | .TP 5 |
151 | 6 (CUPS_BACKEND_RETRY) | |
152 | .br | |
153 | The print file was not successfully transmitted because of a temporary issue. | |
154 | The scheduler will retry the job at a future time - other jobs may print before | |
155 | this one. | |
22c9029b MS |
156 | .TP 5 |
157 | 7 (CUPS_BACKEND_RETRY_CURRENT) | |
158 | .br | |
159 | The print file was not successfully transmitted because of a temporary issue. | |
160 | The scheduler will retry the job immediately without allowing intervening jobs. | |
ef416fc2 | 161 | .PP |
162 | All other exit code values are reserved. | |
ef416fc2 | 163 | .SH SEE ALSO |
f3c17241 MS |
164 | \fIcups-snmp(8)\fR, \fIcupsd(8)\fR, \fIcupsd.conf(5)\fR, \fIfilter(7)\fR, |
165 | \fIlpinfo(8)\fR, | |
ef416fc2 | 166 | .br |
167 | http://localhost:631/help | |
ef416fc2 | 168 | .SH COPYRIGHT |
0fa6c7fa | 169 | Copyright 2007-2013 by Apple Inc. |
ef416fc2 | 170 | .\" |
e4e5666b | 171 | .\" End of "$Id$". |
ef416fc2 | 172 | .\" |