Major overhaul of sunlabel(8).

. Implement option -c, all partition sizes will be calculated
  in cylinders as opposed to sectors.  Since the Sun label is
  inherently cylinder-based, this makes the job a little easier.

. Implement option -h, print the label in `human readable'
  size/offset format.

. Implement SVR4-compatible VTOC-style elements.  They are
  fully optional, defaulting to the current behaviour where no
  VTOC-style table will be written to disk.  However, if
  desired, the full functionality of the partitioning menu of
  Solaris' format(1m) is now offered (and even more).

. When editing the label, do not loop around edit_label() where
  a new template file is generated for each turn, this used to
  be annoying in that any possible syntax error caused a
  complaint, but then the template was created anew, so the
  user had to perform all their editing again.  Rather loop
  inside edit_label(), similar to bsdlabel(8), so in case of
  errors, the user will be presented their previous template
  file again.

. If VTOC-style elements are present, the overlap checks are
  made less stringent.  Overlaps will still be warned about,
  but overlaps of `unmountable' partitions against other ones
  are no longer fatal.  That way, e. g. VxVM encapsulated
  disk labels can be fully edited in FreeBSD (but not in
  Solaris ;-).

. In print_label(), generate the editing hints only if the -e
  flag is in effect.  Additionally, print a hint about the
  total number of sectors in the (hardware) medium.

. When editing a label, allow for changing the geometry
  emulation (and textual name) by modifying the "text:" line
  on top.  That way, a more effective emulation can be
  chosen.

. When editing/reading a label, additionally allow for the
  suffixes `s' (512-byte sectors), and `c' (cylinders) in the
  partition size field.

. Finally, turn the stub man page into something that really
  explains the entire thing.

1 files changed, 352 insertions, 6 deletions

diff --git a/sbin/sunlabel/sunlabel.8 b/sbin/sunlabel/sunlabel.8
index 4e56507..d2d2cff 100644
--- a/sbin/sunlabel/sunlabel.8
+++ b/sbin/sunlabel/sunlabel.8
@@ -1,5 +1,7 @@
 .\" Copyright (c) 2004
 .\"	David E. O'Brien.  All rights reserved.
+.\" Copyright (c) 2004
+.\"	Joerg Wunsch.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -24,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 29, 2004
+.Dd June 1, 2004
 .Dt SUNLABEL 8
 .Os
 .Sh NAME
@@ -33,6 +35,7 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl r
+.Op Fl c No \&| Fl h
 .Ar disk
 .Nm
 .Fl B
@@ -44,35 +47,378 @@
 .Op Fl B Op Fl b Ar boot1
 .Op Fl r
 .Op Fl n
-.Ar disk profile
+.Op Fl c
+.Ar disk protofile
 .Nm
 .Fl e
 .Op Fl B Op Fl b Ar boot1
 .Op Fl r
 .Op Fl n
+.Op Fl c
 .Ar disk
 .Nm
 .Fl w
 .Op Fl B Op Fl b Ar boot1
 .Op Fl r
 .Op Fl n
+.Op Fl c
 .Ar disk type
 .Sh DESCRIPTION
 The
 .Nm
 utility
-installs, examines or modifies the bootable
-.Fx
-label on a disk partition.
+installs, examines or modifies the
+.Em Sun OpenBoot PROM
+label on a disk.
 In addition,
 .Nm
 can install bootstrap code.
+.Ss Introduction
+.Pp
+The label occupies the first sector (i. e. 512 bytes) of each disk.
+It starts with a textual description which by convention also mentions
+the disk geometry in textual form (number of cylinders, alternate
+cylinders, heads, and sectors per track), optionally followed by a
+table of SVR4-compatible VTOC tags and flags per partition, followed
+by the partition table itself.
+Finally, a checksum is recorded to ensure the label has not been
+tampered with.
+.Pp
+The
+.Em Sun OpenBoot PROM
+label allows for 8 disk partitions.
+The partition table lists the starting cylinder of the partition,
+plus the size of the partition in 512-byte sectors.
+Thus, partitions in the
+.Em Sun OpenBoot PROM
+must always start at a cylinder boundary (for whatever geometry
+emulation has been chosen).
+.Pp
+The optional SVR4-compatible VTOC tag and flags table is not used
+by the
+.Fx
+kernel.
+It is maintained solely for compatibilty with the
+.Em Solaris
+operating system that might share disks with
+.Fx
+on the same hardware platform.
+.Pp
+The
+.Em Sun OpenBoot PROM
+label is natively understood by the underlying hardware, which can
+bootstrap from a single partition entry, as opposed to the very first
+block(s) of the entire disk as on many other hardware platforms.
+.Pp
+Note that the hardware platform mandates that two cylinders are set
+aside as
+.Em alternate cylinders
+which are not available to user programs (and not even through the
+.Ql backup
+partition).
+.Ss Options
+Options are listed in alphabetical order here.
+Note that only those option combinations listed under
+.Sx SYNOPSIS
+are allowable.
+.Pp
+.Bl -tag -width ".Fl b Ar bootpath"
+.It Fl b Ar bootpath
+Specify that
+.Ar bootpath
+is to be used as the boot image, rather than the default of
+.Pa /boot/boot1 .
+.It Fl B
+Install bootstrap code onto the disk.
+Note that since the underlying hardware platform bootstraps from
+partitions, not disks, this operation is only useful if there is
+a partition starting at offset 0.
+.It Fl c
+Use cylinders for partition size display rather than
+(512-byte) sectors.
+This also changes the default interpretation of the partition
+size entries when editing the label, or reading from a prototype
+file.
+Thus, prototype files are only compatible when both, obtaining
+the file and re-installing it is done using the same
+.Fl c
+option setting.
+.It Fl e
+Enter edit mode.
+See
+.Sx Edit mode
+below for a more detailed explanation.
+.It Fl h
+When displaying the label, make the partition size and offset
+values
+.Dq human readable .
+The displayed numbers will get a suffix of
+.Ql B
+for bytes,
+.Ql K
+for 1024 bytes each,
+.Ql M
+for 1048576 bytes each, or
+.Ql G
+for 1073741824 bytes each appended.
+Note that due to possible rounding errors, prototype files
+obtained using the
+.Fl h
+option are not suited for re-installing using the
+.Fl R
+option.
+.It Fl n
+No changes.
+All operations, checks etc. are performed normally, but nothing
+is written to disk.
+.It Fl r
+Obsolete option that used to indicate that the operation should
+be done directly on disk, as opposed through the respective kernel
+services.
+Ignored.
+.It Fl R
+Restore label from the prototype in
+.Ar protofile .
+A prototype file is simply the textual representation of the
+label as printed using the first form of the
+.Nm
+utility shown in the
+.Sx SYNOPSIS .
+Note that the
+.Fl c
+option used to obtain the prototype must match the option used
+when restoring the label (both present, or both absent).
+.It Fl w
+Write mode.
+Suitable to write an initial label to disk.
+The
+.Ar type
+argument used to be an entry into a table of predefined labels,
+but this functionality is not supported by
+.Nm .
+Instead, the only allowable
+.Ar type
+argument is the string
+.Dq auto ,
+indicating that an automatically created label should be written
+to disk.
+This automatism will try to create an initial label that fits as
+best as possible into the available disk capacity.
+.El
+.Pp
+If neither of the
+.Fl e ,
+.Fl R ,
+or
+.Fl w
+options is present, the existing label for
+.Ar disk
+will be printed to standard output.
+.Pp
+.Ar disk
+must be given as a plain disk name, without any leading
+.Pa /dev/ .
+.Ss Edit mode
+In edit mode, the existing label from
+.Ar disk
+will be read, and put into a template file.
+The command referenced by the
+.Ev EDITOR
+environmental variable will be started to allow the user
+to edit the label.
+The label is then checked and examined for any errors.
+If no errors have been found, the new label is written to disk.
+If there were any errors, a message is printed to standard
+error output, and the user is asked whether they want to edit
+the template file again.
+If accepted, editing starts over, if declined, no changes will
+be written to disk.
+.Pp
+The label presented for editing is the same as the standard
+printout, with some added hints about the possible options to
+specify the sector size and starting cylinder.
+There are two areas in the template that can be edited:
+.Pp
+.Bl -tag -width indent
+.It Sy Textual label, geometry emulation
+The line
+.Dl "text: XXXX cyl CC alt 2 hd HH sec SS"
+represents the label text.
+It must be retained exactly in the form shown.
+The editable text
+.Sy XXXX
+is a simple (non-whitespace) text describing the disk.
+By convention, this text mentions the approximate size of the
+disk, as in
+.Ql SUN9.0G
+for a 9 GB disk shipped by Sun.
+.Pp
+The values
+.Sy CC ,
+.Sy HH ,
+and
+.Sy SS
+describe the number of cylinders, heads (aka. tracks per
+cylinder), and sectors per track respectively.
+They might be modified to change the geometry emulation.
+Each number must be between 1 and 65535.
+The product
+.D1 Em (CC + 2) * HH * SS
+must be less than or equal to the total number of sectors of the
+disk (which is given as a hint in a comment field).
+.It Sy Partition entries
+Partition entries start with a letter from
+.Ql a
+through
+.Ql h ,
+immediately followed by a colon, followed by the size of this
+partition, and the starting cylinder of the partition.
+The unit of the size field defaults to sectors, or to cylinders
+if the
+.Fl c
+option is in effect.
+Alternatively, a different unit may be specified by appending
+.Ql s
+for (512-byte) sectors,
+.Ql c
+for cylinders,
+.Ql k
+for kilobytes,
+.Ql m
+for megabytes, or
+.Ql g
+for gigabytes.
+The last partition entry may specify the size as
+.Ql \&*
+to indicate that this entry should consume the rest of disk not
+consumed by any other partition so far.
+.Pp
+The start of partition is always taken as a cylinder number (starting
+at 0) since this is what the underlying hardware uses.
+Alternatively, specifying it as
+.Ql \&*
+will make the computation automatically chose the nearest possible
+cylinder boundary.
+.Pp
+Partition
+.Ql c
+must always be present, must start at 0, and must cover the entire
+disk (without considering the alternate cylinders though).
+.Pp
+Optionally, each partition entry may be followed by an SVR4-compatible
+VTOC tag name, and a flag description.
+The following VTOC tag names are known:
+.Bl -column -offset indent ".Li unassigned" ".Sy value" ".Sy comment"
+.It Sy name Ta Sy value Ta Sy comment
+.It Li unassigned Ta No 0x00
+.It Li boot Ta No 0x01
+.It Li root Ta No 0x02
+.It Li swap Ta No 0x03
+.It Li usr Ta No 0x04
+.It Li backup Ta No 0x05 Ta c partition, entire disk
+.It Li stand Ta No 0x06
+.It Li var Ta No 0x07
+.It Li home Ta No 0x08
+.It Li altsctr Ta No 0x09 Ta alternate sector partition
+.It Li cache Ta No 0x0a Ta Solaris cachefs partition
+.It Li VxVM_pub Ta No 0x0e Ta VxVM public region
+.It Li VxVM_priv Ta No 0x0f Ta VxVM private region
+.El
+.Pp
+The following VTOC flags are known:
+.Bl -column -offset indent ".Sy name" ".Sy value" ".Sy comment"
+.It Sy name Ta Sy value Ta Sy comment
+.It Li wm Ta No 0x00 Ta read/write, mountable
+.It Li wu Ta No 0x01 Ta read/write, unmountable
+.It Li rm Ta No 0x10 Ta read/only, mountable
+.It Li ru Ta No 0x11 Ta read/only, unmountable
+.El
+.Pp
+Optionally, both the tag and/or the flag name may be specified
+numerically, using standard
+.Ql C
+numerial notation (prefix
+.Ql 0x
+for hexadecimal numbers,
+.Ql 0
+for octal numbers).
+If the flag field is omitted, it defaults to
+.Ql wm .
+If the tag field is also omitted, it defaults to
+.Ql unassigned .
+If none of the partitions lists any VTOC tag/flags, no
+SVR4-compatible VTOC elements will be written to disk.
+If VTOC-style elements are present, partition
+.Ql c
+must be marked as
+.Ql backup 
+(and should be marked
+.Ql wu ) .
+.El
+.Pp
+When checking the label, partition
+.Ql c
+is checked for presence, and for the mentioned restrictions.
+All other partitions are checked for possible overlaps, as
+well as for not extending past the end of unit.
+If VTOC-style elements are present, overlaps of unmountable
+partitions against other partitions will be warned still but
+do not cause a rejection of the label.
+That way,
+.Em encapsulated disks
+of volume management software are acceptable as long as the
+volume management partitions are clearly marked as unmountable.
+.Pp
+Any other fields in the label template are informational only,
+and will not be parsed when reading the label.
+.Pp
+Note that when changing the geometry emulation by editing the
+textual description line, all partition entries will be
+considered based on the new geometry emulation.
+.Sh ENVIRONMENT
+.Bl -tag -width ".Ev EDITOR" -compact
+.It Ev EDITOR
+Name of the command to edit the template file in edit-mode.
+Defaults to
+.Xr vi 1 .
+.El
 .Sh FILES
 .Bl -tag -width ".Pa /boot/boot1" -compact
 .It Pa /boot/boot1
 Default boot image.
 .El
 .Sh SEE ALSO
+.Xr vi 1 ,
 .Xr geom 4 ,
-.Xr disktab 5 ,
 .Xr bsdlabel 8
+.Sh HISTORY
+The
+.Nm
+utility appeared in
+.Fx 5.1 .
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Jake Burkholder ,
+modeling it after the
+.Xr bsdlabel 8
+command available on other architectures.
+.Pp
+.An -nosplit
+This man page was initially written by
+.An David O'Brien ,
+and later substantially updated by
+.An J\(:org Wunsch .
+.Sh BUGS
+Installing bootstrap code onto an entire disk is merely pointless.
+.Nm
+should rather support installing bootstrap code into a partition
+instead.
+.Pp
+The
+.Dq auto
+layout algorithm could be smarter.
+By now, it tends to emulate fairly large cylinders which due to
+the two reserved alternate cylinders causes a fair amount of
+wasted disk space.