1 STREAMIO(7I) Ioctl Requests STREAMIO(7I) 2 3 NAME 4 streamio - STREAMS ioctl commands 5 6 SYNOPSIS 7 #include <sys/types.h> 8 #include <stropts.h> 9 #include <sys/conf.h> 10 11 int 12 ioctl(int fildes, int command, ... /*arg*/); 13 14 DESCRIPTION 15 STREAMS (see Intro(3)) ioctl() commands are a subset of the ioctl(2) 16 commands and perform a variety of control functions on streams. 17 18 The fildes argument is an open file descriptor that refers to a stream. 19 The command argument determines the control function to be performed as 20 described below. The arg argument represents additional information that 21 is needed by this command. The type of arg depends upon the command, but 22 it is generally an integer or a pointer to a command-specific data 23 structure. The command and arg arguments are interpreted by the STREAM 24 head. Certain combinations of these arguments may be passed to a module 25 or driver in the stream. 26 27 Since these STREAMS commands are ioctls, they are subject to the errors 28 described in ioctl(2). In addition to those errors, the call will fail 29 with errno set to EINVAL, without processing a control function, if the 30 STREAM referenced by fildes is linked below a multiplexor, or if command 31 is not a valid value for a stream. 32 33 Also, as described in ioctl(2), STREAMS modules and drivers can detect 34 errors. In this case, the module or driver sends an error message to the 35 STREAM head containing an error value. This causes subsequent calls to 36 fail with errno set to this value. 37 38 IOCTLS 39 The following ioctl() commands, with error values indicated, are 40 applicable to all STREAMS files: 41 42 I_PUSH Pushes the module whose name is pointed to by arg onto the 43 top of the current stream, just below the STREAM head. If 44 the STREAM is a pipe, the module will be inserted between 45 the stream heads of both ends of the pipe. It then calls 46 the open routine of the newly-pushed module. On failure, 47 errno is set to one of the following values: 48 49 EINVAL Invalid module name. 50 51 EFAULT arg points outside the allocated address space. 52 53 ENXIO Open routine of new module failed. 54 55 ENXIO Hangup received on fildes. 56 57 ENOTSUP Pushing a module is not supported on this stream. 58 59 I_POP Removes the module just below the STREAM head of the STREAM 60 pointed to by fildes. To remove a module from a pipe 61 requires that the module was pushed on the side it is being 62 removed from. arg should be 0 in an I_POP request. On 63 failure, errno is set to one of the following values: 64 65 EINVAL No module present in the stream. 66 67 ENXIO Hangup received on fildes. 68 69 EPERM Attempt to pop through an anchor by an unprivileged 70 process. 71 72 ENOTSUP Removal is not supported. 73 74 I_ANCHOR Positions the stream anchor to be at the stream's module 75 directly below the stream head. Once this has been done, 76 only a privileged process may pop modules below the anchor 77 on the stream. arg must be 0 in an I_ANCHOR request. On 78 failure, errno is set to the following value: 79 80 EINVAL Request to put an anchor on a pipe. 81 82 I_LOOK Retrieves the name of the module just below the stream head 83 of the stream pointed to by fildes, and places it in a null 84 terminated character string pointed at by arg. The buffer 85 pointed to by arg should be at least FMNAMESZ+1 bytes long. 86 This requires the declaration `#include <sys/conf.h>'. On 87 failure, errno is set to one of the following values: 88 89 EFAULT arg points outside the allocated address space. 90 91 EINVAL No module present in stream. 92 93 I_FLUSH This request flushes all input and/or output queues, 94 depending on the value of arg. Legal arg values are: 95 96 FLUSHR Flush read queues. 97 98 FLUSHW Flush write queues. 99 100 FLUSHRW Flush read and write queues. 101 102 If a pipe or FIFO does not have any modules pushed, the read 103 queue of the stream head on either end is flushed depending 104 on the value of arg. 105 106 If FLUSHR is set and fildes is a pipe, the read queue for 107 that end of the pipe is flushed and the write queue for the 108 other end is flushed. If fildes is a FIFO, both queues are 109 flushed. 110 111 If FLUSHW is set and fildes is a pipe and the other end of 112 the pipe exists, the read queue for the other end of the 113 pipe is flushed and the write queue for this end is flushed. 114 If fildes is a FIFO, both queues of the FIFO are flushed. 115 116 If FLUSHRW is set, all read queues are flushed, that is, the 117 read queue for the FIFO and the read queue on both ends of 118 the pipe are flushed. 119 120 Correct flush handling of a pipe or FIFO with modules pushed 121 is achieved via the pipemod module. This module should be 122 the first module pushed onto a pipe so that it is at the 123 midpoint of the pipe itself. 124 125 On failure, errno is set to one of the following values: 126 127 ENOSR Unable to allocate buffers for flush message due to 128 insufficient stream memory resources. 129 130 EINVAL Invalid arg value. 131 132 ENXIO Hangup received on fildes. 133 134 I_FLUSHBAND Flushes a particular band of messages. arg points to a 135 bandinfo structure that has the following members: 136 137 unsigned char bi_pri; 138 int bi_flag; 139 140 The bi_flag field may be one of FLUSHR, FLUSHW, or FLUSHRW 141 as described earlier. 142 143 I_SETSIG Informs the stream head that the user wishes the kernel to 144 issue the SIGPOLL signal (see signal(3C)) when a particular 145 event has occurred on the stream associated with fildes. 146 I_SETSIG supports an asynchronous processing capability in 147 streams. The value of arg is a bitmask that specifies the 148 events for which the user should be signaled. It is the 149 bitwise OR of any combination of the following constants: 150 151 S_INPUT Any message other than an M_PCPROTO has arrived 152 on a stream head read queue. This event is 153 maintained for compatibility with previous 154 releases. This event is triggered even if the 155 message is of zero length. 156 157 S_RDNORM An ordinary (non-priority) message has arrived on 158 a stream head read queue. This event is 159 triggered even if the message is of zero length. 160 161 S_RDBAND A priority band message (band > 0) has arrived on 162 a stream head read queue. This event is 163 triggered even if the message is of zero length. 164 165 S_HIPRI A high priority message is present on the stream 166 head read queue. This event is triggered even if 167 the message is of zero length. 168 169 S_OUTPUT The write queue just below the stream head is no 170 longer full. This notifies the user that there 171 is room on the queue for sending (or writing) 172 data downstream. 173 174 S_WRNORM This event is the same as S_OUTPUT. 175 176 S_WRBAND A priority band greater than 0 of a queue 177 downstream exists and is writable. This notifies 178 the user that there is room on the queue for 179 sending (or writing) priority data downstream. 180 181 S_MSG A STREAMS signal message that contains the 182 SIGPOLL signal has reached the front of the 183 stream head read queue. 184 185 S_ERROR An M_ERROR message has reached the stream head. 186 187 S_HANGUP An M_HANGUP message has reached the stream head. 188 189 S_BANDURG When used in conjunction with S_RDBAND, SIGURG is 190 generated instead of SIGPOLL when a priority 191 message reaches the front of the stream head read 192 queue. 193 194 A user process may choose to be signaled only of high 195 priority messages by setting the arg bitmask to the value 196 S_HIPRI. 197 198 Processes that wish to receive SIGPOLL signals must 199 explicitly register to receive them using I_SETSIG. If 200 several processes register to receive this signal for the 201 same event on the same stream, each process will be signaled 202 when the event occurs. 203 204 If the value of arg is zero, the calling process will be 205 unregistered and will not receive further SIGPOLL signals. 206 On failure, errno is set to one of the following values: 207 208 EINVAL arg value is invalid or arg is zero and process is 209 not registered to receive the SIGPOLL signal. 210 211 EAGAIN Allocation of a data structure to store the signal 212 request failed. 213 214 I_GETSIG Returns the events for which the calling process is 215 currently registered to be sent a SIGPOLL signal. The 216 events are returned as a bitmask pointed to by arg, where 217 the events are those specified in the description of 218 I_SETSIG above. On failure, errno is set to one of the 219 following values: 220 221 EINVAL Process not registered to receive the SIGPOLL 222 signal. 223 224 EFAULT arg points outside the allocated address space. 225 226 I_FIND Compares the names of all modules currently present in the 227 stream to the name pointed to by arg, and returns 1 if the 228 named module is present in the stream. It returns 0 if the 229 named module is not present. On failure, errno is set to 230 one of the following values: 231 232 EFAULT arg points outside the allocated address space. 233 234 EINVAL arg does not contain a valid module name. 235 236 I_PEEK Allows a user to retrieve the information in the first 237 message on the stream head read queue without taking the 238 message off the queue. I_PEEK is analogous to getmsg(2) 239 except that it does not remove the message from the queue. 240 arg points to a strpeek structure, which contains the 241 following members: 242 243 struct strbuf ctlbuf; 244 struct strbuf databuf; 245 long flags; 246 247 The maxlen field in the ctlbuf and databuf strbuf structures 248 (see getmsg(2)) must be set to the number of bytes of 249 control information and/or data information, respectively, 250 to retrieve. flags may be set to RS_HIPRI or 0. If 251 RS_HIPRI is set, I_PEEK will look for a high priority 252 message on the stream head read queue. Otherwise, I_PEEK 253 will look for the first message on the stream head read 254 queue. 255 256 I_PEEK returns 1 if a message was retrieved, and returns 0 257 if no message was found on the stream head read queue. It 258 does not wait for a message to arrive. On return, ctlbuf 259 specifies information in the control buffer, databuf 260 specifies information in the data buffer, and flags contains 261 the value RS_HIPRI or 0. On failure, errno is set to the 262 following value: 263 264 EFAULT arg points, or the buffer area specified in ctlbuf 265 or databuf is, outside the allocated address space. 266 267 EBADMSG Queued message to be read is not valid for I_PEEK. 268 269 EINVAL Illegal value for flags. 270 271 ENOSR Unable to allocate buffers to perform the I_PEEK 272 due to insufficient STREAMS memory resources. 273 274 I_SRDOPT Sets the read mode (see read(2)) using the value of the 275 argument arg. Legal arg values are: 276 277 RNORM Byte-stream mode, the default. 278 279 RMSGD Message-discard mode. 280 281 RMSGN Message-nondiscard mode. 282 283 In addition, the stream head's treatment of control messages 284 may be changed by setting the following flags in arg: 285 286 RPROTNORM Reject read(2) with EBADMSG if a control message 287 is at the front of the stream head read queue. 288 289 RPROTDAT Deliver the control portion of a message as data 290 when a user issues read(2). This is the default 291 behavior. 292 293 RPROTDIS Discard the control portion of a message, 294 delivering any data portion, when a user issues a 295 read(2). 296 297 On failure, errno is set to the following value: 298 299 EINVAL arg is not one of the above legal values, or arg is 300 the bitwise inclusive OR of RMSGD and RMSGN. 301 302 I_GRDOPT Returns the current read mode setting in an int pointed to 303 by the argument arg. Read modes are described in read(2). 304 On failure, errno is set to the following value: 305 306 EFAULT arg points outside the allocated address space. 307 308 I_NREAD Counts the number of data bytes in data blocks in the first 309 message on the stream head read queue, and places this value 310 in the location pointed to by arg. The return value for the 311 command is the number of messages on the stream head read 312 queue. For example, if zero is returned in arg, but the 313 ioctl() return value is greater than zero, this indicates 314 that a zero-length message is next on the queue. On 315 failure, errno is set to the following value: 316 317 EFAULT arg points outside the allocated address space. 318 319 I_FDINSERT Creates a message from specified buffer(s), adds information 320 about another stream and sends the message downstream. The 321 message contains a control part and an optional data part. 322 The data and control parts to be sent are distinguished by 323 placement in separate buffers, as described below. 324 325 The arg argument points to a strfdinsert structure, which 326 contains the following members: 327 328 struct strbuf ctlbuf; 329 struct strbuf databuf; 330 t_uscalar_t flags; 331 int fildes; 332 int offset; 333 334 The len member in the ctlbuf strbuf structure (see 335 putmsg(2)) must be set to the size of a t_uscalar_t plus the 336 number of bytes of control information to be sent with the 337 message. The fildes member specifies the file descriptor of 338 the other stream, and the offset member, which must be 339 suitably aligned for use as a t_uscalar_t, specifies the 340 offset from the start of the control buffer where I_FDINSERT 341 will store a t_uscalar_t whose interpretation is specific to 342 the stream end. The len member in the databuf strbuf 343 structure must be set to the number of bytes of data 344 information to be sent with the message, or to 0 if no data 345 part is to be sent. 346 347 The flags member specifies the type of message to be 348 created. A normal message is created if flags is set to 0, 349 and a high-priority message is created if flags is set to 350 RS_HIPRI. For non-priority messages, I_FDINSERT will block 351 if the stream write queue is full due to internal flow 352 control conditions. For priority messages, I_FDINSERT does 353 not block on this condition. or non-priority messages, 354 I_FDINSERT does not block when the write queue is full and 355 O_NDELAY or O_NONBLOCK is set. Instead, it fails and sets 356 errno to EAGAIN. 357 358 I_FDINSERT also blocks, unless prevented by lack of internal 359 resources, waiting for the availability of message blocks in 360 the stream, regardless of priority or whether O_NDELAY or 361 O_NONBLOCK has been specified. No partial message is sent. 362 363 The ioctl() function with the I_FDINSERT command will fail 364 if: 365 366 EAGAIN A non-priority message is specified, the O_NDELAY or 367 O_NONBLOCK flag is set, and the stream write queue 368 is full due to internal flow control conditions. 369 370 ENOSR Buffers can not be allocated for the message that is 371 to be created. 372 373 EFAULT The arg argument points, or the buffer area 374 specified in ctlbuf or databuf is, outside the 375 allocated address space. 376 377 EINVAL One of the following: The fildes member of the 378 strfdinsert structure is not a valid, open stream 379 file descriptor; the size of a t_uscalar_t plus 380 offset is greater than the len member for the buffer 381 specified through ctlptr; the offset member does not 382 specify a properly-aligned location in the data 383 buffer; or an undefined value is stored in flags. 384 385 ENXIO Hangup received on the fildes argument of the 386 ioctl() call or the fildes member of the strfdinsert 387 structure. 388 389 ERANGE The len field for the buffer specified through 390 databuf does not fall within the range specified by 391 the maximum and minimum packet sizes of the topmost 392 stream module; or the len member for the buffer 393 specified through databuf is larger than the maximum 394 configured size of the data part of a message; or 395 the len member for the buffer specified through 396 ctlbuf is larger than the maximum configured size of 397 the control part of a message. 398 399 I_FDINSERT can also fail if an error message was received by 400 the stream head of the stream corresponding to the fildes 401 member of the strfdinsert structure. In this case, errno 402 will be set to the value in the message. 403 404 I_STR Constructs an internal STREAMS ioctl message from the data 405 pointed to by arg, and sends that message downstream. 406 407 This mechanism is provided to send user ioctl() requests to 408 downstream modules and drivers. It allows information to be 409 sent with the ioctl(), and will return to the user any 410 information sent upstream by the downstream recipient. 411 I_STR blocks until the system responds with either a 412 positive or negative acknowledgement message, or until the 413 request times out after some period of time. If the request 414 times out, it fails with errno set to ETIME. 415 416 To send requests downstream, arg must point to a strioctl 417 structure which contains the following members: 418 419 int ic_cmd; 420 int ic_timout; 421 int ic_len; 422 char *ic_dp; 423 424 ic_cmd is the internal ioctl() command intended for a 425 downstream module or driver and ic_timout is the number of 426 seconds (-1 = infinite, 0 = use default, >0 = as specified) 427 an I_STR request will wait for acknowledgement before timing 428 out. ic_len is the number of bytes in the data argument and 429 ic_dp is a pointer to the data argument. The ic_len field 430 has two uses: on input, it contains the length of the data 431 argument passed in, and on return from the command, it 432 contains the number of bytes being returned to the user (the 433 buffer pointed to by ic_dp should be large enough to contain 434 the maximum amount of data that any module or the driver in 435 the stream can return). 436 437 At most one I_STR can be active on a stream. Further I_STR 438 calls will block until the active I_STR completes via a 439 positive or negative acknowledgement, a timeout, or an error 440 condition at the stream head. By setting the ic_timout 441 field to 0, the user is requesting STREAMS to provide the 442 DEFAULT timeout. The default timeout is specific to the 443 STREAMS implementation and may vary depending on which 444 release of Solaris you are using. For Solaris 8 (and 445 earlier versions), the default timeout is fifteen seconds. 446 The O_NDELAY and O_NONBLOCK (see open(2)) flags have no 447 effect on this call. 448 449 The stream head will convert the information pointed to by 450 the strioctl structure to an internal ioctl() command 451 message and send it downstream. On failure, errno is set to 452 one of the following values: 453 454 ENOSR Unable to allocate buffers for the ioctl() message 455 due to insufficient STREAMS memory resources. 456 457 EFAULT Either arg points outside the allocated address 458 space, or the buffer area specified by ic_dp and 459 ic_len (separately for data sent and data returned) 460 is outside the allocated address space. 461 462 EINVAL ic_len is less than 0 or ic_len is larger than the 463 maximum configured size of the data part of a 464 message or ic_timout is less than -1. 465 466 ENXIO Hangup received on fildes. 467 468 ETIME A downstream ioctl() timed out before 469 acknowledgement was received. 470 471 An I_STR can also fail while waiting for an acknowledgement 472 if a message indicating an error or a hangup is received at 473 the stream head. In addition, an error code can be returned 474 in the positive or negative acknowledgement message, in the 475 event the ioctl command sent downstream fails. For these 476 cases, I_STR will fail with errno set to the value in the 477 message. 478 479 I_SWROPT Sets the write mode using the value of the argument arg. 480 Legal bit settings for arg are: 481 482 SNDZERO Send a zero-length message downstream when a write 483 of 0 bytes occurs. 484 485 To not send a zero-length message when a write of 0 bytes 486 occurs, this bit must not be set in arg. 487 488 On failure, errno may be set to the following value: 489 490 EINVAL arg is not the above legal value. 491 492 I_GWROPT Returns the current write mode setting, as described above, 493 in the int that is pointed to by the argument arg. 494 495 I_SENDFD Requests the stream associated with fildes to send a 496 message, containing a file pointer, to the stream head at 497 the other end of a stream pipe. The file pointer 498 corresponds to arg, which must be an open file descriptor. 499 500 I_SENDFD converts arg into the corresponding system file 501 pointer. It allocates a message block and inserts the file 502 pointer in the block. The user id and group id associated 503 with the sending process are also inserted. This message is 504 placed directly on the read queue (see Intro(3)) of the 505 stream head at the other end of the stream pipe to which it 506 is connected. On failure, errno is set to one of the 507 following values: 508 509 EAGAIN The sending stream is unable to allocate a message 510 block to contain the file pointer. 511 512 EAGAIN The read queue of the receiving stream head is full 513 and cannot accept the message sent by I_SENDFD. 514 515 EBADF arg is not a valid, open file descriptor. 516 517 EINVAL fildes is not connected to a stream pipe. 518 519 ENXIO Hangup received on fildes. 520 521 I_RECVFD Retrieves the file descriptor associated with the message 522 sent by an I_SENDFD ioctl() over a stream pipe. arg is a 523 pointer to a data buffer large enough to hold an strrecvfd 524 data structure containing the following members: 525 526 int fd; 527 uid_t uid; 528 gid_t gid; 529 530 fd is an integer file descriptor. uid and gid are the user 531 id and group id, respectively, of the sending stream. 532 533 If O_NDELAY and O_NONBLOCK are clear (see open(2)), I_RECVFD 534 will block until a message is present at the stream head. 535 If O_NDELAY or O_NONBLOCK is set, I_RECVFD will fail with 536 errno set to EAGAIN if no message is present at the stream 537 head. 538 539 If the message at the stream head is a message sent by an 540 I_SENDFD, a new user file descriptor is allocated for the 541 file pointer contained in the message. The new file 542 descriptor is placed in the fd field of the strrecvfd 543 structure. The structure is copied into the user data 544 buffer pointed to by arg. On failure, errno is set to one 545 of the following values: 546 547 EAGAIN A message is not present at the stream head read 548 queue, and the O_NDELAY or O_NONBLOCK flag is 549 set. 550 551 EBADMSG The message at the stream head read queue is not 552 a message containing a passed file descriptor. 553 554 EFAULT arg points outside the allocated address space. 555 556 EMFILE NOFILES file descriptors are currently open. 557 558 ENXIO Hangup received on fildes. 559 560 EOVERFLOW uid or gid is too large to be stored in the 561 structure pointed to by arg. 562 563 I_LIST Allows the user to list all the module names on the stream, 564 up to and including the topmost driver name. If arg is 565 NULL, the return value is the number of modules, including 566 the driver, that are on the stream pointed to by fildes. 567 This allows the user to allocate enough space for the module 568 names. If arg is non-null, it should point to an str_list 569 structure that has the following members: 570 571 int sl_nmods; 572 struct str_mlist *sl_modlist; 573 574 The str_mlist structure has the following member: 575 576 char l_name[FMNAMESZ+1]; 577 578 The sl_nmods member indicates the number of entries the 579 process has allocated in the array. Upon return, the 580 sl_modlist member of the str_list structure contains the 581 list of module names, and the number of entries that have 582 been filled into the sl_modlist array is found in the 583 sl_nmods member (the number includes the number of modules 584 including the driver). The return value from ioctl() is 0. 585 The entries are filled in starting at the top of the stream 586 and continuing downstream until either the end of the stream 587 is reached, or the number of requested modules (sl_nmods) is 588 satisfied. On failure, errno may be set to one of the 589 following values: 590 591 EINVAL The sl_nmods member is less than 1. 592 593 EAGAIN Unable to allocate buffers 594 595 I_ATMARK Allows the user to see if the current message on the stream 596 head read queue is "marked" by some module downstream. arg 597 determines how the checking is done when there may be 598 multiple marked messages on the stream head read queue. It 599 may take the following values: 600 601 ANYMARK Check if the message is marked. 602 603 LASTMARK Check if the message is the last one marked on the 604 queue. 605 606 The return value is 1 if the mark condition is satisfied and 607 0 otherwise. On failure, errno is set to the following 608 value: 609 610 EINVAL Invalid arg value. 611 612 I_CKBAND Check if the message of a given priority band exists on the 613 stream head read queue. This returns 1 if a message of a 614 given priority exists, 0 if not, or -1 on error. arg should 615 be an integer containing the value of the priority band in 616 question. On failure, errno is set to the following value: 617 618 EINVAL Invalid arg value. 619 620 I_GETBAND Returns the priority band of the first message on the stream 621 head read queue in the integer referenced by arg. On 622 failure, errno is set to the following value: 623 624 ENODATA No message on the stream head read queue. 625 626 I_CANPUT Check if a certain band is writable. arg is set to the 627 priority band in question. The return value is 0 if the 628 priority band arg is flow controlled, 1 if the band is 629 writable, or -1 on error. On failure, errno is set to the 630 following value: 631 632 EINVAL Invalid arg value. 633 634 I_SETCLTIME Allows the user to set the time the stream head will delay 635 when a stream is closing and there are data on the write 636 queues. Before closing each module and driver, the stream 637 head will delay for the specified amount of time to allow 638 the data to drain. Note, however, that the module or driver 639 may itself delay in its close routine; this delay is 640 independent of the stream head's delay and is not settable. 641 If, after the delay, data are still present, data will be 642 flushed. arg is a pointer to an integer containing the 643 number of milliseconds to delay, rounded up to the nearest 644 legal value on the system. The default is fifteen seconds. 645 On failure, errno is set to the following value: 646 647 EINVAL Invalid arg value. 648 649 I_GETCLTIME Returns the close time delay in the integer pointed by arg. 650 651 I_SERROPT Sets the error mode using the value of the argument arg. 652 653 Normally stream head errors are persistent; once they are 654 set due to an M_ERROR or M_HANGUP, the error condition will 655 remain until the stream is closed. This option can be used 656 to set the stream head into non-persistent error mode i.e. 657 once the error has been returned in response to a read(2), 658 getmsg(2), ioctl(2), write(2), or putmsg(2) call the error 659 condition will be cleared. The error mode can be controlled 660 independently for read and write side errors. Legal arg 661 values are either none or one of: 662 663 RERRNORM Persistent read errors, the default. 664 665 RERRNONPERSIST Non-persistent read errors. 666 667 OR'ed with either none or one of: 668 669 WERRNORM Persistent write errors, the default. 670 671 WERRNONPERSIST Non-persistent write errors. 672 673 When no value is specified e.g. for the read side error 674 behavior then the behavior for that side will be left 675 unchanged. 676 677 On failure, errno is set to the following value: 678 679 EINVAL arg is not one of the above legal values. 680 681 I_GERROPT Returns the current error mode setting in an int pointed to 682 by the argument arg. Error modes are described above for 683 I_SERROPT. On failure, errno is set to the following value: 684 685 EFAULT arg points outside the allocated address space. 686 687 The following four commands are used for connecting and disconnecting 688 multiplexed STREAMS configurations. 689 690 I_LINK Connects two streams, where fildes is the file descriptor of 691 the stream connected to the multiplexing driver, and arg is 692 the file descriptor of the stream connected to another driver. 693 The stream designated by arg gets connected below the 694 multiplexing driver. I_LINK requires the multiplexing driver 695 to send an acknowledgement message to the stream head 696 regarding the linking operation. This call returns a 697 multiplexor ID number (an identifier used to disconnect the 698 multiplexor, see I_UNLINK) on success, and -1 on failure. On 699 failure, errno is set to one of the following values: 700 701 ENXIO Hangup received on fildes. 702 703 ETIME Time out before acknowledgement message was received 704 at stream head. 705 706 EAGAIN Temporarily unable to allocate storage to perform the 707 I_LINK. 708 709 ENOSR Unable to allocate storage to perform the I_LINK due 710 to insufficient STREAMS memory resources. 711 712 EBADF arg is not a valid, open file descriptor. 713 714 EINVAL fildes stream does not support multiplexing. 715 716 EINVAL is not a stream, or is already linked under a 717 multiplexor. 718 719 EINVAL The specified link operation would cause a "cycle" in 720 the resulting configuration; that is, a driver would 721 be linked into the multiplexing configuration in more 722 than one place. 723 724 EINVAL fildes is the file descriptor of a pipe or FIFO. 725 726 EINVAL Either the upper or lower stream has a major number >= 727 the maximum major number on the system. 728 729 An I_LINK can also fail while waiting for the multiplexing 730 driver to acknowledge the link request, if a message 731 indicating an error or a hangup is received at the stream head 732 of fildes. In addition, an error code can be returned in the 733 positive or negative acknowledgement message. For these 734 cases, I_LINK will fail with errno set to the value in the 735 message. 736 737 I_UNLINK Disconnects the two streams specified by fildes and arg. 738 fildes is the file descriptor of the stream connected to the 739 multiplexing driver. arg is the multiplexor ID number that 740 was returned by the I_LINK. If arg is -1, then all streams 741 that were linked to fildes are disconnected. As in I_LINK, 742 this command requires the multiplexing driver to acknowledge 743 the unlink. On failure, errno is set to one of the following 744 values: 745 746 ENXIO Hangup received on fildes. 747 748 ETIME Time out before acknowledgement message was received 749 at stream head. 750 751 ENOSR Unable to allocate storage to perform the I_UNLINK due 752 to insufficient STREAMS memory resources. 753 754 EINVAL arg is an invalid multiplexor ID number or fildes is 755 not the stream on which the I_LINK that returned arg 756 was performed. 757 758 EINVAL fildes is the file descriptor of a pipe or FIFO. 759 760 An I_UNLINK can also fail while waiting for the multiplexing 761 driver to acknowledge the link request, if a message 762 indicating an error or a hangup is received at the stream head 763 of fildes. In addition, an error code can be returned in the 764 positive or negative acknowledgement message. For these 765 cases, I_UNLINK will fail with errno set to the value in the 766 message. 767 768 I_PLINK Connects two streams, where fildes is the file descriptor of 769 the stream connected to the multiplexing driver, and arg is 770 the file descriptor of the stream connected to another driver. 771 The stream designated by arg gets connected via a persistent 772 link below the multiplexing driver. I_PLINK requires the 773 multiplexing driver to send an acknowledgement message to the 774 stream head regarding the linking operation. This call 775 creates a persistent link that continues to exist even if the 776 file descriptor fildes associated with the upper stream to the 777 multiplexing driver is closed. This call returns a 778 multiplexor ID number (an identifier that may be used to 779 disconnect the multiplexor, see I_PUNLINK) on success, and -1 780 on failure. On failure, errno is set to one of the following 781 values: 782 783 ENXIO Hangup received on fildes. 784 785 ETIME Time out before acknowledgement message was received 786 at the stream head. 787 788 EAGAIN Unable to allocate STREAMS storage to perform the 789 I_PLINK. 790 791 EBADF arg is not a valid, open file descriptor. 792 793 EINVAL fildes does not support multiplexing. 794 795 EINVAL arg is not a stream or is already linked under a 796 multiplexor. 797 798 EINVAL The specified link operation would cause a "cycle" in 799 the resulting configuration; that is, if a driver 800 would be linked into the multiplexing configuration in 801 more than one place. 802 803 EINVAL fildes is the file descriptor of a pipe or FIFO. 804 805 An I_PLINK can also fail while waiting for the multiplexing 806 driver to acknowledge the link request, if a message 807 indicating an error on a hangup is received at the stream head 808 of fildes. In addition, an error code can be returned in the 809 positive or negative acknowledgement message. For these 810 cases, I_PLINK will fail with errno set to the value in the 811 message. 812 813 I_PUNLINK Disconnects the two streams specified by fildes and arg that 814 are connected with a persistent link. fildes is the file 815 descriptor of the stream connected to the multiplexing driver. 816 arg is the multiplexor ID number that was returned by I_PLINK 817 when a stream was linked below the multiplexing driver. If 818 arg is MUXID_ALL then all streams that are persistent links to 819 fildes are disconnected. As in I_PLINK, this command requires 820 the multiplexing driver to acknowledge the unlink. On 821 failure, errno is set to one of the following values: 822 823 ENXIO Hangup received on fildes. 824 825 ETIME Time out before acknowledgement message was received 826 at the stream head. 827 828 EAGAIN Unable to allocate buffers for the acknowledgement 829 message. 830 831 EINVAL Invalid multiplexor ID number. 832 833 EINVAL fildes is the file descriptor of a pipe or FIFO. 834 835 An I_PUNLINK can also fail while waiting for the multiplexing 836 driver to acknowledge the link request if a message indicating 837 an error or a hangup is received at the stream head of fildes. 838 In addition, an error code can be returned in the positive or 839 negative acknowledgement message. For these cases, I_PUNLINK 840 will fail with errno set to the value in the message. 841 842 RETURN VALUES 843 Unless specified otherwise above, the return value from ioctl(2) is 0 844 upon success and -1 upon failure, with errno set as indicated. 845 846 SEE ALSO 847 close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2), 848 read(2), write(2), Intro(3), signal(3C), signal.h(3HEAD) 849 850 STREAMS Programming Guide 851 852 illumos February 17, 2020 illumos