| blob | 3449c340aa64aff44faf574152a0acbaca71113e |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
44 .\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .TH STROPTS.H 3HEAD "Sep 10, 2004"
47 .SH NAME
48 stropts.h, stropts \- STREAMS interface (STREAMS)
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <\fBstropts.h\fR>
53 .fi
55 .SH DESCRIPTION
56 .sp
57 .LP
58 The <\fBstropts.h\fR> header defines the \fBbandinfo\fR structure, which
59 includes the following members:
60 .sp
61 .in +2
62 .nf
63 unsigned char bi_pri /* priority band */
64 int bi_flag /* flushing type */
65 .fi
66 .in -2
68 .sp
69 .LP
70 The <\fBstropts.h\fR> header defines the \fBstrpeek\fR structure that includes
71 the following members:
72 .sp
73 .in +2
74 .nf
75 struct strbuf ctlbuf /* control portion of the message */
76 struct strbuf databuf /* data portion of the message */
77 t_uscalar_t flags /* RS_HIPRI or 0 */
78 .fi
79 .in -2
81 .sp
82 .LP
83 The <\fBstropts.h\fR> header defines the \fBstrbuf\fR structure that includes
84 the following members:
85 .sp
86 .in +2
87 .nf
88 int maxlen /* maximum buffer length */
89 int len /* length of data */
90 char *buf /* pointer to buffer */
91 .fi
92 .in -2
94 .sp
95 .LP
96 The <\fBstropts.h\fR> header defines the \fBstrfdinsert\fR structure that
97 includes the following members:
98 .sp
99 .in +2
100 .nf
101 struct strbuf ctlbuf /* control portion of the message */
102 struct strbuf databuf /* data portion of the message */
103 t_uscalar_t flags /* RS_HIPRI or 0 */
104 int fildes /* file descriptor of the other stream */
105 int offset /* relative location of the stored value */
106 .fi
107 .in -2
109 .sp
110 .LP
111 The <\fBstropts.h\fR> header defines the \fBstrioctl\fR structure that includes
112 the following members:
113 .sp
114 .in +2
115 .nf
116 int ic_cmd /* ioctl() command */
117 int ic_timout /* timeout for response */
118 int ic_len /* length of data */
119 char *ic_dp /* pointer to buffer */
120 .fi
121 .in -2
123 .sp
124 .LP
125 The <\fBstropts.h\fR> header defines the \fBstrrecvfd\fR structure that
126 includes the following members:
127 .sp
128 .in +2
129 .nf
130 int fda /* received file descriptor */
131 uid_t uid /* UID of sender */
132 gid_t gid /* GID of sender */
133 .fi
134 .in -2
136 .sp
137 .LP
138 The \fBuid_t\fR and \fBgid_t\fR types are defined through \fBtypedef\fR as
139 described in <\fBsys/types.h\fR>. See \fBtypes.h\fR(3HEAD).
140 .sp
141 .LP
142 The <\fBstropts.h\fR> header defines the \fBt_scalar_t\fR and \fBt_uscalar_t\fR
143 types, respectively, as signed and unsigned opaque types of equal length of at
144 least 32 bits.
145 .sp
146 .LP
147 The <\fBstropts.h\fR> header defines the \fBstr_list\fR structure that includes
148 the following members:
149 .sp
150 .in +2
151 .nf
152 int sl_nmods /* number of STREAMS module names */
153 struct str_mlist *sl_modlist /* STREAMS module names */
154 .fi
155 .in -2
157 .sp
158 .LP
159 The <\fBstropts.h\fR> header defines the \fBstr_mlist\fR structure that
160 includes the following member:
161 .sp
162 .ne 2
163 .na
164 \fB\fBchar l_name[FMNAMESZ+1]\fR\fR
165 .ad
166 .RS 27n
167 a STREAMS module name
168 .RE
170 .sp
171 .LP
172 The following macros are defined for use as the request argument to
173 \fBioctl()\fR:
174 .sp
175 .ne 2
176 .na
177 \fB\fBI_PUSH\fR\fR
178 .ad
179 .RS 15n
180 Push a STREAMS module.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBI_POP\fR\fR
187 .ad
188 .RS 15n
189 Pop a STREAMS module.
190 .RE
192 .sp
193 .ne 2
194 .na
195 \fB\fBI_LOOK\fR\fR
196 .ad
197 .RS 15n
198 Get the top module name.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBI_FLUSH\fR\fR
205 .ad
206 .RS 15n
207 Flush a stream.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBI_FLUSHBAND\fR\fR
214 .ad
215 .RS 15n
216 Flush one band of a stream.
217 .RE
219 .sp
220 .ne 2
221 .na
222 \fB\fBI_SETSIG\fR\fR
223 .ad
224 .RS 15n
225 Ask for notification signals.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBI_GETSIG\fR\fR
232 .ad
233 .RS 15n
234 Retrieve current notification signals.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fBI_FIND\fR\fR
241 .ad
242 .RS 15n
243 Look for a STREAMS module.
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fB\fBI_PEEK\fR\fR
250 .ad
251 .RS 15n
252 Peek at the top message on a stream.
253 .RE
255 .sp
256 .ne 2
257 .na
258 \fB\fBI_SRDOPT\fR\fR
259 .ad
260 .RS 15n
261 Set the read mode.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fBI_GRDOPT\fR\fR
268 .ad
269 .RS 15n
270 Get the read mode.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fBI_NREAD\fR\fR
277 .ad
278 .RS 15n
279 Size the top message.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBI_FDINSERT\fR\fR
286 .ad
287 .RS 15n
288 Send implementation-defined information about another stream.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBI_STR\fR\fR
295 .ad
296 .RS 15n
297 Send a STREAMS \fBioctl()\fR.
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fB\fBI_SWROPT\fR\fR
304 .ad
305 .RS 15n
306 Set the write mode.
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fBI_GWROPT\fR\fR
313 .ad
314 .RS 15n
315 Get the write mode.
316 .RE
318 .sp
319 .ne 2
320 .na
321 \fB\fBI_SENDFD\fR\fR
322 .ad
323 .RS 15n
324 Pass a file descriptor through a STREAMS pipe.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fBI_RECVFD\fR\fR
331 .ad
332 .RS 15n
333 Get a file descriptor sent via I_SENDFD.
334 .RE
336 .sp
337 .ne 2
338 .na
339 \fB\fBI_LIST\fR\fR
340 .ad
341 .RS 15n
342 Get all the module names on a stream.
343 .RE
345 .sp
346 .ne 2
347 .na
348 \fB\fBI_ATMARK\fR\fR
349 .ad
350 .RS 15n
351 Is the top message ``marked''?
352 .RE
354 .sp
355 .ne 2
356 .na
357 \fB\fBI_CKBAND\fR\fR
358 .ad
359 .RS 15n
360 See if any messages exist in a band.
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fB\fBI_GETBAND\fR\fR
367 .ad
368 .RS 15n
369 Get the band of the top message on a stream.
370 .RE
372 .sp
373 .ne 2
374 .na
375 \fB\fBI_CANPUT\fR\fR
376 .ad
377 .RS 15n
378 Is a band writable?
379 .RE
381 .sp
382 .ne 2
383 .na
384 \fB\fBI_SETCLTIME\fR\fR
385 .ad
386 .RS 15n
387 Set close time delay.
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fB\fBI_GETCLTIME\fR\fR
394 .ad
395 .RS 15n
396 Get close time delay.
397 .RE
399 .sp
400 .ne 2
401 .na
402 \fB\fBI_LINK\fR\fR
403 .ad
404 .RS 15n
405 Connect two streams.
406 .RE
408 .sp
409 .ne 2
410 .na
411 \fB\fBI_UNLINK\fR\fR
412 .ad
413 .RS 15n
414 Disconnect two streams.
415 .RE
417 .sp
418 .ne 2
419 .na
420 \fB\fBI_PLINK\fR\fR
421 .ad
422 .RS 15n
423 Persistently connect two streams.
424 .RE
426 .sp
427 .ne 2
428 .na
429 \fB\fBI_PUNLINK\fR\fR
430 .ad
431 .RS 15n
432 Dismantle a persistent STREAMS link.
433 .RE
435 .sp
436 .LP
437 The following macro is defined for use with \fBI_LOOK\fR:
438 .sp
439 .ne 2
440 .na
441 \fB\fBFMNAMESZ\fR\fR
442 .ad
443 .RS 12n
444 minimum size in bytes of the buffer referred to by the \fBarg\fR argument
445 .RE
447 .sp
448 .LP
449 The following macros are defined for use with \fBI_FLUSH\fR:
450 .sp
451 .ne 2
452 .na
453 \fB\fBFLUSHR\fR\fR
454 .ad
455 .RS 11n
456 flush read queues
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fBFLUSHW\fR\fR
463 .ad
464 .RS 11n
465 flush write queues
466 .RE
468 .sp
469 .ne 2
470 .na
471 \fB\fBFLUSHRW\fR\fR
472 .ad
473 .RS 11n
474 flush read and write queues
475 .RE
477 .sp
478 .LP
479 The following macros are defined for use with \fBI_SETSIG\fR:
480 .sp
481 .ne 2
482 .na
483 \fB\fBS_RDNORM\fR\fR
484 .ad
485 .RS 13n
486 A normal (priority band set to 0) message has arrived at the head of a stream
487 head read queue.
488 .RE
490 .sp
491 .ne 2
492 .na
493 \fB\fBS_RDBAND\fR\fR
494 .ad
495 .RS 13n
496 A message with a non-zero priority band has arrived at the head of a stream
497 head read queue.
498 .RE
500 .sp
501 .ne 2
502 .na
503 \fB\fBS_INPUT\fR\fR
504 .ad
505 .RS 13n
506 A message, other than a high-priority message, has arrived at the head of a
507 stream head read queue.
508 .RE
510 .sp
511 .ne 2
512 .na
513 \fB\fBS_HIPRI\fR\fR
514 .ad
515 .RS 13n
516 A high-priority message is present on a stream head read queue.
517 .RE
519 .sp
520 .ne 2
521 .na
522 \fB\fBS_OUTPUT\fR\fR
523 .ad
524 .RS 13n
525 The write queue for normal data (priority band 0) just below the stream head is
526 no longer full. This notifies the process that there is room on the queue for
527 sending (or writing) normal data downstream.
528 .RE
530 .sp
531 .ne 2
532 .na
533 \fB\fBS_WRNORM\fR\fR
534 .ad
535 .RS 13n
536 Equivalent to \fBS_OUTPUT\fR.
537 .RE
539 .sp
540 .ne 2
541 .na
542 \fB\fBS_WRBAND\fR\fR
543 .ad
544 .RS 13n
545 The write queue for a non-zero priority band just below the stream head is no
546 longer full.
547 .RE
549 .sp
550 .ne 2
551 .na
552 \fB\fBS_MSG\fR\fR
553 .ad
554 .RS 13n
555 A STREAMS signal message that contains the \fBSIGPOLL\fR signal reaches the
556 front of the stream head read queue.
557 .RE
559 .sp
560 .ne 2
561 .na
562 \fB\fBS_ERROR\fR\fR
563 .ad
564 .RS 13n
565 Notification of an error condition reaches the stream head.
566 .RE
568 .sp
569 .ne 2
570 .na
571 \fB\fBS_HANGUP\fR\fR
572 .ad
573 .RS 13n
574 Notification of a hangup reaches the stream head.
575 .RE
577 .sp
578 .ne 2
579 .na
580 \fB\fBS_BANDURG\fR\fR
581 .ad
582 .RS 13n
583 When used in conjunction with \fBS_RDBAND\fR, \fBSIGURG\fR is generated instead
584 of \fBSIGPOLL\fR when a priority message reaches the front of the stream head
585 read queue.
586 .RE
588 .sp
589 .LP
590 The following macro is defined for use with \fBI_PEEK\fR:
591 .sp
592 .ne 2
593 .na
594 \fB\fBRS_HIPRI\fR\fR
595 .ad
596 .RS 12n
597 Only look for high-priority messages.
598 .RE
600 .sp
601 .LP
602 The following macros are defined for use with \fBI_SRDOPT\fR:
603 .sp
604 .ne 2
605 .na
606 \fB\fBRNORM\fR\fR
607 .ad
608 .RS 13n
609 Byte-stream mode, the default.
610 .RE
612 .sp
613 .ne 2
614 .na
615 \fB\fBRMSGD\fR\fR
616 .ad
617 .RS 13n
618 Message-discard mode.
619 .RE
621 .sp
622 .ne 2
623 .na
624 \fB\fBRMSGN\fR\fR
625 .ad
626 .RS 13n
627 Message-non-discard mode.
628 .RE
630 .sp
631 .ne 2
632 .na
633 \fB\fBRPROTNORM\fR\fR
634 .ad
635 .RS 13n
636 Fail \fBread()\fR with \fB[EBADMSG]\fR if a message containing a control part
637 is at the front of the stream head read queue.
638 .RE
640 .sp
641 .ne 2
642 .na
643 \fB\fBRPROTDAT\fR\fR
644 .ad
645 .RS 13n
646 Deliver the control part of a message as data when a process issues a
647 \fBread()\fR
648 .RE
650 .sp
651 .ne 2
652 .na
653 \fB\fBRPROTDIS\fR\fR
654 .ad
655 .RS 13n
656 Discard the control part of a message, delivering any data part, when a process
657 issues a \fBread()\fR
658 .RE
660 .sp
661 .LP
662 The following macro is defined for use with \fBI_SWOPT\fR:
663 .sp
664 .ne 2
665 .na
666 \fB\fBSNDZERO\fR\fR
667 .ad
668 .RS 11n
669 Send a zero-length message downstream when a \fBwrite()\fR of 0 bytes occurs.
670 .RE
672 .sp
673 .LP
674 The following macros are defined for use with \fBI_ATMARK\fR:
675 .sp
676 .ne 2
677 .na
678 \fB\fBANYMARK\fR\fR
679 .ad
680 .RS 12n
681 Check if the message is marked.
682 .RE
684 .sp
685 .ne 2
686 .na
687 \fB\fBLASTMARK\fR\fR
688 .ad
689 .RS 12n
690 Check if the message is the last one marked on the queue.
691 .RE
693 .sp
694 .LP
695 The following macro is defined for use with \fBI_UNLINK\fR:
696 .sp
697 .ne 2
698 .na
699 \fB\fBMUXID_ALL\fR\fR
700 .ad
701 .RS 13n
702 Unlink all stream linked to the stream associated with \fBfildes\fR.
703 .RE
705 .sp
706 .LP
707 The following macros are defined for \fBgetmsg()\fR, \fBgetpmsg()\fR,
708 \fBputmsg()\fR, and \fBputpmsg()\fR:
709 .sp
710 .ne 2
711 .na
712 \fB\fBMSG_ANY\fR\fR
713 .ad
714 .RS 13n
715 Receive any message.
716 .RE
718 .sp
719 .ne 2
720 .na
721 \fB\fBMSG_BAND\fR\fR
722 .ad
723 .RS 13n
724 Receive message from specified band.
725 .RE
727 .sp
728 .ne 2
729 .na
730 \fB\fBMSG_HIPRI\fR\fR
731 .ad
732 .RS 13n
733 Send/receive high-priority message.
734 .RE
736 .sp
737 .ne 2
738 .na
739 \fB\fBMORECTL\fR\fR
740 .ad
741 .RS 13n
742 More control information is left in message.
743 .RE
745 .sp
746 .ne 2
747 .na
748 \fB\fBMOREDATA\fR\fR
749 .ad
750 .RS 13n
751 More data is left in message.
752 .RE
754 .sp
755 .LP
756 The <\fBstropts.h\fR> header can make visible all of the symbols from
757 <\fBunistd.h\fR>.
758 .SH ATTRIBUTES
759 .sp
760 .LP
761 See \fBattributes\fR(5) for descriptions of the following attributes:
762 .sp
764 .sp
765 .TS
766 box;
767 c | c
768 l | l .
769 ATTRIBUTE TYPE ATTRIBUTE VALUE
770 _
771 Interface Stability Standard
772 .TE
774 .SH SEE ALSO
775 .sp
776 .LP
777 \fBclose\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2), \fBioctl\fR(2), \fBopen\fR(2),
778 \fBpipe\fR(2), \fBpoll\fR(2), \fBputmsg\fR(2), \fBread\fR(2), \fBwrite\fR(2),
779 \fBsignal\fR(3C), \fBtypes.h\fR(3HEAD), \fBunistd.h\fR(3HEAD),
780 \fBattributes\fR(5), \fBstandards\fR(5)