STREAMS Programmer’s Guide HP 9000 and Integrity Server Computer Systems Edition 1 Manufacturing Part Number : 5991-4437 October 2005 United States © Copyright 2005 Hewlett-Packard Development Company L.P. Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty A copy of the specific warranty terms applicable to your Hewlett-Packard product and replacement parts can be obtained from your local Sales and Service Office. U.S. Government License Proprietary computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. Copyright Notice Copyright 2005 Hewlett-Packard Development Company L.P. All rights reserved. Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws. Trademark Notices UNIX is a registered trademark in the United States and other countries, licensed exclusively through The Open Group. Ethernet is a registered trademark of Xerox Corporation. All other product names are trademarks, registered trademarks, or service marks of their respective owners. Printing History New editions of this manual will incorporate all material updated since the previous edition. The manual printing date and part number indicate its current edition. The printing date changes when a new edition is printed. (minor corrections that are incorporated at a reprinting do not cause the date to change.) The manual part number changes when extensive technical changes are incorporated. Edition/Part Number/Date First/5991-4437/October 2005 2 Contents 1. Overview STREAMS Components. 24 Stream Head . 25 STREAMS Module . 25 STREAMS Driver or Pseudo-Driver . 25 Messages and Queues . 26 Queues . 26 Messages . 26 Message Processing . 27 STREAMS Multiplexor . 28 2. STREAMS Mechanism and System Calls STREAMS System Calls . 30 STREAMS Library Routines . 30 Creating a Stream . 31 open(2) Opening a STREAMS Device . 31 pipe(2) Creating a STREAMS-Based pipe. 31 Writing to a Stream . 33 write(2) and writev(2). 33 putmsg(2) and putpmsg(2) . 35 Reading From a Stream. 37 read(2) and readv(2) . 37 getmsg(2) and getpmsg(2) . 39 Pushing and Popping Modules . 42 IOCTL Commands I_PUSH and I_POP . 42 Closing a Stream . 43 close(2) . 43 Polling Streams . 44 poll(2). 44 Events Notified by poll(2). 45 The /dev/poll Interface . 46 select(2) . 48 Differences Between select(2) and poll(2) . 49 Asynchronous Event Notification . 50 IOCTL Command — I_SETSIG . 50 Attaching and Detaching a stream to a file (Named Streams) . 52 3 Contents fattach (3C) . 52 fdetach(3C) . 52 isastream(3C) . 53 3. Messages Message Structures . 56 Using Message Block Fields. 57 Message Queues . 59 Message Processing and Flow Control . 63 Message Processing . 63 Flow Control . 63 Common STREAMS Utilities. 66 4. Modules and Drivers Overview. 72 Cloning . 72 Autopush . 72 Dynamically Loadable Kernel Modules. 73 Data Structures . 74 module_info Structure . 74 qinit Structure . 75 module_stat Structure . 75 Installation Structures and Configuration Routines . 76 d_flags . 79 Configuration Routines . 80 Entry Points . 82 Open. 82 Close . 82 Ioctl . 83 Put Procedure . 92 Service Procedure . 92 Interrupt Service Routine . ..