Remove last remnants of the wd(4) driver which was moved to the Attic some
[dragonfly.git] / lib / libdisk / libdisk.3
CommitLineData
984263bc
MD
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 $
365ae791 29.\" $DragonFly: src/lib/libdisk/Attic/libdisk.3,v 1.5 2005/02/26 12:00:54 swildner Exp $
984263bc
MD
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
127provides an interface to the low-level disk slice and partition labels.
128Most functions operate with arguments of the types
129.Ql struct disk ,
130or
131.Ql struct chunk .
132.Pp
133While both types are mostly opaque to the programmer, the internal
134structure is mentioned below for the sake of completeness.
135.Bd -literal -offset indent
136struct 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
149The only flag value by now is
150.Ql DISK_ON_TRACK ,
151meaning that this disk is handled by the On-Track Disk Manager.
152.Pp
153.Bd -literal -offset indent
154struct 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
171The
172.Ql type
173field can be one of the following values:
174.Ql whole, unknown, fat, freebsd, extended, part, unused .
175.Pp
176These are the valid
177.Ql flag
178values for a
179.Ql struct chunk .
180.Bl -tag -offset indent -width CHUNK_BSD_COMPATXX
181.It CHUNK_PAST_1024
182This chunk cannot be booted from because it extends past cylinder 1024.
183.It CHUNK_BSD_COMPAT
184This chunk is in the
185.Bx Ns -compatibility ,
186and has a short name too, i.e.\&
365ae791 187.Ql ad0s4f -> ad0f .
984263bc
MD
188.It CHUNK_ALIGN
189This chunk should be aligned.
190.It CHUNK_IS_ROOT
191This
192.Ql part
193is a rootfs, allocate partition
194.Sq a .
195.It CHUNK_ACTIVE
196This is the active slice in the MBR.
197.It CHUNK_FORCE_ALL
198Force a dedicated disk for
52ac7bd7
HP
199.Dx
200/
201.Fx Ns ,
984263bc
MD
202bypassing all BIOS geometry considerations.
203.El
204.Pp
205The
206.Ql private_data ,
207.Ql private_free ,
208and
209.Ql private_clone
210fields are for data private to the application, and the management
211thereof. If the functions are not provided, no storage management is
212done, cloning will just copy the pointer and freeing will just forget
213it.
214.Pp
215.Fn Open_Disk
216will open the named disk, and return populated tree.
217.Pp
218.Fn Clone_Disk
219clones a copy of a tree. Useful for
220.Dq Undo
221functionality.
222.Pp
223.Fn Free_Disk
224frees a tree made with
225.Fn Open_Disk
226or
227.Fn Clone_Disk .
228.Pp
229.Fn Debug_Disk
230prints the content of the tree to stdout.
231.Pp
232.Fn Set_Bios_Geom
233sets the geometry the bios uses.
234.Pp
235.Fn Delete_Chunk
236frees a chunk of disk_space.
237.Pp
238.Fn Collapse_Disk
239and
240.Fn Collapse_Chunk
241are experimental, do not use.
242.Pp
243.Fn Create_Chunk
244creates a chunk with the specified parameters.
245.Pp
246.Fn All_FreeBSD
247makes one
52ac7bd7
HP
248.Fx
249/
250.Dx
984263bc
MD
251chunk covering the entire disk; if
252.Ql force_all
253is set, bypass all BIOS geometry considerations.
254.Pp
255.Fn CheckRules
256returns
257.Ql char*
258to warnings about broken design rules in this disklayout.
259.Pp
260.Fn Disk_Names
261returns
262.Ql char**
365ae791 263with all disk's names (ad0, ad1 ...). You must free each pointer, as
984263bc
MD
264well as the array by hand.
265.Pp
266.Fn Set_Boot_Mgr
267sets this boot-manager for use on this disk. Gets written when
268.Fn Write_Disk
269is called.
270.Pp
271.Fn Set_Boot_Blocks
272sets the boot-blocks for use on this disk. Gets written when
273.Fn Write_Disk
274is called.
275.Pp
276.Fn Write_Disk
277writes all the MBRs, disklabels, bootblocks and boot managers.
278.Pp
279.Fn Cyl_Aligned
280checks if
281.Ql offset
282is aligned on a cylinder according to the BIOS geometry.
283.Pp
284.Fn Next_Cyl_Aligned
285rounds
286.Ql offset
287up to next cylinder according to the BIOS geometry.
288.Pp
289.Fn Prev_Cyl_Aligned
290rounds
291.Ql offset
292down to previous cylinder according to the BIOS geometry.
293.Pp
294.Fn Track_Aligned
295checks if
296.Ql offset
297is aligned on a track according to the BIOS geometry.
298.Pp
299.Fn Next_Track_Aligned
300rounds
301.Ql offset
302up to next track according to the BIOS geometry.
303.Pp
304.Fn Prev_Track_Aligned
305checks if
306.Ql offset
307is aligned on a track according to the BIOS geometry.
308.Pp
309.Fn Create_Chunk_DWIM
310creates a partition inside the given parent of the given size, and
311returns a pointer to it. The first unused chunk big enough is used.
312.Pp
313.Fn MakeDev
314makes the device nodes for this chunk.
315.Pp
316.Fn MakeDevDisk
317makes the device nodes for all chunks on this disk.
318.Pp
319.Fn ShowChunkFlags
320returns a string to show flags.
321.Pp
322.Fn ChunkCanBeRoot
323returns NULL if chunk can be
324.Ql / .
325.Pp
326Chunk name strings can be accessed directly using the external array
327.Va chunk_n .
328.Pp
329.Fn slice_type_name
330returns the name strings associated with the specified
331.Ql type .
332.Ql subtype .
333If
334.Fn slice_type_name
335returns "unknown" for slices it isn't familiar with.
336.Sh AUTHORS
337.An -nosplit
338The
339.Nm libdisk
340library was written by
341.An Poul-Henning Kamp .
342.Pp
343This manual page was written by
344.An J\(:org Wunsch .