lib/libdisk/libdisk.3

   1 .\"
   2 .\" Copyright (c) 1996 Joerg Wunsch
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" This program is free software.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\" "
  30 .Dd March 15, 1996
  31 .Dt LIBDISK 3
  32 .Os
  33 .Sh NAME
  34 .Nm Open_Disk ,
  35 .Nm Clone_Disk ,
  36 .Nm Free_Disk ,
  37 .Nm Debug_Disk ,
  38 .Nm Set_Bios_Geom ,
  39 .Nm Delete_Chunk ,
  40 .Nm Collapse_Disk ,
  41 .Nm Collapse_Chunk ,
  42 .Nm Create_Chunk ,
  43 .Nm All_FreeBSD ,
  44 .Nm CheckRules ,
  45 .Nm Disk_Names ,
  46 .Nm Set_Boot_Mgr ,
  47 .Nm Set_Boot_Blocks ,
  48 .Nm Write_Disk ,
  49 .Nm Cyl_Aligned ,
  50 .Nm Next_Cyl_Aligned ,
  51 .Nm Prev_Cyl_Aligned ,
  52 .Nm Track_Aligned ,
  53 .Nm Next_Track_Aligned ,
  54 .Nm Prev_Track_Aligned ,
  55 .Nm Create_Chunk_DWIM ,
  56 .Nm MakeDev ,
  57 .Nm MakeDevDisk ,
  58 .Nm ShowChunkFlags ,
  59 .Nm ChunkCanBeRoot ,
  60 .Nm chunk_n ,
  61 .Nm slice_type_name
  62 .Nd library interface to slice and partition labels
  63 .Sh SYNOPSIS
  64 .Fd #include <sys/types.h>
  65 .Fd #include <libdisk.h>
  66 .\"             What is the correct way to cause a single line break ???
  67 .Bd -literal
  68 .Dv extern const char *chunk_n[];
  69 .Ed
  70 .Ft const char *
  71 .Fn slice_type_name "int type" "int subtype"
  72 .Ft struct disk *
  73 .Fn Open_Disk "const char *devname"
  74 .Ft struct disk *
  75 .Fn Clone_Disk "struct disk *disk"
  76 .Ft void
  77 .Fn Free_Disk "struct disk *disk"
  78 .Ft void
  79 .Fn Debug_Disk "struct disk *disk"
  80 .Ft void
  81 .Fn Set_Bios_Geom "struct disk *disk" "u_long cyl" "u_long heads" "u_long sects"
  82 .Ft int
  83 .Fn Delete_Chunk "struct disk *disk" "struct chunk *"
  84 .Ft void
  85 .Fn Collapse_Disk "struct disk *disk"
  86 .Ft int
  87 .Fn Collapse_Chunk "struct disk *disk" "struct chunk *chunk"
  88 .Ft int
  89 .Fn Create_Chunk "struct disk *disk" "u_long offset" "u_long size" "chunk_e type" "int subtype" "u_long flags"
  90 .Ft void
  91 .Fn All_FreeBSD "struct disk *d" "int force_all"
  92 .Ft char *
  93 .Fn CheckRules "struct disk *"
  94 .Ft char **
  95 .Fn Disk_Names "void"
  96 .Ft void
  97 .Fn Set_Boot_Mgr "struct disk *d" "const u_char *bootmgr"
  98 .Ft void
  99 .Fn Set_Boot_Blocks "struct disk *d" "const u_char *boot1" "const u_char *boot2"
 100 .Ft int
 101 .Fn Write_Disk "struct disk *d"
 102 .Ft int
 103 .Fn Cyl_Aligned "struct disk *d" "u_long offset"
 104 .Ft u_long
 105 .Fn Next_Cyl_Aligned "struct disk *d" "u_long offset"
 106 .Ft u_long
 107 .Fn Prev_Cyl_Aligned "struct disk *d" "u_long offset"
 108 .Ft int
 109 .Fn Track_Aligned "struct disk *d" "u_long offset"
 110 .Ft u_long
 111 .Fn Next_Track_Aligned "struct disk *d" "u_long offset"
 112 .Ft u_long
 113 .Fn Prev_Track_Aligned "struct disk *d" "u_long offset"
 114 .Ft struct chunk *
 115 .Fn Create_Chunk_DWIM "struct disk *d" "struct chunk *parent" "u_long size" "chunk_e type" "int subtype" "u_long flags"
 116 .Ft int
 117 .Fn MakeDev "struct chunk *c" "const char *path"
 118 .Ft int
 119 .Fn MakeDevDisk "struct disk *d" "const char *path"
 120 .Ft char *
 121 .Fn ShowChunkFlags "struct chunk *c"
 122 .Ft char *
 123 .Fn ChunkCanBeRoot "struct chunk *c"
 124 .Sh DESCRIPTION
 125 .Nm Libdisk
 126 provides an interface to the low-level disk slice and partition labels.
 127 Most functions operate with arguments of the types
 128 .Ql struct disk ,
 129 or
 130 .Ql struct chunk .
 131 .Pp
 132 While both types are mostly opaque to the programmer, the internal
 133 structure is mentioned below for the sake of completeness.
 134 .Bd -literal -offset indent
 135 struct disk {
 136         char            *name;
 137         u_long          flags;
 138         u_long          bios_cyl;
 139         u_long          bios_hd;
 140         u_long          bios_sect;
 141         u_char          *bootmgr;
 142         u_char          *boot1;
 143         u_char          *boot2;
 144         struct chunk    *chunks;
 145 };
 146 .Ed
 147 The only flag value by now is
 148 .Ql DISK_ON_TRACK ,
 149 meaning that this disk is handled by the On-Track Disk Manager.
 150 .Pp
 151 .Bd -literal -offset indent
 152 struct chunk {
 153         struct chunk    *next;
 154         struct chunk    *part;
 155         struct disk     *disk;
 156         long            offset;
 157         u_long          size;
 158         u_long          end;
 159         char            *name;
 160         char            *oname;
 161         chunk_e         type;
 162         int             subtype;
 163         u_long          flags;
 164         void            (*private_free)(void*);
 165         void            *(*private_clone)(void*);
 166         void            *private_data;
 167 };
 168 .Ed
 169 The
 170 .Ql type
 171 field can be one of the following values:
 172 .Ql whole, unknown, fat, freebsd, extended, part, unused .
 173 .Pp
 174 These are the valid
 175 .Ql flag
 176 values for a
 177 .Ql struct chunk .
 178 .Bl -tag -offset indent -width CHUNK_BSD_COMPATXX
 179 .It CHUNK_PAST_1024
 180 This chunk cannot be booted from because it extends past cylinder 1024.
 181 .It CHUNK_BSD_COMPAT
 182 This chunk is in the BSD-compatibility, and has a short name too, i.e.
 183 .Ql wd0s4f -> wd0f .
 184 .It CHUNK_BAD144
 185 This chunk has bad144 mapping.
 186 .It CHUNK_ALIGN
 187 This chunk should be aligned.
 188 .It CHUNK_IS_ROOT
 189 This
 190 .Ql part
 191 is a rootfs, allocate partition
 192 .Sq a .
 193 .It CHUNK_ACTIVE
 194 This is the active slice in the MBR.
 195 .It CHUNK_FORCE_ALL
 196 Force a dedicated disk for FreeBSD, bypassing all BIOS geometry
 197 considerations.
 198 .El
 199 .Pp
 200 The
 201 .Ql private_data ,
 202 .Ql private_free ,
 203 and
 204 .Ql private_clone
 205 fields are for data private to the application, and the management
 206 thereof.  If the functions are not provided, no storage management is
 207 done, cloning will just copy the pointer and freeing will just forget
 208 it.
 209 .Pp
 210 .Fn Open_Disk
 211 will open the named disk, and return populated tree.
 212 .Pp
 213 .Fn Clone_Disk
 214 clones a copy of a tree.  Useful for
 215 .Dq Undo
 216 functionality.
 217 .Pp
 218 .Fn Free_Disk
 219 frees a tree made with
 220 .Fn Open_Disk
 221 or
 222 .Fn Clone_Disk .
 223 .Pp
 224 .Fn Debug_Disk
 225 prints the content of the tree to stdout.
 226 .Pp
 227 .Fn Set_Bios_Geom
 228 sets the geometry the bios uses.
 229 .Pp
 230 .Fn Delete_Chunk
 231 frees a chunk of disk_space.
 232 .Pp
 233 .Fn Collapse_Disk,
 234 and
 235 .Fn Collapse_Chunk
 236 are experimental, do not use.
 237 .Pp
 238 .Fn Create_Chunk
 239 creates a chunk with the specified parameters.
 240 .Pp
 241 .Fn All_FreeBSD
 242 makes one FreeBSD chunk covering the entire disk; if
 243 .Ql force_all
 244 is set, bypass all BIOS geometry considerations.
 245 .Pp
 246 .Fn CheckRules
 247 returns
 248 .Ql char*
 249 to warnings about broken design rules in this disklayout.
 250 .Pp
 251 .Fn Disk_Names
 252 returns
 253 .Ql char**
 254 with all disk's names (wd0, wd1 ...).  You must free each pointer, as
 255 well as the array by hand.
 256 .Pp
 257 .Fn Set_Boot_Mgr
 258 sets this boot-manager for use on this disk.  Gets written when
 259 .Fn Write_Disk
 260 is called.
 261 .Pp
 262 .Fn Set_Boot_Blocks
 263 sets the boot-blocks for use on this disk.  Gets written when
 264 .Fn Write_Disk
 265 is called.
 266 .Pp
 267 .Fn Write_Disk
 268 writes all the MBRs, disklabels, bootblocks and boot managers.
 269 .Pp
 270 .Fn Cyl_Aligned
 271 checks if
 272 .Ql offset
 273 is aligned on a cylinder according to the BIOS.
 274 geometry.
 275 .Pp
 276 .Fn Next_Cyl_Aligned
 277 rounds
 278 .Ql offset
 279 up to next cylinder according to the BIOS geometry.
 280 .Pp
 281 .Fn Prev_Cyl_Aligned
 282 rounds
 283 .Ql offset
 284 down to previous cylinder according to the BIOS geometry.
 285 .Pp
 286 .Fn Track_Aligned
 287 checks if
 288 .Ql offset
 289 is aligned on a track according to the BIOS geometry.
 290 .Pp
 291 .Fn Next_Track_Aligned
 292 rounds
 293 .Ql offset
 294 up to next track according to the BIOS geometry.
 295 .Pp
 296 .Fn Prev_Track_Aligned
 297 checks if
 298 .Ql offset
 299 is aligned on a track according to the BIOS geometry.
 300 .Pp
 301 .Fn Create_Chunk_DWIM
 302 creates a partition inside the given parent of the given size, and
 303 returns a pointer to it.  The first unused chunk big enough is used.
 304 .Pp
 305 .Fn MakeDev
 306 makes the device nodes for this chunk.
 307 .Pp
 308 .Fn MakeDevDisk
 309 makes the device nodes for all chunks on this disk.
 310 .Pp
 311 .Fn ShowChunkFlags
 312 returns a string to show flags.
 313 .Pp
 314 .Fn ChunkCanBeRoot
 315 returns NULL if chunk can be
 316 .Pp
 317 Chunk name strings can be accessed directly using the external array
 318 .Va chunk_n .
 319 .Pp
 320 .Fn slice_type_name
 321 returns the name strings associated with the specified
 322 .Ql type .
 323 .Ql subtype .
 324 If
 325 .Fn slice_type_name
 326 returns "unknown" for slices it isn't familiar with.
 327 .Ql / .
 328 .Sh AUTHORS
 329 .Nm Libdisk
 330 has been written by
 331 .An Poul-Henning Kamp .
 332 .Pp
 333 This man page by
 334 .ie t J\(:org Wunsch.
 335 .el Joerg Wunsch.