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