1 files changed, 187 insertions, 28 deletions
diff --git a/usr/src/man/man4/Intro.4 b/usr/src/man/man4/Intro.4
index ce2f7eb2f7..2f7fabf221 100644
--- a/usr/src/man/man4/Intro.4
+++ b/usr/src/man/man4/Intro.4
@@ -1,3 +1,6 @@
+.\" Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright 1989 AT&T
+.\" Copyright 2020 Joyent, Inc.
 .\"
 .\" The contents of this file are subject to the terms of the
 .\" Common Development and Distribution License (the "License").
@@ -14,37 +17,193 @@
 .\" fields enclosed by brackets "[]" replaced with your own identifying
 .\" information: Portions Copyright [yyyy] [name of copyright owner]
 .\"
-.\"
-.\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
-.\" Copyright 1989 AT&T
-.\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
-.\"
-.Dd Mar 18, 2015
+.Dd January  6, 2020
 .Dt INTRO 4
 .Os
 .Sh NAME
 .Nm Intro ,
 .Nm intro
-.Nd introduction to file formats and configurations
+.Nd introduction to special files
 .Sh DESCRIPTION
-This section outlines the formats of various files and configurations of
-various subsystems.
-The C structure declarations for the file formats are given where applicable.
-Usually, the headers containing these structure declarations can be found in the
-directories
-.Pa /usr/include
-or
-.Pa /usr/include/sys .
-For inclusion in C language programs, however, the syntax
-.Sy #include
-.Sm off
-<
-.Em filename.h No >
-.Sm on
-or
-.Sy #include
-.Sm off
-<
-.Sy sys/ Em filename.h No >
-.Sm on
-should be used.
+This section describes various device and network interfaces available on the
+sysstem.
+The types of interfaces described include character and block
+devices,
+.Sy STREAMS
+modules, network protocols, file systems, and ioctl requests
+for driver subsystems and classes.
+.Pp
+This section contains the following major collections:
+.Bl -tag -width "xxxxx"
+.It Pq Sy 4D
+The system provides drivers for a variety of hardware devices, such as disk,
+magnetic tapes, serial communication lines, mice, and frame buffers, as well
+as virtual devices such as pseudo-terminals and windows.
+.Pp
+This section describes special files that refer to specific hardware
+peripherals and device drivers.
+.Sy STREAMS
+device drivers are also described.
+Characteristics of both the hardware device and the corresponding device driver
+are discussed where applicable.
+.Pp
+An application accesses a device through that device's special file.
+This
+section specifies the device special file to be used to access the device as
+well as application programming interface (API) information relevant to the use
+of the device driver.
+All device special files are located under the
+.Pa /devices
+directory.
+The
+.Pa /devices
+directory hierarchy attempts to mirror the hierarchy of system
+busses, controllers, and devices configured on the system.
+Logical device names for special files in
+.Pa /devices
+are located under the
+.Pa /dev
+directory.
+Although not every special file under
+.Pa /devices
+will have a corresponding logical entry under
+.Pa /dev ,
+whenever possible, an
+application should reference a device using the logical name for the device.
+Logical device names are listed in the
+.Sy FILES
+section of the page for the device in question.
+.Pp
+This section also describes driver configuration where applicable.
+Many device drivers have a driver configuration file of the form
+.Em driver_name Ns \&.conf
+associated with them (see
+.Xr driver.conf 5 ) .
+The configuration information stored in the driver
+configuration file is used to configure the driver and the device.
+Driver configuration files are located in
+.Pa /kernel/drv
+and
+.Pa /usr/kernel/drv .
+Driver configuration files for platform dependent
+drivers are located in
+.Pa /platform/`uname\ -i`/kernel/drv
+where
+.Pa `uname\ -i`
+is the output of the
+.Xr uname 1
+command with the
+.Fl i
+option.
+.Pp
+Some driver configuration files may contain user configurable properties.
+Changes in a driver's configuration file will not take effect until the system
+is rebooted or the driver has been removed and re-added (see
+.Xr rem_drv 8
+and
+.Xr add_drv 8 ) .
+.It Pq Sy 4FS
+This section describes the programmatic interface for several file systems
+supported by SunOS.
+.It Pq Sy 4I
+This section describes ioctl requests which apply to a class of drivers or
+subsystems.
+For example, ioctl requests which apply to most tape devices are
+discussed in
+.Xr mtio 4I .
+Ioctl requests relevant to only a specific
+device are described on the man page for that device.
+The page for the device
+in question should still be examined for exceptions to the ioctls listed in
+section 4I.
+.It Pq Sy 4M
+This section describes
+.Sy STREAMS
+modules.
+Note that
+.Sy STREAMS
+drivers are discussed in section 4D.
+.Xr streamio 4I
+contains a list of ioctl requests used to manipulate
+.Sy STREAMS
+modules and interface with the
+.Sy STREAMS
+framework.
+.Xr ioctl 2
+requests specific to a
+.Sy STREAMS
+module will be discussed on the man page for that module.
+.It Pq Sy 4P
+This section describes various network protocols available in SunOS.
+SunOS supports both socket-based and
+.Sy STREAMS Ns -based
+network communications.
+.Pp
+The Internet protocol family, described in
+.Xr inet 4P ,
+is the primary protocol family supported by SunOS, although the system can
+support a number of others.
+The raw interface provides low-level services, such as
+packet fragmentation and reassembly, routing, addressing, and basic transport
+for socket-based implementations.
+Facilities for communicating using an
+Internet-family protocol are generally accessed by specifying the
+.Dv AF_INET
+address family when binding a socket; see
+.Xr socket 3SOCKET
+for details.
+.Pp
+Major protocols in the Internet family include:
+.Bl -bullet -offset indent
+.It
+The Internet Protocol (IP) itself, which supports the universal datagram
+format, as described in
+.Xr ip 4P .
+This is the default protocol for
+.Dv SOCK_RAW
+type sockets within the
+.Dv AF_INET
+domain.
+.It
+The Transmission Control Protocol (TCP); see
+.Xr tcp 4P .
+This is the default protocol for
+.Dv SOCK_STREAM
+type sockets.
+.It
+The User Datagram Protocol (UDP); see
+.Xr udp 4P .
+This is the default
+protocol for
+.Dv SOCK_DGRAM
+type sockets.
+.It
+The Address Resolution Protocol (ARP); see
+.Xr arp 4P .
+.It
+The Internet Control Message Protocol (ICMP); see
+.Xr icmp 4P .
+.El
+.El
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr Intro 3 ,
+.Xr socket 3SOCKET ,
+.Xr st 4D ,
+.Xr mtio 4I ,
+.Xr streamio 4I ,
+.Xr arp 4P ,
+.Xr icmp 4P ,
+.Xr inet 4P ,
+.Xr ip 4P ,
+.Xr tcp 4P ,
+.Xr udp 4P ,
+.Xr driver.conf 5 ,
+.Xr add_drv 8 ,
+.Xr rem_drv 8
+.Pp
+.%T System Administration Guide: IP Services
+.Pp
+.%T STREAMS Programming Guide
+.Pp
+.%T Writing Device Drivers