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