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