Print this page
12745 man page typos
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7d/usbprn.7d
+++ new/usr/src/man/man7d/usbprn.7d
1 1 '\" te
2 2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 3 .\" 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.
4 4 .\" 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.
5 5 .\" 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]
6 -.TH USBPRN 7D "May 13, 2017"
6 +.TH USBPRN 7D "May 17, 2020"
7 7 .SH NAME
8 8 usbprn \- USB printer class driver
9 9 .SH SYNOPSIS
10 -.LP
11 10 .nf
12 11 #include <sys/usb/clients/printer/usb_printer.h>
13 12 .fi
14 13
15 14 .LP
16 15 .nf
17 16 #include <sys/ecppio.h>
18 17 .fi
19 18
20 19 .LP
21 20 .nf
22 21 usbprn@unit-address
23 22 .fi
24 23
25 24 .SH DESCRIPTION
26 -.LP
27 25 The \fBusbprn\fR driver is a USBA (Solaris USB Architecture) compliant client
28 26 driver that supports the \fIUSB Printer Class 1.0\fR specification. The
29 27 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) parallel port
30 28 driver functionality. However, unlike the STREAMS-based \fBecpp\fR driver,
31 29 \fBusbprn\fR is a character driver.
32 30 .sp
33 31 .LP
34 32 The \fBusbprn\fR driver supports all USB printer-class compliant printers.
35 33 .sp
36 34 .LP
37 35 The \fBusbrpn\fR driver includes support for communicating with many different
38 36 printers. To use these printers, it may be necessary to install and configure
39 37 additional format conversion packages available in the Solaris distribution.
40 38 Configuration of these conversion packages under the Solaris printing system
41 39 can be simplified through the use of the \fBprintmgr\fR(1M). This tool allows
42 40 selection of printer manufacturer/model information while creating a print
43 41 queue. For USB connected printers, it attempts to pre-select the
44 42 manufacturer and model information based on the 1284 device id supplied by the
45 43 printer.
46 44 .SS "UGEN (Generic USB)"
47 -.LP
48 45 The \fBusbprn\fR driver also supports a \fBugen\fR(7D) interface allowing raw
49 46 access to the device, for example by libusb applications, by
50 47 passing the drivers bound to each interface. Because a libusb application might
51 48 change the state of the device, you should not access the device through the
52 49 child interface drivers.
53 50 .SH DEFAULT OPERATION
54 -.LP
55 51 With certain minor exceptions (outlined in the Notes sections below), the
56 52 \fBusbprn\fR driver supports a subset of the \fBecpp\fR(7D) ioctl interfaces:
57 53 .sp
58 54 .LP
59 55 Configuration variables are set to their default values each time the USB
60 56 printer device is attached. The \fBwrite_timeout\fR period (defined in the
61 57 ECPPIOC_SETPARMS ioctl description below) is set to 90 seconds. The mode is set
62 58 to centronics mode (ECPP_CENTRONICS). Parameters can be changed through the
63 59 ECPPIOC_SETPARMS ioctl and read through the ECPPIOC_GETPARMS ioctl. Each time
64 60 the USB printer device is opened, the device is marked as busy and all further
65 61 opens will return EBUSY. Once the device is open, applications can write to the
|
↓ open down ↓ |
1 lines elided |
↑ open up ↑ |
66 62 device and the driver can send data and obtain device id and status.
67 63 .LP
68 64 Note -
69 65 .sp
70 66 .RS 2
71 67 Unlike the \fBecpp\fR(7D) driver, \fBusbprn\fR resets configuration variables
72 68 to their default values with each \fBattach\fR(9E). (The \fBecpp\fR(7D) driver
73 69 resets configuration variables with each \fBopen\fR(2).)
74 70 .RE
75 71 .SH WRITE OPERATION
76 -.LP
77 72 A \fBwrite\fR(2) operation returns the number of bytes successfully written to
78 73 the device. If a failure occurs while a driver is transferring data to printer,
79 74 the contents of the status bits are captured at the time of the error and can
80 75 be retrieved by the application program using the ECPPIOC_GETERR \fBioctl\fR(2)
81 76 call. The captured status information is overwritten each time an
82 77 ECPPIOC_TESTIO \fBioctl\fR(2) occurs.
83 78 .SH IOCTLS
84 -.LP
85 79 The \fBusbprn\fR driver supports \fBprnio\fR(7I) interfaces. Note that the
86 80 \fBPRNIOC_RESET\fR command has no effect on USB printers.
87 81 .sp
88 82 .LP
89 83 The following \fBioctl\fR(2) calls are supported for backward compatibility and
90 84 are not recommended for new applications.
91 85 .sp
92 86 .ne 2
93 87 .na
94 88 \fB\fBECPPIOC_GETPARMS\fR\fR
95 89 .ad
96 90 .RS 20n
97 91 Gets current transfer parameters. The argument is a pointer to \fBstruct
98 92 ecpp_transfer_parms\fR. If parameters are not configured after the device is
99 93 opened, the structure will be set to its default configuration.
100 94 .LP
101 95 Note -
102 96 .sp
103 97 .RS 2
104 98 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
105 99 supported in \fBusbprn\fR.
106 100 .RE
107 101 .RE
108 102
109 103 .sp
110 104 .ne 2
111 105 .na
112 106 \fB\fBECPPIOC_SETPARMS\fR\fR
113 107 .ad
114 108 .RS 20n
115 109 Sets transfer parameters. The argument is a pointer to a \fBstruct
116 110 ecpp_transfer_parms\fR. If a parameter is out of range, \fBEINVAL\fR is
117 111 returned. If the peripheral or host device cannot support the requested mode,
118 112 \fBEPROTONOSUPPORT\fR is returned.
119 113 .sp
120 114 The transfer parameters structure is defined in <\fBsys/ecppio.h\fR>:
121 115 .sp
122 116 .in +2
123 117 .nf
124 118 struct ecpp_transfer_parms {
125 119 int write_timeout;
126 120 int mode;
127 121 };
128 122 .fi
129 123 .in -2
130 124
131 125 The \fBwrite_timeout\fR field, which specifies how long the driver will take to
132 126 transfer 8192 bytes of data to the device, is set to a default value of 90
133 127 seconds. The \fBwrite_timeout\fR field must be greater than one second and less
134 128 than 300 seconds (five minutes.)
135 129 .LP
136 130 Note -
137 131 .sp
138 132 .RS 2
139 133 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
140 134 supported in \fBusbprn\fR. Also, the semantics of \fBwrite_timeout\fR in
141 135 \fBusbprn\fR differ from \fBecpp\fR(7D). Refer to \fBecpp\fR(7D) for
142 136 information.
143 137 .RE
144 138 .RE
145 139
146 140 .sp
|
↓ open down ↓ |
52 lines elided |
↑ open up ↑ |
147 141 .ne 2
148 142 .na
149 143 \fB\fBBPPIOC_TESTIO\fR\fR
150 144 .ad
151 145 .RS 20n
152 146 Tests the transfer readiness of a print device and checks status bits to
153 147 determine if a \fBwrite\fR(2) will succeed. If status bits are set, a transfer
154 148 will fail. If a transfer will succeed, zero is returned. If a transfer fails,
155 149 the driver returns \fBEIO\fR and the state of the status bits are captured. The
156 150 captured status can be retrieved using the BPPIOC_GETERR \fBioctl\fR(2) call.
157 -BPPIOC_TESTIO and BPPIOC_GETERR are compatible to the ioctls specified in
158 -\fBbpp\fR(7D).
159 151 .LP
160 152 Note -
161 153 .sp
162 154 .RS 2
163 155 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
164 156 supported in \fBusbprn\fR. Additionally, \fBbus_error\fR and
165 157 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
166 158 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.)
167 159 .RE
168 160 .RE
169 161
170 162 .sp
171 163 .ne 2
172 164 .na
173 165 \fB\fBBPPIOC_GETERR\fR\fR
174 166 .ad
175 167 .RS 20n
176 168 Get last error status. The argument is a pointer to a \fBstruct
177 169 bpp_error_status\fR. This structure indicates the status of all the appropriate
178 170 status bits at the time of the most recent error condition during a
179 171 \fBwrite\fR(2) call, or the status of the bits at the most recent BPPIOC_TESTIO
180 172 \fBioctl\fR(2) call.
181 173 .sp
182 174 .in +2
183 175 .nf
184 176 struct bpp_error_status {
185 177 char timeout_occurred; /* not used */
186 178 char bus_error; /* not used */
187 179 uchar_t pin_status; /* status of pins which
188 180 /* could cause error */
189 181 };
190 182 .fi
191 183 .in -2
192 184
193 185 The pin_status field indicates possible error conditions. The error status
194 186 structure \fBbpp_error_status\fR is defined in the include file
195 187 \fB<sys/bpp_io.h>\fR\&. The valid bits for \fBpin_status\fR can be
196 188 \fBBPP_ERR_ERR\fR, \fBBPP_SLCT_ERR\fR, and \fBBPP_PE_ERR\fR. A set bit
197 189 indicates that the associated pin is asserted.
198 190 .LP
199 191 Note -
200 192 .sp
201 193 .RS 2
202 194 Unlike the \fBecpp\fR(7D) driver, only the ECPP_CENTRONICS mode is currently
203 195 supported in \fBusbprn\fR. Additionally, the \fBbus_error\fR and
204 196 \fBtimeout_occurred\fR fields are not used in the \fBusbprn\fR interface. (In
205 197 \fBecpp\fR(7D), \fBtimeout_occurred\fR is used.) Unlike \fBecpp\fR(7D), the
206 198 BPP_BUSY_ERR status bit is not supported by USB printers.
207 199 .RE
208 200 .RE
209 201
210 202 .sp
211 203 .ne 2
212 204 .na
213 205 \fB\fBECPPIOC_GETDEVID\fR\fR
214 206 .ad
215 207 .RS 20n
216 208 Gets the IEEE 1284 device ID from the peripheral. The argument is a pointer to
217 209 a \fBstruct ecpp_device_id\fR. Applications should set mode to ECPP_CENTRONICS.
218 210 If another mode is used, the driver will return \fBEPROTONOSUPPORT\fR.
219 211 \fBlen\fR is the length of the buffer pointed to by \fBaddr\fR. \fBrlen\fR is
220 212 the actual length of the device ID string returned from the peripheral. If the
221 213 returned \fBrlen\fR is greater than \fBlen\fR, the application should call
222 214 ECPPIOC_GETDEVID a second time with a buffer length equal to \fBrlen\fR.
223 215 .sp
224 216 The 1284 device ID structure:
225 217 .sp
226 218 .in +2
227 219 .nf
228 220 struct ecpp_device_id {
229 221 int mode; /* mode to use for reading device id */
230 222 int len; /* length of buffer */
231 223 int rlen; /* actual length of device id string */
232 224 char *addr; /* buffer address */
233 225 .fi
234 226 .in -2
235 227
|
↓ open down ↓ |
67 lines elided |
↑ open up ↑ |
236 228 .LP
237 229 Note -
238 230 .sp
239 231 .RS 2
240 232 Unlike \fBecpp\fR(7D), only the ECPP_CENTRONICS mode is currently supported in
241 233 \fBusbprn\fR.
242 234 .RE
243 235 .RE
244 236
245 237 .SH READ OPERATION
246 -.LP
247 238 The \fBread\fR operation is not supported and returns \fBEIO\fR.
248 239 .SH ERRORS
249 240 .ne 2
250 241 .na
251 242 \fB\fBEBUSY\fR\fR
252 243 .ad
253 244 .RS 19n
254 245 The device has been opened and another open is attempted. An attempt has been
255 246 made to unload the driver while one of the units is open.
256 247 .RE
257 248
258 249 .sp
259 250 .ne 2
260 251 .na
261 252 \fB\fBEINVAL\fR\fR
262 253 .ad
263 254 .RS 19n
264 255 An unsupported IOCTL has been received. A ECPPIOC_SETPARMS \fBioctl\fR(2) is
265 256 attempted with an out of range value in the \fBecpp_transfer_parms\fR
266 257 structure.
267 258 .RE
268 259
269 260 .sp
270 261 .ne 2
271 262 .na
272 263 \fB\fBEIO\fR\fR
273 264 .ad
274 265 .RS 19n
275 266 The driver has received an unrecoverable device error, or the device is not
276 267 responding, or the device has stalled when attempting an access. A
277 268 \fBwrite\fR(2) or \fBioctl\fR(2) did not complete due to a peripheral access. A
278 269 \fBread\fR(2) system call has been issued.
279 270 .RE
280 271
281 272 .sp
282 273 .ne 2
283 274 .na
284 275 \fB\fBENXIO\fR\fR
285 276 .ad
286 277 .RS 19n
287 278 The driver has received an \fBopen\fR(2) request for a unit for which the
288 279 attach failed.
289 280 .RE
290 281
291 282 .sp
292 283 .ne 2
293 284 .na
294 285 \fB\fBENODEV\fR\fR
295 286 .ad
296 287 .RS 19n
297 288 The driver has received an \fBopen\fR(2) request for a device that has been
298 289 disconnected.
299 290 .RE
300 291
301 292 .sp
302 293 .ne 2
303 294 .na
304 295 \fB\fBEPROTONOSUPPORT\fR\fR
305 296 .ad
306 297 .RS 19n
307 298 The driver has received a ECPPIOC_SETPARMS \fBioctl\fR(2) for a mode argument
308 299 other than ECPP_CENTRONICS in the \fBecpp_transfer_parms\fR structure.
309 300 .RE
310 301
311 302 .SH FILES
312 303 .ne 2
313 304 .na
314 305 \fB\fB/kernel/drv/usbprn\fR\fR
315 306 .ad
316 307 .RS 30n
317 308 32-bit x86 ELF kernel module
318 309 .RE
319 310
320 311 .sp
321 312 .ne 2
322 313 .na
323 314 \fB\fB/kernel/drv/amd64/usbprn\fR\fR
324 315 .ad
325 316 .RS 30n
326 317 64-bit x86 ELF kernel module
327 318 .RE
328 319
329 320 .sp
330 321 .ne 2
331 322 .na
332 323 \fB\fB/kernel/drv/sparcv9/usbprn\fR\fR
333 324 .ad
334 325 .RS 30n
335 326 64-bit SPARC ELF kernel module
336 327 .RE
337 328
338 329 .sp
339 330 .ne 2
340 331 .na
341 332 \fB/dev/usb/*/*/* \fR
342 333 .ad
343 334 .RS 30n
344 335 ugen(7D) nodes.
345 336 .RE
346 337
|
↓ open down ↓ |
90 lines elided |
↑ open up ↑ |
347 338 .sp
348 339 .ne 2
349 340 .na
350 341 \fB\fB/dev/printers/\fIn\fR\fR\fR
351 342 .ad
352 343 .RS 30n
353 344 Character special files
354 345 .RE
355 346
356 347 .SH ATTRIBUTES
357 -.LP
358 348 See \fBattributes\fR(5) for descriptions of the following attributes:
359 349 .sp
360 350
361 351 .sp
362 352 .TS
363 353 box;
364 354 c | c
365 355 l | l .
366 356 ATTRIBUTE TYPE ATTRIBUTE VALUE
367 357 _
368 358 Architecture SPARC, x86, PCI-based systems
369 359 .TE
370 360
371 361 .SH SEE ALSO
372 -.LP
373 362 \fBcfgadm_usb\fR(1M), \fBprintmgr\fR(1M), \fBioctl\fR(2), \fBopen\fR(2),
374 363 \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
375 -\fBbpp\fR(7D), \fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D), \fBprnio\fR(7I),
364 +\fBecpp\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D), \fBprnio\fR(7I),
376 365 \fBattach\fR(9E)
377 366 .sp
378 367 .LP
379 368 \fIWriting Device Drivers\fR
380 369 .sp
381 370 .LP
382 371 \fIUniversal Serial Bus Specification 1.0 and 1.1\fR
383 372 .sp
384 373 .LP
385 374 \fIUSB Device Class Definition for Printing Devices 1.0\fR
386 375 .sp
387 376 .LP
388 377 \fISystem Administration Guide: Basic Administration\fR
389 378 .SH DIAGNOSTICS
390 -.LP
391 379 In addition to being logged, the following messages may appear on the system
392 380 console. All messages are formatted in the following manner:
393 381 .sp
394 382 .in +2
395 383 .nf
396 384 Warning: <device path> (usbprn<instance num>): Error Message...
397 385 .fi
398 386 .in -2
399 387 .sp
400 388
401 389 .sp
402 390 .ne 2
403 391 .na
404 392 \fBDevice was disconnected while open. Data may have been lost.\fR
405 393 .ad
406 394 .sp .6
407 395 .RS 4n
408 396 The device has been hot-removed or powered off while it was open and a possible
409 397 data transfer was in progress. The job may be aborted.
410 398 .RE
411 399
412 400 .sp
413 401 .ne 2
414 402 .na
415 403 \fBCannot access <device>. Please reconnect.\fR
416 404 .ad
417 405 .sp .6
418 406 .RS 4n
419 407 There was an error in accessing the printer during reconnect. Please reconnect
420 408 the device.
421 409 .RE
422 410
423 411 .sp
424 412 .ne 2
425 413 .na
426 414 \fBDevice is not identical to the previous one on this port. Please disconnect
427 415 and reconnect.\fR
428 416 .ad
429 417 .sp .6
430 418 .RS 4n
431 419 A USB printer was hot-removed while open. A new device was hot-inserted which
432 420 is not identical to the original USB printer. Please disconnect the USB device
433 421 and reconnect the printer to the same port.
434 422 .RE
435 423
436 424 .sp
437 425 .ne 2
438 426 .na
|
↓ open down ↓ |
38 lines elided |
↑ open up ↑ |
439 427 \fBPrinter has been reconnected but data may have been lost.\fR
440 428 .ad
441 429 .sp .6
442 430 .RS 4n
443 431 The printer that was hot-removed from its USB port has been re-inserted again
444 432 to the same port. It is available for access but the job that was running prior
445 433 to the hot-removal may be lost.
446 434 .RE
447 435
448 436 .SH NOTES
449 -.LP
450 437 The USB printer will be power managed if the device is closed.
451 438 .sp
452 439 .LP
453 440 If a printer is hot-removed before a job completes, the job is terminated and
454 441 the driver will return EIO. All subsequent opens will return \fBENODEV\fR. If a
455 442 printer is hot-removed, an LP reconfiguration may not be needed if a printer is
456 443 re-inserted on the same port. If re-inserted on a different port, an LP
457 444 reconfiguration may be required.
458 445 .sp
459 446 .LP
460 447 The USB Parallel Printer Adapter is not hotpluggable. The printer should be
461 448 connected to USB Parallel Printer Adapter before plugging the USB cable into
462 449 host or hub port and should be removed only after disconnecting the USB cable
463 450 of USB Parallel Printer Adapter from the host or hub port.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX