Print this page
10530 Convert prnio(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/prnio.7i.man.txt
+++ new/usr/src/man/man7i/prnio.7i.man.txt
1 1 PRNIO(7I) Ioctl Requests PRNIO(7I)
2 2
3 -
4 -
5 3 NAME
6 - prnio - generic printer interface
4 + prnio - generic printer interface
7 5
8 6 SYNOPSIS
9 - #include <sys/prnio.h>
7 + #include <sys/prnio.h>
10 8
11 -
12 9 DESCRIPTION
13 - The prnio generic printer interface defines ioctl commands and data
14 - structures for printer device drivers.
10 + The prnio generic printer interface defines ioctl commands and data
11 + structures for printer device drivers.
15 12
13 + prnio defines and provides facilities for five basic phases of the
14 + printing process:
16 15
17 - prnio defines and provides facilities for five basic phases of the
18 - printing process:
16 + o Identification -- Retrieve device information/attributes
19 17
20 - o Identification -- Retrieve device information/attributes
18 + o Setup -- Set device attributes
21 19
22 - o Setup -- Set device attributes
20 + o Transfer -- Transfer data to or from the device
23 21
24 - o Transfer -- Transfer data to or from the device
22 + o Cleanup -- Transfer phase conclusion
25 23
26 - o Cleanup -- Transfer phase conclusion
24 + o Abort -- Transfer phase interruption
27 25
28 - o Abort -- Transfer phase interruption
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.
29 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.
30 34
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 + 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.
35 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.
36 47
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.
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.
40 51
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 52 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.
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:
99 59
60 + PRN_BIDI When this bit is set, the interface
61 + operates in a bidirectional mode,
62 + instead of forward-only mode.
100 63
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.
64 + PRN_HOTPLUG If this bit is set, the interface
65 + allows device hot-plugging.
118 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).
119 70
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.
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.
126 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.
127 90
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 - };
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.
133 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:
134 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.
135 117
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.
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.
141 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 + };
142 129
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.
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.
152 137
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.
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:
160 141
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.
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
167 147
148 + Printer interface info string is for information only:
149 + no implications should be made from its value.
168 150
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.
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.
174 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.
175 163
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 - };
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.
181 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 + };
182 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 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.
184 + The printer driver must return the most up-to-date
185 + value of the device ID.
189 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:
190 191
191 - The printer driver must return the most up-to-date value of the device
192 - ID.
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.
193 197
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:
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.
200 201
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
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 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
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
219 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.
220 217
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.
218 + struct prn_timeouts {
219 + uint_t tmo_forward; /* forward transfer timeout */
220 + uint_t tmo_reverse; /* reverse transfer timeout */
221 + };
226 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 227
228 - struct prn_timeouts {
229 - uint_t tmo_forward; /* forward transfer timeout */
230 - uint_t tmo_reverse; /* reverse transfer timeout */
231 - };
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.
232 234
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 235 SEE ALSO
263 - close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D),
264 - usbprn(7D), lp(7D)
236 + close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D), lp(7D),
237 + usbprn(7D)
265 238
239 + IEEE Std 1284-1994.
266 240
267 - IEEE Std 1284-1994
268 -
269 -
270 -
271 - January 2, 2002 PRNIO(7I)
241 +illumos August 31, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX