STREAMS Programmer's Guide

Contents

Proprietary Notice

Documentation Log

Introduction

Chapter 1 Introduction to STREAMS

1.1 Introduction

1.1.1 References

1.1.2 Notation Conventions

1.1.3 Notes on Configuring STREAMS Modules and Drivers

1.2 Overview of STREAMS

1.3 Basic Stream Operations

1.4 STREAMS Components

1.4.1 Queues

1.4.2 Messages

1.4.2.1 Message Types

1.4.2.2 Message Queueing Priority

1.4.3 Modules

1.4.4 Drivers

1.5 Multiplexing

1.6 Benefits of STREAMS

1.6.1 Standardized Service Interfaces

1.6.2 Manipulating Modules

1.6.2.1 Protocol Portability

1.6.2.2 Protocol Substitution

1.6.2.3 Protocol Migration

1.6.2.4 Module Reusability

2.1 Introduction

2.1.1 STREAMS System Calls

2.1.1.1 getmsg and putmsg

2.1.1.2 poll

2.2 Stream Construction

2.2.1 Opening a STREAMS Device File

2.2.2 Adding and Removing Modules

2.2.3 Closing the Stream

2.2.4 Stream Construction Example

2.2.4.1 Inserting Modules

2.2.4.2 Module and Driver Control

3.1 Introduction

3.1.1 The STREAMS Subsystem

3.1.1.1 Modularity

3.2 Messages

3.2.1 Message Contents Type

3.2.2 Message Priority

3.2.3 Message Structure

3.3 Structure Declarations

3.4 STREAMS Entry Points

3.4.1 open Routine

3.4.1.1 The CLONE Driver

3.4.2 Message Processing

3.4.3 put Routine

3.4.3.1 put Routine: Switch on Message Type

3.4.3.2 put Routine: Flush Handling

3.4.3.3 put Routine: I/O Control Commands

3.4.3.4 put Routine: Data Output

3.4.3.5 put Routine: Error Detection

3.4.4 service Routine

3.4.4.1 service Routine: Retrieve Message

3.4.4.2 service Routine: Check for Blocking

3.4.4.3 service Routine: Return Message

3.4.4.4 service Routine: Forward Message

3.4.5 close Routine

4.1 Introduction

4.1.1 put Procedure

4.1.2 service Procedure

4.2 Asynchronous Protocol

4.2.1 Read-Side Processing

4.2.1.1 Driver Processing

4.2.1.2 CHARPROC

4.2.1.3 CANONPROC

4.2.2 Write-Side Processing

4.2.3 Analysis

5.1 Introduction

5.1.1 Expedited Data

5.2 Message Structure

5.2.1 Message Linkage

5.2.2 Sending/Receiving Messages

5.2.3 Control Stream Head Processing

5.2.3.1 Read Options

5.2.3.2 Write Offset

5.3 Message Queues and Priorities

5.3.1 queue Structure

5.3.1.1 Using queue Information

5.3.1.2 qband Structure

5.3.1.3 Using qband Information

5.3.2 Message Processing

5.3.2.1 Flow Control

5.4 Service Interfaces

5.4.1 Service Interface Benefits

5.4.2 Service Interface Library

5.4.2.1 Accessing the Service Provider

5.4.2.2 Closing the Service Provider

5.4.2.3 Sending Data to the Service Provider

5.4.2.4 Receiving Data from the Service Provider

5.4.3 Module Service Interface

5.4.3.1 Service Interface Procedure

5.5 Message Allocation and Freeing

5.5.1 Recovering from No Buffers

5.6 Extended STREAMS Buffers

5.7 Message Types

5.7.1 Detailed Description of Message Types

5.8 Ordinary Messages

5.8.1 M_BREAK

5.8.2 M_CTL

5.8.3 M_DATA

5.8.4 M_DELAY

5.8.5 M_IOCTL

5.8.6 M_PASSFP

5.8.7 M_PROTO

5.8.8 M_RSE

5.8.9 M_SETOPTS

5.8.10 M_SIG

5.9 High Priority Messages

5.9.1 M_COPYIN

5.9.2 M_COPYOUT

5.9.3 M_ERROR

5.9.4 M_FLUSH

5.9.5 M_HANGUP

5.9.6 M_IOCACK

5.9.7 M_IOCDATA

5.9.8 M_IOCNAK

5.9.9 M_PCPROTO

5.9.10 M_PCRSE

5.9.11 M_PCSIG

5.9.12 M_READ

5.9.13 M_START and M_STOP

5.9.14 M_STARTI and M_STOPI

6.1 Introduction

6.1.1 Differences Between Modules and Drivers

6.1.2 Similarities Between Modules and Drivers

6.1.3 Module and Driver Declarations

6.1.3.1 Null Module Example

6.2 Module and Driver ioctls

6.2.1 General ioctl Processing

6.2.2 I_STR ioctl Processing

6.2.3 Transparent ioctl Processing

6.2.4 Transparent ioctl Messages

6.2.5 Transparent ioctl Examples

6.2.5.1 M_COPYIN Example

6.2.5.2 M_COPYOUT Example

6.2.5.3 Bidirectional Transfer Example

6.2.6 I_LIST ioctl

6.3 Flush Handling

6.4 Driver-Kernel Interface

6.4.1 STREAMS Interface

6.5 Configuring the System for STREAMS Drivers and Modules

6.5.1 Modules and Drivers

6.5.1.1 Rules for Open/Close Routines

6.5.1.2 Rules for ioctls

6.5.1.3 Rules for put and service Procedures

6.5.2 Data Structures

6.5.3 Header Files

6.5.4 Configuring STREAMS Modules and Drivers

6.5.5 Configuration Example

6.5.6 Accessible Functions

7.1 Introduction

7.1.1 Routines

7.1.2 Filter Module Example

7.2 Flow Control

7.3 Design Guidelines

8.1 Introduction

8.1.1 Driver Classification

8.1.2 Writing a Driver

8.1.3 Major and Minor Device Numbers

8.1.4 STREAMS Drivers

8.1.4.1 Printer Driver Example

8.1.4.2 Driver Flow Control

8.2 Cloning

8.3 Loop-Around Driver

8.4 Design Guidelines

9.1 Introduction

9.1.1 Building a Multiplexor

9.1.2 Dismantling a Multiplexor

9.1.3 Routing Data through a Multiplexor

9.2 Connecting/Disconnecting Lower Streams

9.2.1 Connecting Lower Streams

9.2.2 Disconnecting Lower Streams

9.3 Multiplexor Construction Example

9.4 Multiplexing Driver

9.4.1 Upper Write put Procedure

9.4.2 Upper Write service Procedure

9.4.3 Lower Write service Procedure

9.4.4 Lower Read put Procedure

9.5 Persistent Links

9.6 Design Guidelines

A.1 Command List

A.2 Command Page Format

Appendix C Utilities

C.1 Command List

C.2 Command Page Format

Index

Figures

1-1 Simple Streams

1-2 Stream Communication Driver

1-3 A Message

1-4 Messages on a Message Queue

1-5 Detailed Stream

1-6 Many-to-One Multiplexor

1-7 One-to-Many Multiplexor

1-8 Many-to-Many Multiplexor

1-9 Internet Multiplexing Stream

1-10 X.25 Multiplexing Stream

1-11 X.25 Multiplexing Stream

1-12 Protocol Migration

1-13 Module Reusabiltiy

2-1 Upstream and Downstream Stream Construction

2-2 Stream Queue Relationship

2-3 Opened STREAMS-Based Driver

2-4 Inserting a Module into a Stream

2-5 Case Converter Module

2-6 Module and Driver Control

3-1 Pseudo-Code for a put Routine

3-2 put Routine Example of Flush Handling

3-3 put Routine Example of I/O Control Command Handling

3-4 put Routine Example of Default Error Handling

3-5 Pseudo-Code for service Routine

4-1 Idle Stream Configuration for Example

4-2 Operational Stream for Example

4-3 Module put and service Procedures

5-1 Message Form and Linkage

5-2 Message Ordering on a Queue

5-3 Message Ordering with One Priority Band

5-4 Obtained Fields

5-5 Flow Control

5-6 Protocol Substitution

5-7 Service Interface

5-8 Service Interface Library Example

5-9 Accessing the Service Provider

5-10 Acknowledgment from Service Provider

5-11 Closing the Service Provider

5-12 Sending Data

5-13 Receiving Data

5-14 Module Service Interface Declaration

5-15 Write Procedure

5-16 Appending a Character to a Message Block

5-17 Processing Message Blocks

5-18 Device Receive Interrupt Handler

5-19 Write Service Procedure

5-20 M_PROTO and M_PCPROTO Message Structure

6-1 Module and Driver Declarations

6-2 Required Structures

6-3 Null Module Procedure

6-4 I_STR ioctl Processing

6-5 Request/Response Messages

6-6 GETSTRUCT and GETADDR

6-7 I_STR and Transparent ioctl

6-8 Write-Side put Procedure

6-9 Message Block Allocation

6-10 str_list Structure

6-11 Line Discipline Flush Handling

6-12 Line Discipline Break Flushing

6-13 Flushing the Write-Side of a Stream

6-14 Flushing the Read-Side of a Stream

6-15 Priority Band Flush Handling

6-16 mod Declaration Form

7-1 Read-Side put

7-2 Write-Side put

7-3 service Routine

7-4 Filter Module

7-5 Write-Side put Procedure and Queue Flush

7-6 M_DATA Message Processing

7-7 Read-Side Line Discipline

7-8 Write-Side Line Discipline

8-1 Device Driver Streams

8-2 Line Printer Driver

8-3 Driver Open

8-4 Flush Handling

8-5 Device Interrupt

8-6 Driver Close Routine

8-7 Loop-Around Streams

8-8 Driver Declarations

8-9 Open Procedure

8-10 Driver Sanity Checks

8-11 Write- and Read-Side Flow Control

8-12 Reenabling the Writer

9-1 Protocol Multiplexor

9-2 Daemon Program Declarations and Initialization

9-3 Before Link

9-4 Multiplexor after First Link

9-5 IP Multiplexor

9-6 TP Multiplexor

9-7 Internet Multiplexor before Connecting

9-8 Internet Multiplexor after Connecting

9-9 Multiplexor Declarations

9-10 Canonical Driver Open Code

9-11 Upper Write put Procedure

9-12 Upper Write service Procedure

9-13 Lower Write serviceProcedure

9-14 Lower Read put Procedure

9-15 Clean Upper Queue

9-16 open() of MUXdriver and Driver1

9-17 Multiplexor after I_PLINK

9-18 Other Users Opening a MUXdriver

9-19 Retrieving the MUX ID from the File