Print this page
10596 Convert streamio(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/streamio.7i
+++ new/usr/src/man/man7i/streamio.7i
1 -'\" te
1 +.\" Copyright (c) 2017, Joyent, Inc.
2 2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 1989 AT&T
4 -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
6 -.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 -.TH STREAMIO 7I "Apr 8, 2009"
8 -.SH NAME
9 -streamio \- STREAMS ioctl commands
10 -.SH SYNOPSIS
11 -.LP
12 -.nf
13 -#include <sys/types.h>
14 -#include <stropts.h>
15 -#include <sys/conf.h>
16 -
17 -\fBint\fR \fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcommand\fR, \fB\&... /*arg*/\fR);
18 -.fi
19 -
20 -.SH DESCRIPTION
21 -.sp
22 -.LP
23 -STREAMS (see \fBIntro\fR(3)) \fBioctl\fR commands are a subset of the
24 -\fBioctl\fR(2) commands and perform a variety of control functions on streams.
25 -.sp
26 -.LP
27 -The \fIfildes\fR argument is an open file descriptor that refers to a stream.
28 -The \fIcommand\fR argument determines the control function to be performed as
29 -described below. The \fIarg\fR argument represents additional information that
30 -is needed by this command. The type of \fIarg\fR depends upon the command, but
4 +.\" The contents of this file are subject to the terms of the
5 +.\" Common Development and Distribution License (the "License").
6 +.\" You may not use this file except in compliance with the License.
7 +.\"
8 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 +.\" or http://www.opensolaris.org/os/licensing.
10 +.\" See the License for the specific language governing permissions
11 +.\" and limitations under the License.
12 +.\"
13 +.\" When distributing Covered Code, include this CDDL HEADER in each
14 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 +.\" If applicable, add the following below this CDDL HEADER, with the
16 +.\" fields enclosed by brackets "[]" replaced with your own identifying
17 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
18 +.Dd October 29, 2017
19 +.Dt STREAMIO 7I
20 +.Os
21 +.Sh NAME
22 +.Nm streamio
23 +.Nd STREAMS ioctl commands
24 +.Sh SYNOPSIS
25 +.In sys/types.h
26 +.In stropts.h
27 +.In sys/conf.h
28 +.Ft int
29 +.Fo ioctl
30 +.Fa "int fildes"
31 +.Fa "int command"
32 +.Fa "\&... /*arg*/"
33 +.Fc
34 +.Sh DESCRIPTION
35 +STREAMS (see
36 +.Xr Intro 3 )
37 +.Fn ioctl
38 +commands are a subset of the
39 +.Xr ioctl 2
40 +commands and perform a variety of control functions on streams.
41 +.Pp
42 +The
43 +.Fa fildes
44 +argument is an open file descriptor that refers to a stream.
45 +The
46 +.Fa command
47 +argument determines the control function to be performed as
48 +described below.
49 +The
50 +.Fa arg
51 +argument represents additional information that
52 +is needed by this command.
53 +The type of
54 +.Fa arg
55 +depends upon the command, but
31 56 it is generally an integer or a pointer to a command-specific data structure.
32 -The \fIcommand\fR and \fIarg\fR arguments are interpreted by the STREAM head.
57 +The
58 +.Fa command
59 +and
60 +.Fa arg
61 +arguments are interpreted by the STREAM head.
33 62 Certain combinations of these arguments may be passed to a module or driver in
34 63 the stream.
35 -.sp
36 -.LP
37 -Since these STREAMS commands are \fBioctls\fR, they are subject to the errors
38 -described in \fBioctl\fR(2). In addition to those errors, the call will fail
39 -with \fBerrno\fR set to \fBEINVAL,\fR without processing a control function, if
40 -the STREAM referenced by \fIfildes\fR is linked below a multiplexor, or if
41 -\fIcommand\fR is not a valid value for a stream.
42 -.sp
43 -.LP
44 -Also, as described in \fBioctl\fR(2), STREAMS modules and drivers can detect
45 -errors. In this case, the module or driver sends an error message to the STREAM
46 -head containing an error value. This causes subsequent calls to fail with
47 -\fBerrno\fR set to this value.
48 -.SH IOCTLS
49 -.sp
50 -.LP
51 -The following \fBioctl\fR commands, with error values indicated, are applicable
52 -to all STREAMS files:
53 -.sp
54 -.ne 2
55 -.na
56 -\fB\fBI_PUSH\fR\fR
57 -.ad
58 -.RS 15n
59 -Pushes the module whose name is pointed to by \fIarg\fR onto the top of the
60 -current stream, just below the STREAM head. If the STREAM is a pipe, the module
61 -will be inserted between the stream heads of both ends of the pipe. It then
62 -calls the open routine of the newly-pushed module. On failure, \fBerrno\fR is
63 -set to one of the following values:
64 -.sp
65 -.ne 2
66 -.na
67 -\fB\fBEINVAL\fR\fR
68 -.ad
69 -.RS 11n
64 +.Pp
65 +Since these STREAMS commands are
66 +.Sy ioctls ,
67 +they are subject to the errors described in
68 +.Xr ioctl 2 .
69 +In addition to those errors, the call will fail
70 +with
71 +.Va errno
72 +set to
73 +.Er EINVAL ,
74 +without processing a control function, if the STREAM referenced by
75 +.Fa fildes
76 +is linked below a multiplexor, or if
77 +.Fa command
78 +is not a valid value for a stream.
79 +.Pp
80 +Also, as described in
81 +.Xr ioctl 2 ,
82 +STREAMS modules and drivers can detect
83 +errors.
84 +In this case, the module or driver sends an error message to the STREAM
85 +head containing an error value.
86 +This causes subsequent calls to fail with
87 +.Va errno
88 +set to this value.
89 +.Sh IOCTLS
90 +The following
91 +.Fn ioctl
92 +commands, with error values indicated, are applicable to all STREAMS files:
93 +.Bl -tag -width I_SETCLTIME
94 +.It Dv I_PUSH
95 +Pushes the module whose name is pointed to by
96 +.Va arg
97 +onto the top of the current stream, just below the STREAM head.
98 +If the STREAM is a pipe, the module
99 +will be inserted between the stream heads of both ends of the pipe.
100 +It then calls the open routine of the newly-pushed module.
101 +On failure,
102 +.Va errno
103 +is set to one of the following values:
104 +.Bl -tag -width ENOTSUP
105 +.It Er EINVAL
70 106 Invalid module name.
71 -.RE
72 -
73 -.sp
74 -.ne 2
75 -.na
76 -\fB\fBEFAULT\fR\fR
77 -.ad
78 -.RS 11n
79 -\fIarg\fR points outside the allocated address space.
80 -.RE
81 -
82 -.sp
83 -.ne 2
84 -.na
85 -\fB\fBENXIO\fR\fR
86 -.ad
87 -.RS 11n
107 +.It Er EFAULT
108 +.Va arg
109 +points outside the allocated address space.
110 +.It Er ENXIO
88 111 Open routine of new module failed.
89 -.RE
90 -
91 -.sp
92 -.ne 2
93 -.na
94 -\fB\fBENXIO\fR\fR
95 -.ad
96 -.RS 11n
97 -Hangup received on \fIfildes\fR.
98 -.RE
99 -
100 -.sp
101 -.ne 2
102 -.na
103 -\fB\fBENOTSUP\fR\fR
104 -.ad
105 -.RS 11n
112 +.It Er ENXIO
113 +Hangup received on
114 +.Va fildes .
115 +.It Er ENOTSUP
106 116 Pushing a module is not supported on this stream.
107 -.RE
108 -
109 -.RE
110 -
111 -.sp
112 -.ne 2
113 -.na
114 -\fB\fBI_POP\fR\fR
115 -.ad
116 -.RS 15n
117 +.El
118 +.It Dv I_POP
117 119 Removes the module just below the STREAM head of the STREAM pointed to by
118 -\fIfildes\fR. To remove a module from a pipe requires that the module was
119 -pushed on the side it is being removed from. \fIarg\fR should be \fB0\fR in an
120 -\fBI_POP\fR request. On failure, \fBerrno\fR is set to one of the following
121 -values:
122 -.sp
123 -.ne 2
124 -.na
125 -\fB\fBEINVAL\fR\fR
126 -.ad
127 -.RS 11n
120 +.Fa fildes .
121 +To remove a module from a pipe requires that the module was
122 +pushed on the side it is being removed from.
123 +.Fa arg
124 +should be
125 +.Sy 0
126 +in an
127 +.Dv I_POP
128 +request.
129 +On failure,
130 +.Va errno
131 +is set to one of the following values:
132 +.Bl -tag -width ENOTSUP
133 +.It Er EINVAL
128 134 No module present in the stream.
129 -.RE
130 -
131 -.sp
132 -.ne 2
133 -.na
134 -\fB\fBENXIO\fR\fR
135 -.ad
136 -.RS 11n
137 -Hangup received on \fIfildes\fR.
138 -.RE
139 -
140 -.sp
141 -.ne 2
142 -.na
143 -\fB\fBEPERM\fR\fR
144 -.ad
145 -.RS 11n
135 +.It Er ENXIO
136 +Hangup received on
137 +.Fa fildes .
138 +.It Er EPERM
146 139 Attempt to pop through an anchor by an unprivileged process.
147 -.RE
148 -
149 -.sp
150 -.ne 2
151 -.na
152 -\fB\fBENOTSUP\fR\fR
153 -.ad
154 -.RS 11n
140 +.It Er ENOTSUP
155 141 Removal is not supported.
156 -.RE
157 -
158 -.RE
159 -
160 -.sp
161 -.ne 2
162 -.na
163 -\fB\fBI_ANCHOR\fR\fR
164 -.ad
165 -.RS 15n
142 +.El
143 +.It Dv I_ANCHOR
166 144 Positions the stream anchor to be at the stream's module directly below the
167 -stream head. Once this has been done, only a privileged process may pop modules
168 -below the anchor on the stream. \fIarg\fR must be \fB0\fR in an \fBI_ANCHOR\fR
169 -request. On failure, \fBerrno\fR is set to the following value:
170 -.sp
171 -.ne 2
172 -.na
173 -\fB\fBEINVAL\fR\fR
174 -.ad
175 -.RS 10n
145 +stream head.
146 +Once this has been done, only a privileged process may pop modules
147 +below the anchor on the stream.
148 +.Va arg
149 +must be
150 +.Sy 0
151 +in an
152 +.Dv I_ANCHOR
153 +request.
154 +On failure,
155 +.Va errno
156 +is set to the following value:
157 +.Bl -tag -width EINVAL
158 +.It Er EINVAL
176 159 Request to put an anchor on a pipe.
177 -.RE
178 -
179 -.RE
180 -
181 -.sp
182 -.ne 2
183 -.na
184 -\fB\fBI_LOOK\fR\fR
185 -.ad
186 -.RS 15n
160 +.El
161 +.It Dv I_LOOK
187 162 Retrieves the name of the module just below the stream head of the stream
188 -pointed to by \fIfildes\fR, and places it in a null terminated character string
189 -pointed at by \fIarg\fR. The buffer pointed to by \fIarg\fR should be at least
190 -\fBFMNAMESZ\fR+1 bytes long. This requires the declaration \fB#include
191 -<sys/conf.h>\fR. On failure, \fBerrno\fR is set to one of the following values:
192 -.sp
193 -.ne 2
194 -.na
195 -\fB\fBEFAULT\fR\fR
196 -.ad
197 -.RS 10n
198 -\fIarg\fR points outside the allocated address space.
199 -.RE
200 -
201 -.sp
202 -.ne 2
203 -.na
204 -\fB\fBEINVAL\fR\fR
205 -.ad
206 -.RS 10n
163 +pointed to by
164 +.Fa fildes ,
165 +and places it in a null terminated character string
166 +pointed at by
167 +.Fa arg .
168 +The buffer pointed to by
169 +.Fa arg
170 +should be at least
171 +.Dv FMNAMESZ Ns +1
172 +bytes long.
173 +This requires the declaration
174 +.Ql "#include <sys/conf.h>" .
175 +On failure,
176 +.Dv errno
177 +is set to one of the following values:
178 +.Bl -tag -width EFAULT
179 +.It Er EFAULT
180 +.Fa arg
181 +points outside the allocated address space.
182 +.It Er EINVAL
207 183 No module present in stream.
208 -.RE
209 -
210 -.RE
211 -
212 -.sp
213 -.ne 2
214 -.na
215 -\fB\fBI_FLUSH\fR\fR
216 -.ad
217 -.RS 15n
184 +.El
185 +.It Dv I_FLUSH
218 186 This request flushes all input and/or output queues, depending on the value of
219 -\fIarg\fR. Legal \fIarg\fR values are:
220 -.sp
221 -.ne 2
222 -.na
223 -\fBFLUSHR\fR
224 -.ad
225 -.RS 11n
187 +.Fa arg .
188 +Legal
189 +.Fa arg
190 +values are:
191 +.Bl -tag -width FLUSHRW
192 +.It Dv FLUSHR
226 193 Flush read queues.
227 -.RE
228 -
229 -.sp
230 -.ne 2
231 -.na
232 -\fBFLUSHW\fR
233 -.ad
234 -.RS 11n
194 +.It Dv FLUSHW
235 195 Flush write queues.
236 -.RE
237 -
238 -.sp
239 -.ne 2
240 -.na
241 -\fBFLUSHRW\fR
242 -.ad
243 -.RS 11n
196 +.It Dv FLUSHRW
244 197 Flush read and write queues.
245 -.RE
246 -
198 +.El
199 +.Pp
247 200 If a pipe or FIFO does not have any modules pushed, the read queue of the
248 -stream head on either end is flushed depending on the value of \fIarg\fR.
249 -.sp
250 -If \fBFLUSHR\fR is set and \fIfildes\fR is a pipe, the read queue for that end
251 -of the pipe is flushed and the write queue for the other end is flushed. If
252 -\fIfildes\fR is a FIFO, both queues are flushed.
253 -.sp
254 -If \fBFLUSHW\fR is set and \fIfildes\fR is a pipe and the other end of the pipe
201 +stream head on either end is flushed depending on the value of
202 +.Fa arg .
203 +.Pp
204 +If
205 +.Dv FLUSHR
206 +is set and
207 +.Fa fildes
208 +is a pipe, the read queue for that end
209 +of the pipe is flushed and the write queue for the other end is flushed.
210 +If
211 +.Fa fildes
212 +is a FIFO, both queues are flushed.
213 +.Pp
214 +If
215 +.Dv FLUSHW
216 +is set and
217 +.Fa fildes
218 +is a pipe and the other end of the pipe
255 219 exists, the read queue for the other end of the pipe is flushed and the write
256 -queue for this end is flushed. If \fIfildes\fR is a FIFO, both queues of the
220 +queue for this end is flushed.
221 +If
222 +.Fa fildes
223 +is a FIFO, both queues of the
257 224 FIFO are flushed.
258 -.sp
259 -If \fBFLUSHRW\fR is set, all read queues are flushed, that is, the read queue
225 +.Pp
226 +If
227 +.Dv FLUSHRW
228 +is set, all read queues are flushed, that is, the read queue
260 229 for the FIFO and the read queue on both ends of the pipe are flushed.
261 -.sp
230 +.Pp
262 231 Correct flush handling of a pipe or FIFO with modules pushed is achieved via
263 -the \fBpipemod\fR module. This module should be the first module pushed onto a
232 +the
233 +.Sy pipemod
234 +module.
235 +This module should be the first module pushed onto a
264 236 pipe so that it is at the midpoint of the pipe itself.
265 -.sp
266 -On failure, \fBerrno\fR is set to one of the following values:
267 -.sp
268 -.ne 2
269 -.na
270 -\fB\fBENOSR\fR\fR
271 -.ad
272 -.RS 10n
237 +.Pp
238 +On failure,
239 +.Va errno
240 +is set to one of the following values:
241 +.Bl -tag -width EINVAL
242 +.It Er ENOSR
273 243 Unable to allocate buffers for flush message due to insufficient stream memory
274 244 resources.
275 -.RE
276 -
277 -.sp
278 -.ne 2
279 -.na
280 -\fB\fBEINVAL\fR\fR
281 -.ad
282 -.RS 10n
283 -Invalid \fIarg\fR value.
284 -.RE
285 -
286 -.sp
287 -.ne 2
288 -.na
289 -\fB\fBENXIO\fR\fR
290 -.ad
291 -.RS 10n
292 -Hangup received on \fIfildes\fR.
293 -.RE
294 -
295 -.RE
296 -
297 -.sp
298 -.ne 2
299 -.na
300 -\fB\fBI_FLUSHBAND\fR\fR
301 -.ad
302 -.RS 15n
303 -Flushes a particular band of messages. \fIarg\fR points to a \fBbandinfo\fR
245 +.It Er EINVAL
246 +Invalid
247 +.Va arg
248 +value.
249 +.It Er ENXIO
250 +Hangup received on
251 +.Fa fildes .
252 +.El
253 +.It Dv I_FLUSHBAND
254 +Flushes a particular band of messages.
255 +.Fa arg
256 +points to a
257 +.Vt bandinfo
304 258 structure that has the following members:
305 -.sp
306 -.in +2
307 -.nf
259 +.Bd -literal -offset 2n
308 260 unsigned char bi_pri;
309 261 int bi_flag;
310 -.fi
311 -.in -2
312 -
313 -The \fBbi_flag\fR field may be one of \fBFLUSHR\fR, \fBFLUSHW\fR, or
314 -\fBFLUSHRW\fR as described earlier.
315 -.RE
316 -
317 -.sp
318 -.ne 2
319 -.na
320 -\fB\fBI_SETSIG\fR\fR
321 -.ad
322 -.RS 15n
262 +.Ed
263 +.Pp
264 +The
265 +.Fa bi_flag
266 +field may be one of
267 +.Dv FLUSHR ,
268 +.Dv FLUSHW ,
269 +or
270 +.Dv FLUSHRW
271 +as described earlier.
272 +.It Dv I_SETSIG
323 273 Informs the stream head that the user wishes the kernel to issue the
324 -\fBSIGPOLL\fR signal (see \fBsignal\fR(3C)) when a particular event has
325 -occurred on the stream associated with \fIfildes\fR. \fBI_SETSIG\fR supports an
326 -asynchronous processing capability in streams. The value of \fIarg\fR is a
327 -bitmask that specifies the events for which the user should be signaled. It is
328 -the bitwise OR of any combination of the following constants:
329 -.sp
330 -.ne 2
331 -.na
332 -\fB\fBS_INPUT\fR\fR
333 -.ad
334 -.RS 13n
335 -Any message other than an \fBM_PCPROTO\fR has arrived on a stream head read
336 -queue. This event is maintained for compatibility with previous releases. This
337 -event is triggered even if the message is of zero length.
338 -.RE
339 -
340 -.sp
341 -.ne 2
342 -.na
343 -\fB\fBS_RDNORM\fR\fR
344 -.ad
345 -.RS 13n
274 +.Dv SIGPOLL
275 +signal (see
276 +.Xr signal 3C )
277 +when a particular event has occurred on the stream associated with
278 +.Fa fildes .
279 +.Dv I_SETSIG
280 +supports an asynchronous processing capability in streams.
281 +The value of
282 +.Fa arg
283 +is a bitmask that specifies the events for which the user should be signaled.
284 +It is the bitwise OR of any combination of the following constants:
285 +.Bl -tag -width S_BANDURG
286 +.It Dv S_INPUT
287 +Any message other than an
288 +.Dv M_PCPROTO
289 +has arrived on a stream head read queue.
290 +This event is maintained for compatibility with previous releases.
291 +This event is triggered even if the message is of zero length.
292 +.It Dv S_RDNORM
346 293 An ordinary (non-priority) message has arrived on a stream head read queue.
347 294 This event is triggered even if the message is of zero length.
348 -.RE
349 -
350 -.sp
351 -.ne 2
352 -.na
353 -\fB\fBS_RDBAND\fR\fR
354 -.ad
355 -.RS 13n
295 +.It Dv S_RDBAND
356 296 A priority band message (band > 0) has arrived on a stream head read queue.
357 297 This event is triggered even if the message is of zero length.
358 -.RE
359 -
360 -.sp
361 -.ne 2
362 -.na
363 -\fB\fBS_HIPRI\fR\fR
364 -.ad
365 -.RS 13n
366 -A high priority message is present on the stream head read queue. This event is
367 -triggered even if the message is of zero length.
368 -.RE
369 -
370 -.sp
371 -.ne 2
372 -.na
373 -\fB\fBS_OUTPUT\fR\fR
374 -.ad
375 -.RS 13n
376 -The write queue just below the stream head is no longer full. This notifies the
298 +.It Dv S_HIPRI
299 +A high priority message is present on the stream head read queue.
300 +This event is triggered even if the message is of zero length.
301 +.It Dv S_OUTPUT
302 +The write queue just below the stream head is no longer full.
303 +This notifies the
377 304 user that there is room on the queue for sending (or writing) data downstream.
378 -.RE
379 -
380 -.sp
381 -.ne 2
382 -.na
383 -\fB\fBS_WRNORM\fR\fR
384 -.ad
385 -.RS 13n
386 -This event is the same as \fBS_OUTPUT\fR.
387 -.RE
388 -
389 -.sp
390 -.ne 2
391 -.na
392 -\fB\fBS_WRBAND\fR\fR
393 -.ad
394 -.RS 13n
305 +.It Dv S_WRNORM
306 +This event is the same as
307 +.Dv S_OUTPUT .
308 +.It Dv S_WRBAND
395 309 A priority band greater than 0 of a queue downstream exists and is writable.
396 310 This notifies the user that there is room on the queue for sending (or writing)
397 311 priority data downstream.
398 -.RE
399 -
400 -.sp
401 -.ne 2
402 -.na
403 -\fB\fBS_MSG\fR\fR
404 -.ad
405 -.RS 13n
406 -A STREAMS signal message that contains the \fBSIGPOLL\fR signal has reached the
312 +.It Dv S_MSG
313 +A STREAMS signal message that contains the
314 +.Dv SIGPOLL
315 +signal has reached the
407 316 front of the stream head read queue.
408 -.RE
409 -
410 -.sp
411 -.ne 2
412 -.na
413 -\fB\fBS_ERROR\fR\fR
414 -.ad
415 -.RS 13n
416 -An \fBM_ERROR\fR message has reached the stream head.
417 -.RE
418 -
419 -.sp
420 -.ne 2
421 -.na
422 -\fB\fBS_HANGUP\fR\fR
423 -.ad
424 -.RS 13n
425 -An \fBM_HANGUP\fR message has reached the stream head.
426 -.RE
427 -
428 -.sp
429 -.ne 2
430 -.na
431 -\fB\fBS_BANDURG\fR\fR
432 -.ad
433 -.RS 13n
434 -When used in conjunction with \fBS_RDBAND\fR, \fBSIGURG\fR is generated instead
435 -of \fBSIGPOLL\fR when a priority message reaches the front of the stream head
317 +.It Dv S_ERROR
318 +An
319 +.Dv M_ERROR
320 +message has reached the stream head.
321 +.It Dv S_HANGUP
322 +An
323 +.Dv M_HANGUP
324 +message has reached the stream head.
325 +.It Dv S_BANDURG
326 +When used in conjunction with
327 +.Dv S_RDBAND ,
328 +.Dv SIGURG
329 +is generated instead of
330 +.Dv SIGPOLL
331 +when a priority message reaches the front of the stream head
436 332 read queue.
437 -.RE
438 -
333 +.El
334 +.Pp
439 335 A user process may choose to be signaled only of high priority messages by
440 -setting the \fIarg\fR bitmask to the value \fBS_HIPRI\fR.
441 -.sp
442 -Processes that wish to receive \fBSIGPOLL\fR signals must explicitly register
443 -to receive them using \fBI_SETSIG\fR. If several processes register to receive
336 +setting the
337 +.Fa arg
338 +bitmask to the value
339 +.Dv S_HIPRI .
340 +.Pp
341 +Processes that wish to receive
342 +.Dv SIGPOLL
343 +signals must explicitly register
344 +to receive them using
345 +.Dv I_SETSIG .
346 +If several processes register to receive
444 347 this signal for the same event on the same stream, each process will be
445 348 signaled when the event occurs.
446 -.sp
447 -If the value of \fIarg\fR is zero, the calling process will be unregistered and
448 -will not receive further \fBSIGPOLL\fR signals. On failure, \fBerrno\fR is set
449 -to one of the following values:
450 -.sp
451 -.ne 2
452 -.na
453 -\fB\fBEINVAL\fR\fR
454 -.ad
455 -.RS 10n
456 -\fIarg\fR value is invalid or \fIarg\fR is zero and process is not registered
457 -to receive the \fBSIGPOLL\fR signal.
458 -.RE
459 -
460 -.sp
461 -.ne 2
462 -.na
463 -\fB\fBEAGAIN\fR\fR
464 -.ad
465 -.RS 10n
349 +.Pp
350 +If the value of
351 +.Fa arg
352 +is zero, the calling process will be unregistered and
353 +will not receive further
354 +.Dv SIGPOLL
355 +signals.
356 +On failure,
357 +.Va errno
358 +is set to one of the following values:
359 +.Bl -tag -width EINVAL
360 +.It Sy EINVAL
361 +.Fa arg
362 +value is invalid or
363 +.Fa arg
364 +is zero and process is not registered to receive the
365 +.Dv SIGPOLL
366 +signal.
367 +.It Sy EAGAIN
466 368 Allocation of a data structure to store the signal request failed.
467 -.RE
468 -
469 -.RE
470 -
471 -.sp
472 -.ne 2
473 -.na
474 -\fB\fBI_GETSIG\fR\fR
475 -.ad
476 -.RS 15n
369 +.El
370 +.It Dv I_GETSIG
477 371 Returns the events for which the calling process is currently registered to be
478 -sent a \fBSIGPOLL\fR signal. The events are returned as a bitmask pointed to
479 -by \fIarg\fR, where the events are those specified in the description of
480 -\fBI_SETSIG\fR above. On failure, \fBerrno\fR is set to one of the following
481 -values:
482 -.sp
483 -.ne 2
484 -.na
485 -\fB\fBEINVAL\fR\fR
486 -.ad
487 -.RS 10n
488 -Process not registered to receive the \fBSIGPOLL\fR signal.
489 -.RE
490 -
491 -.sp
492 -.ne 2
493 -.na
494 -\fB\fBEFAULT\fR\fR
495 -.ad
496 -.RS 10n
497 -\fIarg\fR points outside the allocated address space.
498 -.RE
499 -
500 -.RE
501 -
502 -.sp
503 -.ne 2
504 -.na
505 -\fB\fBI_FIND\fR\fR
506 -.ad
507 -.RS 15n
372 +sent a
373 +.Dv SIGPOLL
374 +signal.
375 +The events are returned as a bitmask pointed to by
376 +.Va arg ,
377 +where the events are those specified in the description of
378 +.Dv I_SETSIG
379 +above.
380 +On failure,
381 +.Va errno
382 +is set to one of the following values:
383 +.Bl -tag -width EINVAL
384 +.It Sy EINVAL
385 +Process not registered to receive the
386 +.Dv SIGPOLL
387 +signal.
388 +.It Sy EFAULT
389 +.Fa arg
390 +points outside the allocated address space.
391 +.El
392 +.It Dv I_FIND
508 393 Compares the names of all modules currently present in the stream to the name
509 -pointed to by \fIarg\fR, and returns 1 if the named module is present in the
510 -stream. It returns 0 if the named module is not present. On failure,
511 -\fBerrno\fR is set to one of the following values:
512 -.sp
513 -.ne 2
514 -.na
515 -\fB\fBEFAULT\fR\fR
516 -.ad
517 -.RS 10n
518 -\fIarg\fR points outside the allocated address space.
519 -.RE
520 -
521 -.sp
522 -.ne 2
523 -.na
524 -\fB\fBEINVAL\fR\fR
525 -.ad
526 -.RS 10n
527 -\fIarg\fR does not contain a valid module name.
528 -.RE
529 -
530 -.RE
531 -
532 -.sp
533 -.ne 2
534 -.na
535 -\fB\fBI_PEEK\fR\fR
536 -.ad
537 -.RS 15n
394 +pointed to by
395 +.Fa arg ,
396 +and returns 1 if the named module is present in the stream.
397 +It returns 0 if the named module is not present.
398 +On failure,
399 +.Va errno
400 +is set to one of the following values:
401 +.Bl -tag -width EINVAL
402 +.It Sy EFAULT
403 +.Fa arg
404 +points outside the allocated address space.
405 +.It Sy EINVAL
406 +.Fa arg
407 +does not contain a valid module name.
408 +.El
409 +.It Dv I_PEEK
538 410 Allows a user to retrieve the information in the first message on the stream
539 -head read queue without taking the message off the queue. \fBI_PEEK\fR is
540 -analogous to \fBgetmsg\fR(2) except that it does not remove the message from
541 -the queue. \fIarg\fR points to a \fBstrpeek\fR structure, which contains the
542 -following members:
543 -.sp
544 -.in +2
545 -.nf
411 +head read queue without taking the message off the queue.
412 +.Dv I_PEEK
413 +is analogous to
414 +.Xr getmsg 2
415 +except that it does not remove the message from the queue.
416 +.Fa arg
417 +points to a
418 +.Vt strpeek
419 +structure, which contains the following members:
420 +.Bd -literal -offset 2n
546 421 struct strbuf ctlbuf;
547 -struct strbuf databuf;
422 +struct strbuf databuf;
548 423 long flags;
549 -.fi
550 -.in -2
551 -
552 -The \fBmaxlen\fR field in the \fBctlbuf\fR and \fBdatabuf\fR \fBstrbuf\fR
553 -structures (see \fBgetmsg\fR(2)) must be set to the number of bytes of control
554 -information and/or data information, respectively, to retrieve. \fBflags\fR may
555 -be set to \fBRS_HIPRI\fR or \fB0\fR. If \fBRS_HIPRI\fR is set, \fBI_PEEK\fR
556 -will look for a high priority message on the stream head read queue. Otherwise,
557 -\fBI_PEEK\fR will look for the first message on the stream head read queue.
558 -.sp
559 -\fBI_PEEK\fR returns \fB1\fR if a message was retrieved, and returns \fB0\fR if
560 -no message was found on the stream head read queue. It does not wait for a
561 -message to arrive. On return, \fBctlbuf\fR specifies information in the control
562 -buffer, \fBdatabuf\fR specifies information in the data buffer, and \fBflags\fR
563 -contains the value \fBRS_HIPRI\fR or \fB0\fR. On failure, \fBerrno\fR is set to
564 -the following value:
565 -.sp
566 -.ne 2
567 -.na
568 -\fB\fBEFAULT\fR\fR
569 -.ad
570 -.RS 11n
571 -\fIarg\fR points, or the buffer area specified in \fBctlbuf\fR or \fBdatabuf\fR
424 +.Ed
425 +.Pp
426 +The
427 +.Ft maxlen
428 +field in the
429 +.Vt ctlbuf
430 +and
431 +.Vt databuf
432 +.Vt strbuf
433 +structures (see
434 +.Xr getmsg 2 )
435 +must be set to the number of bytes of control
436 +information and/or data information, respectively, to retrieve.
437 +.Fa flags
438 +may be set to
439 +.Dv RS_HIPRI
440 +or
441 +.Sy 0 .
442 +If
443 +.Dv RS_HIPRI
444 +is set,
445 +.Dv I_PEEK
446 +will look for a high priority message on the stream head read queue.
447 +Otherwise,
448 +.Dv I_PEEK
449 +will look for the first message on the stream head read queue.
450 +.Pp
451 +.Dv I_PEEK
452 +returns
453 +.Sy 1
454 +if a message was retrieved, and returns
455 +.Sy 0
456 +if no message was found on the stream head read queue.
457 +It does not wait for a message to arrive.
458 +On return,
459 +.Vt ctlbuf
460 +specifies information in the control buffer,
461 +.Vt databuf
462 +specifies information in the data buffer, and
463 +.Fa flags
464 +contains the value
465 +.Dv RS_HIPRI
466 +or
467 +.Sy 0 .
468 +On failure,
469 +.Va errno
470 +is set to the following value:
471 +.Bl -tag -width EBADMSG
472 +.It Er EFAULT
473 +.Fa arg
474 +points, or the buffer area specified in
475 +.Vt ctlbuf
476 +or
477 +.Vt databuf
572 478 is, outside the allocated address space.
573 -.RE
574 -
575 -.sp
576 -.ne 2
577 -.na
578 -\fB\fBEBADMSG\fR\fR
579 -.ad
580 -.RS 11n
581 -Queued message to be read is not valid for \fBI_PEEK\fR.
582 -.RE
583 -
584 -.sp
585 -.ne 2
586 -.na
587 -\fB\fBEINVAL\fR\fR
588 -.ad
589 -.RS 11n
590 -Illegal value for \fBflags\fR.
591 -.RE
592 -
593 -.sp
594 -.ne 2
595 -.na
596 -\fB\fBENOSR\fR\fR
597 -.ad
598 -.RS 11n
599 -Unable to allocate buffers to perform the I_PEEK due to insufficient STREAMS
600 -memory resources.
601 -.RE
602 -
603 -.RE
604 -
605 -.sp
606 -.ne 2
607 -.na
608 -\fB\fBI_SRDOPT\fR\fR
609 -.ad
610 -.RS 15n
611 -Sets the read mode (see \fBread\fR(2)) using the value of the argument
612 -\fIarg\fR. Legal \fIarg\fR values are:
613 -.sp
614 -.ne 2
615 -.na
616 -\fBRNORM\fR
617 -.ad
618 -.RS 9n
479 +.It Er EBADMSG
480 +Queued message to be read is not valid for
481 +.Dv I_PEEK .
482 +.It Er EINVAL
483 +Illegal value for
484 +.Vt flags .
485 +.It Er ENOSR
486 +Unable to allocate buffers to perform the
487 +.Dv I_PEEK
488 +due to insufficient STREAMS memory resources.
489 +.El
490 +.It Dv I_SRDOPT
491 +Sets the read mode (see
492 +.Xr read 2 )
493 +using the value of the argument
494 +.Va arg .
495 +Legal
496 +.Va arg
497 +values are:
498 +.Bl -tag -width RNORM
499 +.It Dv RNORM
619 500 Byte-stream mode, the default.
620 -.RE
621 -
622 -.sp
623 -.ne 2
624 -.na
625 -\fBRMSGD\fR
626 -.ad
627 -.RS 9n
501 +.It Dv RMSGD
628 502 Message-discard mode.
629 -.RE
630 -
631 -.sp
632 -.ne 2
633 -.na
634 -\fBRMSGN\fR
635 -.ad
636 -.RS 9n
503 +.It Dv RMSGN
637 504 Message-nondiscard mode.
638 -.RE
639 -
505 +.El
506 +.Pp
640 507 In addition, the stream head's treatment of control messages may be changed by
641 -setting the following flags in \fIarg\fR:
642 -.sp
643 -.ne 2
644 -.na
645 -\fBRPROTNORM\fR
646 -.ad
647 -.RS 13n
648 -Reject \fBread()\fR with \fBEBADMSG\fR if a control message is at the front of
649 -the stream head read queue.
650 -.RE
651 -
652 -.sp
653 -.ne 2
654 -.na
655 -\fBRPROTDAT\fR
656 -.ad
657 -.RS 13n
508 +setting the following flags in
509 +.Va arg :
510 +.Bl -tag -width RPROTNORM
511 +.It Dv RPROTNORM
512 +Reject
513 +.Xr read 2
514 +with
515 +.Er EBADMSG
516 +if a control message is at the front of the stream head read queue.
517 +.It Dv RPROTDAT
658 518 Deliver the control portion of a message as data when a user issues
659 -\fBread()\fR. This is the default behavior.
660 -.RE
661 -
662 -.sp
663 -.ne 2
664 -.na
665 -\fBRPROTDIS\fR
666 -.ad
667 -.RS 13n
519 +.Xr read 2 .
520 +This is the default behavior.
521 +.It Dv RPROTDIS
668 522 Discard the control portion of a message, delivering any data portion, when a
669 -user issues a \fBread\fR(\|).
670 -.RE
671 -
672 -On failure, \fBerrno\fR is set to the following value:
673 -.sp
674 -.ne 2
675 -.na
676 -\fB\fBEINVAL\fR\fR
677 -.ad
678 -.RS 10n
679 -\fIarg\fR is not one of the above legal values, or \fIarg\fR is the bitwise
680 -inclusive \fBOR\fR of \fBRMSGD\fR and \fBRMSGN\fR.
681 -.RE
682 -
683 -.RE
684 -
685 -.sp
686 -.ne 2
687 -.na
688 -\fB\fBI_GRDOPT\fR\fR
689 -.ad
690 -.RS 15n
691 -Returns the current read mode setting in an \fBint\fR pointed to by the
692 -argument \fIarg\fR. Read modes are described in \fBread\fR(\|). On failure,
693 -\fBerrno\fR is set to the following value:
694 -.sp
695 -.ne 2
696 -.na
697 -\fB\fBEFAULT\fR\fR
698 -.ad
699 -.RS 10n
700 -\fIarg\fR points outside the allocated address space.
701 -.RE
702 -
703 -.RE
704 -
705 -.sp
706 -.ne 2
707 -.na
708 -\fB\fBI_NREAD\fR\fR
709 -.ad
710 -.RS 15n
523 +user issues a
524 +.Xr read 2 .
525 +.El
526 +.Pp
527 +On failure,
528 +.Va errno
529 +is set to the following value:
530 +.Bl -tag -width EINVAL
531 +.It Er EINVAL
532 +.Va arg
533 +is not one of the above legal values, or
534 +.Va arg
535 +is the bitwise
536 +inclusive
537 +.Sy OR
538 +of
539 +.Dv RMSGD
540 +and
541 +.Dv RMSGN .
542 +.El
543 +.It Dv I_GRDOPT
544 +Returns the current read mode setting in an
545 +.Vt int
546 +pointed to by the argument
547 +.Fa arg .
548 +Read modes are described in
549 +.Xr read 2 .
550 +On failure,
551 +.Va errno
552 +is set to the following value:
553 +.Bl -tag -width EFAULT
554 +.It Er EFAULT
555 +.Fa arg
556 +points outside the allocated address space.
557 +.El
558 +.It Dv I_NREAD
711 559 Counts the number of data bytes in data blocks in the first message on the
712 560 stream head read queue, and places this value in the location pointed to by
713 -\fIarg\fR. The return value for the command is the number of messages on the
714 -stream head read queue. For example, if zero is returned in \fIarg\fR, but the
715 -\fBioctl\fR return value is greater than zero, this indicates that a
716 -zero-length message is next on the queue. On failure, \fBerrno\fR is set to the
717 -following value:
718 -.sp
719 -.ne 2
720 -.na
721 -\fB\fBEFAULT\fR\fR
722 -.ad
723 -.RS 10n
724 -\fIarg\fR points outside the allocated address space.
725 -.RE
726 -
727 -.RE
728 -
729 -.sp
730 -.ne 2
731 -.na
732 -\fB\fBI_FDINSERT\fR\fR
733 -.ad
734 -.RS 15n
561 +.Fa arg .
562 +The return value for the command is the number of messages on the
563 +stream head read queue.
564 +For example, if zero is returned in
565 +.Fa arg ,
566 +but the
567 +.Fn ioctl
568 +return value is greater than zero, this indicates that a
569 +zero-length message is next on the queue.
570 +On failure,
571 +.Va errno
572 +is set to the following value:
573 +.Bl -tag -width EFAULT
574 +.It Er EFAULT
575 +.Fa arg
576 +points outside the allocated address space.
577 +.El
578 +.It Dv I_FDINSERT
735 579 Creates a message from specified buffer(s), adds information about another
736 -stream and sends the message downstream. The message contains a control part
737 -and an optional data part. The data and control parts to be sent are
580 +stream and sends the message downstream.
581 +The message contains a control part and an optional data part.
582 +The data and control parts to be sent are
738 583 distinguished by placement in separate buffers, as described below.
739 -.sp
740 -The \fIarg\fR argument points to a \fBstrfdinsert\fR structure, which contains
584 +.Pp
585 +The
586 +.Fa arg
587 +argument points to a
588 +.Vt strfdinsert
589 +structure, which contains
741 590 the following members:
742 -.sp
743 -.in +2
744 -.nf
591 +.Bd -literal -offset 2n
745 592 struct strbuf ctlbuf;
746 593 struct strbuf databuf;
747 -t_uscalar_t flags;
748 -int fildes;
749 -int offset;
750 -.fi
751 -.in -2
752 -
753 -The \fBlen\fR member in the \fBctlbuf strbuf\fR structure (see \fBputmsg\fR(2))
754 -must be set to the size of a \fBt_uscalar_t\fR plus the number of bytes of
755 -control information to be sent with the message. The \fBfildes\fR member
756 -specifies the file descriptor of the other stream, and the \fBoffset\fR member,
757 -which must be suitably aligned for use as a \fBt_uscalar_t\fR, specifies the
758 -offset from the start of the control buffer where \fBI_FDINSERT\fR will store a
759 -\fBt_uscalar_t\fR whose interpretation is specific to the stream end. The
760 -\fBlen\fR member in the \fBdatabuf strbuf\fR structure must be set to the
761 -number of bytes of data information to be sent with the message, or to 0 if no
762 -data part is to be sent.
763 -.sp
764 -The \fBflags\fR member specifies the type of message to be created. A normal
765 -message is created if \fBflags\fR is set to 0, and a high-priority message is
766 -created if \fBflags\fR is set to \fBRS_HIPRI\fR. For non-priority messages,
767 -\fBI_FDINSERT\fR will block if the stream write queue is full due to internal
768 -flow control conditions. For priority messages, \fBI_FDINSERT\fR does not
769 -block on this condition. For non-priority messages, \fBI_FDINSERT\fR does not
770 -block when the write queue is full and \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is
771 -set. Instead, it fails and sets \fBerrno\fR to \fBEAGAIN\fR.
772 -.sp
773 -\fBI_FDINSERT\fR also blocks, unless prevented by lack of internal resources,
774 -waiting for the availability of message blocks in the stream, regardless of
775 -priority or whether \fBO_NDELAY\fR or \fBO_NONBLOCK\fR has been specified. No
776 -partial message is sent.
777 -.sp
778 -The \fBioctl()\fR function with the \fBI_FDINSERT\fR command will fail if:
779 -.sp
780 -.ne 2
781 -.na
782 -\fB\fBEAGAIN\fR\fR
783 -.ad
784 -.RS 10n
785 -A non-priority message is specified, the \fBO_NDELAY\fR or \fBO_NONBLOCK\fR
594 +t_uscalar_t flags;
595 +int fildes;
596 +int offset;
597 +.Ed
598 +.Pp
599 +The
600 +.Fa len
601 +member in the
602 +.Vt ctlbuf
603 +.Vt strbuf
604 +structure (see
605 +.Xr putmsg 2 )
606 +must be set to the size of a
607 +.Vt t_uscalar_t
608 +plus the number of bytes of
609 +control information to be sent with the message.
610 +The
611 +.Fa fildes
612 +member specifies the file descriptor of the other stream, and the
613 +.Fa offset
614 +member, which must be suitably aligned for use as a
615 +.Vt t_uscalar_t ,
616 +specifies the offset from the start of the control buffer where
617 +.Dv I_FDINSERT
618 +will store a
619 +.Vt t_uscalar_t
620 +whose interpretation is specific to the stream end.
621 +The
622 +.Fa len
623 +member in the
624 +.Vt databuf
625 +.Vt strbuf
626 +structure must be set to the number of bytes of data information to be sent with
627 +the message, or to 0 if no data part is to be sent.
628 +.Pp
629 +The
630 +.Fa flags
631 +member specifies the type of message to be created.
632 +A normal message is created if
633 +.Fa flags
634 +is set to 0, and a high-priority message is created if
635 +.Fa flags
636 +is set to
637 +.Dv RS_HIPRI .
638 +For non-priority messages,
639 +.Dv I_FDINSERT
640 +will block if the stream write queue is full due to internal
641 +flow control conditions.
642 +For priority messages,
643 +.Dv I_FDINSERT
644 +does not block on this condition.
645 +or non-priority messages,
646 +.Dv I_FDINSERT
647 +does not
648 +block when the write queue is full and
649 +.Dv O_NDELAY
650 +or
651 +.Dv O_NONBLOCK
652 +is set.
653 +Instead, it fails and sets
654 +.Va errno
655 +to
656 +.Er EAGAIN .
657 +.Pp
658 +.Dv I_FDINSERT
659 +also blocks, unless prevented by lack of internal resources, waiting for the
660 +availability of message blocks in the stream, regardless of priority or whether
661 +.Dv O_NDELAY
662 +or
663 +.Dv O_NONBLOCK
664 +has been specified.
665 +No partial message is sent.
666 +.Pp
667 +The
668 +.Fn ioctl
669 +function with the
670 +.Dv I_FDINSERT
671 +command will fail if:
672 +.Bl -tag -width EAGAIN
673 +.It Er EAGAIN
674 +A non-priority message is specified, the
675 +.Dv O_NDELAY
676 +or
677 +.Dv O_NONBLOCK
786 678 flag is set, and the stream write queue is full due to internal flow control
787 679 conditions.
788 -.RE
789 -
790 -.sp
791 -.ne 2
792 -.na
793 -\fB\fBENOSR\fR\fR
794 -.ad
795 -.RS 10n
680 +.It Er ENOSR
796 681 Buffers can not be allocated for the message that is to be created.
797 -.RE
798 -
799 -.sp
800 -.ne 2
801 -.na
802 -\fB\fBEFAULT\fR\fR
803 -.ad
804 -.RS 10n
805 -The \fIarg\fR argument points, or the buffer area specified in \fBctlbuf\fR or
806 -\fBdatabuf\fR is, outside the allocated address space.
807 -.RE
808 -
809 -.sp
810 -.ne 2
811 -.na
812 -\fB\fBEINVAL\fR\fR
813 -.ad
814 -.RS 10n
815 -One of the following: The \fBfildes\fR member of the \fBstrfdinsert\fR
682 +.It Er EFAULT
683 +The
684 +.Fa arg
685 +argument points, or the buffer area specified in
686 +.Vt ctlbuf
687 +or
688 +.Vt databuf
689 +is, outside the allocated address space.
690 +.It Er EINVAL
691 +One of the following: The
692 +.Fa fildes
693 +member of the
694 +.Vt strfdinsert
816 695 structure is not a valid, open stream file descriptor; the size of a
817 -\fBt_uscalar_t\fR plus \fBoffset\fR is greater than the \fBlen\fR member for
818 -the buffer specified through \fBctlptr\fR; the \fBoffset\fR member does not
819 -specify a properly-aligned location in the data buffer; or an undefined value
820 -is stored in \fBflags\fR.
821 -.RE
822 -
823 -.sp
824 -.ne 2
825 -.na
826 -\fB\fBENXIO\fR\fR
827 -.ad
828 -.RS 10n
829 -Hangup received on the \fBfildes\fR argument of the \fBioctl\fR call or the
830 -\fBfildes\fR member of the \fBstrfdinsert\fR structure.
831 -.RE
832 -
833 -.sp
834 -.ne 2
835 -.na
836 -\fB\fBERANGE\fR\fR
837 -.ad
838 -.RS 10n
839 -The \fBlen\fR field for the buffer specified through \fBdatabuf\fR does not
840 -fall within the range specified by the maximum and minimum packet sizes of the
841 -topmost stream module; or the \fBlen\fR member for the buffer specified through
842 -\fBdatabuf\fR is larger than the maximum configured size of the data part of a
843 -message; or the \fBlen\fR member for the buffer specified through \fBctlbuf\fR
696 +.Vt t_uscalar_t
697 +plus
698 +.Fa offset
699 +is greater than the
700 +.Fa len
701 +member for the buffer specified through
702 +.Fa ctlptr ;
703 +the
704 +.Fa offset
705 +member does not specify a properly-aligned location in the data buffer; or an
706 +undefined value is stored in
707 +.Fa flags .
708 +.It Er ENXIO
709 +Hangup received on the
710 +.Fa fildes
711 +argument of the
712 +.Fn ioctl
713 +call or the
714 +.Fa fildes
715 +member of the
716 +.Vt strfdinsert
717 +structure.
718 +.It Er ERANGE
719 +The
720 +.Fa len
721 +field for the buffer specified through
722 +.Vt databuf
723 +does not fall within the range specified by the maximum and minimum packet
724 +sizes of the topmost stream module; or the
725 +.Fa len
726 +member for the buffer specified through
727 +.Vt databuf
728 +is larger than the maximum configured size of the data part of a message; or the
729 +.Fa len
730 +member for the buffer specified through
731 +.Vt ctlbuf
844 732 is larger than the maximum configured size of the control part of a message.
845 -.RE
846 -
847 -\fBI_FDINSERT\fR can also fail if an error message was received by the stream
848 -head of the stream corresponding to the \fBfildes\fR member of the
849 -\fBstrfdinsert\fR structure. In this case, \fBerrno\fR will be set to the value
850 -in the message.
851 -.RE
852 -
853 -.sp
854 -.ne 2
855 -.na
856 -\fB\fBI_STR\fR\fR
857 -.ad
858 -.RS 15n
859 -Constructs an internal \fBSTREAMS\fR ioctl message from the data pointed to by
860 -\fIarg\fR, and sends that message downstream.
861 -.sp
862 -This mechanism is provided to send user \fBioctl\fR requests to downstream
863 -modules and drivers. It allows information to be sent with the \fBioctl\fR, and
864 -will return to the user any information sent upstream by the downstream
865 -recipient. \fBI_STR\fR blocks until the system responds with either a positive
866 -or negative acknowledgement message, or until the request times out after some
867 -period of time. If the request times out, it fails with \fBerrno\fR set to
868 -\fBETIME\fR.
869 -.sp
870 -To send requests downstream, \fIarg\fR must point to a \fBstrioctl\fR structure
871 -which contains the following members:
872 -.sp
873 -.in +2
874 -.nf
733 +.El
734 +.Pp
735 +.Dv I_FDINSERT
736 +can also fail if an error message was received by the stream
737 +head of the stream corresponding to the
738 +.Fa fildes
739 +member of the
740 +.Vt strfdinsert
741 +structure.
742 +In this case,
743 +.Va errno
744 +will be set to the value in the message.
745 +.It Dv I_STR
746 +Constructs an internal
747 +.Sy STREAMS
748 +ioctl message from the data pointed to by
749 +.Fa arg ,
750 +and sends that message downstream.
751 +.Pp
752 +This mechanism is provided to send user
753 +.Fn ioctl
754 +requests to downstream modules and drivers.
755 +It allows information to be sent with the
756 +.Fn ioctl ,
757 +and will return to the user any information sent upstream by the downstream
758 +recipient.
759 +.Dv I_STR
760 +blocks until the system responds with either a positive or negative
761 +acknowledgement message, or until the request times out after some period of
762 +time.
763 +If the request times out, it fails with
764 +.Va errno
765 +set to
766 +.Er ETIME .
767 +.Pp
768 +To send requests downstream,
769 +.Fa arg
770 +must point to a
771 +.Vt strioctl
772 +structure which contains the following members:
773 +.Bd -literal -offset 2n
875 774 int ic_cmd;
876 775 int ic_timout;
877 776 int ic_len;
878 777 char *ic_dp;
879 -.fi
880 -.in -2
881 -
882 -\fBic_cmd\fR is the internal \fBioctl\fR command intended for a downstream
883 -module or driver and \fBic_timout\fR is the number of seconds (-1 = infinite, 0
884 -= use default, >0 = as specified) an \fBI_STR\fR request will wait for
885 -acknowledgement before timing out. \fBic_len\fR is the number of bytes in the
886 -data argument and \fBic_dp\fR is a pointer to the data argument. The
887 -\fBic_len\fR field has two uses: on input, it contains the length of the data
778 +.Ed
779 +.Pp
780 +.Fa ic_cmd
781 +is the internal
782 +.Fn ioctl
783 +command intended for a downstream module or driver and
784 +.Fa ic_timout
785 +is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) an
786 +.Dv I_STR
787 +request will wait for acknowledgement before timing out.
788 +.Fa ic_len
789 +is the number of bytes in the data argument and
790 +.Fa ic_dp
791 +is a pointer to the data argument.
792 +The
793 +.Fa ic_len
794 +field has two uses: on input, it contains the length of the data
888 795 argument passed in, and on return from the command, it contains the number of
889 -bytes being returned to the user (the buffer pointed to by \fBic_dp\fR should
890 -be large enough to contain the maximum amount of data that any module or the
891 -driver in the stream can return).
892 -.sp
893 -At most one \fBI_STR\fR can be active on a stream. Further \fBI_STR\fR calls
894 -will block until the active \fBI_STR\fR completes via a positive or negative
895 -acknowlegment, a timeout, or an error condition at the stream head. By setting
896 -the \fBic_timout\fR field to 0, the user is requesting STREAMS to provide
897 -the \fBDEFAULT\fR timeout. The default timeout is specific to the STREAMS
796 +bytes being returned to the user (the buffer pointed to by
797 +.Fa ic_dp
798 +should be large enough to contain the maximum amount of data that any module or
799 +the driver in the stream can return).
800 +.Pp
801 +At most one
802 +.Dv I_STR
803 +can be active on a stream.
804 +Further
805 +.Dv I_STR
806 +calls
807 +will block until the active
808 +.Dv I_STR
809 +completes via a positive or negative
810 +acknowlegment, a timeout, or an error condition at the stream head.
811 +By setting the
812 +.Fa ic_timout
813 +field to 0, the user is requesting STREAMS to provide
814 +the
815 +.Sy DEFAULT
816 +timeout.
817 +The default timeout is specific to the STREAMS
898 818 implementation and may vary depending on which release of Solaris you are
899 -using. For Solaris 8 (and earlier versions), the default timeout is fifteen
900 -seconds. The \fBO_NDELAY\fR and \fBO_NONBLOCK\fR (see \fBopen\fR(2)) flags have
901 -no effect on this call.
902 -.sp
903 -The stream head will convert the information pointed to by the \fBstrioctl\fR
904 -structure to an internal \fBioctl\fR command message and send it downstream. On
905 -failure, \fBerrno\fR is set to one of the following values:
906 -.sp
907 -.ne 2
908 -.na
909 -\fB\fBENOSR\fR\fR
910 -.ad
911 -.RS 10n
912 -Unable to allocate buffers for the \fBioctl\fR message due to insufficient
913 -STREAMS memory resources.
914 -.RE
915 -
916 -.sp
917 -.ne 2
918 -.na
919 -\fB\fBEFAULT\fR\fR
920 -.ad
921 -.RS 10n
922 -Either \fIarg\fR points outside the allocated address space, or the buffer area
923 -specified by \fBic_dp\fR and \fBic_len\fR (separately for data sent and data
924 -returned) is outside the allocated address space.
925 -.RE
926 -
927 -.sp
928 -.ne 2
929 -.na
930 -\fB\fBEINVAL\fR\fR
931 -.ad
932 -.RS 10n
933 -\fBic_len\fR is less than 0 or \fBic_len\fR is larger than the maximum
934 -configured size of the data part of a message or \fBic_timout\fR is less than
935 --1.
936 -.RE
937 -
938 -.sp
939 -.ne 2
940 -.na
941 -\fB\fBENXIO\fR\fR
942 -.ad
943 -.RS 10n
944 -Hangup received on \fIfildes\fR.
945 -.RE
946 -
947 -.sp
948 -.ne 2
949 -.na
950 -\fB\fBETIME\fR\fR
951 -.ad
952 -.RS 10n
953 -A downstream \fBioctl\fR timed out before acknowledgement was received.
954 -.RE
955 -
956 -An \fBI_STR\fR can also fail while waiting for an acknowledgement if a message
957 -indicating an error or a hangup is received at the stream head. In addition, an
819 +using.
820 +For Solaris 8 (and earlier versions), the default timeout is fifteen
821 +seconds.
822 +The
823 +.Dv O_NDELAY
824 +and
825 +.Dv O_NONBLOCK
826 +(see
827 +.Xr open 2 )
828 +flags have no effect on this call.
829 +.Pp
830 +The stream head will convert the information pointed to by the
831 +.Vt strioctl
832 +structure to an internal
833 +.Fn ioctl
834 +command message and send it downstream.
835 +On failure,
836 +.Va errno
837 +is set to one of the following values:
838 +.Bl -tag -width EFAULT
839 +.It Er ENOSR
840 +Unable to allocate buffers for the
841 +.Fn ioctl
842 +message due to insufficient STREAMS memory resources.
843 +.It Er EFAULT
844 +Either
845 +.Fa arg
846 +points outside the allocated address space, or the buffer area
847 +specified by
848 +.Fa ic_dp
849 +and
850 +.Fa ic_len
851 +(separately for data sent and data returned) is outside the allocated address
852 +space.
853 +.It Er EINVAL
854 +.Fa ic_len
855 +is less than 0 or
856 +.Fa ic_len
857 +is larger than the maximum configured size of the data part of a message or
858 +.Fa ic_timout
859 +is less than \(mi1.
860 +.It Er ENXIO
861 +Hangup received on
862 +.Fa fildes .
863 +.It Er ETIME
864 +A downstream
865 +.Fn ioctl
866 +timed out before acknowledgement was received.
867 +.El
868 +.Pp
869 +An
870 +.Dv I_STR
871 +can also fail while waiting for an acknowledgement if a message
872 +indicating an error or a hangup is received at the stream head.
873 +In addition, an
958 874 error code can be returned in the positive or negative acknowledgement message,
959 -in the event the ioctl command sent downstream fails. For these cases,
960 -\fBI_STR\fR will fail with \fBerrno\fR set to the value in the message.
961 -.RE
962 -
963 -.sp
964 -.ne 2
965 -.na
966 -\fB\fBI_SWROPT\fR\fR
967 -.ad
968 -.RS 15n
969 -Sets the write mode using the value of the argument \fIarg\fR. Legal bit
970 -settings for \fIarg\fR are:
971 -.sp
972 -.ne 2
973 -.na
974 -\fB\fBSNDZERO\fR\fR
975 -.ad
976 -.RS 11n
875 +in the event the ioctl command sent downstream fails.
876 +For these cases,
877 +.Dv I_STR
878 +will fail with
879 +.Va errno
880 +set to the value in the message.
881 +.It Dv I_SWROPT
882 +Sets the write mode using the value of the argument
883 +.Fa arg .
884 +Legal bit settings for
885 +.Fa arg
886 +are:
887 +.Bl -tag -width SNDZERO
888 +.It Dv SNDZERO
977 889 Send a zero-length message downstream when a write of 0 bytes occurs.
978 -.RE
979 -
890 +.El
891 +.Pp
980 892 To not send a zero-length message when a write of 0 bytes occurs, this bit must
981 -not be set in \fIarg\fR.
982 -.sp
983 -On failure, \fBerrno\fR may be set to the following value:
984 -.sp
985 -.ne 2
986 -.na
987 -\fB\fBEINVAL\fR\fR
988 -.ad
989 -.RS 10n
990 -\fIarg\fR is not the above legal value.
991 -.RE
992 -
993 -.RE
994 -
995 -.sp
996 -.ne 2
997 -.na
998 -\fB\fBI_GWROPT\fR\fR
999 -.ad
1000 -.RS 15n
1001 -Returns the current write mode setting, as described above, in the \fBint\fR
1002 -that is pointed to by the argument \fIarg\fR.
1003 -.RE
1004 -
1005 -.sp
1006 -.ne 2
1007 -.na
1008 -\fB\fBI_SENDFD\fR\fR
1009 -.ad
1010 -.RS 15n
1011 -Requests the stream associated with \fIfildes\fR to send a message, containing
1012 -a file pointer, to the stream head at the other end of a stream pipe. The file
1013 -pointer corresponds to \fIarg\fR, which must be an open file descriptor.
1014 -.sp
1015 -\fBI_SENDFD\fR converts \fIarg\fR into the corresponding system file pointer.
1016 -It allocates a message block and inserts the file pointer in the block. The
1017 -user id and group id associated with the sending process are also inserted.
1018 -This message is placed directly on the read queue (see \fBIntro\fR(3)) of the
1019 -stream head at the other end of the stream pipe to which it is connected. On
1020 -failure, \fBerrno\fR is set to one of the following values:
1021 -.sp
1022 -.ne 2
1023 -.na
1024 -\fB\fBEAGAIN\fR\fR
1025 -.ad
1026 -.RS 10n
893 +not be set in
894 +.Fa arg .
895 +.Pp
896 +On failure,
897 +.Va errno
898 +may be set to the following value:
899 +.Bl -tag -width EINVAL
900 +.It Sy EINVAL
901 +.Fa arg
902 +is not the above legal value.
903 +.El
904 +.It Dv I_GWROPT
905 +Returns the current write mode setting, as described above, in the
906 +.Vt int
907 +that is pointed to by the argument
908 +.Fa arg .
909 +.It Dv I_SENDFD
910 +Requests the stream associated with
911 +.Fa fildes
912 +to send a message, containing
913 +a file pointer, to the stream head at the other end of a stream pipe.
914 +The file
915 +pointer corresponds to
916 +.Fa arg ,
917 +which must be an open file descriptor.
918 +.Pp
919 +.Dv I_SENDFD
920 +converts
921 +.Fa arg
922 +into the corresponding system file pointer.
923 +It allocates a message block and inserts the file pointer in the block.
924 +The user id and group id associated with the sending process are also inserted.
925 +This message is placed directly on the read queue (see
926 +.Xr Intro 3 )
927 +of the stream head at the other end of the stream pipe to which it is connected.
928 +On failure,
929 +.Va errno
930 +is set to one of the following values:
931 +.Bl -tag -width EAGAIN
932 +.It Er EAGAIN
1027 933 The sending stream is unable to allocate a message block to contain the file
1028 934 pointer.
1029 -.RE
1030 -
1031 -.sp
1032 -.ne 2
1033 -.na
1034 -\fB\fBEAGAIN\fR\fR
1035 -.ad
1036 -.RS 10n
935 +.It Er EAGAIN
1037 936 The read queue of the receiving stream head is full and cannot accept the
1038 -message sent by \fBI_SENDFD.\fR
1039 -.RE
1040 -
1041 -.sp
1042 -.ne 2
1043 -.na
1044 -\fB\fBEBADF\fR\fR
1045 -.ad
1046 -.RS 10n
1047 -\fIarg\fR is not a valid, open file descriptor.
1048 -.RE
1049 -
1050 -.sp
1051 -.ne 2
1052 -.na
1053 -\fB\fBEINVAL\fR\fR
1054 -.ad
1055 -.RS 10n
1056 -\fIfildes\fR is not connected to a stream pipe.
1057 -.RE
1058 -
1059 -.sp
1060 -.ne 2
1061 -.na
1062 -\fB\fBENXIO\fR\fR
1063 -.ad
1064 -.RS 10n
1065 -Hangup received on \fIfildes\fR.
1066 -.RE
1067 -
1068 -.RE
1069 -
1070 -.sp
1071 -.ne 2
1072 -.na
1073 -\fB\fBI_RECVFD\fR\fR
1074 -.ad
1075 -.RS 15n
937 +message sent by
938 +.Dv I_SENDFD .
939 +.It Er EBADF
940 +.Fa arg
941 +is not a valid, open file descriptor.
942 +.It Er EINVAL
943 +.Va fildes
944 +is not connected to a stream pipe.
945 +.It Er ENXIO
946 +Hangup received on
947 +.Fa fildes .
948 +.El
949 +.It Dv I_RECVFD
1076 950 Retrieves the file descriptor associated with the message sent by an
1077 -\fBI_SENDFD\fR \fBioctl\fR over a stream pipe. \fIarg\fR is a pointer to a data
1078 -buffer large enough to hold an \fBstrrecvfd\fR data structure containing the
1079 -following members:
1080 -.sp
1081 -.in +2
1082 -.nf
1083 -int fd;
1084 -uid_t uid;
1085 -gid_t gid;
1086 -.fi
1087 -.in -2
1088 -
1089 -\fBfd\fR is an integer file descriptor. \fBuid\fR and \fBgid\fR are the user id
1090 -and group id, respectively, of the sending stream.
1091 -.sp
1092 -If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear (see \fBopen\fR(2)),
1093 -\fBI_RECVFD\fR will block until a message is present at the stream head. If
1094 -\fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set, \fBI_RECVFD\fR will fail with
1095 -\fBerrno\fR set to \fBEAGAIN\fR if no message is present at the stream head.
1096 -.sp
1097 -If the message at the stream head is a message sent by an \fBI_SENDFD\fR, a new
951 +.Dv I_SENDFD
952 +.Fn ioctl
953 +over a stream pipe.
954 +.Fa arg
955 +is a pointer to a data buffer large enough to hold an
956 +.Vt strrecvfd
957 +data structure containing the following members:
958 +.Bd -literal -offset 2n
959 +int fd;
960 +uid_t uid;
961 +gid_t gid;
962 +.Ed
963 +.Pp
964 +.Fa fd
965 +is an integer file descriptor.
966 +.Fa uid
967 +and
968 +.Fa gid
969 +are the user id and group id, respectively, of the sending stream.
970 +.Pp
971 +If
972 +.Dv O_NDELAY
973 +and
974 +.Dv O_NONBLOCK
975 +are clear (see
976 +.Xr open 2 ) ,
977 +.Dv I_RECVFD
978 +will block until a message is present at the stream head.
979 +If
980 +.Dv O_NDELAY
981 +or
982 +.Dv O_NONBLOCK
983 +is set,
984 +.Dv I_RECVFD
985 +will fail with
986 +.Va errno
987 +set to
988 +.Er EAGAIN
989 +if no message is present at the stream head.
990 +.Pp
991 +If the message at the stream head is a message sent by an
992 +.Dv I_SENDFD ,
993 +a new
1098 994 user file descriptor is allocated for the file pointer contained in the
1099 -message. The new file descriptor is placed in the \fBfd\fR field of the
1100 -\fBstrrecvfd\fR structure. The structure is copied into the user data buffer
1101 -pointed to by \fIarg\fR. On failure, \fBerrno\fR is set to one of the following
1102 -values:
1103 -.sp
1104 -.ne 2
1105 -.na
1106 -\fB\fBEAGAIN\fR\fR
1107 -.ad
1108 -.RS 13n
1109 -A message is not present at the stream head read queue, and the \fBO_NDELAY\fR
1110 -or \fBO_NONBLOCK\fR flag is set.
1111 -.RE
1112 -
1113 -.sp
1114 -.ne 2
1115 -.na
1116 -\fB\fBEBADMSG\fR\fR
1117 -.ad
1118 -.RS 13n
995 +message.
996 +The new file descriptor is placed in the
997 +.Fa fd
998 +field of the
999 +.Vt strrecvfd
1000 +structure.
1001 +The structure is copied into the user data buffer pointed to by
1002 +.Fa arg .
1003 +On failure,
1004 +.Va errno
1005 +is set to one of the following values:
1006 +.Bl -tag -width EOVERFLOW
1007 +.It Er EAGAIN
1008 +A message is not present at the stream head read queue, and the
1009 +.Dv O_NDELAY
1010 +or
1011 +.Dv O_NONBLOCK
1012 +flag is set.
1013 +.It Er EBADMSG
1119 1014 The message at the stream head read queue is not a message containing a passed
1120 1015 file descriptor.
1121 -.RE
1122 -
1123 -.sp
1124 -.ne 2
1125 -.na
1126 -\fB\fBEFAULT\fR\fR
1127 -.ad
1128 -.RS 13n
1129 -\fIarg\fR points outside the allocated address space.
1130 -.RE
1131 -
1132 -.sp
1133 -.ne 2
1134 -.na
1135 -\fB\fBEMFILE\fR\fR
1136 -.ad
1137 -.RS 13n
1138 -\fBNOFILES\fR file descriptors are currently open.
1139 -.RE
1140 -
1141 -.sp
1142 -.ne 2
1143 -.na
1144 -\fB\fBENXIO\fR\fR
1145 -.ad
1146 -.RS 13n
1147 -Hangup received on \fIfildes\fR.
1148 -.RE
1149 -
1150 -.sp
1151 -.ne 2
1152 -.na
1153 -\fB\fBEOVERFLOW\fR\fR
1154 -.ad
1155 -.RS 13n
1156 -\fIuid\fR or \fIgid\fR is too large to be stored in the structure pointed to by
1157 -\fIarg\fR.
1158 -.RE
1159 -
1160 -.RE
1161 -
1162 -.sp
1163 -.ne 2
1164 -.na
1165 -\fB\fBI_LIST\fR\fR
1166 -.ad
1167 -.RS 15n
1016 +.It Er EFAULT
1017 +.Fa arg
1018 +points outside the allocated address space.
1019 +.It Er EMFILE
1020 +.Dv NOFILES
1021 +file descriptors are currently open.
1022 +.It Er ENXIO
1023 +Hangup received on
1024 +.Fa fildes .
1025 +.It Er EOVERFLOW
1026 +.Fa uid
1027 +or
1028 +.Fa gid
1029 +is too large to be stored in the structure pointed to by
1030 +.Fa arg .
1031 +.El
1032 +.It Dv I_LIST
1168 1033 Allows the user to list all the module names on the stream, up to and including
1169 -the topmost driver name. If \fIarg\fR is \fINULL\fR, the return value is the
1170 -number of modules, including the driver, that are on the stream pointed to by
1171 -\fIfildes\fR. This allows the user to allocate enough space for the module
1172 -names. If \fIarg\fR is non-null, it should point to an \fBstr_list\fR structure
1173 -that has the following members:
1174 -.sp
1175 -.in +2
1176 -.nf
1034 +the topmost driver name.
1035 +If
1036 +.Fa arg
1037 +is
1038 +.Dv NULL ,
1039 +the return value is the number of modules, including the driver, that are on
1040 +the stream pointed to by
1041 +.Fa fildes .
1042 +This allows the user to allocate enough space for the module
1043 +names.
1044 +If
1045 +.Fa arg
1046 +is non-null, it should point to an
1047 +.Vt str_list
1048 +structure that has the following members:
1049 +.Bd -literal -offset 2n
1177 1050 int sl_nmods;
1178 1051 struct str_mlist *sl_modlist;
1179 -.fi
1180 -.in -2
1181 -
1182 -The \fBstr_mlist\fR structure has the following member:
1183 -.sp
1184 -.in +2
1185 -.nf
1052 +.Ed
1053 +.Pp
1054 +The
1055 +.Vt str_mlist
1056 +structure has the following member:
1057 +.Bd -literal -offset 2n
1186 1058 char l_name[FMNAMESZ+1];
1187 -.fi
1188 -.in -2
1189 -
1190 -The \fBsl_nmods\fR member indicates the number of entries the process has
1191 -allocated in the array. Upon return, the \fBsl_modlist\fR member of the
1192 -\fBstr_list\fR structure contains the list of module names, and the number of
1193 -entries that have been filled into the \fBsl_modlist\fR array is found in the
1194 -\fBsl_nmods\fR member (the number includes the number of modules including the
1195 -driver). The return value from \fBioctl()\fR is 0. The entries are filled in
1059 +.Ed
1060 +.Pp
1061 +The
1062 +.Fa sl_nmods
1063 +member indicates the number of entries the process has allocated in the array.
1064 +Upon return, the
1065 +.Fa sl_modlist
1066 +member of the
1067 +.Vt str_list
1068 +structure contains the list of module names, and the number of
1069 +entries that have been filled into the
1070 +.Fa sl_modlist
1071 +array is found in the
1072 +.Fa sl_nmods
1073 +member (the number includes the number of modules including the driver).
1074 +The return value from
1075 +.Fn ioctl
1076 +is 0.
1077 +The entries are filled in
1196 1078 starting at the top of the stream and continuing downstream until either the
1197 1079 end of the stream is reached, or the number of requested modules
1198 -(\fBsl_nmods\fR) is satisfied. On failure, \fBerrno\fR may be set to one of the
1199 -following values:
1200 -.sp
1201 -.ne 2
1202 -.na
1203 -\fB\fBEINVAL\fR\fR
1204 -.ad
1205 -.RS 10n
1206 -The \fBsl_nmods\fR member is less than 1.
1207 -.RE
1208 -
1209 -.sp
1210 -.ne 2
1211 -.na
1212 -\fB\fBEAGAIN\fR\fR
1213 -.ad
1214 -.RS 10n
1080 +.Pq Fa sl_nmods
1081 +is satisfied.
1082 +On failure,
1083 +.Va errno
1084 +may be set to one of the following values:
1085 +.Bl -tag -width EINVAL
1086 +.It Er EINVAL
1087 +The
1088 +.Fa sl_nmods
1089 +member is less than 1.
1090 +.It Er EAGAIN
1215 1091 Unable to allocate buffers
1216 -.RE
1217 -
1218 -.RE
1219 -
1220 -.sp
1221 -.ne 2
1222 -.na
1223 -\fB\fBI_ATMARK\fR\fR
1224 -.ad
1225 -.RS 15n
1092 +.El
1093 +.It Dv I_ATMARK
1226 1094 Allows the user to see if the current message on the stream head read queue is
1227 -``marked'' by some module downstream. \fIarg\fR determines how the checking is
1095 +.Dq marked
1096 +by some module downstream.
1097 +.Fa arg
1098 +determines how the checking is
1228 1099 done when there may be multiple marked messages on the stream head read queue.
1229 1100 It may take the following values:
1230 -.sp
1231 -.ne 2
1232 -.na
1233 -\fB\fBANYMARK\fR\fR
1234 -.ad
1235 -.RS 12n
1101 +.Bl -tag -width LASTMARK
1102 +.It Dv ANYMARK
1236 1103 Check if the message is marked.
1237 -.RE
1238 -
1239 -.sp
1240 -.ne 2
1241 -.na
1242 -\fB\fBLASTMARK\fR\fR
1243 -.ad
1244 -.RS 12n
1104 +.It Dv LASTMARK
1245 1105 Check if the message is the last one marked on the queue.
1246 -.RE
1247 -
1248 -The return value is \fB1\fR if the mark condition is satisfied and \fB0\fR
1249 -otherwise. On failure, \fBerrno\fR is set to the following value:
1250 -.sp
1251 -.ne 2
1252 -.na
1253 -\fB\fBEINVAL\fR\fR
1254 -.ad
1255 -.RS 10n
1256 -Invalid \fIarg\fR value.
1257 -.RE
1258 -
1259 -.RE
1260 -
1261 -.sp
1262 -.ne 2
1263 -.na
1264 -\fB\fBI_CKBAND\fR\fR
1265 -.ad
1266 -.RS 15n
1106 +.El
1107 +.Pp
1108 +The return value is
1109 +.Sy 1
1110 +if the mark condition is satisfied and
1111 +.Sy 0
1112 +otherwise.
1113 +On failure,
1114 +.Va errno
1115 +is set to the following value:
1116 +.Bl -tag -width EINVAL
1117 +.It Er EINVAL
1118 +Invalid
1119 +.Fa arg
1120 +value.
1121 +.El
1122 +.It Dv I_CKBAND
1267 1123 Check if the message of a given priority band exists on the stream head read
1268 -queue. This returns \fB1\fR if a message of a given priority exists, \fB0\fR if
1269 -not, or \fB\(mi1\fR on error. \fIarg\fR should be an integer containing the
1270 -value of the priority band in question. On failure, \fBerrno\fR is set to the
1271 -following value:
1272 -.sp
1273 -.ne 2
1274 -.na
1275 -\fB\fBEINVAL\fR\fR
1276 -.ad
1277 -.RS 10n
1278 -Invalid \fIarg\fR value.
1279 -.RE
1280 -
1281 -.RE
1282 -
1283 -.sp
1284 -.ne 2
1285 -.na
1286 -\fB\fBI_GETBAND\fR\fR
1287 -.ad
1288 -.RS 15n
1124 +queue.
1125 +This returns
1126 +.Sy 1
1127 +if a message of a given priority exists,
1128 +.Sy 0
1129 +if not, or
1130 +.Sy \(mi1
1131 +on error.
1132 +.Fa arg
1133 +should be an integer containing the value of the priority band in question.
1134 +On failure,
1135 +.Va errno
1136 +is set to the following value:
1137 +.Bl -tag -width EINVAL
1138 +.It Er EINVAL
1139 +Invalid
1140 +.Fa arg
1141 +value.
1142 +.El
1143 +.It Dv I_GETBAND
1289 1144 Returns the priority band of the first message on the stream head read queue in
1290 -the integer referenced by \fIarg\fR. On failure, \fBerrno\fR is set to the
1291 -following value:
1292 -.sp
1293 -.ne 2
1294 -.na
1295 -\fB\fBENODATA\fR\fR
1296 -.ad
1297 -.RS 11n
1145 +the integer referenced by
1146 +.Fa arg .
1147 +On failure,
1148 +.Va errno
1149 +is set to the following value:
1150 +.Bl -tag -width ENODATA
1151 +.It Er ENODATA
1298 1152 No message on the stream head read queue.
1299 -.RE
1300 -
1301 -.RE
1302 -
1303 -.sp
1304 -.ne 2
1305 -.na
1306 -\fB\fBI_CANPUT\fR\fR
1307 -.ad
1308 -.RS 15n
1309 -Check if a certain band is writable. \fIarg\fR is set to the priority band in
1310 -question. The return value is \fB0\fR if the priority band \fIarg\fR is flow
1311 -controlled, \fB1\fR if the band is writable, or \fB\(mi1\fR on error. On
1312 -failure, \fBerrno\fR is set to the following value:
1313 -.sp
1314 -.ne 2
1315 -.na
1316 -\fB\fBEINVAL\fR\fR
1317 -.ad
1318 -.RS 10n
1319 -Invalid \fIarg\fR value.
1320 -.RE
1321 -
1322 -.RE
1323 -
1324 -.sp
1325 -.ne 2
1326 -.na
1327 -\fB\fBI_SETCLTIME\fR\fR
1328 -.ad
1329 -.RS 15n
1153 +.El
1154 +.It Dv I_CANPUT
1155 +Check if a certain band is writable.
1156 +.Fa arg
1157 +is set to the priority band in question.
1158 +The return value is
1159 +.Sy 0
1160 +if the priority band
1161 +.Fa arg
1162 +is flow controlled,
1163 +.Sy 1
1164 +if the band is writable, or
1165 +.Sy \(mi1
1166 +on error.
1167 +On failure,
1168 +.Va errno
1169 +is set to the following value:
1170 +.Bl -tag -width EINVAL
1171 +.It Sy EINVAL
1172 +Invalid
1173 +.Va arg
1174 +value.
1175 +.El
1176 +.It Dv I_SETCLTIME
1330 1177 Allows the user to set the time the stream head will delay when a stream is
1331 -closing and there are data on the write queues. Before closing each module and
1332 -driver, the stream head will delay for the specified amount of time to allow
1333 -the data to drain. Note, however, that the module or driver may itself delay in
1334 -its close routine; this delay is independent of the stream head's delay and is
1335 -not settable. If, after the delay, data are still present, data will be
1336 -flushed. \fIarg\fR is a pointer to an integer containing the number of
1178 +closing and there are data on the write queues.
1179 +Before closing each module and driver, the stream head will delay for the
1180 +specified amount of time to allow the data to drain.
1181 +Note, however, that the module or driver may itself delay in its close routine;
1182 +this delay is independent of the stream head's delay and is not settable.
1183 +If, after the delay, data are still present, data will be flushed.
1184 +.Fa arg
1185 +is a pointer to an integer containing the number of
1337 1186 milliseconds to delay, rounded up to the nearest legal value on the system.
1338 -The default is fifteen seconds. On failure, \fBerrno\fR is set to the following
1339 -value:
1340 -.sp
1341 -.ne 2
1342 -.na
1343 -\fB\fBEINVAL\fR\fR
1344 -.ad
1345 -.RS 10n
1346 -Invalid \fIarg\fR value.
1347 -.RE
1348 -
1349 -.RE
1350 -
1351 -.sp
1352 -.ne 2
1353 -.na
1354 -\fB\fBI_GETCLTIME\fR\fR
1355 -.ad
1356 -.RS 15n
1357 -Returns the close time delay in the integer pointed by \fIarg\fR.
1358 -.RE
1359 -
1360 -.sp
1361 -.ne 2
1362 -.na
1363 -\fB\fBI_SERROPT\fR\fR
1364 -.ad
1365 -.RS 15n
1366 -Sets the error mode using the value of the argument \fIarg\fR.
1367 -.sp
1187 +The default is fifteen seconds.
1188 +On failure,
1189 +.Va errno
1190 +is set to the following value:
1191 +.Bl -tag -width EINVAL
1192 +.It Er EINVAL
1193 +Invalid
1194 +.Fa arg
1195 +value.
1196 +.El
1197 +.It Dv I_GETCLTIME
1198 +Returns the close time delay in the integer pointed by
1199 +.Va arg .
1200 +.It Dv I_SERROPT
1201 +Sets the error mode using the value of the argument
1202 +.Fa arg .
1203 +.Pp
1368 1204 Normally stream head errors are persistent; once they are set due to an
1369 -\fBM_ERROR\fR or \fBM_HANGUP\fR, the error condition will remain until the
1370 -stream is closed. This option can be used to set the stream head into
1371 -non-persistent error mode i.e. once the error has been returned in response to
1372 -a \fBread\fR(2), \fBgetmsg\fR(2), \fBioctl\fR(2), \fBwrite\fR(2), or
1373 -\fBputmsg\fR(2) call the error condition will be cleared. The error mode can be
1374 -controlled independently for read and write side errors. Legal \fIarg\fR values
1205 +.Dv M_ERROR
1206 +or
1207 +.Dv M_HANGUP ,
1208 +the error condition will remain until the stream is closed.
1209 +This option can be used to set the stream head into
1210 +non-persistent error mode i\.e\. once the error has been returned in response
1211 +to a
1212 +.Xr read 2 ,
1213 +.Xr getmsg 2 ,
1214 +.Xr ioctl 2 ,
1215 +.Xr write 2 ,
1216 +or
1217 +.Xr putmsg 2
1218 +call the error condition will be cleared.
1219 +The error mode can be controlled independently for read and write side errors.
1220 +Legal
1221 +.Fa arg
1222 +values
1375 1223 are either none or one of:
1376 -.sp
1377 -.ne 2
1378 -.na
1379 -\fB\fBRERRNORM\fR\fR
1380 -.ad
1381 -.RS 18n
1224 +.Bl -tag -width RERRNONPERSIST
1225 +.It Dv RERRNORM
1382 1226 Persistent read errors, the default.
1383 -.RE
1384 -
1385 -.sp
1386 -.ne 2
1387 -.na
1388 -\fB\fBRERRNONPERSIST\fR\fR
1389 -.ad
1390 -.RS 18n
1227 +.It Dv RERRNONPERSIST
1391 1228 Non-persistent read errors.
1392 -.RE
1393 -
1394 -\fBOR'ed\fR with either none or one of:
1395 -.sp
1396 -.ne 2
1397 -.na
1398 -\fB\fBWERRNORM\fR\fR
1399 -.ad
1400 -.RS 18n
1229 +.El
1230 +.Pp
1231 +.Sy OR Ns 'ed
1232 +with either none or one of:
1233 +.Bl -tag -width WERRNONPERSIST
1234 +.It Dv WERRNORM
1401 1235 Persistent write errors, the default.
1402 -.RE
1403 -
1404 -.sp
1405 -.ne 2
1406 -.na
1407 -\fB\fBWERRNONPERSIST\fR\fR
1408 -.ad
1409 -.RS 18n
1236 +.It Dv WERRNONPERSIST
1410 1237 Non-persistent write errors.
1411 -.sp
1412 -When no value is specified e.g. for the read side error behavior then the
1238 +.El
1239 +.Pp
1240 +When no value is specified e\.g\. for the read side error behavior then the
1413 1241 behavior for that side will be left unchanged.
1414 -.RE
1415 -
1416 -On failure, \fBerrno\fR is set to the following value:
1417 -.sp
1418 -.ne 2
1419 -.na
1420 -\fB\fBEINVAL\fR\fR
1421 -.ad
1422 -.RS 10n
1423 -\fIarg\fR is not one of the above legal values.
1424 -.RE
1425 -
1426 -.RE
1427 -
1428 -.sp
1429 -.ne 2
1430 -.na
1431 -\fB\fBI_GERROPT\fR\fR
1432 -.ad
1433 -.RS 15n
1434 -Returns the current error mode setting in an \fBint\fR pointed to by the
1435 -argument \fIarg\fR. Error modes are described above for \fBI_SERROPT\fR. On
1436 -failure,\fBerrno\fR is set to the following value:
1437 -.sp
1438 -.ne 2
1439 -.na
1440 -\fB\fBEFAULT\fR\fR
1441 -.ad
1442 -.RS 10n
1443 -\fIarg\fR points outside the allocated address space.
1444 -.RE
1445 -
1446 -.RE
1447 -
1448 -.sp
1449 -.LP
1242 +.Pp
1243 +On failure,
1244 +.Va errno
1245 +is set to the following value:
1246 +.Bl -tag -width EINVAL
1247 +.It Er EINVAL
1248 +.Va arg
1249 +is not one of the above legal values.
1250 +.El
1251 +.It Dv I_GERROPT
1252 +Returns the current error mode setting in an
1253 +.Vt int
1254 +pointed to by the argument
1255 +.Fa arg .
1256 +Error modes are described above for
1257 +.Dv I_SERROPT .
1258 +On failure,
1259 +.Va errno
1260 +is set to the following value:
1261 +.Bl -tag -width EFAULT
1262 +.It Sy EFAULT
1263 +.Fa arg
1264 +points outside the allocated address space.
1265 +.El
1266 +.El
1267 +.Pp
1450 1268 The following four commands are used for connecting and disconnecting
1451 1269 multiplexed STREAMS configurations.
1452 -.sp
1453 -.ne 2
1454 -.na
1455 -\fB\fBI_LINK\fR\fR
1456 -.ad
1457 -.RS 13n
1458 -Connects two streams, where \fIfildes\fR is the file descriptor of the stream
1459 -connected to the multiplexing driver, and \fIarg\fR is the file descriptor of
1460 -the stream connected to another driver. The stream designated by \fIarg\fR gets
1461 -connected below the multiplexing driver. \fBI_LINK\fR requires the multiplexing
1270 +.Bl -tag -width I_PUNLINK
1271 +.It Dv I_LINK
1272 +Connects two streams, where
1273 +.Fa fildes
1274 +is the file descriptor of the stream
1275 +connected to the multiplexing driver, and
1276 +.Fa arg
1277 +is the file descriptor of the stream connected to another driver.
1278 +The stream designated by
1279 +.Va arg
1280 +gets
1281 +connected below the multiplexing driver.
1282 +.Dv I_LINK
1283 +requires the multiplexing
1462 1284 driver to send an acknowledgement message to the stream head regarding the
1463 -linking operation. This call returns a multiplexor ID number (an identifier
1464 -used to disconnect the multiplexor, see \fBI_UNLINK\fR) on success, and -1 on
1465 -failure. On failure, \fBerrno\fR is set to one of the following values:
1466 -.sp
1467 -.ne 2
1468 -.na
1469 -\fB\fBENXIO\fR\fR
1470 -.ad
1471 -.RS 10n
1472 -Hangup received on \fIfildes\fR.
1473 -.RE
1474 -
1475 -.sp
1476 -.ne 2
1477 -.na
1478 -\fB\fBETIME\fR\fR
1479 -.ad
1480 -.RS 10n
1285 +linking operation.
1286 +This call returns a multiplexor ID number (an identifier
1287 +used to disconnect the multiplexor, see
1288 +.Dv I_UNLINK )
1289 +on success, and \(mi1 on failure.
1290 +On failure,
1291 +.Va errno
1292 +is set to one of the following values:
1293 +.Bl -tag -width EAGAIN
1294 +.It Er ENXIO
1295 +Hangup received on
1296 +.Va fildes .
1297 +.It Er ETIME
1481 1298 Time out before acknowledgement message was received at stream head.
1482 -.RE
1483 -
1484 -.sp
1485 -.ne 2
1486 -.na
1487 -\fB\fBEAGAIN\fR\fR
1488 -.ad
1489 -.RS 10n
1490 -Temporarily unable to allocate storage to perform the \fBI_LINK.\fR
1491 -.RE
1492 -
1493 -.sp
1494 -.ne 2
1495 -.na
1496 -\fB\fBENOSR\fR\fR
1497 -.ad
1498 -.RS 10n
1499 -Unable to allocate storage to perform the \fBI_LINK\fR due to insufficient
1500 -\fBSTREAMS\fR memory resources.
1501 -.RE
1502 -
1503 -.sp
1504 -.ne 2
1505 -.na
1506 -\fB\fBEBADF\fR\fR
1507 -.ad
1508 -.RS 10n
1509 -\fIarg\fR is not a valid, open file descriptor.
1510 -.RE
1511 -
1512 -.sp
1513 -.ne 2
1514 -.na
1515 -\fB\fBEINVAL\fR\fR
1516 -.ad
1517 -.RS 10n
1518 -\fIfildes\fR stream does not support multiplexing.
1519 -.RE
1520 -
1521 -.sp
1522 -.ne 2
1523 -.na
1524 -\fB\fBEINVAL\fR\fR
1525 -.ad
1526 -.RS 10n
1527 -\fIarg\fR is not a stream, or is already linked under a multiplexor.
1528 -.RE
1529 -
1530 -.sp
1531 -.ne 2
1532 -.na
1533 -\fB\fBEINVAL\fR\fR
1534 -.ad
1535 -.RS 10n
1536 -The specified link operation would cause a ``cycle'' in the resulting
1537 -configuration; that is, a driver would be linked into the multiplexing
1538 -configuration in more than one place.
1539 -.RE
1540 -
1541 -.sp
1542 -.ne 2
1543 -.na
1544 -\fB\fBEINVAL\fR\fR
1545 -.ad
1546 -.RS 10n
1547 -\fIfildes\fR is the file descriptor of a pipe or FIFO.
1548 -.RE
1549 -
1550 -.sp
1551 -.ne 2
1552 -.na
1553 -\fB\fBEINVAL\fR\fR
1554 -.ad
1555 -.RS 10n
1556 -Either the upper or lower stream has a major number >= the maximum major number
1557 -on the system.
1558 -.RE
1559 -
1560 -An \fBI_LINK\fR can also fail while waiting for the multiplexing driver to
1299 +.It Er EAGAIN
1300 +Temporarily unable to allocate storage to perform the
1301 +.Dv I_LINK .
1302 +.It Er ENOSR
1303 +Unable to allocate storage to perform the
1304 +.Dv I_LINK
1305 +due to insufficient
1306 +.Sy STREAMS
1307 +memory resources.
1308 +.It Er EBADF
1309 +.Va arg
1310 +is not a valid, open file descriptor.
1311 +.It Er EINVAL
1312 +.Va fildes
1313 +stream does not support multiplexing.
1314 +.It Er EINVAL
1315 +is not a stream, or is already linked under a multiplexor.
1316 +.It Er EINVAL
1317 +The specified link operation would cause a
1318 +.Dq cycle
1319 +in the resulting configuration; that is, a driver would be linked into the
1320 +multiplexing configuration in more than one place.
1321 +.It Er EINVAL
1322 +.Va fildes
1323 +is the file descriptor of a pipe or FIFO.
1324 +.It Er EINVAL
1325 +Either the upper or lower stream has a major number \(>= the maximum major
1326 +number on the system.
1327 +.El
1328 +.Pp
1329 +An
1330 +.Dv I_LINK
1331 +can also fail while waiting for the multiplexing driver to
1561 1332 acknowledge the link request, if a message indicating an error or a hangup is
1562 -received at the stream head of \fIfildes\fR. In addition, an error code can be
1563 -returned in the positive or negative acknowledgement message. For these cases,
1564 -\fBI_LINK\fR will fail with \fBerrno\fR set to the value in the message.
1565 -.RE
1566 -
1567 -.sp
1568 -.ne 2
1569 -.na
1570 -\fB\fBI_UNLINK\fR\fR
1571 -.ad
1572 -.RS 13n
1573 -Disconnects the two streams specified by \fIfildes\fR and \fIarg\fR.
1574 -\fIfildes\fR is the file descriptor of the stream connected to the multiplexing
1575 -driver. \fIarg\fR is the multiplexor ID number that was returned by the
1576 -\fBI_LINK\fR. If \fIarg\fR is -1, then all streams that were linked to
1577 -\fIfildes\fR are disconnected. As in \fBI_LINK\fR, this command requires the
1578 -multiplexing driver to acknowledge the unlink. On failure, \fBerrno\fR is set
1579 -to one of the following values:
1580 -.sp
1581 -.ne 2
1582 -.na
1583 -\fB\fBENXIO\fR\fR
1584 -.ad
1585 -.RS 10n
1586 -Hangup received on \fIfildes\fR.
1587 -.RE
1588 -
1589 -.sp
1590 -.ne 2
1591 -.na
1592 -\fB\fBETIME\fR\fR
1593 -.ad
1594 -.RS 10n
1333 +received at the stream head of
1334 +.Fa fildes .
1335 +In addition, an error code can be
1336 +returned in the positive or negative acknowledgement message.
1337 +For these cases,
1338 +.Dv I_LINK
1339 +will fail with
1340 +.Va errno
1341 +set to the value in the message.
1342 +.It Dv I_UNLINK
1343 +Disconnects the two streams specified by
1344 +.Fa fildes
1345 +and
1346 +.Fa arg .
1347 +.Fa fildes
1348 +is the file descriptor of the stream connected to the multiplexing
1349 +driver.
1350 +.Fa arg
1351 +is the multiplexor ID number that was returned by the
1352 +.Dv I_LINK .
1353 +If
1354 +.Fa arg
1355 +is \(mi1, then all streams that were linked to
1356 +.Fa fildes
1357 +are disconnected.
1358 +As in
1359 +.Dv I_LINK ,
1360 +this command requires the multiplexing driver to acknowledge the unlink.
1361 +On failure,
1362 +.Va errno
1363 +is set to one of the following values:
1364 +.Bl -tag -width EINVAL
1365 +.It Er ENXIO
1366 +Hangup received on
1367 +.Va fildes .
1368 +.It Er ETIME
1595 1369 Time out before acknowledgement message was received at stream head.
1596 -.RE
1597 -
1598 -.sp
1599 -.ne 2
1600 -.na
1601 -\fB\fBENOSR\fR\fR
1602 -.ad
1603 -.RS 10n
1604 -Unable to allocate storage to perform the \fBI_UNLINK\fR due to insufficient
1370 +.It Er ENOSR
1371 +Unable to allocate storage to perform the
1372 +.Dv I_UNLINK
1373 +due to insufficient
1605 1374 STREAMS memory resources.
1606 -.RE
1607 -
1608 -.sp
1609 -.ne 2
1610 -.na
1611 -\fB\fBEINVAL\fR\fR
1612 -.ad
1613 -.RS 10n
1614 -\fIarg\fR is an invalid multiplexor ID number or \fIfildes\fR is not the stream
1615 -on which the \fBI_LINK\fR that returned \fIarg\fR was performed.
1616 -.RE
1617 -
1618 -.sp
1619 -.ne 2
1620 -.na
1621 -\fB\fBEINVAL\fR\fR
1622 -.ad
1623 -.RS 10n
1624 -\fIfildes\fR is the file descriptor of a pipe or FIFO.
1625 -.RE
1626 -
1627 -An \fBI_UNLINK\fR can also fail while waiting for the multiplexing driver to
1375 +.It Er EINVAL
1376 +.Fa arg
1377 +is an invalid multiplexor ID number or
1378 +.Fa fildes
1379 +is not the stream on which the
1380 +.Dv I_LINK
1381 +that returned
1382 +.Fa arg
1383 +was performed.
1384 +.It Er EINVAL
1385 +.Fa fildes
1386 +is the file descriptor of a pipe or FIFO.
1387 +.El
1388 +.Pp
1389 +An
1390 +.Dv I_UNLINK
1391 +can also fail while waiting for the multiplexing driver to
1628 1392 acknowledge the link request, if a message indicating an error or a hangup is
1629 -received at the stream head of \fIfildes\fR. In addition, an error code can be
1630 -returned in the positive or negative acknowledgement message. For these cases,
1631 -\fBI_UNLINK\fR will fail with \fBerrno\fR set to the value in the message.
1632 -.RE
1633 -
1634 -.sp
1635 -.ne 2
1636 -.na
1637 -\fB\fBI_PLINK\fR\fR
1638 -.ad
1639 -.RS 13n
1640 -Connects two streams, where \fIfildes\fR is the file descriptor of the stream
1641 -connected to the multiplexing driver, and \fIarg\fR is the file descriptor of
1642 -the stream connected to another driver. The stream designated by \fIarg\fR gets
1643 -connected via a persistent link below the multiplexing driver. \fBI_PLINK\fR
1393 +received at the stream head of
1394 +.Fa fildes .
1395 +In addition, an error code can be
1396 +returned in the positive or negative acknowledgement message.
1397 +For these cases,
1398 +.Dv I_UNLINK
1399 +will fail with
1400 +.Va errno
1401 +set to the value in the message.
1402 +.It Dv I_PLINK
1403 +Connects two streams, where
1404 +.Fa fildes
1405 +is the file descriptor of the stream
1406 +connected to the multiplexing driver, and
1407 +.Fa arg
1408 +is the file descriptor of
1409 +the stream connected to another driver.
1410 +The stream designated by
1411 +.Fa arg
1412 +gets
1413 +connected via a persistent link below the multiplexing driver.
1414 +.Dv I_PLINK
1644 1415 requires the multiplexing driver to send an acknowledgement message to the
1645 -stream head regarding the linking operation. This call creates a persistent
1646 -link that continues to exist even if the file descriptor \fIfildes\fR
1647 -associated with the upper stream to the multiplexing driver is closed. This
1416 +stream head regarding the linking operation.
1417 +This call creates a persistent
1418 +link that continues to exist even if the file descriptor
1419 +.Fa fildes
1420 +associated with the upper stream to the multiplexing driver is closed.
1421 +This
1648 1422 call returns a multiplexor ID number (an identifier that may be used to
1649 -disconnect the multiplexor, see \fBI_PUNLINK\fR) on success, and -1 on failure.
1650 -On failure, \fBerrno\fR is set to one of the following values:
1651 -.sp
1652 -.ne 2
1653 -.na
1654 -\fB\fBENXIO\fR\fR
1655 -.ad
1656 -.RS 10n
1657 -Hangup received on \fIfildes\fR.
1658 -.RE
1659 -
1660 -.sp
1661 -.ne 2
1662 -.na
1663 -\fB\fBETIME\fR\fR
1664 -.ad
1665 -.RS 10n
1423 +disconnect the multiplexor, see
1424 +.Dv I_PUNLINK )
1425 +on success, and \(mi1 on failure.
1426 +On failure,
1427 +.Va errno
1428 +is set to one of the following values:
1429 +.Bl -tag -width EAGAIN
1430 +.It Er ENXIO
1431 +Hangup received on
1432 +.Fa fildes .
1433 +.It Er ETIME
1666 1434 Time out before acknowledgement message was received at the stream head.
1667 -.RE
1668 -
1669 -.sp
1670 -.ne 2
1671 -.na
1672 -\fB\fBEAGAIN\fR\fR
1673 -.ad
1674 -.RS 10n
1675 -Unable to allocate STREAMS storage to perform the \fBI_PLINK.\fR
1676 -.RE
1677 -
1678 -.sp
1679 -.ne 2
1680 -.na
1681 -\fB\fBEBADF\fR\fR
1682 -.ad
1683 -.RS 10n
1684 -\fIarg\fR is not a valid, open file descriptor.
1685 -.RE
1686 -
1687 -.sp
1688 -.ne 2
1689 -.na
1690 -\fB\fBEINVAL\fR\fR
1691 -.ad
1692 -.RS 10n
1693 -\fIfildes\fR does not support multiplexing.
1694 -.RE
1695 -
1696 -.sp
1697 -.ne 2
1698 -.na
1699 -\fB\fBEINVAL\fR\fR
1700 -.ad
1701 -.RS 10n
1702 -\fIarg\fR is not a stream or is already linked under a multiplexor.
1703 -.RE
1704 -
1705 -.sp
1706 -.ne 2
1707 -.na
1708 -\fB\fBEINVAL\fR\fR
1709 -.ad
1710 -.RS 10n
1711 -The specified link operation would cause a ``cycle'' in the resulting
1712 -configuration; that is, if a driver would be linked into the multiplexing
1713 -configuration in more than one place.
1714 -.RE
1715 -
1716 -.sp
1717 -.ne 2
1718 -.na
1719 -\fB\fBEINVAL\fR\fR
1720 -.ad
1721 -.RS 10n
1722 -\fIfildes\fR is the file descriptor of a pipe or FIFO.
1723 -.RE
1724 -
1725 -An \fBI_PLINK\fR can also fail while waiting for the multiplexing driver to
1435 +.It Er EAGAIN
1436 +Unable to allocate STREAMS storage to perform the
1437 +.Dv I_PLINK .
1438 +.It Er EBADF
1439 +.Va arg
1440 +is not a valid, open file descriptor.
1441 +.It Er EINVAL
1442 +.Va fildes
1443 +does not support multiplexing.
1444 +.It Er EINVAL
1445 +.Va arg
1446 +is not a stream or is already linked under a multiplexor.
1447 +.It Er EINVAL
1448 +The specified link operation would cause a
1449 +.Dq cycle
1450 +in the resulting configuration; that is, if a driver would be linked into the
1451 +multiplexing configuration in more than one place.
1452 +.It Er EINVAL
1453 +.Fa fildes
1454 +is the file descriptor of a pipe or FIFO.
1455 +.El
1456 +.Pp
1457 +An
1458 +.Dv I_PLINK
1459 +can also fail while waiting for the multiplexing driver to
1726 1460 acknowledge the link request, if a message indicating an error on a hangup is
1727 -received at the stream head of \fIfildes\fR. In addition, an error code can be
1728 -returned in the positive or negative acknowledgement message. For these cases,
1729 -\fBI_PLINK\fR will fail with \fBerrno\fR set to the value in the message.
1730 -.RE
1731 -
1732 -.sp
1733 -.ne 2
1734 -.na
1735 -\fB\fBI_PUNLINK\fR\fR
1736 -.ad
1737 -.RS 13n
1738 -Disconnects the two streams specified by \fIfildes\fR and \fIarg\fR that are
1739 -connected with a persistent link. \fIfildes\fR is the file descriptor of the
1740 -stream connected to the multiplexing driver. \fIarg\fR is the multiplexor ID
1741 -number that was returned by \fBI_PLINK\fR when a stream was linked below the
1742 -multiplexing driver. If \fIarg\fR is \fBMUXID_ALL\fR then all streams that are
1743 -persistent links to \fIfildes\fR are disconnected. As in \fBI_PLINK,\fR this
1744 -command requires the multiplexing driver to acknowledge the unlink. On failure,
1745 -\fBerrno\fR is set to one of the following values:
1746 -.sp
1747 -.ne 2
1748 -.na
1749 -\fB\fBENXIO\fR\fR
1750 -.ad
1751 -.RS 10n
1752 -Hangup received on \fIfildes\fR.
1753 -.RE
1754 -
1755 -.sp
1756 -.ne 2
1757 -.na
1758 -\fB\fBETIME\fR\fR
1759 -.ad
1760 -.RS 10n
1461 +received at the stream head of
1462 +.Fa fildes .
1463 +In addition, an error code can be
1464 +returned in the positive or negative acknowledgement message.
1465 +For these cases,
1466 +.Dv I_PLINK
1467 +will fail with
1468 +.Va errno
1469 +set to the value in the message.
1470 +.It Dv I_PUNLINK
1471 +Disconnects the two streams specified by
1472 +.Fa fildes
1473 +and
1474 +.Fa arg
1475 +that are
1476 +connected with a persistent link.
1477 +.Fa fildes
1478 +is the file descriptor of the
1479 +stream connected to the multiplexing driver.
1480 +.Fa arg
1481 +is the multiplexor ID number that was returned by
1482 +.Dv I_PLINK
1483 +when a stream was linked below the multiplexing driver.
1484 +If
1485 +.Fa arg
1486 +is
1487 +.Dv MUXID_ALL
1488 +then all streams that are persistent links to
1489 +.Fa fildes
1490 +are disconnected.
1491 +As in
1492 +.Dv I_PLINK ,
1493 +this command requires the multiplexing driver to acknowledge the unlink.
1494 +On failure,
1495 +.Va errno
1496 +is set to one of the following values:
1497 +.Bl -tag -width EAGAIN
1498 +.It Sy ENXIO
1499 +Hangup received on
1500 +.Fa fildes .
1501 +.It Er ETIME
1761 1502 Time out before acknowledgement message was received at the stream head.
1762 -.RE
1763 -
1764 -.sp
1765 -.ne 2
1766 -.na
1767 -\fB\fBEAGAIN\fR\fR
1768 -.ad
1769 -.RS 10n
1503 +.It Er EAGAIN
1770 1504 Unable to allocate buffers for the acknowledgement message.
1771 -.RE
1772 -
1773 -.sp
1774 -.ne 2
1775 -.na
1776 -\fB\fBEINVAL\fR\fR
1777 -.ad
1778 -.RS 10n
1505 +.It Er EINVAL
1779 1506 Invalid multiplexor ID number.
1780 -.RE
1781 -
1782 -.sp
1783 -.ne 2
1784 -.na
1785 -\fB\fBEINVAL\fR\fR
1786 -.ad
1787 -.RS 10n
1788 -\fIfildes\fR is the file descriptor of a pipe or FIFO.
1789 -.RE
1790 -
1791 -An \fBI_PUNLINK\fR can also fail while waiting for the multiplexing driver to
1507 +.It Er EINVAL
1508 +.Fa fildes
1509 +is the file descriptor of a pipe or FIFO.
1510 +.El
1511 +.Pp
1512 +An
1513 +.Dv I_PUNLINK
1514 +can also fail while waiting for the multiplexing driver to
1792 1515 acknowledge the link request if a message indicating an error or a hangup is
1793 -received at the stream head of \fIfildes\fR. In addition, an error code can be
1794 -returned in the positive or negative acknowledgement message. For these cases,
1795 -\fBI_PUNLINK\fR will fail with \fBerrno\fR set to the value in the message.
1796 -.RE
1797 -
1798 -.SH RETURN VALUES
1799 -.sp
1800 -.LP
1801 -Unless specified otherwise above, the return value from \fBioctl()\fR is
1802 -\fB0\fR upon success and \fB\(mi1\fR upon failure, with \fIerrno\fR set as
1803 -indicated.
1804 -.SH SEE ALSO
1805 -.sp
1806 -.LP
1807 -\fBIntro\fR(3), \fBclose\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2),
1808 -\fBioctl\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBputmsg\fR(2), \fBread\fR(2),
1809 -\fBwrite\fR(2), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD),
1810 -.sp
1811 -.LP
1812 -\fISTREAMS Programming Guide\fR
1516 +received at the stream head of
1517 +.Fa fildes .
1518 +In addition, an error code can be
1519 +returned in the positive or negative acknowledgement message.
1520 +For these cases,
1521 +.Dv I_PUNLINK
1522 +will fail with
1523 +.Va errno
1524 +set to the value in the message.
1525 +.El
1526 +.Sh RETURN VALUES
1527 +Unless specified otherwise above, the return value from
1528 +.Xr ioctl 2
1529 +is
1530 +.Sy 0
1531 +upon success and
1532 +.Sy \(mi1
1533 +upon failure, with
1534 +.Va errno
1535 +set as indicated.
1536 +.Sh SEE ALSO
1537 +.Xr close 2 ,
1538 +.Xr fcntl 2 ,
1539 +.Xr getmsg 2 ,
1540 +.Xr ioctl 2 ,
1541 +.Xr open 2 ,
1542 +.Xr poll 2 ,
1543 +.Xr putmsg 2 ,
1544 +.Xr read 2 ,
1545 +.Xr write 2 ,
1546 +.Xr Intro 3 ,
1547 +.Xr signal 3C ,
1548 +.Xr signal.h 3HEAD
1549 +.Pp
1550 +.%B STREAMS Programming Guide
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX