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