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 January 30, 2006
  31 .Dt LIBDISK 3
  32 .Os
  33 .Sh NAME
  34 .Nm Open_Disk ,
  35 .Nm Free_Disk ,
  36 .Nm Debug_Disk ,
  37 .Nm Set_Bios_Geom ,
  38 .Nm Delete_Chunk ,
  39 .Nm Collapse_Disk ,
  40 .Nm Collapse_Chunk ,
  41 .Nm Create_Chunk ,
  42 .Nm All_FreeBSD ,
  43 .Nm CheckRules ,
  44 .Nm Disk_Names ,
  45 .Nm Set_Boot_Mgr ,
  46 .Nm Set_Boot_Blocks ,
  47 .Nm Write_Disk ,
  48 .Nm Cyl_Aligned ,
  49 .Nm Next_Cyl_Aligned ,
  50 .Nm Prev_Cyl_Aligned ,
  51 .Nm Track_Aligned ,
  52 .Nm Next_Track_Aligned ,
  53 .Nm Prev_Track_Aligned ,
  54 .Nm Create_Chunk_DWIM ,
  55 .Nm MakeDev ,
  56 .Nm MakeDevDisk ,
  57 .Nm ShowChunkFlags ,
  58 .Nm chunk_name ,
  59 .Nm slice_type_name
  60 .Nd library interface to slice and partition labels
  61 .Sh LIBRARY
  62 .Lb libdisk
  63 .Sh SYNOPSIS
  64 .In sys/types.h
  65 .In libdisk.h
  66 .Pp
  67 .Ft struct disk *
  68 .Fn Open_Disk "const char *devname"
  69 .Ft void
  70 .Fn Free_Disk "struct disk *disk"
  71 .Ft void
  72 .Fn Debug_Disk "struct disk *disk"
  73 .Ft void
  74 .Fn Set_Bios_Geom "struct disk *disk" "u_long cyl" "u_long heads" "u_long sects"
  75 .Ft int
  76 .Fn Delete_Chunk "struct disk *disk" "struct chunk *"
  77 .Ft void
  78 .Fn Collapse_Disk "struct disk *disk"
  79 .Ft int
  80 .Fn Collapse_Chunk "struct disk *disk" "struct chunk *chunk"
  81 .Ft int
  82 .Fn Create_Chunk "struct disk *disk" "daddr_t offset" "daddr_t size" "chunk_e type" "int subtype" "u_long flags" "const char *sname"
  83 .Ft void
  84 .Fn All_FreeBSD "struct disk *d" "int force_all"
  85 .Ft char *
  86 .Fn CheckRules "const struct disk *"
  87 .Ft char **
  88 .Fn Disk_Names "void"
  89 .Ft void
  90 .Fn Set_Boot_Mgr "struct disk *d" "const u_char *bootmgr" "const size_t bootmgr_size"
  91 .Ft int
  92 .Fn Set_Boot_Blocks "struct disk *d" "const u_char *boot1" "const u_char *boot2"
  93 .Ft int
  94 .Fn Write_Disk "const struct disk *d"
  95 .Ft int
  96 .Fn Cyl_Aligned "struct disk *d" "daddr_t offset"
  97 .Ft daddr_t
  98 .Fn Next_Cyl_Aligned "const struct disk *d" "daddr_t offset"
  99 .Ft daddr_t
 100 .Fn Prev_Cyl_Aligned "const struct disk *d" "daddr_t offset"
 101 .Ft int
 102 .Fn Track_Aligned "const struct disk *d" "daddr_t offset"
 103 .Ft daddr_t
 104 .Fn Next_Track_Aligned "const struct disk *d" "daddr_t offset"
 105 .Ft daddr_t
 106 .Fn Prev_Track_Aligned "const struct disk *d" "daddr_t offset"
 107 .Ft struct chunk *
 108 .Fn Create_Chunk_DWIM "struct disk *d" "struct chunk *parent" "daddr_t size" "chunk_e type" "int subtype" "u_long flags"
 109 .Ft int
 110 .Fn MakeDev "struct chunk *c" "const char *path"
 111 .Ft int
 112 .Fn MakeDevDisk "struct disk *d" "const char *path"
 113 .Ft char *
 114 .Fn ShowChunkFlags "struct chunk *c"
 115 .Ft const char *
 116 .Fn chunk_name "chunk_e type"
 117 .Ft const char *
 118 .Fn slice_type_name "int type" "int subtype"
 119 .Sh DESCRIPTION
 120 .Bf Sy
 121 .Nm libdisk
 122 is just for the use of
 123 .Xr sysinstall 8 .
 124 You should consider using
 125 .Xr libgeom 3
 126 instead.
 127 .Ef
 128 .Pp
 129 The
 130 .Nm libdisk
 131 library provides an interface to the low-level disk slice and partition labels.
 132 Most functions operate with arguments of the types
 133 .Ql struct disk ,
 134 or
 135 .Ql struct chunk .
 136 .Pp
 137 While both types are mostly opaque to the programmer, the internal
 138 structure is mentioned below for the sake of completeness.
 139 .Bd -literal -offset indent
 140 struct disk {
 141         char            *name;
 142         u_long          flags;
 143         u_long          bios_cyl;
 144         u_long          bios_hd;
 145         u_long          bios_sect;
 146         u_char          *bootmgr;
 147         u_char          *boot1;
 148         u_char          *boot2;
 149         struct chunk    *chunks;
 150         u_long          sector_size;
 151 };
 152 .Ed
 153 The only flag value by now is
 154 .Ql DISK_ON_TRACK ,
 155 meaning that this disk is handled by the On-Track Disk Manager.
 156 .Pp
 157 .Bd -literal -offset indent
 158 struct chunk {
 159         struct chunk    *next;
 160         struct chunk    *part;
 161         struct disk     *disk;
 162         daddr_t         offset;
 163         daddr_t         size;
 164         daddr_t         end;
 165         char            *name;
 166         char            *oname;
 167         chunk_e         type;
 168         int             subtype;
 169         u_long          flags;
 170         void            (*private_free)(void*);
 171         void            *(*private_clone)(void*);
 172         void            *private_data;
 173 };
 174 .Ed
 175 The
 176 .Ql type
 177 field can be one of the following values:
 178 .Ql whole, unknown, fat, freebsd, extended, part, unused .
 179 .Pp
 180 These are the valid
 181 .Ql flags
 182 values for a
 183 .Ql struct chunk .
 184 .Bl -tag -offset indent -width CHUNK_BSD_COMPATXX
 185 .It CHUNK_PAST_1024
 186 This chunk cannot be booted from because it extends past cylinder 1024.
 187 .It CHUNK_BSD_COMPAT
 188 This chunk is in the
 189 .Bx Ns -compatibility ,
 190 and has a short name too, i.e.\&
 191 .Ql wd0s4f -> wd0f .
 192 .It CHUNK_ALIGN
 193 This chunk should be aligned.
 194 .It CHUNK_IS_ROOT
 195 This
 196 .Ql part
 197 is a rootfs, allocate partition
 198 .Sq a .
 199 .It CHUNK_ACTIVE
 200 This is the active slice in the MBR.
 201 .It CHUNK_FORCE_ALL
 202 Force a dedicated disk for
 203 .Fx ,
 204 bypassing all BIOS geometry considerations.
 205 .El
 206 .Pp
 207 The
 208 .Ql private_data ,
 209 .Ql private_free ,
 210 and
 211 .Ql private_clone
 212 fields are for data private to the application, and the management
 213 thereof.
 214 If the functions are not provided, no storage management is
 215 done, cloning will just copy the pointer and freeing will just forget
 216 it.
 217 .Pp
 218 .Fn Open_Disk
 219 will open the named disk, and return populated tree.
 220 .Pp
 221 .Fn Free_Disk
 222 frees a tree made with
 223 .Fn Open_Disk
 224 or
 225 .Fn Clone_Disk .
 226 .Pp
 227 .Fn Debug_Disk
 228 prints the content of the tree to
 229 .Dv stdout .
 230 .Pp
 231 .Fn Set_Bios_Geom
 232 sets the geometry the bios uses.
 233 .Pp
 234 .Fn Delete_Chunk
 235 frees a chunk of disk_space.
 236 .Pp
 237 .Fn Collapse_Disk
 238 and
 239 .Fn Collapse_Chunk
 240 are experimental, do not use.
 241 .Pp
 242 .Fn Create_Chunk
 243 creates a chunk with the specified parameters.
 244 .Pp
 245 .Fn All_FreeBSD
 246 makes one
 247 .Fx
 248 chunk covering the entire disk; if
 249 .Ql force_all
 250 is set, bypass all BIOS geometry considerations.
 251 .Pp
 252 .Fn CheckRules
 253 returns
 254 .Ql char*
 255 to warnings about broken design rules in this disklayout.
 256 .Pp
 257 .Fn Disk_Names
 258 returns
 259 .Ql char**
 260 with all disk's names (wd0, wd1 ...).
 261 You must free each pointer, as
 262 well as the array by hand.
 263 .Pp
 264 .Fn Set_Boot_Mgr
 265 sets this boot-manager for use on this disk.
 266 Gets written when
 267 .Fn Write_Disk
 268 is called.
 269 .Pp
 270 .Fn Set_Boot_Blocks
 271 sets the boot-blocks for use on this disk.
 272 Gets written when
 273 .Fn Write_Disk
 274 is called.
 275 .Pp
 276 .Fn Write_Disk
 277 writes all the MBRs, disklabels, bootblocks and boot managers.
 278 .Pp
 279 .Fn Cyl_Aligned
 280 checks if
 281 .Ql offset
 282 is aligned on a cylinder according to the BIOS geometry.
 283 .Pp
 284 .Fn Next_Cyl_Aligned
 285 rounds
 286 .Ql offset
 287 up to next cylinder according to the BIOS geometry.
 288 .Pp
 289 .Fn Prev_Cyl_Aligned
 290 rounds
 291 .Ql offset
 292 down to previous cylinder according to the BIOS geometry.
 293 .Pp
 294 .Fn Track_Aligned
 295 checks if
 296 .Ql offset
 297 is aligned on a track according to the BIOS geometry.
 298 .Pp
 299 .Fn Next_Track_Aligned
 300 rounds
 301 .Ql offset
 302 up to next track according to the BIOS geometry.
 303 .Pp
 304 .Fn Prev_Track_Aligned
 305 rounds
 306 .Ql offset
 307 up to previous track according to the BIOS geometry.
 308 .Pp
 309 .Fn Create_Chunk_DWIM
 310 creates a partition inside the given parent of the given size, and
 311 returns a pointer to it.
 312 The first unused chunk big enough is used.
 313 .Pp
 314 .Fn MakeDev
 315 makes the device nodes for this chunk.
 316 .Pp
 317 .Fn MakeDevDisk
 318 makes the device nodes for all chunks on this disk.
 319 .Pp
 320 .Fn ShowChunkFlags
 321 returns a string to show flags.
 322 .Pp
 323 The
 324 .Fn chunk_name
 325 function takes the enumerated chunk type and returns its name.
 326 .Fn chunk_name
 327 replaces the old external array
 328 .Va chunk_n .
 329 .Pp
 330 .Fn slice_type_name
 331 returns the name strings associated with the specified
 332 .Ql type .
 333 .Ql subtype .
 334 If
 335 .Fn slice_type_name
 336 returns "unknown" for slices it is not familiar with.
 337 .Sh AUTHORS
 338 .An -nosplit
 339 The
 340 .Nm libdisk
 341 library was written by
 342 .An Poul-Henning Kamp .
 343 .Pp
 344 This manual page was written by
 345 .An J\(:org Wunsch .