STREAMS Programming Guide
Total Page:16
File Type:pdf, Size:1020Kb
STREAMS Programming Guide Sun Microsystems, Inc. 901 San Antonio Road Palo Alto, CA 94303 U.S.A. Part No: 805-7478–05 August 1999 Copyright 1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, docs.sun.com, AnswerBook, AnswerBook2, tags does not print or display in your document. Do not modify any text except the attributions you type.–> and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227–14(g)(2)(6/87) and FAR 52.227–19(6/87), or DFAR 252.227–7015(b)(6/95) and DFAR 227.7202–3(a). DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, Californie 94303-4900 Etats-Unis. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, docs.sun.com, AnswerBook, AnswerBook2, et Solaris sont des marques de fabrique ou des marques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L’interface d’utilisation graphique OPEN LOOK et SunTM a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, Y COMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU. Please Recycle Contents xv Part I Application Programming Interface 1. Overview of STREAMS 3 What Is STREAMS? 3 STREAMS Definitions 4 Stream 5 Stream Head 5 Module 5 Driver 5 Messages 5 Queues 6 streamio 6 Multiplexing 7 Polling 7 Flow Control 7 When to Use STREAMS 7 How STREAMS Works—Application Interface 8 Opening a Stream 8 Closing a Stream 9 Contents iii Controlling Data Flow 9 Simple Stream Example 9 How STREAMS Works—Kernel-level 10 Stream Head 10 Modules 11 Drivers 13 Messages 13 Message Queueing Priority 14 Queues 15 Multiplexing 16 Multithreading 17 STREAMS in Operation 17 Service Interfaces 17 Manipulating Modules 17 2. STREAMS Application-Level Components 21 STREAMS Interfaces 21 STREAMS System Calls 21 Action Summary 23 Opening a STREAMS Device File 23 Initializing Details 24 Queueing 24 Adding and Removing Modules 24 Closing the Stream 25 Closing Delay Details 25 Stream Construction Example 26 Inserting Modules 26 Module and Driver Control 28 3. STREAMS Application-Level Mechanisms 31 iv STREAMS Programming Guide ♦ August 1999 Message Handling 31 Modifying Messages 31 Message Types 32 Control of Stream Head Processing 32 Message Queueing and Priorities 34 Controlling Flow and Priorities 34 Accessing the Service Provider 35 Closing the Service Provider 38 Sending Data to the Service Provider 38 Receiving Data 39 Input and Output Polling 40 Synchronous Input and Output 41 Asynchronous Input and Output 45 Signals 46 Stream as a Controlling Terminal 47 Job Control 47 Allocation and Deallocation 50 Hungup Streams 51 Hangup Signals 51 Accessing the Controlling Terminal 51 4. STREAMS Driver and Module Interfaces 53 System Calls Used 53 Module and Driver ioctl(2) 54 General ioctl(2) Processing 56 I_STR ioctl(2) Processing 56 Transparent ioctl(2) Processing 57 I_LIST ioctl(2) 57 Other ioctl(2) Commands 59 Contents v Message Direction 61 Flush Handling 62 Flushing Priority Bands 62 5. STREAMS Administration 65 Tools Available 65 Autopush Facility 66 Application Interface 67 Administration Tool Description 69 strace(1M) 69 strlog(9F) 69 strqget(9F) 70 strqset(9F) 70 strerr(1M) 70 6. Pipes and Queues 71 Overview of Pipes and FIFOs 71 Creating and Opening Pipes and FIFOs 72 Using Pipes and FIFOs 74 Flushing Pipes and FIFOs 76 Named Streams 77 Unique Connections 77 Part II Kernel Interfaces 7. STREAMS Framework –Kernel Level 83 Overview of Streams in Kernel Space 83 Stream Head 84 Kernel–Level Messages 84 Message Types 84 Message Structure 86 Message Linkage 89 vi STREAMS Programming Guide ♦ August 1999 Queued Messages 89 Shared Data 90 Sending and Receiving Messages 91 Message Queues and Message Priority 92 Queues 94 queue(9S) Structure 94 Using Queue Information 96 Entry Points 97 open Routine 98 close Routine 101 The put Procedure 102 service Procedure 105 qband(9S) Structure 107 Message Processing 109 Flow Control in Service Procedures 111 8. Messages - Kernel Level 115 ioctl(2) Processing 115 Message Allocation and Freeing 116 Recovering From No Buffers 118 Releasing Callback Requests 120 Extended STREAMS Buffers 121 esballoc(9F) Example 122 General ioctl(2) Processing 124 STREAMS ioctl Issues 125 I_STR ioctl(2) Processing 126 Transparent ioctls 128 Transparent ioctl(2) Messages 128 Transparent ioctl(2) Examples 131 Contents vii Flush Handling 143 Flushing Priority Bands 143 Driver and Module Service Interfaces 148 Service Interface Library Example 150 Message Type Change Rules 156 Well-known ioctl Interfaces 157 FIORDCHK 157 FIONREAD 157 I_NREAD 157 Signals 158 9. STREAMS Drivers 159 STREAMS Device Drivers 159 Basic Driver 160 STREAMS Driver Topics 160 STREAMS Configuration Entry Points 161 STREAMS Initialization Entry Points 162 STREAMS Table-Driven Entry Points 162 STREAMS Queue Processing Entry Points 163 STREAMS Interrupt Handlers 164 Driver Unloading 164 STREAMS Driver Code Samples 164 Printer Driver Example 165 Cloning 177 Loop-Around Driver 181 Summary 192 Answers to Frequently Asked Questions 192 10. Modules 195 Module Overview 195 viii STREAMS Programming Guide ♦ August 1999 STREAMS Module Configuration 195 Module Procedures 196 Filter Module Example 199 Flow Control 202 Design Guidelines 204 htonl(3N) and ntohl(3N) 204 Answers to Frequently Asked Questions 205 11. Configuration 207 Configuring STREAMS Drivers and Modules 207 modlinkage(9S) 208 modldrv(9S) 208 modlstrmod(9S) 209 dev_ops(9S) 209 cb_ops(9S) 209 streamtab(9S) 210 qinit(9S) 210 Entry Points 211 pts(7D) example 211 STREAMS Module Configuration 215 Compilation 216 Kernel Loading 216 Checking Module Type 216 Tunable Parameters 217 autopush(1M) Facility 217 Application Interface 218 STREAMS Anchors 220 12. MultiThreaded STREAMS 225 MultiThreaded (MT) STREAMS Overview 225 Contents ix MT STREAMS Framework 226 STREAMS Framework Integrity 227 Message Ordering 227 MT Configurations 228 MT SAFE modules 228 MT UNSAFE Modules 228 Preparing to Port 229 Porting to the SunOS 5 System 230 MT SAFE Modules 231 MT STREAMS Perimeters 231 Perimeter options 233 MT Configuration 234 qprocson(9F)/ qprocsoff(9F) 234 qtimeout(9F)/ qunbufcall(9F) 234 qwriter(9F) 234 qwait(9F) 235 Asynchronous Callbacks 235 Close Race Conditions 236 Module Unloading and esballoc(9F) 236 Use of q_next 236 MT SAFE Modules Using Explicit Locks 237 Constraints When Using Locks 237 Preserving Message Ordering 238 Sample Multithreaded Device Driver 238 Sample Multithreaded Module with Outer Perimeter 244 13.