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