1 PRNIO(7I) Ioctl Requests PRNIO(7I)
2
3
4
5 NAME
6 prnio - generic printer interface
7
8 SYNOPSIS
9 #include <sys/prnio.h>
10
11
12 DESCRIPTION
13 The prnio generic printer interface defines ioctl commands and data
14 structures for printer device drivers.
15
16
17 prnio defines and provides facilities for five basic phases of the
18 printing process:
19
20 o Identification -- Retrieve device information/attributes
21
22 o Setup -- Set device attributes
23
24 o Transfer -- Transfer data to or from the device
25
26 o Cleanup -- Transfer phase conclusion
27
28 o Abort -- Transfer phase interruption
29
30
31 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
36
37 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
41
42 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
45 compliant 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
48 transfer to monitor the device state.
49
50
51 The Cleanup phase is accomplished by closing the device using close(2).
52 Device drivers supporting prnio may set non-zero error code as
53 appropriate. Applications should explicitly close(2) a device before
54 exiting and check errno value.
55
56
57 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
60 section.
61
62 IOCTLS
63 PRNIOC_GET_IFCAP
64 Application can retrieve printer interface
65 capabilities using this command. The ioctl(2)
66 argument is a pointer to uint_t, a bit field
67 representing a set of properties and services
68 provided by a printer driver. Set bit means
69 supported capability. The following values are
70 defined:
71 PRN_BIDI - When this bit is set, the interface
72 operates in a bidirectional mode, instead of
73 forward-only mode.
74 PRN_HOTPLUG - If this bit is set, the interface
75 allows device hot-plugging.
76 PRN_1284_DEVID - If this bit is set, the device
77 is capable of returning 1284 device ID (see
78 PRNIOC_GET_1284_DEVID.)
79 PRN_1284_STATUS - If this bit is set, the device
80 driver can return device status lines (see
81 PRNIOC_GET_1284_STATUS). Some devices support
82 this ioctl in unidirectional mode only.
83 PRN_TIMEOUTS - If this bit is set the peripheral
84 may stall during the transfer phase and the
85 driver can timeout and return from the write(2)
86 and read(2) returning the number of bytes that
87 have been transferred. If PRN_TIMEOUTS is set,
88 the driver supports this functionality and the
89 timeout values can be retrieved and modified via
90 the PRNIOC_GET_TIMEOUTS and PRNIOC_SET_TIMEOUTS
91 ioctls. Otherwise, applications can implement
92 their own timeouts and abort phase.
93 PRN_STREAMS - This bit impacts the application
94 abort phase behaviour. If the device claimed
95 PRN_STREAMS capability, the application must
96 issue an I_FLUSH ioctl(2) before close(2) to
97 dismiss the untransferred data. Only STREAMS
98 drivers can support this capability.
99
100
101 PRNIOC_SET_IFCAP
102 This ioctl can be used to change interface
103 capabilities. The argument is a pointer to uint_t
104 bit field that is described in detail in the
105 PRNIOC_GET_IFCAP section. Capabilities should be
106 set one at a time; otherwise the command will
107 return EINVAL. The following capabilities can be
108 changed by this ioctl:
109 PRN_BIDI - When this capability is set, the
110 interface operates in a bidirectional mode,
111 instead of forward-only mode. Devices that
112 support only one mode will not return error;
113 applications should use PRNIOC_GET_IFCAP to
114 check if the mode was successfully changed.
115 Because some capabilities may be altered as a
116 side effect of changing other capabilities, this
117 command should be followed by PRNIOC_GET_IFCAP.
118
119
120 PRNIOC_GET_IFINFO
121 This command can be used to retrieve printer
122 interface info string, which is an arbitrary
123 format string usually describing the bus type. The
124 argument is a pointer to struct prn_interface_info
125 as described below.
126
127
128 struct prn_interface_info {
129 uint_t if_len; /* length of buffer */
130 uint_t if_rlen; /* actual info length */
131 char *if_data; /* buffer address */
132 };
133
134
135
136 The application allocates a buffer and sets if_data and if_len values
137 to its address and length, respectively. The driver returns the string
138 to this buffer and sets if_len to its length. If if_len is less that
139 if_rlen, the driver must return the first if_len bytes of the string.
140 The application may then repeat the command with a bigger buffer.
141
142
143 Although prnio does not limit the contents of the interface info
144 string, some values are recommended and defined in <sys/prnio.h> by the
145 following macros:
146 PRN_PARALLEL - Centronics or IEEE 1284 compatible devices
147 PRN_SERIAL - EIA-232/EIA-485 serial ports
148 PRN_USB - Universal Serial Bus printers
149 PRN_1394 - IEEE 1394 peripherals
150 Printer interface info string is for information only: no
151 implications should be made from its value.
152
153 PRNIOC_RESET
154 Some applications may want to reset the
155 printer state during Setup and/or Cleanup
156 phase using PRNIOC_RESET command. Reset
157 semantics are device-specific, and in general,
158 applications using this command should be
159 aware of the printer type.
160
161 Each prnio compliant driver is required to
162 accept this request, although performed
163 actions are completely driver-dependent. More
164 information on the PRNIOC_RESET implementation
165 for the particular driver is available in the
166 corresponding man page and printer manual.
167
168
169 PRNIOC_GET_1284_DEVID
170 This command can be used to retrieve printer
171 device ID as defined by IEEE 1284-1994.The
172 ioctl(2) argument is a pointer to struct
173 prn_1284_device_id as described below.
174
175
176 struct prn_1284_device_id {
177 uint_t id_len; /* length of buffer */
178 uint_t id_rlen; /* actual ID length */
179 char *id_data; /* buffer address */
180 };
181
182
183
184 For convenience, the two-byte length field is not considered part of
185 device ID string and is not returned in the user buffer. Instead,
186 id_rlen value shall be set to (length - 2) by the driver, where length
187 is the ID length field value. If buffer length is less than id_rlen,
188 the driver returns the first id_len bytes of the ID.
189
190
191 The printer driver must return the most up-to-date value of the device
192 ID.
193
194 PRNIOC_GET_STATUS
195 This command can be used by applications to
196 retrieve current device status. The argument is a
197 pointer to uint_t, where the status word is
198 returned. Status is a combination of the
199 following bits:
200
201 PRN_ONLINE - For devices that support PRN_HOTPLUG capability, this
202 bit is set when the device is online, otherwise the device is
203 offline. Devices without PRN_HOTPLUG support should always have this
204 bit set.
205 PRN_READY - This bit indicates if the device is ready to receive/send
206 data. Applications may use this bit for an outbound flow control
207
208 PRNIOC_GET_1284_STATUS
209 Devices that support PRN_1284_STATUS
210 capability accept this ioctl to retrieve the
211 device status lines defined in IEEE 1284 for
212 use in Compatibility mode. The following bits
213 may be set by the driver:
214 PRN_1284_NOFAULT - Device is not in error
215 state
216 PRN_1284_SELECT - Device is selected
217 PRN_1284_PE - Paper error
218 PRN_1284_BUSY - Device is busy
219
220
221 PRNIOC_GET_TIMEOUTS
222 This command retrieves current transfer
223 timeout values for the driver. The argument
224 is a pointer to struct prn_timeouts as
225 described below.
226
227
228 struct prn_timeouts {
229 uint_t tmo_forward; /* forward transfer timeout */
230 uint_t tmo_reverse; /* reverse transfer timeout */
231 };
232
233
234
235 tmo_forward and tmo_reverse define forward and reverse transfer
236 timeouts in seconds. This command is only valid for drivers that
237 support PRN_TIMEOUTS capability.
238
239 PRNIOC_SET_TIMEOUTS
240 This command sets current transfer timeout
241 values for the driver. The argument is a
242 pointer to struct prn_timeouts. See
243 PRNIOC_GET_TIMEOUTS for description of this
244 structure. This command is only valid for
245 drivers that support PRN_TIMEOUTS capability.
246
247
248 ATTRIBUTES
249 See attributes(5) for descriptions of the following attributes:
250
251
252
253
254 +--------------------+-----------------+
255 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
256 +--------------------+-----------------+
257 |Architecture | SPARC, IA |
258 +--------------------+-----------------+
259 |Interface Stability | Evolving |
260 +--------------------+-----------------+
261
262 SEE ALSO
263 close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D),
264 usbprn(7D), lp(7D)
265
266
267 IEEE Std 1284-1994
268
269
270
271 January 2, 2002 PRNIO(7I)