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 compatibility 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
123 .Bl -tag -width ".Fl b Ar bootpath"
127 is to be used as the boot image, rather than the default of
130 Install bootstrap code onto the disk.
131 Note that since the underlying hardware platform bootstraps from
132 partitions, not disks, this operation is only useful if there is
133 a partition starting at offset 0.
135 Use cylinders for partition size display rather than
137 This also changes the default interpretation of the partition
138 size entries when editing the label, or reading from a prototype
140 Thus, prototype files are only compatible when both, obtaining
141 the file and re-installing it is done using the same
148 below for a more detailed explanation.
150 When displaying the label, make the partition size and offset
153 The displayed numbers will get a suffix of
159 for 1048576 bytes each, or
161 for 1073741824 bytes each appended.
162 Note that due to possible rounding errors, prototype files
165 option are not suited for re-installing using the
170 All operations, checks etc., are performed normally, but nothing
173 Obsolete option that used to indicate that the operation should
174 be done directly on disk, as opposed through the respective kernel
178 Restore label from the prototype in
180 A prototype file is simply the textual representation of the
181 label as printed using the first form of the
187 option used to obtain the prototype must match the option used
188 when restoring the label (both present, or both absent).
191 Suitable to write an initial label to disk.
194 argument used to be an entry into a table of predefined labels,
195 but this functionality is not supported by
197 Instead, the only allowable
199 argument is the string
201 indicating that an automatically created label should be written
203 This automatism will try to create an initial label that fits as
204 best as possible into the available disk capacity.
211 options are present, the existing label for
213 will be printed to standard output.
218 must be given as a plain disk name, without any leading
221 In edit mode, the existing label from
223 will be read, and put into a template file.
224 The command referenced by the
226 environmental variable will be started to allow the user
228 The label is then checked and examined for any errors.
229 If no errors have been found, the new label is written to disk.
230 If there were any errors, a message is printed to standard
231 error output, and the user is given the opportunity to edit
232 the template file again.
233 If accepted, editing starts over.
234 If declined, no changes will
237 The label presented for editing is the same as the standard
238 printout, with some added hints about the possible options to
239 specify the sector size and starting cylinder.
240 The following areas in the template can be edited:
241 .Bl -tag -width indent
242 .It Sy Textual label, geometry emulation
244 .D1 Li text: Ar XXXX Li cyl Ar CC Li alt 2 hd Ar HH Li sec Ar SS
245 represents the label text.
246 It must be retained exactly in the form shown.
249 is a simple (non-whitespace) text describing the disk.
250 By convention, this text mentions the approximate size of the
253 for a 9 GB disk shipped by Sun.
260 describe the number of cylinders, heads (tracks per
261 cylinder), and sectors per track respectively.
262 They might be modified to change the geometry emulation.
263 Each number must be between 1 and 65535.
265 .D1 Em (CC + 2) * HH * SS
266 must be less than or equal to the total number of sectors of the
267 disk (which is given as a hint in a comment field).
269 The volume name (if present) is introduced by the string
271 It can be up to 8 characters long, and might be useful to distinguish
272 different disks in a system.
273 Note that volume names require the VTOC elements to be present, so
274 any of the VTOC constraints described below need to be obeyed as well
275 if a volume name is to be set.
276 Setting an empty volume name will delete it from the label.
277 .It Sy Partition entries
278 Partition entries start with a letter from
282 immediately followed by a colon, followed by the size of this
283 partition, and the starting cylinder of the partition.
284 The unit of the size field defaults to sectors, or to cylinders
288 Alternatively, a different unit may be specified by appending
290 for (512-byte) sectors,
299 The last partition entry may specify the size as
301 to indicate that this entry should consume the rest of disk not
302 consumed by any other partition so far.
304 The start of partition is always taken as a cylinder number (starting
305 at 0) since this is what the underlying hardware uses.
306 Alternatively, specifying it as
308 will make the computation automatically chose the nearest possible
313 must always be present, must start at 0, and must cover the entire
314 disk (without considering the alternate cylinders though).
316 Optionally, each partition entry may be followed by an SVR4-compatible
317 VTOC tag name, and a flag description.
318 The following VTOC tag names are known:
319 .Bl -column -offset indent ".Li unassigned" ".Sy value" ".Sy comment"
320 .It Sy name Ta Sy value Ta Sy comment
321 .It Li unassigned Ta No 0x00 Ta \&
322 .It Li boot Ta No 0x01 Ta \&
323 .It Li root Ta No 0x02 Ta \&
324 .It Li swap Ta No 0x03 Ta \&
325 .It Li usr Ta No 0x04 Ta \&
326 .It Li backup Ta No 0x05 Ta c partition, entire disk
327 .It Li stand Ta No 0x06 Ta \&
328 .It Li var Ta No 0x07 Ta \&
329 .It Li home Ta No 0x08 Ta \&
330 .It Li altsctr Ta No 0x09 Ta alternate sector partition
331 .It Li cache Ta No 0x0a Ta Solaris cachefs partition
332 .It Li VxVM_pub Ta No 0x0e Ta VxVM public region
333 .It Li VxVM_priv Ta No 0x0f Ta VxVM private region
336 The following VTOC flags are known:
337 .Bl -column -offset indent ".Sy name" ".Sy value" ".Sy comment"
338 .It Sy name Ta Sy value Ta Sy comment
339 .It Li wm Ta No 0x00 Ta read/write, mountable
340 .It Li wu Ta No 0x01 Ta read/write, unmountable
341 .It Li rm Ta No 0x10 Ta read/only, mountable
342 .It Li ru Ta No 0x11 Ta read/only, unmountable
345 Optionally, both the tag and/or the flag name may be specified
346 numerically, using standard
348 numerical notation (prefix
350 for hexadecimal numbers,
353 If the flag field is omitted, it defaults to
355 If the tag field is also omitted, it defaults to
357 If none of the partitions lists any VTOC tag/flags, no
358 SVR4-compatible VTOC elements will be written to disk.
359 If VTOC-style elements are present, partition
363 (and should be marked
367 When checking the label, partition
369 is checked for presence, and for the mentioned restrictions.
370 All other partitions are checked for possible overlaps, as
371 well as for not extending past the end of unit.
372 If VTOC-style elements are present, overlaps of unmountable
373 partitions against other partitions will be warned still but
374 do not cause a rejection of the label.
376 .Em encapsulated disks
377 of volume management software are acceptable as long as the
378 volume management partitions are clearly marked as unmountable.
380 Any other fields in the label template are informational only,
381 and will not be parsed when reading the label.
383 Note that when changing the geometry emulation by editing the
384 textual description line, all partition entries will be
385 considered based on the new geometry emulation.
387 .Bl -tag -width ".Ev EDITOR" -compact
389 Name of the command to edit the template file in edit-mode.
394 .Bl -tag -width ".Pa /boot/boot1" -compact
410 utility was written by
411 .An Jake Burkholder ,
412 modeling it after the
414 command available on other architectures.
417 This man page was initially written by
419 and later substantially updated by
422 Installing bootstrap code onto an entire disk is merely pointless.
424 should rather support installing bootstrap code into a partition
429 layout algorithm could be smarter.
430 By now, it tends to emulate fairly large cylinders which due to
431 the two reserved alternate cylinders causes a fair amount of
projects / FreeBSD / stable / 10.git / blob