| blob | 2b7e45629b2b3a303809a7b9489f1769db594104 |
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>
17 \fBint\fR \fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcommand\fR, \fB\&... /*arg*/\fR);
18 .fi
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
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
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
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
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
109 .RE
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
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
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
149 .sp
150 .ne 2
151 .na
152 \fB\fBENOTSUP\fR\fR
153 .ad
154 .RS 11n
155 Removal is not supported.
156 .RE
158 .RE
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
179 .RE
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
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
210 .RE
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
229 .sp
230 .ne 2
231 .na
232 \fBFLUSHW\fR
233 .ad
234 .RS 11n
235 Flush write queues.
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fBFLUSHRW\fR
242 .ad
243 .RS 11n
244 Flush read and write queues.
245 .RE
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
277 .sp
278 .ne 2
279 .na
280 \fB\fBEINVAL\fR\fR
281 .ad
282 .RS 10n
283 Invalid \fIarg\fR value.
284 .RE
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
295 .RE
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
313 The \fBbi_flag\fR field may be one of \fBFLUSHR\fR, \fBFLUSHW\fR, or
314 \fBFLUSHRW\fR as described earlier.
315 .RE
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
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
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
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
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
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
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
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
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
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
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
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
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
469 .RE
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
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
500 .RE
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
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
530 .RE
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
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
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
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
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
603 .RE
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
622 .sp
623 .ne 2
624 .na
625 \fBRMSGD\fR
626 .ad
627 .RS 9n
628 Message-discard mode.
629 .RE
631 .sp
632 .ne 2
633 .na
634 \fBRMSGN\fR
635 .ad
636 .RS 9n
637 Message-nondiscard mode.
638 .RE
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
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
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
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
683 .RE
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
703 .RE
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
727 .RE
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
993 .RE
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
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
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
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
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
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
1068 .RE
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
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
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
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
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
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
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
1160 .RE
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
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
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
1209 .sp
1210 .ne 2
1211 .na
1212 \fB\fBEAGAIN\fR\fR
1213 .ad
1214 .RS 10n
1215 Unable to allocate buffers
1216 .RE
1218 .RE
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
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
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
1259 .RE
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
1281 .RE
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
1301 .RE
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
1322 .RE
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
1349 .RE
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
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
1385 .sp
1386 .ne 2
1387 .na
1388 \fB\fBRERRNONPERSIST\fR\fR
1389 .ad
1390 .RS 18n
1391 Non-persistent read errors.
1392 .RE
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
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
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
1426 .RE
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
1446 .RE
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
1773 .sp
1774 .ne 2
1775 .na
1776 \fB\fBEINVAL\fR\fR
1777 .ad
1778 .RS 10n
1779 Invalid multiplexor ID number.
1780 .RE
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
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
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