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