2 .\" David E. O'Brien. All rights reserved.
3 .\" Copyright (c) 2004, 2005
4 .\" Joerg Wunsch. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .Nd read and write disk pack label suitable for Sun's OpenBoot PROM
47 .Op Fl B Op Fl b Ar boot1
54 .Op Fl B Op Fl b Ar boot1
61 .Op Fl B Op Fl b Ar boot1
70 installs, examines or modifies the
75 can install bootstrap code.
77 The label occupies the first sector (i.e., 512 bytes) of each disk.
78 It starts with a textual description which by convention also mentions
79 the disk geometry in textual form (number of cylinders, alternate
80 cylinders, heads, and sectors per track), optionally followed by a
81 table of SVR4-compatible VTOC tags and flags per partition, followed
82 by the partition table itself.
83 Finally, a checksum is recorded to ensure the label has not been
88 label allows for 8 disk partitions.
89 The partition table lists the starting cylinder of the partition,
90 plus the size of the partition in 512-byte sectors.
91 Thus, partitions in the
93 must always start at a cylinder boundary (for whatever geometry
94 emulation has been chosen).
96 The optional SVR4-compatible VTOC tag and flags table is not used
100 It is maintained solely for compatibilty with the
102 operating system that might share disks with
104 on the same hardware platform.
107 .Em Sun OpenBoot PROM
108 label is natively understood by the underlying hardware, which can
109 bootstrap from a single partition entry, as opposed to the very first
110 block(s) of the entire disk as on many other hardware platforms.
112 Note that the hardware platform mandates that two cylinders are set
114 .Em alternate cylinders
115 which are not available to user programs (and not even through the
119 Options are listed in alphabetical order here.
120 Note that only those option combinations listed under
124 .Bl -tag -width ".Fl b Ar bootpath"
128 is to be used as the boot image, rather than the default of
131 Install bootstrap code onto the disk.
132 Note that since the underlying hardware platform bootstraps from
133 partitions, not disks, this operation is only useful if there is
134 a partition starting at offset 0.
136 Use cylinders for partition size display rather than
138 This also changes the default interpretation of the partition
139 size entries when editing the label, or reading from a prototype
141 Thus, prototype files are only compatible when both, obtaining
142 the file and re-installing it is done using the same
149 below for a more detailed explanation.
151 When displaying the label, make the partition size and offset
154 The displayed numbers will get a suffix of
160 for 1048576 bytes each, or
162 for 1073741824 bytes each appended.
163 Note that due to possible rounding errors, prototype files
166 option are not suited for re-installing using the
171 All operations, checks etc., are performed normally, but nothing
174 Obsolete option that used to indicate that the operation should
175 be done directly on disk, as opposed through the respective kernel
179 Restore label from the prototype in
181 A prototype file is simply the textual representation of the
182 label as printed using the first form of the
188 option used to obtain the prototype must match the option used
189 when restoring the label (both present, or both absent).
192 Suitable to write an initial label to disk.
195 argument used to be an entry into a table of predefined labels,
196 but this functionality is not supported by
198 Instead, the only allowable
200 argument is the string
202 indicating that an automatically created label should be written
204 This automatism will try to create an initial label that fits as
205 best as possible into the available disk capacity.
212 options are present, the existing label for
214 will be printed to standard output.
219 must be given as a plain disk name, without any leading
222 In edit mode, the existing label from
224 will be read, and put into a template file.
225 The command referenced by the
227 environmental variable will be started to allow the user
229 The label is then checked and examined for any errors.
230 If no errors have been found, the new label is written to disk.
231 If there were any errors, a message is printed to standard
232 error output, and the user is given the opportunity to edit
233 the template file again.
234 If accepted, editing starts over.
235 If declined, no changes will
238 The label presented for editing is the same as the standard
239 printout, with some added hints about the possible options to
240 specify the sector size and starting cylinder.
241 The following areas in the template can be edited:
242 .Bl -tag -width indent
243 .It Sy Textual label, geometry emulation
245 .D1 Li text: Ar XXXX Li cyl Ar CC Li alt 2 hd Ar HH Li sec Ar SS
246 represents the label text.
247 It must be retained exactly in the form shown.
250 is a simple (non-whitespace) text describing the disk.
251 By convention, this text mentions the approximate size of the
254 for a 9 GB disk shipped by Sun.
261 describe the number of cylinders, heads (tracks per
262 cylinder), and sectors per track respectively.
263 They might be modified to change the geometry emulation.
264 Each number must be between 1 and 65535.
266 .D1 Em (CC + 2) * HH * SS
267 must be less than or equal to the total number of sectors of the
268 disk (which is given as a hint in a comment field).
270 The volume name (if present) is introduced by the string
272 It can be up to 8 characters long, and might be useful to distinguish
273 different disks in a system.
274 Note that volume names require the VTOC elements to be present, so
275 any of the VTOC constraints described below need to be obeyed as well
276 if a volume name is to be set.
277 Setting an empty volume name will delete it from the label.
278 .It Sy Partition entries
279 Partition entries start with a letter from
283 immediately followed by a colon, followed by the size of this
284 partition, and the starting cylinder of the partition.
285 The unit of the size field defaults to sectors, or to cylinders
289 Alternatively, a different unit may be specified by appending
291 for (512-byte) sectors,
300 The last partition entry may specify the size as
302 to indicate that this entry should consume the rest of disk not
303 consumed by any other partition so far.
305 The start of partition is always taken as a cylinder number (starting
306 at 0) since this is what the underlying hardware uses.
307 Alternatively, specifying it as
309 will make the computation automatically chose the nearest possible
314 must always be present, must start at 0, and must cover the entire
315 disk (without considering the alternate cylinders though).
317 Optionally, each partition entry may be followed by an SVR4-compatible
318 VTOC tag name, and a flag description.
319 The following VTOC tag names are known:
320 .Bl -column -offset indent ".Li unassigned" ".Sy value" ".Sy comment"
321 .It Sy name Ta Sy value Ta Sy comment
322 .It Li unassigned Ta No 0x00
323 .It Li boot Ta No 0x01
324 .It Li root Ta No 0x02
325 .It Li swap Ta No 0x03
326 .It Li usr Ta No 0x04
327 .It Li backup Ta No 0x05 Ta c partition, entire disk
328 .It Li stand Ta No 0x06
329 .It Li var Ta No 0x07
330 .It Li home Ta No 0x08
331 .It Li altsctr Ta No 0x09 Ta alternate sector partition
332 .It Li cache Ta No 0x0a Ta Solaris cachefs partition
333 .It Li VxVM_pub Ta No 0x0e Ta VxVM public region
334 .It Li VxVM_priv Ta No 0x0f Ta VxVM private region
337 The following VTOC flags are known:
338 .Bl -column -offset indent ".Sy name" ".Sy value" ".Sy comment"
339 .It Sy name Ta Sy value Ta Sy comment
340 .It Li wm Ta No 0x00 Ta read/write, mountable
341 .It Li wu Ta No 0x01 Ta read/write, unmountable
342 .It Li rm Ta No 0x10 Ta read/only, mountable
343 .It Li ru Ta No 0x11 Ta read/only, unmountable
346 Optionally, both the tag and/or the flag name may be specified
347 numerically, using standard
349 numerial notation (prefix
351 for hexadecimal numbers,
354 If the flag field is omitted, it defaults to
356 If the tag field is also omitted, it defaults to
358 If none of the partitions lists any VTOC tag/flags, no
359 SVR4-compatible VTOC elements will be written to disk.
360 If VTOC-style elements are present, partition
364 (and should be marked
368 When checking the label, partition
370 is checked for presence, and for the mentioned restrictions.
371 All other partitions are checked for possible overlaps, as
372 well as for not extending past the end of unit.
373 If VTOC-style elements are present, overlaps of unmountable
374 partitions against other partitions will be warned still but
375 do not cause a rejection of the label.
377 .Em encapsulated disks
378 of volume management software are acceptable as long as the
379 volume management partitions are clearly marked as unmountable.
381 Any other fields in the label template are informational only,
382 and will not be parsed when reading the label.
384 Note that when changing the geometry emulation by editing the
385 textual description line, all partition entries will be
386 considered based on the new geometry emulation.
388 .Bl -tag -width ".Ev EDITOR" -compact
390 Name of the command to edit the template file in edit-mode.
395 .Bl -tag -width ".Pa /boot/boot1" -compact
411 utility was written by
412 .An Jake Burkholder ,
413 modeling it after the
415 command available on other architectures.
418 This man page was initially written by
420 and later substantially updated by
423 Installing bootstrap code onto an entire disk is merely pointless.
425 should rather support installing bootstrap code into a partition
430 layout algorithm could be smarter.
431 By now, it tends to emulate fairly large cylinders which due to
432 the two reserved alternate cylinders causes a fair amount of
projects / FreeBSD / releng / 8.1.git / blob