Remove last remnants of the wd(4) driver which was moved to the Attic some
[dragonfly.git] / 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.5 2005/02/26 12:00:54 swildner 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 ad0s4f -> ad0f .
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 (ad0, ad1 ...).  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 .