1 '\" te
2 .\" Copyright (c) 20002 Sun Microsystems, Inc.
3 .\" All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH PRNIO 7I "Jan 2, 2002"
8 .SH NAME
9 prnio \- generic printer interface
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB#include <sys/prnio.h>\fR
14 .fi
15
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The \fBprnio\fR generic printer interface defines ioctl commands and data
20 structures for printer device drivers.
21 .sp
22 .LP
23 \fBprnio\fR defines and provides facilities for five basic phases of the
24 printing process:
25 .RS +4
26 .TP
27 .ie t \(bu
28 .el o
29 Identification \(em Retrieve device information/attributes
30 .RE
31 .RS +4
32 .TP
33 .ie t \(bu
34 .el o
35 Setup \(em Set device attributes
36 .RE
37 .RS +4
38 .TP
39 .ie t \(bu
40 .el o
41 Transfer \(em Transfer data to or from the device
42 .RE
43 .RS +4
44 .TP
45 .ie t \(bu
46 .el o
47 Cleanup \(em Transfer phase conclusion
48 .RE
49 .RS +4
50 .TP
51 .ie t \(bu
52 .el o
53 Abort \(em Transfer phase interruption
54 .RE
55 .sp
56 .LP
57 During the Identification phase, the application retrieves a set of device
58 capabilities and additional information using the \fBPRNIOC_GET_IFCAP\fR,
59 \fBPRNIOC_GET_STATUS\fR, \fBPRNIOC_GET_TIMEOUTS\fR, \fBPRNIOC_GET_IFINFO\fR and
60 \fBPRNIOC_GET_1284_DEVID\fR commands.
61 .sp
62 .LP
63 During the Setup phase the application sets some interface attributes and
64 probably resets the printer as described in the \fBPRNIOC_SET_IFCAP\fR,
65 \fBPRNIOC_SET_TIMEOUTS\fR and \fBPRNIOC_RESET\fR sections.
66 .sp
67 .LP
68 During the Transfer phase, data is transferred in a forward (host to
69 peripheral) or reverse direction (peripheral to host). Transfer is accomplished
70 using \fBwrite\fR(2) and \fBread\fR(2) system calls. For \fBprnio\fR compliant
71 printer drivers, forward transfer support is mandatory, while reverse transfer
72 support is optional. Applications can also use \fBPRNIOC_GET_STATUS\fR and
73 \fBPRNIOC_GET_1284_STATUS\fR commands during the transfer to monitor the device
74 state.
75 .sp
76 .LP
77 The Cleanup phase is accomplished by closing the device using \fBclose\fR(2).
78 Device drivers supporting \fBprnio\fR may set non-zero error code as
79 appropriate. Applications should explicitly \fBclose\fR(2) a device before
80 exiting and check \fBerrno\fR value.
81 .sp
82 .LP
83 The Abort phase is accomplished by interrupting the \fBwrite\fR(2) and
84 \fBread\fR(2) system calls. The application can perform some additional cleanup
85 during the Abort phase as described in \fBPRNIOC_GET_IFCAP\fR section.
86 .SH IOCTLS
87 .sp
88 .ne 2
89 .na
90 \fB\fBPRNIOC_GET_IFCAP\fR\fR
91 .ad
92 .RS 21n
93 Application can retrieve printer interface capabilities using this command. The
94 \fBioctl\fR(2) argument is a pointer to \fBuint_t\fR, a bit field representing
95 a set of properties and services provided by a printer driver. Set bit means
96 supported capability. The following values are defined:
97 .br
98 .in +2
99 \fBPRN_BIDI\fR - When this bit is set, the interface operates in a
100 bidirectional mode, instead of forward-only mode.
101 .in -2
102 .br
103 .in +2
104 \fBPRN_HOTPLUG\fR - If this bit is set, the interface allows device
105 hot-plugging.
106 .in -2
107 .br
108 .in +2
109 \fBPRN_1284_DEVID\fR - If this bit is set, the device is capable of returning
110 \fI1284\fR device ID (see \fBPRNIOC_GET_1284_DEVID\fR.)
111 .in -2
112 .br
113 .in +2
114 \fBPRN_1284_STATUS\fR - If this bit is set, the device driver can return device
115 status lines (see \fBPRNIOC_GET_1284_STATUS\fR). Some devices support this
116 ioctl in unidirectional mode only.
117 .in -2
118 .br
119 .in +2
120 \fBPRN_TIMEOUTS\fR - If this bit is set the peripheral may stall during the
121 transfer phase and the driver can timeout and return from the \fBwrite\fR(2)
122 and \fBread\fR(2) returning the number of bytes that have been transferred. If
123 \fBPRN_TIMEOUTS\fR is set, the driver supports this functionality and the
124 timeout values can be retrieved and modified via the \fBPRNIOC_GET_TIMEOUTS\fR
125 and \fBPRNIOC_SET_TIMEOUTS\fR ioctls. Otherwise, applications can implement
126 their own timeouts and abort phase.
127 .in -2
128 .br
129 .in +2
130 \fBPRN_STREAMS\fR - This bit impacts the application abort phase behaviour. If
131 the device claimed \fBPRN_STREAMS\fR capability, the application must issue an
132 \fBI_FLUSH\fR \fBioctl\fR(2) before \fBclose\fR(2) to dismiss the untransferred
133 data. Only STREAMS drivers can support this capability.
134 .in -2
135 .RE
136
137 .sp
138 .ne 2
139 .na
140 \fBPRNIOC_SET_IFCAP\fR
141 .ad
142 .RS 21n
143 This ioctl can be used to change interface capabilities. The argument is a
144 pointer to \fBuint_t\fR bit field that is described in detail in the
145 \fBPRNIOC_GET_IFCAP\fR section. Capabilities should be set one at a time;
146 otherwise the command will return \fBEINVAL\fR. The following capabilities can
147 be changed by this ioctl:
148 .br
149 .in +2
150 \fBPRN_BIDI\fR - When this capability is set, the interface operates in a
151 bidirectional mode, instead of forward-only mode. Devices that support only one
152 mode will not return error; applications should use \fBPRNIOC_GET_IFCAP\fR to
153 check if the mode was successfully changed. Because some capabilities may be
154 altered as a side effect of changing other capabilities, this command should be
155 followed by \fBPRNIOC_GET_IFCAP\fR.
156 .in -2
157 .RE
158
159 .sp
160 .ne 2
161 .na
162 \fBPRNIOC_GET_IFINFO\fR
163 .ad
164 .RS 21n
165 This command can be used to retrieve printer interface info string, which is an
166 arbitrary format string usually describing the bus type. The argument is a
167 pointer to \fBstruct prn_interface_info\fR as described below.
168 .RE
169
170 .sp
171 .in +2
172 .nf
173 struct prn_interface_info {
174 uint_t if_len; /* length of buffer */
175 uint_t if_rlen; /* actual info length */
176 char *if_data; /* buffer address */
177 };
178 .fi
179 .in -2
180
181 .sp
182 .LP
183 The application allocates a buffer and sets \fBif_data\fR and \fBif_len\fR
184 values to its address and length, respectively. The driver returns the string
185 to this buffer and sets \fBif_len\fR to its length. If \fBif_len\fR is less
186 that \fBif_rlen\fR, the driver must return the first \fBif_len\fR bytes of the
187 string. The application may then repeat the command with a bigger buffer.
188 .sp
189 .LP
190 Although \fBprnio\fR does not limit the contents of the interface info string,
191 some values are recommended and defined in <\fBsys/prnio.h\fR> by the following
192 macros:
193 .br
194 .in +2
195 \fBPRN_PARALLEL\fR - Centronics or \fIIEEE 1284\fR compatible devices
196 .in -2
197 .br
198 .in +2
199 \fBPRN_SERIAL\fR - EIA-232/EIA-485 serial ports
200 .in -2
201 .br
202 .in +2
203 \fBPRN_USB\fR - Universal Serial Bus printers
204 .in -2
205 .br
206 .in +2
207 \fBPRN_1394\fR - \fIIEEE 1394\fR peripherals
208 .in -2
209 .br
210 .in +2
211 Printer interface info string is for information only: no implications should
212 be made from its value.
213 .in -2
214 .sp
215 .ne 2
216 .na
217 \fBPRNIOC_RESET\fR
218 .ad
219 .RS 25n
220 Some applications may want to reset the printer state during Setup and/or
221 Cleanup phase using \fBPRNIOC_RESET\fR command. Reset semantics are
222 device-specific, and in general, applications using this command should be
223 aware of the printer type.
224 .sp
225 Each \fBprnio\fR compliant driver is required to accept this request, although
226 performed actions are completely driver-dependent. More information on the
227 \fBPRNIOC_RESET\fR implementation for the particular driver is available in the
228 corresponding man page and printer manual.
229 .RE
230
231 .sp
232 .ne 2
233 .na
234 \fBPRNIOC_GET_1284_DEVID\fR
235 .ad
236 .RS 25n
237 This command can be used to retrieve printer device ID as defined by \fIIEEE
238 1284-1994\fR.The \fBioctl\fR(2) argument is a pointer to \fBstruct
239 prn_1284_device_id\fR as described below.
240 .RE
241
242 .sp
243 .in +2
244 .nf
245 struct prn_1284_device_id {
246 uint_t id_len; /* length of buffer */
247 uint_t id_rlen; /* actual ID length */
248 char *id_data; /* buffer address */
249 };
250 .fi
251 .in -2
252
253 .sp
254 .LP
255 For convenience, the two-byte length field is not considered part of device ID
256 string and is not returned in the user buffer. Instead, \fBid_rlen\fR value
257 shall be set to (length - 2) by the driver, where length is the ID length field
258 value. If buffer length is less than \fBid_rlen\fR, the driver returns the
259 first \fBid_len\fR bytes of the ID.
260 .sp
261 .LP
262 The printer driver must return the most up-to-date value of the device ID.
263 .sp
264 .ne 2
265 .na
266 \fBPRNIOC_GET_STATUS\fR
267 .ad
268 .RS 21n
269 This command can be used by applications to retrieve current device status. The
270 argument is a pointer to \fBuint_t\fR, where the status word is returned.
271 Status is a combination of the following bits:
272 .RE
273
274 .br
275 .in +2
276 \fBPRN_ONLINE\fR - For devices that support \fBPRN_HOTPLUG\fR capability,
277 this bit is set when the device is online, otherwise the device is offline.
278 Devices without \fBPRN_HOTPLUG\fR support should always have this bit set.
279 .in -2
280 .br
281 .in +2
282 \fBPRN_READY\fR - This bit indicates if the device is ready to receive/send
283 data. Applications may use this bit for an outbound flow control
284 .in -2
285 .sp
286 .ne 2
287 .na
288 \fB\fBPRNIOC_GET_1284_STATUS\fR\fR
289 .ad
290 .RS 26n
291 Devices that support \fBPRN_1284_STATUS\fR capability accept this ioctl to
292 retrieve the device status lines defined in \fIIEEE 1284\fR for use in
293 Compatibility mode. The following bits may be set by the driver:
294 .br
295 .in +2
296 \fBPRN_1284_NOFAULT\fR - Device is not in error state
297 .in -2
298 .br
299 .in +2
300 \fBPRN_1284_SELECT\fR - Device is selected
301 .in -2
302 .br
303 .in +2
304 \fBPRN_1284_PE\fR - Paper error
305 .in -2
306 .br
307 .in +2
308 \fBPRN_1284_BUSY\fR - Device is busy
309 .in -2
310 .RE
311
312 .sp
313 .ne 2
314 .na
315 \fB\fBPRNIOC_GET_TIMEOUTS\fR\fR
316 .ad
317 .RS 26n
318 This command retrieves current transfer timeout values for the driver. The
319 argument is a pointer to \fBstruct prn_timeouts\fR as described below.
320 .RE
321
322 .sp
323 .in +2
324 .nf
325 struct prn_timeouts {
326 uint_t tmo_forward; /* forward transfer timeout */
327 uint_t tmo_reverse; /* reverse transfer timeout */
328 };
329 .fi
330 .in -2
331
332 .sp
333 .LP
334 \fBtmo_forward\fR and \fBtmo_reverse\fR define forward and reverse transfer
335 timeouts in seconds. This command is only valid for drivers that support
336 \fBPRN_TIMEOUTS\fR capability.
337 .sp
338 .ne 2
339 .na
340 \fB\fBPRNIOC_SET_TIMEOUTS\fR\fR
341 .ad
342 .RS 23n
343 This command sets current transfer timeout values for the driver. The
344 argument is a pointer to \fBstruct prn_timeouts\fR. See
345 \fBPRNIOC_GET_TIMEOUTS\fR for description of this structure. This command is
346 only valid for drivers that support \fBPRN_TIMEOUTS\fR capability.
347 .RE
348
349 .SH ATTRIBUTES
350 .sp
351 .LP
352 See \fBattributes\fR(5) for descriptions of the following attributes:
353 .sp
354
355 .sp
356 .TS
357 box;
358 c | c
359 l | l .
360 ATTRIBUTE TYPE ATTRIBUTE VALUE
361 _
362 Architecture SPARC, IA
363 _
364 Interface Stability Evolving
365 .TE
366
367 .SH SEE ALSO
368 .sp
369 .LP
370 \fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBwrite\fR(2),
371 \fBattributes\fR(5), \fBecpp\fR(7D), \fBusbprn\fR(7D), \fBlp\fR(7D)
372 .sp
373 .LP
374 \fIIEEE Std 1284-1994\fR