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)
|
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
|