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