]>
Commit | Line | Data |
---|---|---|
771e5703 | 1 | .\" |
b2e10895 | 2 | .\" "$Id$" |
771e5703 | 3 | .\" |
7cfa02ab | 4 | .\" Backend man page for CUPS. |
771e5703 | 5 | .\" |
dc0f86cb | 6 | .\" Copyright 2007-2013 by Apple Inc. |
766ef83d | 7 | .\" Copyright 1997-2006 by Easy Software Products. |
771e5703 | 8 | .\" |
9 | .\" These coded instructions, statements, and computer programs are the | |
4e8d321f | 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/". | |
771e5703 | 14 | .\" |
c45401bb | 15 | .TH backend 7 "CUPS" "23 April 2012" "Apple Inc." |
6248387b | 16 | |
771e5703 | 17 | .SH NAME |
e6c9b8b4 | 18 | backend \- cups backend transmission interfaces |
771e5703 | 19 | .SH SYNOPSIS |
20 | .B backend | |
684e9864 | 21 | .br |
22 | .B backend | |
e6c9b8b4 | 23 | job user title num-copies options [ |
24 | .I filename | |
25 | ] | |
771e5703 | 26 | .SH DESCRIPTION |
c45401bb | 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. | |
771e5703 | 29 | .LP |
c45401bb | 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. | |
771e5703 | 33 | .LP |
5363607d | 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. | |
684e9864 | 39 | .LP |
766ef83d | 40 | Back-channel data from the device should be relayed to the job |
684e9864 | 41 | filters by writing to file descriptor 3. The CUPS API includes |
766ef83d | 42 | the \fIcupsBackChannelWrite\fR function for this purpose. |
74dfc645 | 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. | |
684e9864 | 58 | .SH DEVICE DISCOVERY |
74dfc645 | 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: | |
684e9864 | 62 | |
63 | .nf | |
766ef83d | 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" | |
2317ac1e | 67 | device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location" |
684e9864 | 68 | .fi |
684e9864 | 69 | .LP |
70 | The \fIdevice-class\fR field is one of the following values: | |
684e9864 | 71 | .TP 5 |
72 | direct | |
73 | .br | |
74dfc645 | 74 | The device-uri refers to a specific direct-access device with no options, such |
75 | as a parallel, USB, or SCSI device. | |
684e9864 | 76 | .TP 5 |
77 | file | |
78 | .br | |
79 | The device-uri refers to a file on disk. | |
684e9864 | 80 | .TP 5 |
81 | network | |
82 | .br | |
74dfc645 | 83 | The device-uri refers to a networked device and conforms to the general form for |
84 | network URIs. | |
684e9864 | 85 | .TP 5 |
86 | serial | |
87 | .br | |
74dfc645 | 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. | |
684e9864 | 91 | .LP |
74dfc645 | 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. | |
684e9864 | 96 | .LP |
74dfc645 | 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". | |
684e9864 | 100 | .LP |
74dfc645 | 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". | |
684e9864 | 104 | .LP |
74dfc645 | 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. | |
2317ac1e | 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. | |
766ef83d | 111 | .SH PERMISSIONS |
74dfc645 | 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". | |
6248387b | 114 | .SH EXIT CODES |
74dfc645 | 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: | |
6248387b | 117 | .TP 5 |
118 | 0 (CUPS_BACKEND_OK) | |
119 | .br | |
74dfc645 | 120 | The print file was successfully transmitted to the device or remote server. |
6248387b | 121 | .TP 5 |
122 | 1 (CUPS_BACKEND_FAILED) | |
123 | .br | |
74dfc645 | 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. | |
6248387b | 127 | .TP 5 |
59de43b4 | 128 | 2 (CUPS_BACKEND_AUTH_REQUIRED) |
6248387b | 129 | .br |
74dfc645 | 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. | |
6248387b | 134 | .TP 5 |
135 | 3 (CUPS_BACKEND_HOLD) | |
136 | .br | |
74dfc645 | 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. | |
6248387b | 139 | .TP 5 |
140 | 4 (CUPS_BACKEND_STOP) | |
141 | .br | |
74dfc645 | 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. | |
6248387b | 144 | .TP 5 |
59de43b4 | 145 | 5 (CUPS_BACKEND_CANCEL) |
6248387b | 146 | .br |
74dfc645 | 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. | |
7cfa02ab | 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. | |
7cfa02ab | 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. | |
6248387b | 161 | .PP |
162 | All other exit code values are reserved. | |
771e5703 | 163 | .SH SEE ALSO |
c45401bb | 164 | \fIcups-snmp(8)\fR, \fIcupsd(8)\fR, \fIcupsd.conf(5)\fR, \fIfilter(7)\fR, |
165 | \fIlpinfo(8)\fR, | |
684e9864 | 166 | .br |
6248387b | 167 | http://localhost:631/help |
771e5703 | 168 | .SH COPYRIGHT |
dc0f86cb | 169 | Copyright 2007-2013 by Apple Inc. |
771e5703 | 170 | .\" |
b2e10895 | 171 | .\" End of "$Id$". |
771e5703 | 172 | .\" |