1 .\" Copyright (c) 2017, Joyent, Inc.
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   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
  56 it is generally an integer or a pointer to a command-specific data structure.
  57 The
  58 .Fa command
  59 and
  60 .Fa arg
  61 arguments are interpreted by the STREAM head.
  62 Certain combinations of these arguments may be passed to a module or driver in
  63 the stream.
  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
 106 Invalid module name.
 107 .It Er EFAULT
 108 .Va arg
 109 points outside the allocated address space.
 110 .It Er ENXIO
 111 Open routine of new module failed.
 112 .It Er ENXIO
 113 Hangup received on
 114 .Va fildes .
 115 .It Er ENOTSUP
 116 Pushing a module is not supported on this stream.
 117 .El
 118 .It Dv I_POP
 119 Removes the module just below the STREAM head of the STREAM pointed to by
 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
 134 No module present in the stream.
 135 .It Er ENXIO
 136 Hangup received on
 137 .Fa fildes .
 138 .It Er EPERM
 139 Attempt to pop through an anchor by an unprivileged process.
 140 .It Er ENOTSUP
 141 Removal is not supported.
 142 .El
 143 .It Dv I_ANCHOR
 144 Positions the stream anchor to be at the stream's module directly below the
 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
 159 Request to put an anchor on a pipe.
 160 .El
 161 .It Dv I_LOOK
 162 Retrieves the name of the module just below the stream head of the stream
 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
 183 No module present in stream.
 184 .El
 185 .It Dv I_FLUSH
 186 This request flushes all input and/or output queues, depending on the value of
 187 .Fa arg .
 188 Legal
 189 .Fa arg
 190 values are:
 191 .Bl -tag -width FLUSHRW
 192 .It Dv FLUSHR
 193 Flush read queues.
 194 .It Dv FLUSHW
 195 Flush write queues.
 196 .It Dv FLUSHRW
 197 Flush read and write queues.
 198 .El
 199 .Pp
 200 If a pipe or FIFO does not have any modules pushed, the read queue of the
 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
 219 exists, the read queue for the other end of the pipe is flushed and the write
 220 queue for this end is flushed.
 221 If
 222 .Fa fildes
 223 is a FIFO, both queues of the
 224 FIFO are flushed.
 225 .Pp
 226 If
 227 .Dv FLUSHRW
 228 is set, all read queues are flushed, that is, the read queue
 229 for the FIFO and the read queue on both ends of the pipe are flushed.
 230 .Pp
 231 Correct flush handling of a pipe or FIFO with modules pushed is achieved via
 232 the
 233 .Sy pipemod
 234 module.
 235 This module should be the first module pushed onto a
 236 pipe so that it is at the midpoint of the pipe itself.
 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
 243 Unable to allocate buffers for flush message due to insufficient stream memory
 244 resources.
 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
 258 structure that has the following members:
 259 .Bd -literal -offset 2n
 260 unsigned char bi_pri;
 261 int bi_flag;
 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
 273 Informs the stream head that the user wishes the kernel to issue the
 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
 293 An ordinary (non-priority) message has arrived on a stream head read queue.
 294 This event is triggered even if the message is of zero length.
 295 .It Dv S_RDBAND
 296 A priority band message (band > 0) has arrived on a stream head read queue.
 297 This event is triggered even if the message is of zero length.
 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
 304 user that there is room on the queue for sending (or writing) data downstream.
 305 .It Dv S_WRNORM
 306 This event is the same as
 307 .Dv S_OUTPUT .
 308 .It Dv S_WRBAND
 309 A priority band greater than 0 of a queue downstream exists and is writable.
 310 This notifies the user that there is room on the queue for sending (or writing)
 311 priority data downstream.
 312 .It Dv S_MSG
 313 A STREAMS signal message that contains the
 314 .Dv SIGPOLL
 315 signal has reached the
 316 front of the stream head read queue.
 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
 332 read queue.
 333 .El
 334 .Pp
 335 A user process may choose to be signaled only of high priority messages by
 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
 347 this signal for the same event on the same stream, each process will be
 348 signaled when the event occurs.
 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
 368 Allocation of a data structure to store the signal request failed.
 369 .El
 370 .It Dv I_GETSIG
 371 Returns the events for which the calling process is currently registered to be
 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
 393 Compares the names of all modules currently present in the stream to the name
 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
 410 Allows a user to retrieve the information in the first message on the stream
 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
 421 struct strbuf ctlbuf;
 422 struct strbuf databuf;
 423 long flags;
 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
 478 is, outside the allocated address space.
 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
 500 Byte-stream mode, the default.
 501 .It Dv RMSGD
 502 Message-discard mode.
 503 .It Dv RMSGN
 504 Message-nondiscard mode.
 505 .El
 506 .Pp
 507 In addition, the stream head's treatment of control messages may be changed by
 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
 518 Deliver the control portion of a message as data when a user issues
 519 .Xr read 2 .
 520 This is the default behavior.
 521 .It Dv RPROTDIS
 522 Discard the control portion of a message, delivering any data portion, when a
 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
 559 Counts the number of data bytes in data blocks in the first message on the
 560 stream head read queue, and places this value in the location pointed to by
 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
 579 Creates a message from specified buffer(s), adds information about another
 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
 583 distinguished by placement in separate buffers, as described below.
 584 .Pp
 585 The
 586 .Fa arg
 587 argument points to a
 588 .Vt strfdinsert
 589 structure, which contains
 590 the following members:
 591 .Bd -literal -offset 2n
 592 struct  strbuf  ctlbuf;
 593 struct  strbuf  databuf;
 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
 678 flag is set, and the stream write queue is full due to internal flow control
 679 conditions.
 680 .It Er ENOSR
 681 Buffers can not be allocated for the message that is to be created.
 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
 695 structure is not a valid, open stream file descriptor; the size of a
 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
 732 is larger than the maximum configured size of the control part of a message.
 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
 774 int  ic_cmd;
 775 int  ic_timout;
 776 int  ic_len;
 777 char  *ic_dp;
 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
 795 argument passed in, and on return from the command, it contains the number of
 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
 818 implementation and may vary depending on which release of Solaris you are
 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
 874 error code can be returned in the positive or negative acknowledgement message,
 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
 889 Send a zero-length message downstream when a write of 0 bytes occurs.
 890 .El
 891 .Pp
 892 To not send a zero-length message when a write of 0 bytes occurs, this bit must
 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
 933 The sending stream is unable to allocate a message block to contain the file
 934 pointer.
 935 .It Er EAGAIN
 936 The read queue of the receiving stream head is full and cannot accept the
 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
 950 Retrieves the file descriptor associated with the message sent by an
 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
 994 user file descriptor is allocated for the file pointer contained in the
 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
1014 The message at the stream head read queue is not a message containing a passed
1015 file descriptor.
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
1033 Allows the user to list all the module names on the stream, up to and including
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
1050 int sl_nmods;
1051 struct  str_mlist  *sl_modlist;
1052 .Ed
1053 .Pp
1054 The
1055 .Vt str_mlist
1056 structure has the following member:
1057 .Bd -literal -offset 2n
1058 char l_name[FMNAMESZ+1];
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
1078 starting at the top of the stream and continuing downstream until either the
1079 end of the stream is reached, or the number of requested modules
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
1091 Unable to allocate buffers
1092 .El
1093 .It Dv I_ATMARK
1094 Allows the user to see if the current message on the stream head read queue is
1095 .Dq marked
1096 by some module downstream.
1097 .Fa arg
1098 determines how the checking is
1099 done when there may be multiple marked messages on the stream head read queue.
1100 It may take the following values:
1101 .Bl -tag -width LASTMARK
1102 .It Dv ANYMARK
1103 Check if the message is marked.
1104 .It Dv LASTMARK
1105 Check if the message is the last one marked on the queue.
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
1123 Check if the message of a given priority band exists on the stream head read
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
1144 Returns the priority band of the first message on the stream head read queue in
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
1152 No message on the stream head read queue.
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
1177 Allows the user to set the time the stream head will delay when a stream is
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
1186 milliseconds to delay, rounded up to the nearest legal value on the system.
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
1204 Normally stream head errors are persistent; once they are set due to an
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
1223 are either none or one of:
1224 .Bl -tag -width RERRNONPERSIST
1225 .It Dv RERRNORM
1226 Persistent read errors, the default.
1227 .It Dv RERRNONPERSIST
1228 Non-persistent read errors.
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
1235 Persistent write errors, the default.
1236 .It Dv WERRNONPERSIST
1237 Non-persistent write errors.
1238 .El
1239 .Pp
1240 When no value is specified e\.g\.  for the read side error behavior then the
1241 behavior for that side will be left unchanged.
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
1268 The following four commands are used for connecting and disconnecting
1269 multiplexed STREAMS configurations.
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
1284 driver to send an acknowledgement message to the stream head regarding the
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
1298 Time out before acknowledgement message was received at stream head.
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
1332 acknowledge the link request, if a message indicating an error or a hangup is
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
1369 Time out before acknowledgement message was received at stream head.
1370 .It Er ENOSR
1371 Unable to allocate storage to perform the
1372 .Dv I_UNLINK
1373 due to insufficient
1374 STREAMS memory resources.
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
1392 acknowledge the link request, if a message indicating an error or a hangup is
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
1415 requires the multiplexing driver to send an acknowledgement message to the
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
1422 call returns a multiplexor ID number (an identifier that may be used to
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
1434 Time out before acknowledgement message was received at the stream head.
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
1460 acknowledge the link request, if a message indicating an error on a hangup is
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
1502 Time out before acknowledgement message was received at the stream head.
1503 .It Er EAGAIN
1504 Unable to allocate buffers for the acknowledgement message.
1505 .It Er EINVAL
1506 Invalid multiplexor ID number.
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
1515 acknowledge the link request if a message indicating an error or a hangup is
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