Subject: Linux-Activists - Channel DOC digest. 92-11-22-19:24
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Wed, 23 Dec 1992 03:21:42 +0200

Topics:
	 Devices in man pages
	 Re: Linux-Activists - Channel DOC digest. 92-11-22-16:39

----------------------------------------------------------------------

From: Matt Welsh <[email-masked]>
Subject: Devices in man pages
Date: Tue, 22 Dec 1992 21:00:46 +0200

Rick: devices ARE in man pages, on some systems at least. I know that on
DG/UX I could do "man rmt" to a description of the tape device driver, and
so on for almost all of the devices. I honestly think it would be a great
idea for devices to be covered by man pages for Linux as well. It would be 
cool to type 'man scsi' to see documentation on the scsi driver, known
bugs, the use of the driver, and so on. It's not difficult to do, and you 
don't need a speerate man page for EACH device... you'll want one man page
for 'hda'/'hdb', one for 'fd...' and so on. 

I don't know what kind of UNIX you've been using, but on systems I'm familiar
with (which is a good number), I've run into device man pages more than once.

mdw

------------------------------

From: Rik Faith <[email-masked]>
Subject: Re: Linux-Activists - Channel DOC digest. 92-11-22-16:39
Date: Tue, 22 Dec 1992 22:22:16 +0200

"Linux Activists" wrote (Tue, 22 Dec 1992 20:35:51 +0200):
> From: Rick Miller <[email-masked]>
> Subject: Do Devices belong in "man" pages?
> Date: Tue, 22 Dec 1992 14:58:26 +0200

> BTW:  I've been a UNIX[tm] user for about seven years, and an avidly
>         curious one at that... but I've never heard of "man" pages for
>         device names.  Let's not get wierd here.  You just can't put
>         *everything* in "man" pages.

See section 4 of the Manual.  This is sometimes part of the "system
manager's manual."  Here is an example draft of a more complete man page
for the sd interface.  (It is based loosely on the Sun man page format.)

For Linux, the man pages need to spend a bit more time on major and minor
numbers and should follow the tradition of commenting on how to configure
the device in the kernel.  The other major part of a traditional section 4
man page is a reference for the ioctl's associated with the device.
Section 4 man pages are essential for low level programming.

SD(4)               Linux Programmer's Manual               SD(4)

NAME
       sd - Driver for SCSI Disk Drives

SYNOPSIS
       #include <linux/hdreg.h>

CONFIG
       The  block device name has the following form: sdlp, where
       l is a letter denoting the physical drive, and p is a num-
       ber denoting the partition on that physical drive.  Often,
       the partition number, p, will be left off when the  device
       corresponds to the whole drive.

       SCSI  disks  have  a major device number of 8, and a minor
       device number of the form (16  *  drive_number)  +  parti-
       tion_number, where drive_number is the number of the phys-
       ical drive in order of detection, and partition_number  is
       as follows:

       parition 0 is the whole drive
       partitions 1-4 are the DOS "primary" partitions
       partitions  5-8 are the DOS "extended" (or "logical") par-
       titions

       For example, /dev/sda will have major 8, minor 0, and will
       refer  to  all  of the first SCSI drive in the system; and
       /dev/sdb3 will have major 8, minor 19, and will  refer  to
       the third DOS "primary" partition on the second SCSI drive
       in the system.

       At this  time,  only  block  devices  are  provided.   Raw
       devices have not yet been implemented.

DESCRIPTION
       The following ioctl's are provided:

       HDIO_REQ
              Returns  the  BIOS disk parameters in the following
              structure:
                     struct hd_geometry {
                           unsigned char heads;
                           unsigned char sectors;
                           unsigned short cylinders;
                           unsigned long start;
                     };

              A pointer  to  this  structure  is  passed  as  the
              ioctl(2) parameter.

              The  information  returned  in the parameter is the
              disk geometry of the drive as  understood  by  DOS!
              This  geometry  is not the physical geometry of the
              drive.  It is used when  constructing  the  drive's
              partition   table,   however,  and  is  needed  for

                     Thu Dec 17 10:15:53 1992                   1

SD(4)               Linux Programmer's Manual               SD(4)

              convenient  operation  of  fdisk(1),efdisk(1),  and
              lilo(1).  If the geometry information is not avail-
              able, zero will be returned for all of the  parame-
              ters.

       BLKGETSIZE
              Returns  the  device size in sectors.  The ioctl(2)
              parameter should be a pointer to a long.

       BLKRRPART
              Forces a re-read of the SCSI disk partition tables.
              No parameter is needed.

              The  scsi(4)  ioctl's  are  also supported.  If the
              ioctl(2) parameter is required,  and  it  is  NULL,
              then ioctl(2) will return -EINVAL.

FILES
       /dev/sd[a-h]: the whole device
       /dev/sd[a-h][0-8]: individual block partitions

SEE ALSO
       scsi(4)

                     Thu Dec 17 10:15:53 1992                   2

------------------------------

End of DOC Digest
*****************
-------