About This Book

This book discusses how to write device drivers for computer systems running the Digital UNIX® operating system.

Audience

This book is intended for systems engineers who:

Use standard library interfaces to develop programs in the C language
Know the Bourne or some other shell based on the UNIX operating system
Understand basic Digital UNIX concepts such as kernel, shell, process, configuration, and autoconfiguration
Understand how to use the Digital UNIX programming tools, compilers, and debuggers
Develop programs in an environment that involves dynamic memory allocation, linked list data structures, and multitasking
Understand the hardware device for which the driver is being written
Understand the basics of the CPU hardware architecture, including interrupts, direct memory access (DMA) operations, and I/O

Although the book assumes a strong background in UNIX-based operating systems and C programming, it does not assume any background in device drivers. In addition, the book assumes that the audience has no source code licenses.

A secondary audience is systems engineers who need to implement a new bus or make changes to the implementation of an existing bus. Topics of interest to this audience include descriptions of the bus structure members.

New and Changed Features

The following sections summarize the changes and additions made to this version of the book.

Organizational Changes

The following list summarizes the organizational changes made to the book:

The /dev/cb device driver no longer appears as an example. If you are still interested in studying the /dev/cb driver, see Writing TURBOchannel Device Drivers.
The /dev/none device driver example no longer appears in a single chapter. Instead, this example appears in several of the chapters in Part 3 to illustrate how to implement some of the character device driver interfaces.
Part 2 contains two new chapters. One chapter describes CPU and bus-related issues that affect device driver design. The other chapter describes issues related to porting device drivers.
Part 3 contains five new chapters that describe how to implement the interfaces for block and character device drivers. Whenever possible, the /dev/none device driver is used to illustrate how to implement the interface. For some interfaces, however, the /dev/xx driver is used to illustrate how to implement the interface.
Part 4 contains new chapters that describe the device driver kits delivery process and how to statically and dynamically configure device drivers into the kernel.
Chapter 18, Using Kernel Interfaces with Device Drivers, is rewritten to eliminate discussion of some kernel interfaces discussed in the chapters contained in Part 3.

Miscellaneous Changes

The following list summarizes miscellaneous changes made to the book:

Section 7.1.7 provides an example on how to register and enable an interrupt interface that is implemented to take advantage of the shared interrupt functionality.
The traditional device driver configuration model is no longer discussed. Digital recommends that third-party device driver writers use the automated tools to configure device drivers into the kernel. All instructions related to the traditional device driver configuration model have been deleted.
The uio and buf structures are now discussed in Section 8.1.2 and Section 9.3.3, respectively.
The ihandler_t and handler_intr_info structures are now discussed in Section 7.1.5.1 and Section 7.1.5.2, respectively.
The cfg_subsys_attr_t and cfg_attr_t structures are now discussed in Section 6.1 and Section 6.2, respectively.
Section 5.4.7 corrects errors regarding the description of the DEV_FUNNEL and DEV_FUNNELNULL that appeared in a previous version of the book.

Terminology Changes and Issues

The following list summarizes terminology changes and issues. See the Glossary for definitions of these new terms.

The term traditional device driver configuration model has been deleted and is no longer used.
The term third-party device driver configuration model has been deleted and replaced by the term device driver kits delivery process.
The term load module has been deleted and replaced by single binary module.
The term system configuration file has been replaced by target configuration file.
The terms static device driver and loadable device driver have been deleted and are no longer used. For this version of Digital UNIX you write one device driver that a system manager can statically or dynamically configure into the kernel.
The figures associated with the member descriptions for the bus, controller, and device structures in Chapter 17 have been removed. The figures no longer accurately depict how the autoconfiguration software populates these members. In addition, the way the autoconfiguration software populates these members may change in the future.

Scope of the Book

The book is directed towards users of the Digital UNIX operating system on computer systems developed by Digital Equipment Corporation. However, the book provides information on designing drivers, on data structures, and kernel interfaces that would be useful to any systems engineer interested in writing UNIX-based device drivers.

The book presents a simple fictitious device driver called /dev/none that introduces the driver development process. In addition, code fragments from a fictitious driver called /dev/xx illustrate how to set up and implement device driver interfaces that are not applicable to the /dev/none driver. Both driver examples show how to use many of the kernel support interfaces that device drivers call.

The book does not emphasize any specific types of device drivers. However, mastering the concepts and examples presented in this book would be very useful preparation for writing a variety of device drivers, including drivers for disk and tape controllers as well as more specialized drivers such as array processors.

Organization

The book contains the following chapters and appendixes.

Part 1 Overview

Part 1 contains one chapter, whose goal is to provide you with an overview of device drivers.

Chapter 1 Introduction to Device Drivers

Provides an overview of device drivers. Read this chapter to obtain introductory information on device drivers and to understand the place of a device driver in Digital UNIX.

Part 2 Anatomy of a Device Driver

Part 2 contains four chapters, whose combined goal is to provide the background information you need to write a simple Digital UNIX device driver.

Chapter 2 Developing a Device Driver

Describes how to design a device driver. Read this chapter if you are not familiar with the driver development process on Digital UNIX.

Chapter 3 Understanding CPU and Bus Issues That Influence Device Driver Design

Describes the CPU- and bus-related issues that influence the design of device drivers. Read this chapter to learn about issues you need to consider when you want to write device drivers that are portable across multiple Alpha CPU platforms and Digital-implemented bus architectures.

Chapter 4 Porting Digital UNIX Device Drivers

Discusses how to port device drivers from the ULTRIX operating system to the Digital UNIX operating system. The chapter also describes the issues you need to consider when deciding whether to update device drivers from previous versions of Digital UNIX to the current version of Digital UNIX. Read this chapter to obtain information about porting tasks.

Chapter 5 Analyzing the Structure of a Device Driver

Analyzes the sections that make up character and block device drivers. Read this chapter if you are not familiar with the sections that make up character and block drivers on Digital UNIX. If you have experience in writing UNIX device drivers, you may want to read selected sections, particularly the section that describes the header files you can include in your device drivers.

Part 3 Writing and Testing a Device Driver

Part 3 contains six chapters, whose combined goal is to provide the information you need to implement the device driver interfaces for block and character device drivers.

Chapter 6 Implementing a Configure Interface to Support Static and Dynamic Configuration

Describes how to implement a configure interface to support static and dynamic configuration of device drivers. Read this chapter if you are not familiar with the tasks associated with implementing this interface.

Chapter 7 Implementing Device Driver Interfaces That Support Device Autoconfiguration

Describes how to implement the probe and unattach interfaces. The chapter also shows you how to set up the attach and slave interfaces. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.

Chapter 8 Implementing Character Device Driver Interfaces

Describes how to implement the read, write, and select interfaces. The chapter also shows you how to set up the reset, stop, and mmap interfaces. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.

Chapter 9 Implementing Block Device Driver Interfaces

Describes how to set up the dump, psize, and strategy interfaces. Read this chapter if you are not familiar with the tasks associated with setting up these interfaces.

Chapter 10 Implementing Character and Block Device Driver Interfaces

Describes how to implement the open, close, and ioctl interfaces. The chapter also shows you how to set up an interrupt handler. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.

Chapter 11 Testing a Device Driver

Describes how to test a device driver. Read this chapter to learn how to write simple test programs for a device driver.

Part 4 Delivering Device Drivers

Part 4 contains three chapters, whose combined goal is to give you the information necessary to deliver device driver products to customers and to statically or dynamically configure these driver products into the Digital UNIX kernel. The Guide to Preparing Product Kits provides detailed information on how to create device driver product kits.

Chapter 12 Device Driver Kits Delivery Process

Provides an overview of the device driver kits delivery process. The overview provides a summary of the tasks performed during the device driver development, device driver kit development, and device driver installation phases. Read this chapter to obtain a general overview of the driver kits delivery process.

Chapter 13 Device Driver Configuration Files and File Fragments

Describes how some of the system management utilities use the files and file fragments related to device driver configuration. Read this chapter to learn how the system management utilities operate on these files and file fragments.

Chapter 14 Building a Device Driver

Discusses how to create the single binary module from the driver source file and how to statically and dynamically configure the single binary module into the kernel. Driver writers perform these tasks during the device driver development phase. Read this chapter to learn how to create the single binary module and how to statically and dynamically configure this single binary module into the kernel.

Part 5 Hardware Environment

Part 5 contains two chapters, whose combined goal is to provide you with a view into the device drivers' hardware environment.

Chapter 15 Hardware-Independent Model and Device Drivers

Provides an overview of the hardware-independent model and how it relates to device drivers. Read this chapter to gain an understanding of how device drivers fit into the hardware-independent model.

Chapter 16 Hardware Components and Hardware Activities

Describes the hardware components and activities related to device drivers. Read this chapter to obtain an understanding or to refresh your knowledge about the individual hardware components you will work with when writing your drivers.

Part 6 Kernel Environment

Part 6 contains two chapters, whose combined goal is to provide information about the kernel environment.

Chapter 17 Data Structures That the Autoconfiguration Software Uses

Discusses data structures related to device autoconfiguration. Read this chapter if you are not familiar with these data structures. If you have experience in writing UNIX device drivers, you may want to read selected sections, especially the sections that discuss data structure members that are not familiar to you.

Chapter 18 Using Kernel Interfaces with Device Drivers

Discusses the kernel interfaces that device drivers use most commonly, including those interfaces used to copy and move data. Read this chapter if you need examples of when, how, and why you would use these kernel interfaces in device drivers.

Part 7 Appendixes

Part 7 contains three appendixes and a glossary.

Appendix A Summary Tables

Presents tables that summarize the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

Appendix B Device Driver Example Source Listings

Contains the source code listing for the /dev/none example driver. It also contains the source code listing for a pseudodevice driver called /dev/edpseudo.

Appendix C Device Driver Development Worksheets

Provides worksheets for use in designing and coding a device driver.

Glossary Glossary

Provides definitions of terms used in the book.

Related Documentation

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience Icon Color Code

General users G Blue

System and network administrators S Red

Programmers P Purple

Device driver writers D Orange

Reference page users R Green

Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.

Writing device drivers is a complex task; driver writers require knowledge in a variety of areas. One way to acquire this knowledge is to have at least the following categories of documentation available:

Hardware documentation
Bus-specific device driver documentation
Operating system overview documentation
Programming tools documentation
Network programming documentation
System management documentation
Porting documentation
Kernel kits product documentation
Reference pages

The following sections list the documentation associated with each of these categories.

Hardware Documentation

You should have available the hardware manual associated with the device for which you are writing the device driver. You should also have access to the manual that describes the architecture associated with the CPU that the driver operates on, for example, the Alpha Architecture Reference Manual.

Bus-Specific Device Driver Documentation

Writing Device Drivers: Tutorial is the core manual for developing device drivers on the Digital UNIX operating system. It contains information needed for developing drivers on any bus that operates on Digital platforms. Writing Device Drivers: Advanced Topics and Writing Device Drivers: Reference are companion volumes to the tutorial.

Writing Device Drivers: Advanced Topics describes topics that are beyond the scope of the core tutorial. Systems engineers can find information on such advanced topics as kernel threads and writing device drivers in a symmetric multiprocessing (SMP) environment. This book also provides information on how to write disk device drivers.

Writing Device Drivers: Reference describes, in reference-page style, the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

The following books provide information about writing device drivers for a specific bus that is beyond the scope of the core tutorial, advanced topics, and reference:

Writing EISA and ISA Bus Device Drivers
This manual provides information for systems engineers who write device drivers for the EISA/ISA bus. The manual describes EISA/ISA bus-specific topics, including EISA/ISA bus architecture and data structures that EISA/ISA bus device drivers use.
Writing PCI Bus Device Drivers
This manual provides information for systems engineers who write device drivers for the PCI bus. The manual describes PCI bus-specific topics, including PCI bus architecture and data structures that PCI bus device drivers use.
Writing Device Drivers for the SCSI/CAM Architecture Interfaces
This manual provides information for systems engineers who write device drivers for the SCSI/CAM Architecture interfaces.
The manual provides an overview of the Digital UNIX SCSI/CAM Architecture and describes User Agent routines, data structures, common and generic routines and macros, error handling and debugging routines.
The manual includes information on configuration and installation. Examples show how programmers can define SCSI/CAM device drivers and write to the SCSI/CAM special I/O interface supplied by Digital to process special SCSI I/O commands.
Writing TURBOchannel Device Drivers
This manual contains information systems engineers need to write device drivers that operate on the TURBOchannel bus. The manual describes TURBOchannel-specific topics, including TURBOchannel kernel interfaces that TURBOchannel device drivers use.
Writing VMEbus Device Drivers
This manual contains information systems engineers need to write device drivers that operate on the VMEbus. The manual describes VMEbus-specific topics, including VMEbus architecture and kernel interfaces that VMEbus device drivers use. A VMEbus device driver example illustrates the use of these kernel interfaces.

Operating System Overview Documentation

Refer to the Technical Overview for a technical introduction to the Digital UNIX operating system. This manual provides a technical overview of the Digital UNIX system, focusing on the networking subsystem, the file system, virtual memory, and the development environment. In addition, the manual lists all system limits.

This manual does not supersede the Software Product Description (SPD), which is the definitive description of the Digital UNIX system.

Programming Tools Documentation

To create your device drivers, you use a number of programming development tools and should have on hand the manuals that describe how to use these tools. The following manuals provide information related to programming tools used in the Digital UNIX operating system environment:

Kernel Debugging
This manual provides information about debugging kernels. The manual describes using the dbx, kdbx, and kdebug debuggers to find problems in kernel code. It also describes how to write a kdbx utility extension and how to create and analyze a crash dump file.
This manual is for system administrators responsible for modifying, rebuilding, and debugging the kernel configuration. It is also for system programmers who need to debug their kernel space programs.
Programming Support Tools
This manual describes several commands and utilities in the Digital UNIX system, including facilities for text manipulation, macro and program generation, and source file management.
The commands and utilities described in this manual are primarily for programmers, but some of them (such as grep, awk, sed, and the Source Code Control System (SCCS)) are useful for other users. This manual assumes that you are a moderately experienced user of UNIX systems.
Programmer's Guide
This manual describes the programming environment of the Digital UNIX operating system, with an emphasis on the C programming language.
This manual is for all programmers who use the Digital UNIX operating system to create or maintain programs in any supported language.

Network Programming Documentation

Writing Device Drivers: Tutorial does not discuss how to write streams device drivers. However, Writing Device Drivers: Reference contains reference pages for kernel interfaces that STREAMS device drivers use. Refer to the Network Programmer's Guide for general information on STREAMS programming. This manual describes the Digital UNIX network programming environment. It describes in depth the X/Open Transport Interface (XTI) and the sockets and STREAMS programming frameworks, including information about system calls, header files, and libraries. Additionally, it provides information about porting sockets-based applications to XTI.

This manual also describes the software bridge ifnet (STREAMS module and DLPI STREAMS pseudodevice driver) that the Digital UNIX operating system supports. This bridge allows programs that use sockets-based protocol stacks to access STREAMS drivers, and programs that use STREAMS-based protocol stacks to access BSD-based drivers.

This manual is for experienced UNIX programmers and the reader is familiar with the following:

C language
Programming interfaces for UNIX operating systems
Basic data communications concepts, including the Open System Interconnection 7-layer model
Typical software interfaces at each layer of the OSI model
Requirements for writing communications applications

System Management Documentation

Refer to the System Administration manual for information about building a kernel and for general information on system administration. This manual describes how to configure, use, and maintain the Digital UNIX operating system. It includes information on general day-to-day activities and tasks, changing your system configuration, and locating and eliminating sources of trouble.

This manual is for the system administrators responsible for managing the operating system. It assumes a knowledge of operating system concepts, commands, and configurations.

Porting Documentation

Refer to the Digital UNIX Migration Guide for a discussion of the differences between the Digital UNIX and ULTRIX operating systems. This manual compares the Digital UNIX operating system to the ULTRIX operating system by describing the differences between the two systems.

This manual has three audiences, as follows:

General users can read this manual to determine the differences between using an ULTRIX system and using the Digital UNIX system.
System and network administrators can read this manual to determine the differences between ULTRIX and Digital UNIX system administration.
Programmers can read this manual to determine the differences between the ULTRIX programming environment and the Digital UNIX programming environment.

This manual assumes the reader is familiar with the ULTRIX operating system.

Kernel Kit Products Documentation

Refer to the Guide to Preparing Product Kits for information on how to create kernel (device driver) products kits. This manual provides the information that kit developers need to produce kernel products and layered products kits.

Reference Pages

The following reference pages are of interest to device driver writers:

Reference Pages Section 2
This section defines system calls (entries into the Digital UNIX kernel) that programmers use. The introduction to Section 2, intro(2), lists error numbers with brief descriptions of their meanings. The introduction also defines many of the terms used in this section. This section is for programmers.
Reference Pages Section 3
This section describes the routines available in Digital UNIX programming libraries, including the C library, Motif library, and X library. This section is for programmers. In printed format, this section is divided into six volumes.
Reference Pages Section 4
This section describes the format of system files and how the files are used. The files described include assembler and link editor output, system accounting, and file system formats. This section is for programmers and system administrators. In printed format, this section is divided into two volumes.
Reference Pages Section 5
This section contains miscellaneous information, including ASCII character codes, mail-addressing formats, text-formatting macros, and a description of the root file system. This section is for programmers and system administrators.
Reference Pages Section 7
This section describes special files, related device driver functions, databases, and network support. This section is for programmers and system administrators.
Reference Pages Section 8 and 1m
This section describes commands for system operation and maintenance. It is for system administrators. In printed format, this section is divided into two volumes.

Reader's Comments

Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals.

You can send your comments in the following ways:

Fax: 603-881-0120 Attn: UEG Publications, ZK03-3/Y32
Internet electronic mail: readers_comment@zk3.dec.com
A Reader's Comment form is located on your system in the following location:
```
/usr/doc/readers_comment.txt
```
Mail:
Digital Equipment Corporation
UEG Publications Manager
ZK03-3/Y32
110 Spit Brook Road
Nashua, NH 03062-9987
A Reader's Comment form is located in the back of each printed manual. The form is postage paid if you mail it in the United States.

Please include the following information along with your comments:

The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
The section numbers and page numbers of the information on which you are commenting.
The version of Digital UNIX that you are using.
If known, the type of processor that is running the Digital UNIX software.

The Digital UNIX Publications group cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.

Conventions

The following conventions are used in this book:

.
.
.
A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.

. . . In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.

filename In examples, syntax descriptions, and function definitions, this typeface indicates variable values.

buf In function definitions this typeface is used to indicate names that you must type exactly as shown.

[ ] In formal parameter declarations in function definitions and in structure declarations, brackets indicate arrays. Brackets are also used to specify ranges for device minor numbers and device special files in sysconfigtab file fragments.

This book uses the word kernel ``interface'' instead of kernel ``routine'' or kernel ``macro.''

Chapter 1	Introduction to Device Drivers
	Provides an overview of device drivers. Read this chapter to obtain introductory information on device drivers and to understand the place of a device driver in Digital UNIX.

Chapter 2	Developing a Device Driver
	Describes how to design a device driver. Read this chapter if you are not familiar with the driver development process on Digital UNIX.
Chapter 3	Understanding CPU and Bus Issues That Influence Device Driver Design
	Describes the CPU- and bus-related issues that influence the design of device drivers. Read this chapter to learn about issues you need to consider when you want to write device drivers that are portable across multiple Alpha CPU platforms and Digital-implemented bus architectures.
Chapter 4	Porting Digital UNIX Device Drivers
	Discusses how to port device drivers from the ULTRIX operating system to the Digital UNIX operating system. The chapter also describes the issues you need to consider when deciding whether to update device drivers from previous versions of Digital UNIX to the current version of Digital UNIX. Read this chapter to obtain information about porting tasks.
Chapter 5	Analyzing the Structure of a Device Driver
	Analyzes the sections that make up character and block device drivers. Read this chapter if you are not familiar with the sections that make up character and block drivers on Digital UNIX. If you have experience in writing UNIX device drivers, you may want to read selected sections, particularly the section that describes the header files you can include in your device drivers.

Chapter 6	Implementing a Configure Interface to Support Static and Dynamic Configuration
	Describes how to implement a `configure` interface to support static and dynamic configuration of device drivers. Read this chapter if you are not familiar with the tasks associated with implementing this interface.
Chapter 7	Implementing Device Driver Interfaces That Support Device Autoconfiguration
	Describes how to implement the `probe` and `unattach` interfaces. The chapter also shows you how to set up the `attach` and `slave` interfaces. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.
Chapter 8	Implementing Character Device Driver Interfaces
	Describes how to implement the `read`, `write`, and `select` interfaces. The chapter also shows you how to set up the `reset`, `stop`, and `mmap` interfaces. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.
Chapter 9	Implementing Block Device Driver Interfaces
	Describes how to set up the `dump`, `psize`, and `strategy` interfaces. Read this chapter if you are not familiar with the tasks associated with setting up these interfaces.
Chapter 10	Implementing Character and Block Device Driver Interfaces
	Describes how to implement the `open`, `close`, and `ioctl` interfaces. The chapter also shows you how to set up an interrupt handler. Read this chapter if you are not familiar with the tasks associated with implementing or setting up these interfaces.
Chapter 11	Testing a Device Driver
	Describes how to test a device driver. Read this chapter to learn how to write simple test programs for a device driver.

Chapter 12	Device Driver Kits Delivery Process
	Provides an overview of the device driver kits delivery process. The overview provides a summary of the tasks performed during the device driver development, device driver kit development, and device driver installation phases. Read this chapter to obtain a general overview of the driver kits delivery process.
Chapter 13	Device Driver Configuration Files and File Fragments
	Describes how some of the system management utilities use the files and file fragments related to device driver configuration. Read this chapter to learn how the system management utilities operate on these files and file fragments.
Chapter 14	Building a Device Driver
	Discusses how to create the single binary module from the driver source file and how to statically and dynamically configure the single binary module into the kernel. Driver writers perform these tasks during the device driver development phase. Read this chapter to learn how to create the single binary module and how to statically and dynamically configure this single binary module into the kernel.

Chapter 15	Hardware-Independent Model and Device Drivers
	Provides an overview of the hardware-independent model and how it relates to device drivers. Read this chapter to gain an understanding of how device drivers fit into the hardware-independent model.
Chapter 16	Hardware Components and Hardware Activities
	Describes the hardware components and activities related to device drivers. Read this chapter to obtain an understanding or to refresh your knowledge about the individual hardware components you will work with when writing your drivers.

Chapter 17	Data Structures That the Autoconfiguration Software Uses
	Discusses data structures related to device autoconfiguration. Read this chapter if you are not familiar with these data structures. If you have experience in writing UNIX device drivers, you may want to read selected sections, especially the sections that discuss data structure members that are not familiar to you.
Chapter 18	Using Kernel Interfaces with Device Drivers
	Discusses the kernel interfaces that device drivers use most commonly, including those interfaces used to copy and move data. Read this chapter if you need examples of when, how, and why you would use these kernel interfaces in device drivers.

Appendix A	Summary Tables
	Presents tables that summarize the header files, kernel interfaces, data structures, and other interfaces that device drivers use.
Appendix B	Device Driver Example Source Listings
	Contains the source code listing for the `/dev/none` example driver. It also contains the source code listing for a pseudodevice driver called `/dev/edpseudo`.
Appendix C	Device Driver Development Worksheets
	Provides worksheets for use in designing and coding a device driver.
Glossary	Glossary
	Provides definitions of terms used in the book.

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

. . .	A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.
. . .	In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.
`filename`	In examples, syntax descriptions, and function definitions, this typeface indicates variable values.
`buf`	In function definitions this typeface is used to indicate names that you must type exactly as shown.
`[ ]`	In formal parameter declarations in function definitions and in structure declarations, brackets indicate arrays. Brackets are also used to specify ranges for device minor numbers and device special files in `sysconfigtab` file fragments.