Preface

The Purpose of This Manual

VOS Communications Software: STREAMS Programmer's Guide (R306-00) documents the application program interface to the VOS STREAMS software. It describes how applications use the VOS STREAMS application program interface to communicate with STREAMS devices.

Audience

This manual is for programmers who write or design STREAMS applications under the VOS operating system. Programmers are expected to be familiar with the STREAMS protocol and with the VOS programming environment in order to use the VOS STREAMS software.

Revision Information

This is the first publication of this manual. For information on which release of the software this manual documents, see the Notice page.

Manual Organization

Chapter 1, "Introduction to VOS STREAMS," briefly describes STREAMS and STREAMS-related concepts and terms, and introduces the VOS STREAMS software.

Chapter 2, "VOS STREAMS Programming Support," presents various elements of VOS STREAMS programming support and other programming considerations for developing application programs for VOS STREAMS.

Chapter 3, "Application Program Interface," documents the application program interface to VOS STREAMS. VOS STREAMS applications can use either the VOS C language interface or VOS subroutines as the interface to VOS STREAMS, as documented in this chapter.

Appendix A, "System Analysis Requests," documents the analyze_system requests for VOS STREAMS.

Appendix B, "Polling and Tasking Example for VOS STREAMS," contains a coding fragment example that shows the use of polling and tasking in a VOS STREAMS application.

Appendix C, "PL/I Usage," shows the VOS STREAMS subroutine declarations in VOS PL/I.

Notation

Stratus documentation uses italics to introduce or define new terms. For example:

A Stream is a communications path between a STREAMS driver in kernel space and a user process.

Computer font is used to represent text that would appear on your display screen or on a printer. (Such text is referred to as literal text.) For example:

The VOS subroutine s$streams_open is used to obtain the port ID for a STREAMS device.

Slanted font is used to represent general terms that are to be replaced by literal values. In the example below, eventsN is to be replaced by an integer number.

long int      event_ids[eventsN];

Boldface is used to emphasize words within the text.

Note that while s$poll supports polling of VOS events, it does not support polling of VOS device events.

Format for Subroutines

Stratus System/88 manuals use the following format conventions for documenting subroutines. Note that the subroutine descriptions do not necessarily include each of the following sections.

subroutine_name
The name of the subroutine is at the top of the first page of the subroutine description.

Purpose
Explains briefly what the subroutine does.

Usage
Shows how to declare the variables passed as arguments to the subroutine, declare the subroutine entry in a program, and call the subroutine.

Arguments
Describes the subroutine's arguments.

Explanation
Provides information about how to use the subroutine.

Error Codes
Explains some error codes that the subroutine can return.

Examples
Illustrates how to use the subroutine or provides sample input to and output from the subroutine.

Related Manuals

Refer to the following sources for additional information on STREAMS.

  • AT&T STREAMS documention, published by Wiley and Sons.
  • AT&T STREAMS documentation, published by Prentice Hall.
  • AT&T UNIXÆ System V Release 4 Programmer's Guide: STREAMS, published by Prentice Hall.

Refer to the following Stratus manuals for related documentation.

  • VOS PL/I Subroutines Manual
  • VOS C Subroutines Manual
  • VOS C Language Manual
  • VOS System Administration: Configuring a System
  • VOS Commands Reference Manual
  • VOS PL/I Transaction Processing Facility Reference Manual
  • VOS C Transaction Processing Facility Reference Manual

Online Documentation

You can find additional information by viewing the system's online documentation in >system>doc. The online documentation contains the latest information available, including updates and corrections to Stratus manuals.

A Note on the Contents of Stratus Manuals

Stratus manuals document all the subroutines and commands of the user interface. Any other commands and subroutines contained in the operating system are intended solely for use by Stratus personnel and are subject to change without warning.

How to Comment on This Manual

You can comment on this manual by using the command comment_on_manual, described in the VOS System Administration: Administering and Customizing a System . Type comment_on_manual, press , and then complete the form that appears on your screen. You must fill in this manual's part number, R306. When you have completed the form, press . Your comments are sent to Stratus over the Remote Service Network. Note that the operating system includes your name with your comments.

Stratus welcomes any corrections and suggestions for improving this manual.

Survey and Manual-Ordering Form

A customer survey and manual-ordering information are included at the back of this manual.

Stratus encourages you to complete the survey. The survey form folds into a self-addressed envelope.

To order a manual, follow the instructions that precede the order form.