STREAMS Programming Guide

Preface

The STREAMS Programming Guide describes how to use STREAMS in designing and implementing applications and STREAMS modules and drivers, for architectures that conform to the Solaris^TM 7 DDI/DDK.

Who Should Read This Book

The manual is a guide for application, driver, and module developers. The reader must know C programming in a UNIX^TM environment, and be familiar with the system interfaces. Driver and module developers should also be familiar with the book Writing Device Drivers.

How This Book Is Organized

This guide is divided into three parts. Part IPart 1 describes how to use STREAMS facilities in applications. Part IIPart 2 describes how to design STREAMS modules and STREAMS drivers. Part IIIPart 3 contains advanced topics. Every developer should read Chapter 1.

Part I

Chapter 1, Overview of STREAMS is a general overview of STREAMS concepts and mechanisms.
Chapter 2, STREAMS Application-Level Components describes the basic operations to assemble, use, and dismantle Streams.
Chapter 3, STREAMS Application-Level Mechanisms details the operations of messages, the flow of Streams, and how to manipulate Steams from applications.
Chapter 4, STREAMS Driver and Module Interfaces describes putting messages into and receiving them from a Stream.
Chapter 5, STREAMS Administration identifies and describes tools to monitor names and modules, and gather statistics.
Chapter 6, Pipes and Queues describes pipes and named pipes (FIFOs).

Part II

Chapter 7, STREAMS Framework -Kernel Level describes STREAMS modules, drivers, and how they relate.
Chapter 8, Messages - Kernel Level describes message types, structure, and linkage in detail. Flow control is also covered.
Chapter 9, STREAMS Drivers describes specific STREAMS drivers, using code samples.
Chapter 10, Modules describes how specific examples of modules work based on code samples.
Chapter 11, Configuration describes configuring modules and drivers into the OS.
Chapter 12, MultiThreaded STREAMS describes the multithreaded environment and how to make modules and drivers MT- safe.
Chapter 13, Multiplexing describes how to implement multiplexing in a driver.

Part III

Chapter 14, STREAMS-Based Terminal Subsystem explains setting up a terminal subsystem, and keeping track of processes and handling interrupts.
Chapter 15, Debugging addresses commonly encountered problems and their resolution.

Appendices

Appendix A, Message Types describes STREAMS messages and their use.
Appendix B, STREAMS Utilities describes STREAMS utility routines and their use.
Appendix C, STREAMS F.A.Q. contains answers to a variety of commonly asked questions about STREAMS.
Glossary defines terms unique to STREAMS.

Code Examples

All code examples used in this book conform to ANSI C specifications.

Conventions Used

The word "STREAMS" refers to the mechanism and "Stream" refers to an explicit path between a user application and a driver.

Examples highlight common capabilities of STREAMS, and reference fictional drivers and modules. Where possible, examples are executable code.

The following table describes the typographic conventions used in this book.

Table P-1 Typographic Conventions


Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% You have mail.`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name%` `su` `Password:`
`AaBbCc123`	Interface or command-line variable: provide a real path or value	To delete a file, type `rm` `filename`.
AaBbCc123	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

Caution -

The warning sign shows possible damage to data, system, application, or person.

Caution -

The caution sign shows possible harm or damage to a system, an application, a process, or a piece of hardware.

Note -

Notes are used to emphasize points of interest, to present parenthetical information, and to cite references to other documents and commands.

Related Books

You can obtain more information on STREAMS system calls and utilities from the on-line manual pages. For more information on driver-related issues, including autoconfiguration, see Writing Device Drivers.

You can also find STREAMS described to some extent in the System V Interface Definition, and in the following publications:

Goodheart, Berny and Cox, James. The Magic Garden Explained. Australia, & Englewood Cliffs, New Jersey: Prentice Hall, 1994.

Rago, Stephen A. UNIX System V Network Programming. Reading, Massachusetts: Addison-Wesley, 1993.

Ordering Sun Documents

The SunDocs^SM program provides more than 250 manuals from Sun Microsystems, Inc. If you live in the United States, Canada, Europe, or Japan, you can purchase documentation sets or individual manuals using this program.

For a list of documents and how to order them, see the catalog section of SunExpress^TM Internet site at http://www.sun.com/sunexpress.