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