| blob | 43e7ba1df684312b293be816963bb57080339819 |
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 .