1streamio(7I) Ioctl Requests streamio(7I)
2
6 streamio - STREAMS ioctl commands
7
9 #include <sys/types.h>
10 #include <stropts.h>
11 #include <sys/conf.h>
12 int ioctl(int fildes, int command, ... /*arg*/);
14
17 STREAMS (see Intro(3)) ioctl commands are a subset of the ioctl(2) com‐
18 mands and perform a variety of control functions on streams.
19 The fildes argument is an open file descriptor that refers to a stream.
22 The command argument determines the control function to be performed as
23 described below. The arg argument represents additional information
24 that is needed by this command. The type of arg depends upon the com‐
25 mand, but it is generally an integer or a pointer to a command-specific
26 data structure. The command and arg arguments are interpreted by the
27 STREAM head. Certain combinations of these arguments may be passed to a
28 module or driver in the stream.
29 Since these STREAMS commands are ioctls, they are subject to the errors
32 described in ioctl(2). In addition to those errors, the call will fail
33 with errno set to EINVAL, without processing a control function, if the
34 STREAM referenced by fildes is linked below a multiplexor, or if com‐
35 mand is not a valid value for a stream.
36 Also, as described in ioctl(2), STREAMS modules and drivers can detect
39 errors. In this case, the module or driver sends an error message to
40 the STREAM head containing an error value. This causes subsequent calls
41 to fail with errno set to this value.
42
44 The following ioctl commands, with error values indicated, are applica‐
45 ble to all STREAMS files:
46 I_PUSH Pushes the module whose name is pointed to by arg onto
48 the top of the current stream, just below the STREAM
49 head. If the STREAM is a pipe, the module will be
50 inserted between the stream heads of both ends of the
51 pipe. It then calls the open routine of the newly-pushed
52 module. On failure, errno is set to one of the following
53 values:
54 EINVAL Invalid module name.
56 EFAULT arg points outside the allocated address
59 space.
60 ENXIO Open routine of new module failed.
63 ENXIO Hangup received on fildes.
66 ENOTSUP Pushing a module is not supported on this
69 stream.
70 I_POP Removes the module just below the STREAM head of the
74 STREAM pointed to by fildes. To remove a module from a
75 pipe requires that the module was pushed on the side it
76 is being removed from. arg should be 0 in an I_POP
77 request. On failure, errno is set to one of the follow‐
78 ing values:
79 EINVAL No module present in the stream.
81 ENXIO Hangup received on fildes.
84 EPERM Attempt to pop through an anchor by an
87 unprivileged process.
88 ENOTSUP Removal is not supported.
91 I_ANCHOR Positions the stream anchor to be at the stream's module
95 directly below the stream head. Once this has been done,
96 only a privileged process may pop modules below the
97 anchor on the stream. arg must be 0 in an I_ANCHOR
98 request. On failure, errno is set to the following
99 value:
100 EINVAL Request to put an anchor on a pipe.
102 I_LOOK Retrieves the name of the module just below the stream
106 head of the stream pointed to by fildes, and places it
107 in a null terminated character string pointed at by arg.
108 The buffer pointed to by arg should be at least
109 FMNAMESZ+1 bytes long. This requires the declaration
110 #include <sys/conf.h>. On failure, errno is set to one
111 of the following values:
112 EFAULT arg points outside the allocated address
114 space.
115 EINVAL No module present in stream.
118 I_FLUSH This request flushes all input and/or output queues,
122 depending on the value of arg. Legal arg values are:
123 FLUSHR Flush read queues.
125 FLUSHW Flush write queues.
128 FLUSHRW Flush read and write queues.
131 If a pipe or FIFO does not have any modules pushed, the
133 read queue of the stream head on either end is flushed
134 depending on the value of arg.
135 If FLUSHR is set and fildes is a pipe, the read queue
137 for that end of the pipe is flushed and the write queue
138 for the other end is flushed. If fildes is a FIFO, both
139 queues are flushed.
140 If FLUSHW is set and fildes is a pipe and the other end
142 of the pipe exists, the read queue for the other end of
143 the pipe is flushed and the write queue for this end is
144 flushed. If fildes is a FIFO, both queues of the FIFO
145 are flushed.
146 If FLUSHRW is set, all read queues are flushed, that is,
148 the read queue for the FIFO and the read queue on both
149 ends of the pipe are flushed.
150 Correct flush handling of a pipe or FIFO with modules
152 pushed is achieved via the pipemod module. This module
153 should be the first module pushed onto a pipe so that it
154 is at the midpoint of the pipe itself.
155 On failure, errno is set to one of the following values:
157 ENOSR Unable to allocate buffers for flush message
159 due to insufficient stream memory resources.
160 EINVAL Invalid arg value.
163 ENXIO Hangup received on fildes.
166 I_FLUSHBAND Flushes a particular band of messages. arg points to a
170 bandinfo structure that has the following members:
171 unsigned char bi_pri;
173 int bi_flag;
174 The bi_flag field may be one of FLUSHR, FLUSHW, or
176 FLUSHRW as described earlier.
177 I_SETSIG Informs the stream head that the user wishes the kernel
180 to issue the SIGPOLL signal (see signal(3C)) when a par‐
181 ticular event has occurred on the stream associated with
182 fildes. I_SETSIG supports an asynchronous processing
183 capability in streams. The value of arg is a bitmask
184 that specifies the events for which the user should be
185 signaled. It is the bitwise OR of any combination of the
186 following constants:
187 S_INPUT Any message other than an M_PCPROTO has
189 arrived on a stream head read queue. This
190 event is maintained for compatibility with
191 previous releases. This event is triggered
192 even if the message is of zero length.
193 S_RDNORM An ordinary (non-priority) message has
196 arrived on a stream head read queue. This
197 event is triggered even if the message is
198 of zero length.
199 S_RDBAND A priority band message (band > 0) has
202 arrived on a stream head read queue. This
203 event is triggered even if the message is
204 of zero length.
205 S_HIPRI A high priority message is present on the
208 stream head read queue. This event is trig‐
209 gered even if the message is of zero
210 length.
211 S_OUTPUT The write queue just below the stream head
214 is no longer full. This notifies the user
215 that there is room on the queue for sending
216 (or writing) data downstream.
217 S_WRNORM This event is the same as S_OUTPUT.
220 S_WRBAND A priority band greater than 0 of a queue
223 downstream exists and is writable. This
224 notifies the user that there is room on the
225 queue for sending (or writing) priority
226 data downstream.
227 S_MSG A STREAMS signal message that contains the
230 SIGPOLL signal has reached the front of the
231 stream head read queue.
232 S_ERROR An M_ERROR message has reached the stream
235 head.
236 S_HANGUP An M_HANGUP message has reached the stream
239 head.
240 S_BANDURG When used in conjunction with S_RDBAND,
243 SIGURG is generated instead of SIGPOLL when
244 a priority message reaches the front of the
245 stream head read queue.
246 A user process may choose to be signaled only of high
248 priority messages by setting the arg bitmask to the
249 value S_HIPRI.
250 Processes that wish to receive SIGPOLL signals must
252 explicitly register to receive them using I_SETSIG. If
253 several processes register to receive this signal for
254 the same event on the same stream, each process will be
255 signaled when the event occurs.
256 If the value of arg is zero, the calling process will be
258 unregistered and will not receive further SIGPOLL sig‐
259 nals. On failure, errno is set to one of the following
260 values:
261 EINVAL arg value is invalid or arg is zero and
263 process is not registered to receive the SIG‐
264 POLL signal.
265 EAGAIN Allocation of a data structure to store the
268 signal request failed.
269 I_GETSIG Returns the events for which the calling process is cur‐
273 rently registered to be sent a SIGPOLL signal. The
274 events are returned as a bitmask pointed to by arg,
275 where the events are those specified in the description
276 of I_SETSIG above. On failure, errno is set to one of
277 the following values:
278 EINVAL Process not registered to receive the SIGPOLL
280 signal.
281 EFAULT arg points outside the allocated address
284 space.
285 I_FIND Compares the names of all modules currently present in
289 the stream to the name pointed to by arg, and returns 1
290 if the named module is present in the stream. It returns
291 0 if the named module is not present. On failure, errno
292 is set to one of the following values:
293 EFAULT arg points outside the allocated address
295 space.
296 EINVAL arg does not contain a valid module name.
299 I_PEEK Allows a user to retrieve the information in the first
303 message on the stream head read queue without taking the
304 message off the queue. I_PEEK is analogous to getmsg(2)
305 except that it does not remove the message from the
306 queue. arg points to a strpeek structure, which contains
307 the following members:
308 struct strbuf ctlbuf;
310 struct strbuf databuf;
311 long flags;
312 The maxlen field in the ctlbuf and databuf strbuf struc‐
314 tures (see getmsg(2)) must be set to the number of bytes
315 of control information and/or data information, respec‐
316 tively, to retrieve. flags may be set to RS_HIPRI or 0.
317 If RS_HIPRI is set, I_PEEK will look for a high priority
318 message on the stream head read queue. Otherwise, I_PEEK
319 will look for the first message on the stream head read
320 queue.
321 I_PEEK returns 1 if a message was retrieved, and returns
323 0 if no message was found on the stream head read queue.
324 It does not wait for a message to arrive. On return,
325 ctlbuf specifies information in the control buffer,
326 databuf specifies information in the data buffer, and
327 flags contains the value RS_HIPRI or 0. On failure,
328 errno is set to the following value:
329 EFAULT arg points, or the buffer area specified in
331 ctlbuf or databuf is, outside the allocated
332 address space.
333 EBADMSG Queued message to be read is not valid for
336 I_PEEK.
337 EINVAL Illegal value for flags.
340 ENOSR Unable to allocate buffers to perform the
343 I_PEEK due to insufficient STREAMS memory
344 resources.
345 I_SRDOPT Sets the read mode (see read(2)) using the value of the
349 argument arg. Legal arg values are:
350 RNORM Byte-stream mode, the default.
352 RMSGD Message-discard mode.
355 RMSGN Message-nondiscard mode.
358 In addition, the stream head's treatment of control mes‐
360 sages may be changed by setting the following flags in
361 arg:
362 RPROTNORM Reject read() with EBADMSG if a control
364 message is at the front of the stream head
365 read queue.
366 RPROTDAT Deliver the control portion of a message as
369 data when a user issues read(). This is the
370 default behavior.
371 RPROTDIS Discard the control portion of a message,
374 delivering any data portion, when a user
375 issues a read().
376 On failure, errno is set to the following value:
378 EINVAL arg is not one of the above legal values, or
380 arg is the bitwise inclusive OR of RMSGD and
381 RMSGN.
382 I_GRDOPT Returns the current read mode setting in an int pointed
386 to by the argument arg. Read modes are described in
387 read(). On failure, errno is set to the following value:
388 EFAULT arg points outside the allocated address
390 space.
391 I_NREAD Counts the number of data bytes in data blocks in the
395 first message on the stream head read queue, and places
396 this value in the location pointed to by arg. The return
397 value for the command is the number of messages on the
398 stream head read queue. For example, if zero is returned
399 in arg, but the ioctl return value is greater than zero,
400 this indicates that a zero-length message is next on the
401 queue. On failure, errno is set to the following value:
402 EFAULT arg points outside the allocated address
404 space.
405 I_FDINSERT Creates a message from specified buffer(s), adds infor‐
409 mation about another stream and sends the message down‐
410 stream. The message contains a control part and an
411 optional data part. The data and control parts to be
412 sent are distinguished by placement in separate buffers,
413 as described below.
414 The arg argument points to a strfdinsert structure,
416 which contains the following members:
417 struct strbuf ctlbuf;
419 struct strbuf databuf;
420 t_uscalar_t flags;
421 int fildes;
422 int offset;
423 The len member in the ctlbuf strbuf structure (see
425 putmsg(2)) must be set to the size of a t_uscalar_t
426 plus the number of bytes of control information to be
427 sent with the message. The fildes member specifies the
428 file descriptor of the other stream, and the offset mem‐
429 ber, which must be suitably aligned for use as a
430 t_uscalar_t, specifies the offset from the start of the
431 control buffer where I_FDINSERT will store a
432 t_uscalar_t whose interpretation is specific to the
433 stream end. The len member in the databuf strbuf struc‐
434 ture must be set to the number of bytes of data informa‐
435 tion to be sent with the message, or to 0 if no data
436 part is to be sent.
437 The flags member specifies the type of message to be
439 created. A normal message is created if flags is set to
440 0, and a high-priority message is created if flags is
441 set to RS_HIPRI. For non-priority messages, I_FDINSERT
442 will block if the stream write queue is full due to
443 internal flow control conditions. For priority messages,
444 I_FDINSERT does not block on this condition. For non-
445 priority messages, I_FDINSERT does not block when the
446 write queue is full and O_NDELAY or O_NONBLOCK is set.
447 Instead, it fails and sets errno to EAGAIN.
448 I_FDINSERT also blocks, unless prevented by lack of
450 internal resources, waiting for the availability of mes‐
451 sage blocks in the stream, regardless of priority or
452 whether O_NDELAY or O_NONBLOCK has been specified. No
453 partial message is sent.
454 The ioctl() function with the I_FDINSERT command will
456 fail if:
457 EAGAIN A non-priority message is specified, the
459 O_NDELAY or O_NONBLOCK flag is set, and the
460 stream write queue is full due to internal
461 flow control conditions.
462 ENOSR Buffers can not be allocated for the message
465 that is to be created.
466 EFAULT The arg argument points, or the buffer area
469 specified in ctlbuf or databuf is, outside the
470 allocated address space.
471 EINVAL One of the following: The fildes member of the
474 strfdinsert structure is not a valid, open
475 stream file descriptor; the size of a
476 t_uscalar_t plus offset is greater than the
477 len member for the buffer specified through
478 ctlptr; the offset member does not specify a
479 properly-aligned location in the data buffer;
480 or an undefined value is stored in flags.
481 ENXIO Hangup received on the fildes argument of the
484 ioctl call or the fildes member of the
485 strfdinsert structure.
486 ERANGE The len field for the buffer specified through
489 databuf does not fall within the range speci‐
490 fied by the maximum and minimum packet sizes
491 of the topmost stream module; or the len mem‐
492 ber for the buffer specified through databuf
493 is larger than the maximum configured size of
494 the data part of a message; or the len member
495 for the buffer specified through ctlbuf is
496 larger than the maximum configured size of the
497 control part of a message.
498 I_FDINSERT can also fail if an error message was
500 received by the stream head of the stream corresponding
501 to the fildes member of the strfdinsert structure. In
502 this case, errno will be set to the value in the mes‐
503 sage.
504 I_STR Constructs an internal STREAMS ioctl message from the
507 data pointed to by arg, and sends that message down‐
508 stream.
509 This mechanism is provided to send user ioctl requests
511 to downstream modules and drivers. It allows information
512 to be sent with the ioctl, and will return to the user
513 any information sent upstream by the downstream recipi‐
514 ent. I_STR blocks until the system responds with either
515 a positive or negative acknowledgement message, or until
516 the request times out after some period of time. If the
517 request times out, it fails with errno set to ETIME.
518 To send requests downstream, arg must point to a stri‐
520 octl structure which contains the following members:
521 int ic_cmd;
523 int ic_timout;
524 int ic_len;
525 char *ic_dp;
526 ic_cmd is the internal ioctl command intended for a
528 downstream module or driver and ic_timout is the number
529 of seconds (-1 = infinite, 0 = use default, >0 = as
530 specified) an I_STR request will wait for acknowledge‐
531 ment before timing out. ic_len is the number of bytes in
532 the data argument and ic_dp is a pointer to the data
533 argument. The ic_len field has two uses: on input, it
534 contains the length of the data argument passed in, and
535 on return from the command, it contains the number of
536 bytes being returned to the user (the buffer pointed to
537 by ic_dp should be large enough to contain the maximum
538 amount of data that any module or the driver in the
539 stream can return).
540 At most one I_STR can be active on a stream. Further
542 I_STR calls will block until the active I_STR completes
543 via a positive or negative acknowlegment, a timeout,
544 or an error condition at the stream head. By setting
545 the ic_timout field to 0, the user is requesting
546 STREAMS to provide the DEFAULT timeout. The default
547 timeout is specific to the STREAMS implementation and
548 may vary depending on which release of Solaris you are
549 using. For Solaris 8 (and earlier versions), the default
550 timeout is fifteen seconds. The O_NDELAY and O_NONBLOCK
551 (see open(2)) flags have no effect on this call.
552 The stream head will convert the information pointed to
554 by the strioctl structure to an internal ioctl command
555 message and send it downstream. On failure, errno is set
556 to one of the following values:
557 ENOSR Unable to allocate buffers for the ioctl mes‐
559 sage due to insufficient STREAMS memory
560 resources.
561 EFAULT Either arg points outside the allocated
564 address space, or the buffer area specified by
565 ic_dp and ic_len (separately for data sent and
566 data returned) is outside the allocated
567 address space.
568 EINVAL ic_len is less than 0 or ic_len is larger than
571 the maximum configured size of the data part
572 of a message or ic_timout is less than -1.
573 ENXIO Hangup received on fildes.
576 ETIME A downstream ioctl timed out before acknowl‐
579 edgement was received.
580 An I_STR can also fail while waiting for an acknowledge‐
582 ment if a message indicating an error or a hangup is
583 received at the stream head. In addition, an error code
584 can be returned in the positive or negative acknowledge‐
585 ment message, in the event the ioctl command sent down‐
586 stream fails. For these cases, I_STR will fail with
587 errno set to the value in the message.
588 I_SWROPT Sets the write mode using the value of the argument arg.
591 Legal bit settings for arg are:
592 SNDZERO Send a zero-length message downstream when a
594 write of 0 bytes occurs.
595 To not send a zero-length message when a write of 0
597 bytes occurs, this bit must not be set in arg.
598 On failure, errno may be set to the following value:
600 EINVAL arg is not the above legal value.
602 I_GWROPT Returns the current write mode setting, as described
606 above, in the int that is pointed to by the argument
607 arg.
608 I_SENDFD Requests the stream associated with fildes to send a
611 message, containing a file pointer, to the stream head
612 at the other end of a stream pipe. The file pointer cor‐
613 responds to arg, which must be an open file descriptor.
614 I_SENDFD converts arg into the corresponding system file
616 pointer. It allocates a message block and inserts the
617 file pointer in the block. The user id and group id
618 associated with the sending process are also inserted.
619 This message is placed directly on the read queue (see
620 Intro(3)) of the stream head at the other end of the
621 stream pipe to which it is connected. On failure, errno
622 is set to one of the following values:
623 EAGAIN The sending stream is unable to allocate a
625 message block to contain the file pointer.
626 EAGAIN The read queue of the receiving stream head is
629 full and cannot accept the message sent by
630 I_SENDFD.
631 EBADF arg is not a valid, open file descriptor.
634 EINVAL fildes is not connected to a stream pipe.
637 ENXIO Hangup received on fildes.
640 I_RECVFD Retrieves the file descriptor associated with the mes‐
644 sage sent by an I_SENDFD ioctl over a stream pipe. arg
645 is a pointer to a data buffer large enough to hold an
646 strrecvfd data structure containing the following mem‐
647 bers:
648 int fd;
650 uid_t uid;
651 gid_t gid;
652 fd is an integer file descriptor. uid and gid are the
654 user id and group id, respectively, of the sending
655 stream.
656 If O_NDELAY and O_NONBLOCK are clear (see open(2)),
658 I_RECVFD will block until a message is present at the
659 stream head. If O_NDELAY or O_NONBLOCK is set, I_RECVFD
660 will fail with errno set to EAGAIN if no message is
661 present at the stream head.
662 If the message at the stream head is a message sent by
664 an I_SENDFD, a new user file descriptor is allocated for
665 the file pointer contained in the message. The new file
666 descriptor is placed in the fd field of the strrecvfd
667 structure. The structure is copied into the user data
668 buffer pointed to by arg. On failure, errno is set to
669 one of the following values:
670 EAGAIN A message is not present at the stream head
672 read queue, and the O_NDELAY or O_NONBLOCK
673 flag is set.
674 EBADMSG The message at the stream head read queue
677 is not a message containing a passed file
678 descriptor.
679 EFAULT arg points outside the allocated address
682 space.
683 EMFILE NOFILES file descriptors are currently
686 open.
687 ENXIO Hangup received on fildes.
690 EOVERFLOW uid or gid is too large to be stored in the
693 structure pointed to by arg.
694 I_LIST Allows the user to list all the module names on the
698 stream, up to and including the topmost driver name. If
699 arg is NULL, the return value is the number of modules,
700 including the driver, that are on the stream pointed to
701 by fildes. This allows the user to allocate enough space
702 for the module names. If arg is non-null, it should
703 point to an str_list structure that has the following
704 members:
705 int sl_nmods;
707 struct str_mlist *sl_modlist;
708 The str_mlist structure has the following member:
710 char l_name[FMNAMESZ+1];
712 The sl_nmods member indicates the number of entries the
714 process has allocated in the array. Upon return, the
715 sl_modlist member of the str_list structure contains the
716 list of module names, and the number of entries that
717 have been filled into the sl_modlist array is found in
718 the sl_nmods member (the number includes the number of
719 modules including the driver). The return value from
720 ioctl() is 0. The entries are filled in starting at the
721 top of the stream and continuing downstream until either
722 the end of the stream is reached, or the number of
723 requested modules (sl_nmods) is satisfied. On failure,
724 errno may be set to one of the following values:
725 EINVAL The sl_nmods member is less than 1.
727 EAGAIN Unable to allocate buffers
730 I_ATMARK Allows the user to see if the current message on the
734 stream head read queue is ``marked'' by some module
735 downstream. arg determines how the checking is done when
736 there may be multiple marked messages on the stream head
737 read queue. It may take the following values:
738 ANYMARK Check if the message is marked.
740 LASTMARK Check if the message is the last one marked
743 on the queue.
744 The return value is 1 if the mark condition is satisfied
746 and 0 otherwise. On failure, errno is set to the follow‐
747 ing value:
748 EINVAL Invalid arg value.
750 I_CKBAND Check if the message of a given priority band exists on
754 the stream head read queue. This returns 1 if a message
755 of a given priority exists, 0 if not, or −1 on error.
756 arg should be an integer containing the value of the
757 priority band in question. On failure, errno is set to
758 the following value:
759 EINVAL Invalid arg value.
761 I_GETBAND Returns the priority band of the first message on the
765 stream head read queue in the integer referenced by arg.
766 On failure, errno is set to the following value:
767 ENODATA No message on the stream head read queue.
769 I_CANPUT Check if a certain band is writable. arg is set to the
773 priority band in question. The return value is 0 if the
774 priority band arg is flow controlled, 1 if the band is
775 writable, or −1 on error. On failure, errno is set to
776 the following value:
777 EINVAL Invalid arg value.
779 I_SETCLTIME Allows the user to set the time the stream head will
783 delay when a stream is closing and there are data on the
784 write queues. Before closing each module and driver,
785 the stream head will delay for the specified amount of
786 time to allow the data to drain. Note, however, that the
787 module or driver may itself delay in its close routine;
788 this delay is independent of the stream head's delay and
789 is not settable. If, after the delay, data are still
790 present, data will be flushed. arg is a pointer to an
791 integer containing the number of milliseconds to delay,
792 rounded up to the nearest legal value on the system.
793 The default is fifteen seconds. On failure, errno is set
794 to the following value:
795 EINVAL Invalid arg value.
797 I_GETCLTIME Returns the close time delay in the integer pointed by
801 arg.
802 I_SERROPT Sets the error mode using the value of the argument arg.
805 Normally stream head errors are persistent; once they
807 are set due to an M_ERROR or M_HANGUP, the error condi‐
808 tion will remain until the stream is closed. This option
809 can be used to set the stream head into non-persistent
810 error mode i.e. once the error has been returned in
811 response to a read(2), getmsg(2), ioctl(2), write(2), or
812 putmsg(2) call the error condition will be cleared. The
813 error mode can be controlled independently for read and
814 write side errors. Legal arg values are either none or
815 one of:
816 RERRNORM Persistent read errors, the default.
818 RERRNONPERSIST Non-persistent read errors.
821 OR'ed with either none or one of:
823 WERRNORM Persistent write errors, the default.
825 WERRNONPERSIST Non-persistent write errors.
828 When no value is specified e.g. for
830 the read side error behavior then the
831 behavior for that side will be left
832 unchanged.
833 On failure, errno is set to the following value:
835 EINVAL arg is not one of the above legal values.
837 I_GERROPT Returns the current error mode setting in an int pointed
841 to by the argument arg. Error modes are described above
842 for I_SERROPT. On failure,errno is set to the following
843 value:
844 EFAULT arg points outside the allocated address
846 space.
847 The following four commands are used for connecting and disconnecting
852 multiplexed STREAMS configurations.
853 I_LINK Connects two streams, where fildes is the file descriptor
855 of the stream connected to the multiplexing driver, and
856 arg is the file descriptor of the stream connected to
857 another driver. The stream designated by arg gets con‐
858 nected below the multiplexing driver. I_LINK requires the
859 multiplexing driver to send an acknowledgement message to
860 the stream head regarding the linking operation. This call
861 returns a multiplexor ID number (an identifier used to
862 disconnect the multiplexor, see I_UNLINK) on success, and
863 -1 on failure. On failure, errno is set to one of the fol‐
864 lowing values:
865 ENXIO Hangup received on fildes.
867 ETIME Time out before acknowledgement message was
870 received at stream head.
871 EAGAIN Temporarily unable to allocate storage to per‐
874 form the I_LINK.
875 ENOSR Unable to allocate storage to perform the I_LINK
878 due to insufficient STREAMS memory resources.
879 EBADF arg is not a valid, open file descriptor.
882 EINVAL fildes stream does not support multiplexing.
885 EINVAL arg is not a stream, or is already linked under
888 a multiplexor.
889 EINVAL The specified link operation would cause a
892 ``cycle'' in the resulting configuration; that
893 is, a driver would be linked into the multiplex‐
894 ing configuration in more than one place.
895 EINVAL fildes is the file descriptor of a pipe or FIFO.
898 EINVAL Either the upper or lower stream has a major
901 number >= the maximum major number on the sys‐
902 tem.
903 An I_LINK can also fail while waiting for the multiplexing
905 driver to acknowledge the link request, if a message indi‐
906 cating an error or a hangup is received at the stream head
907 of fildes. In addition, an error code can be returned in
908 the positive or negative acknowledgement message. For
909 these cases, I_LINK will fail with errno set to the value
910 in the message.
911 I_UNLINK Disconnects the two streams specified by fildes and arg.
914 fildes is the file descriptor of the stream connected to
915 the multiplexing driver. arg is the multiplexor ID number
916 that was returned by the I_LINK. If arg is -1, then all
917 streams that were linked to fildes are disconnected. As
918 in I_LINK, this command requires the multiplexing driver
919 to acknowledge the unlink. On failure, errno is set to one
920 of the following values:
921 ENXIO Hangup received on fildes.
923 ETIME Time out before acknowledgement message was
926 received at stream head.
927 ENOSR Unable to allocate storage to perform the
930 I_UNLINK due to insufficient STREAMS memory
931 resources.
932 EINVAL arg is an invalid multiplexor ID number or
935 fildes is not the stream on which the I_LINK
936 that returned arg was performed.
937 EINVAL fildes is the file descriptor of a pipe or FIFO.
940 An I_UNLINK can also fail while waiting for the multi‐
942 plexing driver to acknowledge the link request, if a mes‐
943 sage indicating an error or a hangup is received at the
944 stream head of fildes. In addition, an error code can be
945 returned in the positive or negative acknowledgement mes‐
946 sage. For these cases, I_UNLINK will fail with errno set
947 to the value in the message.
948 I_PLINK Connects two streams, where fildes is the file descriptor
951 of the stream connected to the multiplexing driver, and
952 arg is the file descriptor of the stream connected to
953 another driver. The stream designated by arg gets con‐
954 nected via a persistent link below the multiplexing
955 driver. I_PLINK requires the multiplexing driver to send
956 an acknowledgement message to the stream head regarding
957 the linking operation. This call creates a persistent link
958 that continues to exist even if the file descriptor fildes
959 associated with the upper stream to the multiplexing
960 driver is closed. This call returns a multiplexor ID num‐
961 ber (an identifier that may be used to disconnect the mul‐
962 tiplexor, see I_PUNLINK) on success, and -1 on failure. On
963 failure, errno is set to one of the following values:
964 ENXIO Hangup received on fildes.
966 ETIME Time out before acknowledgement message was
969 received at the stream head.
970 EAGAIN Unable to allocate STREAMS storage to perform
973 the I_PLINK.
974 EBADF arg is not a valid, open file descriptor.
977 EINVAL fildes does not support multiplexing.
980 EINVAL arg is not a stream or is already linked under a
983 multiplexor.
984 EINVAL The specified link operation would cause a
987 ``cycle'' in the resulting configuration; that
988 is, if a driver would be linked into the multi‐
989 plexing configuration in more than one place.
990 EINVAL fildes is the file descriptor of a pipe or FIFO.
993 An I_PLINK can also fail while waiting for the multiplex‐
995 ing driver to acknowledge the link request, if a message
996 indicating an error on a hangup is received at the stream
997 head of fildes. In addition, an error code can be returned
998 in the positive or negative acknowledgement message. For
999 these cases, I_PLINK will fail with errno set to the value
1000 in the message.
1001 I_PUNLINK Disconnects the two streams specified by fildes and arg
1004 that are connected with a persistent link. fildes is the
1005 file descriptor of the stream connected to the multiplex‐
1006 ing driver. arg is the multiplexor ID number that was
1007 returned by I_PLINK when a stream was linked below the
1008 multiplexing driver. If arg is MUXID_ALL then all streams
1009 that are persistent links to fildes are disconnected. As
1010 in I_PLINK, this command requires the multiplexing driver
1011 to acknowledge the unlink. On failure, errno is set to one
1012 of the following values:
1013 ENXIO Hangup received on fildes.
1015 ETIME Time out before acknowledgement message was
1018 received at the stream head.
1019 EAGAIN Unable to allocate buffers for the acknowledge‐
1022 ment message.
1023 EINVAL Invalid multiplexor ID number.
1026 EINVAL fildes is the file descriptor of a pipe or FIFO.
1029 An I_PUNLINK can also fail while waiting for the multi‐
1031 plexing driver to acknowledge the link request if a mes‐
1032 sage indicating an error or a hangup is received at the
1033 stream head of fildes. In addition, an error code can be
1034 returned in the positive or negative acknowledgement mes‐
1035 sage. For these cases, I_PUNLINK will fail with errno set
1036 to the value in the message.
1037
1040 Unless specified otherwise above, the return value from ioctl() is 0
1041 upon success and −1 upon failure, with errno set as indicated.
1042
1044 Intro(3), close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2),
1045 putmsg(2), read(2), write(2), signal(3C), signal.h(3HEAD),
1046 STREAMS Programming Guide
1049SunOS 5.11 8 Apr 2009 streamio(7I)