............................Contents


1. Introduction	1
..Introduction to This Guide	1
....Audience	1
....Organization	1
....Code Examples	3
....Conventions Used	3
....Other Documentation	4
2. Overview of STREAMS	5
..What Is STREAMS?	5
..Basic Streams Operations	9
..STREAMS Components	12
....Queues	12
....Messages	13
....Modules	16
....Drivers	18


..Multiplexing	18
..Benefits of STREAMS	23
....Standardized Service Interfaces	23
....Manipulating Modules	24
3. STREAMS Mechanism	29
..STREAMS Mechanism Overview	29
....STREAMS System Calls	30
..Stream Construction	30
....Opening a STREAMS Device File	33
....Creating a STREAMS-based Pipe	34
....Adding and Removing Modules	35
....Closing the Stream	35
....Stream Construction Example	36
4. STREAMS Processing Routines	43
..Put and Service Procedures	43
....Put Procedure	44
....Service Procedure	45
..An Asynchronous Protocol Stream Example	46
....Read-Side Processing	49
....Write-Side Processing	52
....Analysis	52
5. Messages	53
..Message Overview	53
....Message Types	53


....Expedited Data	55
..Message Structure	56
....Message Linkage	57
....Sending/Receiving Messages	59
....Control of Stream Head Processing	64
..Message Queues and Message Priority	66
....The queue Structure	70
....Message Processing	75
..Service Interfaces	82
....Service Interface Benefits	83
....Service Interface Library Example	86
..Message Allocation and Freeing	99
....Recovering From No Buffers	102
....Releasing Callback Requests	105
..Extended STREAMS Buffers	105
.... esballoc Example	108
6. Polling and Signaling	111
..Input/Output Polling	111
....Synchronous Input/Output	112
....Asynchronous Input/Output	116
....Signals	118
..Stream as a Controlling Terminal	119
....Job Control	119
....Allocation and Deallocation	122


....Hungup Streams	122
....Hangup Signals	122
....Accessing the Controlling Terminal	123
7. Overview of Modules and Drivers	125
..Module and Driver Environment	125
....Module and Driver Declarations	126
..Module and Driver ioctls	130
....General ioctl Processing	132
....I_STR ioctl Processing	134
....Transparent ioctl Processing	135
....Transparent ioctl Messages	138
....Transparent ioctl Examples	139
....I_LIST ioctl	151
..Flush Handling	153
....Flushing Priority Bands	156
....Device Driver Interface and Driver-Kernel Interface	158
....STREAMS Interface	159
..Configuring the System for STREAMS Drivers and Modules .	160
..Design Guidelines	160
....Data Structures	165
8. Modules	167
..Module Overview	167
....Module Procedures	167
....Filter Module Example	171


..Flow Control	175
..Design Guidelines	178
9. Drivers	181
..Device Drivers	181
.....Overview of Drivers	181
.....Driver Classification	182
.....Writing a Driver	182
..STREAMS Drivers	184
.....STREAMS Driver Configuration	184
.....STREAMS Entry Points	185
..Printer Driver Example	187
.....Driver Flush Handling	190
..... Driver Interrupt	192
.....Driver Close	194
.....Driver Flow Control	194
..Cloning	195
.....Loop-Around Driver	198
..Design Guidelines	209
10. Multiplexing	211
..Overview of Multiplexing	211
.....Building a Multiplexer	212
.....Dismantling a Multiplexer	220
.....Routing Data Through a Multiplexer	222
..Connecting / Disconnecting Lower Streams	222


.....Connecting Lower Streams	223
.....Disconnecting Lower Streams	224
..Multiplexer Construction Example	225
..Multiplexing Driver	228
.....Upper Write Put Procedure	232
.....Upper Write Service Procedure	235
.....Lower Write Service Procedure	236
.....Lower Read Put Procedure	237
..Persistent Links	239
..Design Guidelines	243
11. STREAMS-Based Pipes and FIFOS	245
..Overview of Pipes and FIFOs	245
..Creating and Opening Pipes and FIFOs	246
.....Accessing Pipes and FIFOs	247
.....Flushing Pipes and FIFOs	250
.....Named Streams	250
.....Unique Connections	254
12. STREAMS-Based Terminal Subsystem	259
..Overview of Terminal Subsystem	259
.....Line-Discipline Module	261
.....Hardware Emulation Module	268
..STREAMS-based Pseudo-Terminal Subsystem	270
.....Line-Discipline Module	271
.....Pseudo-TTY Emulation Module - PTEM	272


.....Remote Mode	276
.....Packet Mode	276
.....Pseudo-TTY Drivers - ptm and pts	277
13. Multi-Threaded STREAMS	283
..MT STREAMS Overview	283
..MT STREAMS Framework	284
.....STREAMS Framework Integrity	285
.....Message Ordering	285
..Your MT Options	286
.....MT SAFE modules	286
.....MT UNSAFE modules	287
..Preparing to Port	287
.....Porting to SunOS 5.x	289
..MT SAFE Modules	290
.....MT STREAMS perimeters	290
.....Perimeter options	292
.....MT configuration	293
.....qprocson()/qprocsoff()	293
.....qtimeout()/qbufcall()	294
.....qwriter()	294
.....qwait()	295
.....Asynchronous Callbacks	295
.....Close Race Conditions	296
.....Module unloading and esballoc	296


.....Use of q_next	297
..MT SAFE Modules using Explicit Locks	297
.....Constraints when using locks	297
.....Preserving message ordering	298
..MT UNSAFE Modules	298
.....Modifying UNSAFE Drivers	299
.....Caveats	300
.....New facilities	301
..Old Facilities	301
.....spl	302
.....sleep/wakeup	302
..Sample Multi-threaded Device Driver	303
..Sample Multi-threaded Module with Outer perimeter	312
A. STREAMS Data Structures	321
..streamtab	321
..QUEUE Structures	322
..... queue	322
.....qinit	323
.....module_info	323
.....qband	324
..Message Structures	324
.....iocblk	325
.....copyreq	325
.....copyresp	326


..Other Structures	326
.....strioctl	326
.....linkblk	327
.....stroptions	327
B. Message Types	329
..Introduction	329
..Ordinary Messages	329
.....M_BREAK	329
.....M_CTL	330
.....M_DATA	330
.....M_DELAY	330
.....M_IOCTL	331
.....M_PASSFP	334
.....M_PROTO	334
.....M_RSE	335
.....M_SETOPTS	336
..High-Priority Messages	340
.....M_COPYIN	340
.....M_COPYOUT	341
.....M_ERROR	341
.....M_FLUSH	342
.....M_HANGUP	343
.....M_IOCACK	344
.....M_IOCDATA	344


.....M_IOCNAK	345
.....M_PCPROTO	346
.....M_PCRSE	346
.....M_PCSIG	346
.....M_READ	346
.....M_START and M_STOP	347
.....M_STARTI and M_STOPI	347
.....M_UNHANGUP	347
C. STREAMS Utilities	349
..Introduction	349
..Utility Descriptions	350
.....adjmsg - trim bytes in a message	350
.....allocb - allocate a message and data block	351
.....backq - get pointer to the queue behind a given queue	351
.....bcanput - test for flow control in the given priority band .	351
.....bcanputnext- test for flow control in the given priority band	351
.....bufcall - recover from failure of allocb	352
.....canput - test for room in a queue	352
.....canputnext - test for room in the next queue	353
.....copyb - copy a message block	353
.....copymsg - copy a message	353
.....datamsg - test whether message is a data message	354
.....dupb - duplicate a message block descriptor	354
.....dupmsg - duplicate a message	354


.....enableok - re-allow a queue to be scheduled for service	355
.....esballoc - allocate message and data blocks	355
.....esbbcall - call function when buffer is available	355
.....flushband - flush the messages in a given priority band .	356
.....flushq - flush a queue	356
.....freeb - free a single message block	356
.....freemsg - free all message blocks in a message	357
.....freezestr - freeze a stream	357
.....getq - get a message from a queue	357
.....insq - put a message at a specific place in a queue	358
.....linkb - concatenate two messages into one	358
.....msgdsize - get the number of data bytes in a message	359
.....msgpullup - concatenate bytes in a message	359
.....noenable - prevent a queue from being scheduled	359
.....OTHERQ - get pointer to the mate queue	359
.....pullupmsg - concatenate and align bytes in a message	359
.....put - call a STREAMS put procedure	360
.....putbq - return a message to the beginning of a queue	360
.....putctl - put a control message	360
.....putctl1 - put a control message with a one-byte parameter	361
.....putnext - put a message to the next queue	361
.....putnextctl - put a control message	361
.....putnextctl1 - put a control message	361
.....putq - put a message on a queue	362


.....qenable - enable a queue	363
.....qsize - find the number of messages on a queue	364
.....RD - get pointer to the read queue	364
.....rmvb - remove a message block from a message	364
.....rmvq - remove a message from a queue	364
.....strlog - submit messages for logging	365
.....testb - check for an available buffer	366
.....unbufcall - cancel a bufcall request	366
.....unfreezestr- unfreeze a stream	367
.....WR - get pointer to the write queue	367
..DKI Interface	367
..New MT perimeter utility routines	367
.....qbufcall - recover from failure of allocb	368
.....qunbufcall - cancel a qbufcall request	369
.....quntimeout - cancel a qtimeout request	369
.....qwait/qwait_sig -STREAMS perimeter wait routines	369
.....qwriter - asynchronous STREAMS perimeter upgrade	370
..Utility Routine Summary	371
D. Debugging	375
..Overview of Debugging Facilities	375
..Kernel Debug Printing	376
.....Console Messages	376
..STREAMS Error Logging	377
.....Error and Trace Logging	377


..Kernel Examination Tools	379
.....The crash(1M) Command	379
.....The adb(1) Command	380
.....The kadb(1M) Command	380
E. Configuration	381
..Introduction	381
..Configuring STREAMS Drivers and Modules	381
.. Data Structure Layout	382
.....modlinkage	382
.....modldrv	383
.....modlstrmod	383
.....dev_ops	383
.....cb_ops	384
.....streamtab	385
.....qinit	386
..Entry Points	386
.....pts example	386
.....STREAMS Module Configuration	392
.....Compilation	393
.....Kernel Loading	393
.....Checking module type	393
..Tunable Parameters	393
..Autopush Facility	394
.....User Interface	395


F. Manual Pages	399
......DDI/DKI Entry Points	400
......DDI/DKI Functions	401
......DDI/DKI Data Structures	403
Glossary	405
Index	I- 413