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