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