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