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