[thirdparty/cups.git] / man / backend.man

.\"
.\" "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $"
.\"
.\"   Backend man page for the Common UNIX Printing System (CUPS).
.\"
.\"   Copyright 1997-2005 by Easy Software Products.
.\"
.\"   These coded instructions, statements, and computer programs are the
.\"   property of Easy Software Products and are protected by Federal
.\"   copyright law.  Distribution and use rights are outlined in the file
.\"   "LICENSE.txt" which should have been included with this file.  If this
.\"   file is missing or damaged please contact Easy Software Products
.\"   at:
.\"
.\"       Attn: CUPS Licensing Information
.\"       Easy Software Products
.\"       44141 Airport View Drive, Suite 204
.\"       Hollywood, Maryland 20636 USA
.\"
.\"       Voice: (301) 373-9600
.\"       EMail: cups-info@cups.org
.\"         WWW: http://www.cups.org
.\"
.TH backend 1 "Common UNIX Printing System" "15 December 2005" "Easy Software Products"

.SH NAME
backend \- cups backend transmission interfaces

.SH SYNOPSIS
.B backend
.br
.B backend
job user title num-copies options [
.I filename
]

.SH DESCRIPTION
The CUPS backend interface provides a standard method for sending
document files to different physical interfaces.

.LP
Backends must be capable of reading from a filename on the
command-line or from the standard input, copying the standard
input to a temporary file if required by the physical interface.

.LP
The command name (argv[0]) is set to the device URI of the
destination printer. Starting with CUPS 1.1.22, any
authentication information in argv[0] will be removed, so
backend developers are urged to use the DEVICE_URI environment
variable whenever authentication information is required.

.LP
Backchannel data from the device should be relayed to the job
filters by writing to file descriptor 3. The CUPS API includes
the \fIcupsBackchannelWrite\fR function for this purpose.

.SH DEVICE DISCOVERY
When run with no arguments, the backend should list the devices
and schemes it supports or is advertising to stdout. The output
consists of zero or more lines consisting of any of the following
forms:

.nf
device-class scheme "Unknown" "device-info"
device-class device-uri "device-make-and-model" "device-info"
device-class device-uri "device-make-and-model" "device-info" "device-id"
.fi

.LP
The \fIdevice-class\fR field is one of the following values:

.TP 5
direct
.br
The device-uri refers to a specific direct-access device with no
options, such as a parallel, USB, or SCSI device.

.TP 5
file
.br
The device-uri refers to a file on disk.

.TP 5
network
.br
The device-uri refers to a networked device and conforms to the
general form for network URIs.

.TP 5
serial
.br
The device-uri refers to a serial device with configurable baud
rate and other options. If the device-uri contains a baud value,
it represents the maximum baud rate supported by the device.

.LP
The \fIscheme\fR field provides the URI scheme that is supported
by the backend. Backends should use this form only when the
backend supports any URI using that scheme. The \fIdevice-uri\fR
field specifies the full URI to use when communicating with the
device.

.LP
The \fIdevice-make-and-model\fR field specifies the make and
model of the device, e.g. "Acme Foojet 2000". If the make and
model is not known, you must report "Unknown".

.LP
The \fIdevice-info\fR field specifies additional information
about the device. Typically this includes the make and model
along with the port number or network address, e.g. "Acme Foojet
2000 USB #1".

.LP
The optional \fIdevice-id\fR field specifies the IEEE-1284 device
ID string for the device, which is used to select a matching
driver.

.SH EXIT CODES
The following exit codes are defined for backends:

.TP 5
0 (CUPS_BACKEND_OK)
.br
The print file was successfully transmitted to the device or
remote server.

.TP 5
1 (CUPS_BACKEND_FAILED)
.br
The print file was not successfully transmitted to the device or
remote server. The scheduler will respond to this by canceling
the job, retrying the job, or stopping the queue depending on the
state of the error-policy attribute.

.TP 5
2 (CUPS_BACKEND_CANCEL)
.br
The print file was not successfully transmitted because one or
more attributes are not supported. The scheduler will respond to
this by canceling the job.

.TP 5
3 (CUPS_BACKEND_HOLD)
.br
The print file was not successfully transmitted because it cannot
be printed at this time. The scheduler will respond to this by
holding the job.

.TP 5
4 (CUPS_BACKEND_STOP)
.br
The print file was not successfully transmitted because it cannot
be printed at this time. The scheduler will respond to this by
stopping the queue.

.TP 5
5 (CUPS_BACKEND_AUTH_REQUIRED)
.br
The print file was not successfully transmitted because valid
authentication information is required. The scheduler will
respond to this by holding the job and adding the
authentication-required job-reasons keyword.

.PP
All other exit code values are reserved.

.SH LOG MESSAGES
Messages sent to stderr are generally logged to
printer-state-message attribute and the current ErrorLog. Each
line begins with a standard prefix:

.TP 5
ALERT: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "alert" log level.

.TP 5
ATTR: attribute=value [attribute=value]
.br
Sets the named job attribute(s). Typically this will be used to
set the job-remote-id attribute.

.TP 5
CRIT: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "critical" log level.

.TP 5
DEBUG: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "debug" log level.

.TP 5
DEBUG2: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "debug2" log level.

.TP 5
EMERG: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "emergency" log level.

.TP 5
ERROR: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "error" log level.

.TP 5
INFO: message
.br
Sets the printer-state-message attribute. If the current LogLevel
is set to "debug2", also adds the specified message to the
current ErrorLog using the "info" log level.

.TP 5
NOTICE: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "notice" log level.

.TP 5
PAGE: page-number #-copies
.TP 5
PAGE: #-pages total
.br
Adds an entry to the current PageLog. The first form adds
#-copies to the job-media-sheets-completed attribute. The second
form sets the job-media-sheets-completed attribute to #-pages.

.TP 5
STATE: printer-state-reason [printer-state-reason ...]
.TP 5
STATE: + printer-state-reason [printer-state-reason ...]
.TP 5
STATE: - printer-state-reason [printer-state-reason ...]
.br
Sets, adds, or removes printer-state-reason keywords to the
current queue. Typically this is used to indicate media, ink, and
toner conditions on a printer.

.TP 5
WARNING: message
.br
Sets the printer-state-message attribute and adds the specified
message to the current ErrorLog using the "warning" log level.

.SH ENVIRONMENT VARIABLES
The following environment variables are defined by the CUPS
server when executing the backend:

.TP 5
CHARSET
.br
The default text character set, typically utf-8.

.TP 5
CLASS
.br
When a job is submitted to a printer class, contains the name of
the destination printer class. Otherwise this environment
variable will not be set.

.TP 5
CONTENT_TYPE
.br
The MIME type associated with the file (e.g.
application/postscript).

.TP 5
CUPS_DATADIR
.br
The directory where data files can be found.

.TP 5
CUPS_SERVERROOT
.br
The root directory of the server.

.TP 5
DEVICE_URI
.br
The device-uri associated with the printer; this is provided for
shell scripts which may not be able to get the passed argv[0]
string and for backends that require any authentication
information which is not included in argv[0].

.TP 5
LANG
.br
The default language locale (typically C or en).

.TP 5
PATH
.br
The standard execution path for external programs that may be run by
the backend.

.TP 5
PPD
.br
The full pathname of the PostScript Printer Description (PPD)
file for this printer.

.TP 5
PRINTER
.br
The name of the printer.

.TP 5
RIP_CACHE
.br
The recommended amount of memory to use for Raster Image
Processors (RIPs).

.TP 5
SOFTWARE
.br
The name and version number of the server (typically CUPS/1.1).

.TP 5
TZ
.br
The timezone of the server.

.TP 5
USER
.br
The user executing the backend, typically root; consult the
cupsd.conf file for the current setting.

.SH SEE ALSO
cupsd(8), filter(1)
.br
http://localhost:631/help

.SH COPYRIGHT
Copyright 1993-2005 by Easy Software Products, All Rights Reserved.
.\"
.\" End of "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $".
.\"
Commit	Line	Data
ef416fc2	1	.\"
	2	.\" "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $"
	3	.\"
	4	.\" Backend man page for the Common UNIX Printing System (CUPS).
	5	.\"
	6	.\" Copyright 1997-2005 by Easy Software Products.
	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	.\"
	24	.TH backend 1 "Common UNIX Printing System" "15 December 2005" "Easy Software Products"
	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
	38	The CUPS backend interface provides a standard method for sending
	39	document files to different physical interfaces.
	40
	41	.LP
	42	Backends must be capable of reading from a filename on the
	43	command-line or from the standard input, copying the standard
	44	input to a temporary file if required by the physical interface.
	45
	46	.LP
	47	The command name (argv[0]) is set to the device URI of the
	48	destination printer. Starting with CUPS 1.1.22, any
	49	authentication information in argv[0] will be removed, so
	50	backend developers are urged to use the DEVICE_URI environment
	51	variable whenever authentication information is required.
	52
	53	.LP
	54	Backchannel data from the device should be relayed to the job
	55	filters by writing to file descriptor 3. The CUPS API includes
	56	the \fIcupsBackchannelWrite\fR function for this purpose.
	57
	58	.SH DEVICE DISCOVERY
	59	When run with no arguments, the backend should list the devices
	60	and schemes it supports or is advertising to stdout. The output
	61	consists of zero or more lines consisting of any of the following
	62	forms:
	63
	64	.nf
65	device-class scheme "Unknown" "device-info"
66	device-class device-uri "device-make-and-model" "device-info"
67	device-class device-uri "device-make-and-model" "device-info" "device-id"
68	.fi
69
70	.LP
71	The \fIdevice-class\fR field is one of the following values:
72
73	.TP 5
74	direct
75	.br
76	The device-uri refers to a specific direct-access device with no
77	options, such as a parallel, USB, or SCSI device.
78
79	.TP 5
80	file
81	.br
82	The device-uri refers to a file on disk.
83
84	.TP 5
85	network
86	.br
87	The device-uri refers to a networked device and conforms to the
88	general form for network URIs.
89
90	.TP 5
91	serial
92	.br
93	The device-uri refers to a serial device with configurable baud
94	rate and other options. If the device-uri contains a baud value,
95	it represents the maximum baud rate supported by the device.
96
97	.LP
98	The \fIscheme\fR field provides the URI scheme that is supported
99	by the backend. Backends should use this form only when the
100	backend supports any URI using that scheme. The \fIdevice-uri\fR
101	field specifies the full URI to use when communicating with the
102	device.
103
104	.LP
105	The \fIdevice-make-and-model\fR field specifies the make and
106	model of the device, e.g. "Acme Foojet 2000". If the make and
107	model is not known, you must report "Unknown".
108
109	.LP
110	The \fIdevice-info\fR field specifies additional information
111	about the device. Typically this includes the make and model
112	along with the port number or network address, e.g. "Acme Foojet
113	2000 USB #1".
114
115	.LP
116	The optional \fIdevice-id\fR field specifies the IEEE-1284 device
117	ID string for the device, which is used to select a matching
118	driver.
119
120	.SH EXIT CODES
121	The following exit codes are defined for backends:
122
123	.TP 5
124	0 (CUPS_BACKEND_OK)
125	.br
126	The print file was successfully transmitted to the device or
127	remote server.
128
129	.TP 5
130	1 (CUPS_BACKEND_FAILED)
131	.br
132	The print file was not successfully transmitted to the device or
133	remote server. The scheduler will respond to this by canceling
134	the job, retrying the job, or stopping the queue depending on the
135	state of the error-policy attribute.
136
137	.TP 5
138	2 (CUPS_BACKEND_CANCEL)
139	.br
140	The print file was not successfully transmitted because one or
141	more attributes are not supported. The scheduler will respond to
142	this by canceling the job.
143
144	.TP 5
145	3 (CUPS_BACKEND_HOLD)
146	.br
147	The print file was not successfully transmitted because it cannot
148	be printed at this time. The scheduler will respond to this by
149	holding the job.
150
151	.TP 5
152	4 (CUPS_BACKEND_STOP)
153	.br
154	The print file was not successfully transmitted because it cannot
155	be printed at this time. The scheduler will respond to this by
156	stopping the queue.
157
158	.TP 5
159	5 (CUPS_BACKEND_AUTH_REQUIRED)
160	.br
161	The print file was not successfully transmitted because valid
162	authentication information is required. The scheduler will
163	respond to this by holding the job and adding the
164	authentication-required job-reasons keyword.
165
166	.PP
167	All other exit code values are reserved.
168
169	.SH LOG MESSAGES
170	Messages sent to stderr are generally logged to
171	printer-state-message attribute and the current ErrorLog. Each
172	line begins with a standard prefix:
173
174	.TP 5
175	ALERT: message
176	.br
177	Sets the printer-state-message attribute and adds the specified
178	message to the current ErrorLog using the "alert" log level.
179
180	.TP 5
181	ATTR: attribute=value [attribute=value]
182	.br
183	Sets the named job attribute(s). Typically this will be used to
184	set the job-remote-id attribute.
185
186	.TP 5
187	CRIT: message
188	.br
189	Sets the printer-state-message attribute and adds the specified
190	message to the current ErrorLog using the "critical" log level.
191
192	.TP 5
193	DEBUG: message
194	.br
195	Sets the printer-state-message attribute and adds the specified
196	message to the current ErrorLog using the "debug" log level.
197
198	.TP 5
199	DEBUG2: message
200	.br
201	Sets the printer-state-message attribute and adds the specified
202	message to the current ErrorLog using the "debug2" log level.
203
204	.TP 5
205	EMERG: message
206	.br
207	Sets the printer-state-message attribute and adds the specified
208	message to the current ErrorLog using the "emergency" log level.
209
210	.TP 5
211	ERROR: message
212	.br
213	Sets the printer-state-message attribute and adds the specified
214	message to the current ErrorLog using the "error" log level.
215
216	.TP 5
217	INFO: message
218	.br
219	Sets the printer-state-message attribute. If the current LogLevel
220	is set to "debug2", also adds the specified message to the
221	current ErrorLog using the "info" log level.
222
223	.TP 5
224	NOTICE: message
225	.br
226	Sets the printer-state-message attribute and adds the specified
227	message to the current ErrorLog using the "notice" log level.
228
229	.TP 5
230	PAGE: page-number #-copies
231	.TP 5
232	PAGE: #-pages total
233	.br
234	Adds an entry to the current PageLog. The first form adds
235	#-copies to the job-media-sheets-completed attribute. The second
236	form sets the job-media-sheets-completed attribute to #-pages.
237
238	.TP 5
239	STATE: printer-state-reason [printer-state-reason ...]
240	.TP 5
241	STATE: + printer-state-reason [printer-state-reason ...]
242	.TP 5
243	STATE: - printer-state-reason [printer-state-reason ...]
244	.br
245	Sets, adds, or removes printer-state-reason keywords to the
246	current queue. Typically this is used to indicate media, ink, and
247	toner conditions on a printer.
248
249	.TP 5
250	WARNING: message
251	.br
252	Sets the printer-state-message attribute and adds the specified
253	message to the current ErrorLog using the "warning" log level.
254
255	.SH ENVIRONMENT VARIABLES
256	The following environment variables are defined by the CUPS
257	server when executing the backend:
258
259	.TP 5
260	CHARSET
261	.br
262	The default text character set, typically utf-8.
263
264	.TP 5
265	CLASS
266	.br
267	When a job is submitted to a printer class, contains the name of
268	the destination printer class. Otherwise this environment
269	variable will not be set.
270
271	.TP 5
272	CONTENT_TYPE
273	.br
274	The MIME type associated with the file (e.g.
275	application/postscript).
276
277	.TP 5
278	CUPS_DATADIR
279	.br
280	The directory where data files can be found.
281
282	.TP 5
283	CUPS_SERVERROOT
284	.br
285	The root directory of the server.
286
287	.TP 5
288	DEVICE_URI
289	.br
290	The device-uri associated with the printer; this is provided for
291	shell scripts which may not be able to get the passed argv[0]
292	string and for backends that require any authentication
293	information which is not included in argv[0].
294
295	.TP 5
296	LANG
297	.br
298	The default language locale (typically C or en).
299
300	.TP 5
301	PATH
302	.br
303	The standard execution path for external programs that may be run by
304	the backend.
305
306	.TP 5
307	PPD
308	.br
309	The full pathname of the PostScript Printer Description (PPD)
310	file for this printer.
311
312	.TP 5
313	PRINTER
314	.br
315	The name of the printer.
316
317	.TP 5
318	RIP_CACHE
319	.br
320	The recommended amount of memory to use for Raster Image
321	Processors (RIPs).
322
323	.TP 5
324	SOFTWARE
325	.br
326	The name and version number of the server (typically CUPS/1.1).
327
328	.TP 5
329	TZ
330	.br
331	The timezone of the server.
332
333	.TP 5
334	USER
335	.br
336	The user executing the backend, typically root; consult the
337	cupsd.conf file for the current setting.
338
339	.SH SEE ALSO
340	cupsd(8), filter(1)
341	.br
342	http://localhost:631/help
343
344	.SH COPYRIGHT
345	Copyright 1993-2005 by Easy Software Products, All Rights Reserved.
346	.\"
347	.\" End of "$Id: backend.man 4884 2005-12-16 01:02:42Z mike $".
348	.\"