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 LIBRARY
  64 .Lb libdisk
  65 .Sh SYNOPSIS
  66 .In sys/types.h
  67 .In libdisk.h
  68 .Pp
  69 .Vt extern const char *chunk_n[] ;
  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" "const size_t bootmgr_size"
  98 .Ft int
  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         u_long          sector_size;
 146 };
 147 .Ed
 148 The only flag value by now is
 149 .Ql DISK_ON_TRACK ,
 150 meaning that this disk is handled by the On-Track Disk Manager.
 151 .Pp
 152 .Bd -literal -offset indent
 153 struct chunk {
 154         struct chunk    *next;
 155         struct chunk    *part;
 156         struct disk     *disk;
 157         long            offset;
 158         u_long          size;
 159         u_long          end;
 160         char            *name;
 161         char            *oname;
 162         chunk_e         type;
 163         int             subtype;
 164         u_long          flags;
 165         void            (*private_free)(void*);
 166         void            *(*private_clone)(void*);
 167         void            *private_data;
 168 };
 169 .Ed
 170 The
 171 .Ql type
 172 field can be one of the following values:
 173 .Ql whole, unknown, fat, freebsd, extended, part, unused .
 174 .Pp
 175 These are the valid
 176 .Ql flag
 177 values for a
 178 .Ql struct chunk .
 179 .Bl -tag -offset indent -width CHUNK_BSD_COMPATXX
 180 .It CHUNK_PAST_1024
 181 This chunk cannot be booted from because it extends past cylinder 1024.
 182 .It CHUNK_BSD_COMPAT
 183 This chunk is in the
 184 .Bx Ns -compatibility ,
 185 and has a short name too, i.e.\&
 186 .Ql wd0s4f -> wd0f .
 187 .It CHUNK_ALIGN
 188 This chunk should be aligned.
 189 .It CHUNK_IS_ROOT
 190 This
 191 .Ql part
 192 is a rootfs, allocate partition
 193 .Sq a .
 194 .It CHUNK_ACTIVE
 195 This is the active slice in the MBR.
 196 .It CHUNK_FORCE_ALL
 197 Force a dedicated disk for
 198 .Fx ,
 199 bypassing all BIOS geometry considerations.
 200 .El
 201 .Pp
 202 The
 203 .Ql private_data ,
 204 .Ql private_free ,
 205 and
 206 .Ql private_clone
 207 fields are for data private to the application, and the management
 208 thereof.  If the functions are not provided, no storage management is
 209 done, cloning will just copy the pointer and freeing will just forget
 210 it.
 211 .Pp
 212 .Fn Open_Disk
 213 will open the named disk, and return populated tree.
 214 .Pp
 215 .Fn Clone_Disk
 216 clones a copy of a tree.  Useful for
 217 .Dq Undo
 218 functionality.
 219 .Pp
 220 .Fn Free_Disk
 221 frees a tree made with
 222 .Fn Open_Disk
 223 or
 224 .Fn Clone_Disk .
 225 .Pp
 226 .Fn Debug_Disk
 227 prints the content of the tree to stdout.
 228 .Pp
 229 .Fn Set_Bios_Geom
 230 sets the geometry the bios uses.
 231 .Pp
 232 .Fn Delete_Chunk
 233 frees a chunk of disk_space.
 234 .Pp
 235 .Fn Collapse_Disk
 236 and
 237 .Fn Collapse_Chunk
 238 are experimental, do not use.
 239 .Pp
 240 .Fn Create_Chunk
 241 creates a chunk with the specified parameters.
 242 .Pp
 243 .Fn All_FreeBSD
 244 makes one
 245 .Fx
 246 chunk covering the entire disk; if
 247 .Ql force_all
 248 is set, bypass all BIOS geometry considerations.
 249 .Pp
 250 .Fn CheckRules
 251 returns
 252 .Ql char*
 253 to warnings about broken design rules in this disklayout.
 254 .Pp
 255 .Fn Disk_Names
 256 returns
 257 .Ql char**
 258 with all disk's names (wd0, wd1 ...).  You must free each pointer, as
 259 well as the array by hand.
 260 .Pp
 261 .Fn Set_Boot_Mgr
 262 sets this boot-manager for use on this disk.  Gets written when
 263 .Fn Write_Disk
 264 is called.
 265 .Pp
 266 .Fn Set_Boot_Blocks
 267 sets the boot-blocks for use on this disk.  Gets written when
 268 .Fn Write_Disk
 269 is called.
 270 .Pp
 271 .Fn Write_Disk
 272 writes all the MBRs, disklabels, bootblocks and boot managers.
 273 .Pp
 274 .Fn Cyl_Aligned
 275 checks if
 276 .Ql offset
 277 is aligned on a cylinder according to the BIOS geometry.
 278 .Pp
 279 .Fn Next_Cyl_Aligned
 280 rounds
 281 .Ql offset
 282 up to next cylinder according to the BIOS geometry.
 283 .Pp
 284 .Fn Prev_Cyl_Aligned
 285 rounds
 286 .Ql offset
 287 down to previous cylinder according to the BIOS geometry.
 288 .Pp
 289 .Fn Track_Aligned
 290 checks if
 291 .Ql offset
 292 is aligned on a track according to the BIOS geometry.
 293 .Pp
 294 .Fn Next_Track_Aligned
 295 rounds
 296 .Ql offset
 297 up to next track according to the BIOS geometry.
 298 .Pp
 299 .Fn Prev_Track_Aligned
 300 checks if
 301 .Ql offset
 302 is aligned on a track according to the BIOS geometry.
 303 .Pp
 304 .Fn Create_Chunk_DWIM
 305 creates a partition inside the given parent of the given size, and
 306 returns a pointer to it.  The first unused chunk big enough is used.
 307 .Pp
 308 .Fn MakeDev
 309 makes the device nodes for this chunk.
 310 .Pp
 311 .Fn MakeDevDisk
 312 makes the device nodes for all chunks on this disk.
 313 .Pp
 314 .Fn ShowChunkFlags
 315 returns a string to show flags.
 316 .Pp
 317 .Fn ChunkCanBeRoot
 318 returns NULL if chunk can be
 319 .Ql / .
 320 .Pp
 321 Chunk name strings can be accessed directly using the external array
 322 .Va chunk_n .
 323 .Pp
 324 .Fn slice_type_name
 325 returns the name strings associated with the specified
 326 .Ql type .
 327 .Ql subtype .
 328 If
 329 .Fn slice_type_name
 330 returns "unknown" for slices it isn't familiar with.
 331 .Sh AUTHORS
 332 .An -nosplit
 333 The
 334 .Nm libdisk
 335 library was written by
 336 .An Poul-Henning Kamp .
 337 .Pp
 338 This manual page was written by
 339 .An J\(:org Wunsch .