1prnio(7I) Ioctl Requests prnio(7I)
2
6 prnio - generic printer interface
7
9 #include <sys/prnio.h>
10
13 The prnio generic printer interface defines ioctl commands and data
14 structures for printer device drivers.
15 prnio defines and provides facilities for five basic phases of the
18 printing process:
19 o Identification — Retrieve device information/attributes
21 o Setup — Set device attributes
23 o Transfer — Transfer data to or from the device
25 o Cleanup — Transfer phase conclusion
27 o Abort — Transfer phase interruption
29 During the Identification phase, the application retrieves a set of
32 device capabilities and additional information using the
33 PRNIOC_GET_IFCAP, PRNIOC_GET_STATUS, PRNIOC_GET_TIMEOUTS,
34 PRNIOC_GET_IFINFO and PRNIOC_GET_1284_DEVID commands.
35 During the Setup phase the application sets some interface attributes
38 and probably resets the printer as described in the PRNIOC_SET_IFCAP,
39 PRNIOC_SET_TIMEOUTS and PRNIOC_RESET sections.
40 During the Transfer phase, data is transferred in a forward (host to
43 peripheral) or reverse direction (peripheral to host). Transfer is
44 accomplished using write(2) and read(2) system calls. For prnio compli‐
45 ant printer drivers, forward transfer support is mandatory, while
46 reverse transfer support is optional. Applications can also use
47 PRNIOC_GET_STATUS and PRNIOC_GET_1284_STATUS commands during the trans‐
48 fer to monitor the device state.
49 The Cleanup phase is accomplished by closing the device using close(2).
52 Device drivers supporting prnio may set non-zero error code as appro‐
53 priate. Applications should explicitly close(2) a device before exiting
54 and check errno value.
55 The Abort phase is accomplished by interrupting the write(2) and
58 read(2) system calls. The application can perform some additional
59 cleanup during the Abort phase as described in PRNIOC_GET_IFCAP sec‐
60 tion.
61
63 PRNIOC_GET_IFCAP Application can retrieve printer interface capa‐
64 bilities using this command. The ioctl(2) argument
65 is a pointer to uint_t, a bit field representing a
66 set of properties and services provided by a
67 printer driver. Set bit means supported capabil‐
68 ity. The following values are defined:
69 PRN_BIDI - When this bit is set, the interface
70 operates in a bidirectional mode, instead of
71 forward-only mode.
72 PRN_HOTPLUG - If this bit is set, the interface
73 allows device hot-plugging.
74 PRN_1284_DEVID - If this bit is set, the device
75 is capable of returning 1284 device ID (see
76 PRNIOC_GET_1284_DEVID.)
77 PRN_1284_STATUS - If this bit is set, the device
78 driver can return device status lines (see
79 PRNIOC_GET_1284_STATUS). Some devices support
80 this ioctl in unidirectional mode only.
81 PRN_TIMEOUTS - If this bit is set the peripheral
82 may stall during the transfer phase and the
83 driver can timeout and return from the write(2)
84 and read(2) returning the number of bytes that
85 have been transferred. If PRN_TIMEOUTS is set,
86 the driver supports this functionality and the
87 timeout values can be retrieved and modified via
88 the PRNIOC_GET_TIMEOUTS and PRNIOC_SET_TIMEOUTS
89 ioctls. Otherwise, applications can implement
90 their own timeouts and abort phase.
91 PRN_STREAMS - This bit impacts the application
92 abort phase behaviour. If the device claimed
93 PRN_STREAMS capability, the application must
94 issue an I_FLUSH ioctl(2) before close(2) to
95 dismiss the untransferred data. Only STREAMS
96 drivers can support this capability.
97 PRNIOC_SET_IFCAP This ioctl can be used to change interface capa‐
100 bilities. The argument is a pointer to uint_t bit
101 field that is described in detail in the
102 PRNIOC_GET_IFCAP section. Capabilities should be
103 set one at a time; otherwise the command will
104 return EINVAL. The following capabilities can be
105 changed by this ioctl:
106 PRN_BIDI - When this capability is set, the
107 interface operates in a bidirectional mode,
108 instead of forward-only mode. Devices that sup‐
109 port only one mode will not return error; appli‐
110 cations should use PRNIOC_GET_IFCAP to check if
111 the mode was successfully changed. Because some
112 capabilities may be altered as a side effect of
113 changing other capabilities, this command should
114 be followed by PRNIOC_GET_IFCAP.
115 PRNIOC_GET_IFINFO This command can be used to retrieve printer
118 interface info string, which is an arbitrary for‐
119 mat string usually describing the bus type. The
120 argument is a pointer to struct prn_interface_info
121 as described below.
122 struct prn_interface_info {
125 uint_t if_len; /* length of buffer */
126 uint_t if_rlen; /* actual info length */
127 char *if_data; /* buffer address */
128 };
129 The application allocates a buffer and sets if_data and if_len values
133 to its address and length, respectively. The driver returns the string
134 to this buffer and sets if_len to its length. If if_len is less that
135 if_rlen, the driver must return the first if_len bytes of the string.
136 The application may then repeat the command with a bigger buffer.
137 Although prnio does not limit the contents of the interface info
140 string, some values are recommended and defined in <sys/prnio.h> by the
141 following macros:
142 PRN_PARALLEL - Centronics or IEEE 1284 compatible devices
143 PRN_SERIAL - EIA-232/EIA-485 serial ports
144 PRN_USB - Universal Serial Bus printers
145 PRN_1394 - IEEE 1394 peripherals
146 Printer interface info string is for information only: no implica‐
147 tions should be made from its value.
148 PRNIOC_RESET Some applications may want to reset the
150 printer state during Setup and/or Cleanup
151 phase using PRNIOC_RESET command. Reset seman‐
152 tics are device-specific, and in general,
153 applications using this command should be
154 aware of the printer type.
155 Each prnio compliant driver is required to
157 accept this request, although performed
158 actions are completely driver-dependent. More
159 information on the PRNIOC_RESET implementation
160 for the particular driver is available in the
161 corresponding man page and printer manual.
162 PRNIOC_GET_1284_DEVID This command can be used to retrieve printer
165 device ID as defined by IEEE 1284-1994.The
166 ioctl(2) argument is a pointer to struct
167 prn_1284_device_id as described below.
168 struct prn_1284_device_id {
171 uint_t id_len; /* length of buffer */
172 uint_t id_rlen; /* actual ID length */
173 char *id_data; /* buffer address */
174 };
175 For convenience, the two-byte length field is not considered part of
179 device ID string and is not returned in the user buffer. Instead,
180 id_rlen value shall be set to (length - 2) by the driver, where length
181 is the ID length field value. If buffer length is less than id_rlen,
182 the driver returns the first id_len bytes of the ID.
183 The printer driver must return the most up-to-date value of the device
186 ID.
187 PRNIOC_GET_STATUS This command can be used by applications to
189 retrieve current device status. The argument is a
190 pointer to uint_t, where the status word is
191 returned. Status is a combination of the following
192 bits:
193 PRN_ONLINE - For devices that support PRN_HOTPLUG capability,
195 this bit is set when the device is online, otherwise the
196 device is offline. Devices without PRN_HOTPLUG support should always
197 have this bit set.
198 PRN_READY - This bit indicates if the device is ready to receive/send
199 data. Applications may use this bit for an outbound flow control
200 PRNIOC_GET_1284_STATUS Devices that support PRN_1284_STATUS capabil‐
202 ity accept this ioctl to retrieve the device
203 status lines defined in IEEE 1284 for use in
204 Compatibility mode. The following bits may be
205 set by the driver:
206 PRN_1284_NOFAULT - Device is not in error
207 state
208 PRN_1284_SELECT - Device is selected
209 PRN_1284_PE - Paper error
210 PRN_1284_BUSY - Device is busy
211 PRNIOC_GET_TIMEOUTS This command retrieves current transfer
214 timeout values for the driver. The argument
215 is a pointer to struct prn_timeouts as
216 described below.
217 struct prn_timeouts {
220 uint_t tmo_forward; /* forward transfer timeout */
221 uint_t tmo_reverse; /* reverse transfer timeout */
222 };
223 tmo_forward and tmo_reverse define forward and reverse transfer time‐
227 outs in seconds. This command is only valid for drivers that support
228 PRN_TIMEOUTS capability.
229 PRNIOC_SET_TIMEOUTS This command sets current transfer timeout val‐
231 ues for the driver. The argument is a pointer
232 to struct prn_timeouts. See PRNIOC_GET_TIMEOUTS
233 for description of this structure. This com‐
234 mand is only valid for drivers that support
235 PRN_TIMEOUTS capability.
236
239 See attributes(5) for descriptions of the following attributes:
240 ┌─────────────────────────────┬─────────────────────────────┐
245 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
246 ├─────────────────────────────┼─────────────────────────────┤
247 │Architecture │ SPARC, IA │
248 ├─────────────────────────────┼─────────────────────────────┤
249 │Interface Stability │Evolving │
250 └─────────────────────────────┴─────────────────────────────┘
251
253 close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D),
254 usbprn(7D), lp(7D)
255 IEEE Std 1284-1994
258SunOS 5.11 2 Jan 2002 prnio(7I)