libdisk is now `adult':

. install libdisk.h into /usr/include
. add a (preliminary) manpage, mostly featured after phk's comments
  in libdisk.h

2 files changed, 353 insertions, 1 deletions

diff --git a/lib/libdisk/Makefile b/lib/libdisk/Makefile
index 328ab2b..b5be7b0 100644
--- a/lib/libdisk/Makefile
+++ b/lib/libdisk/Makefile
@@ -9,16 +9,53 @@ NOPROFILE=	yes
 NOSHARED=	yes
 NOPIC=		yes
 
+MAN3=		libdisk.3
+MLINKS+=	libdisk.3 \
+		libdisk.3 Open_Disk.3 \
+		libdisk.3 Clone_Disk.3 \
+		libdisk.3 Free_Disk.3 \
+		libdisk.3 Debug_Disk.3 \
+		libdisk.3 Set_Bios_Geom.3 \
+		libdisk.3 Delete_Chunk.3 \
+		libdisk.3 Collapse_Disk.3 \
+		libdisk.3 Collapse_Chunk.3 \
+		libdisk.3 Create_Chunk.3 \
+		libdisk.3 All_FreeBSD.3 \
+		libdisk.3 CheckRules.3 \
+		libdisk.3 Disk_Names.3 \
+		libdisk.3 Set_Boot_Mgr.3 \
+		libdisk.3 Set_Boot_Blocks.3 \
+		libdisk.3 Write_Disk.3 \
+		libdisk.3 Cyl_Aligned.3 \
+		libdisk.3 Next_Cyl_Aligned.3 \
+		libdisk.3 Prev_Cyl_Aligned.3 \
+		libdisk.3 Track_Aligned.3 \
+		libdisk.3 Next_Track_Aligned.3 \
+		libdisk.3 Prev_Track_Aligned.3 \
+		libdisk.3 Create_Chunk_DWIM.3 \
+		libdisk.3 MakeDev.3 \
+		libdisk.3 MakeDevDisk.3 \
+		libdisk.3 ShowChunkFlags.3 \
+		libdisk.3 ChunkCanBeRoot.3
+
 .include <bsd.lib.mk>
 
 BOOTS=/usr/mdec
 
-data.c:	libdisk.h ${BOOTS}/boot1 ${BOOTS}/boot2
+data.c:	${.CURDIR}/libdisk.h ${BOOTS}/boot1 ${BOOTS}/boot2
 	file2c 'const unsigned char boot1[] = {' '};' \
                 < ${BOOTS}/boot1 > tmp.c
 	file2c 'const unsigned char boot2[] = {' '};' \
                 < ${BOOTS}/boot2 >> tmp.c
 	mv tmp.c data.c
 
+beforeinstall:
+	@${ECHO} installing libdisk.h
+	@cd ${.CURDIR}; \
+	cmp -s libdisk.h ${DESTDIR}/usr/include/libdisk.h || \
+	    ${INSTALL} -c -o ${BINOWN} -g ${BINGRP} -m 444 libdisk.h \
+	    ${DESTDIR}/usr/include/libdisk.h
+
+
 tst01: tst01.o libdisk.a
 	cc ${CFLAGS} -static tst01.o -o tst01 libdisk.a
diff --git a/lib/libdisk/libdisk.3 b/lib/libdisk/libdisk.3
new file mode 100644
index 0000000..cf8b05b
--- /dev/null
+++ b/lib/libdisk/libdisk.3
@@ -0,0 +1,315 @@
+.\"
+.\" Copyright (c) 1996 Joerg Wunsch
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $Id$
+.\" "
+.Dd March 15, 1996
+.Dt LIBDISK 3
+.Os
+.Sh NAME
+.Nm Open_Disk ,
+.Nm Clone_Disk ,
+.Nm Free_Disk ,
+.Nm Debug_Disk ,
+.Nm Set_Bios_Geom ,
+.Nm Delete_Chunk ,
+.Nm Collapse_Disk ,
+.Nm Collapse_Chunk ,
+.Nm Create_Chunk ,
+.Nm All_FreeBSD ,
+.Nm CheckRules ,
+.Nm Disk_Names ,
+.Nm Set_Boot_Mgr ,
+.Nm Set_Boot_Blocks ,
+.Nm Write_Disk ,
+.Nm Cyl_Aligned ,
+.Nm Next_Cyl_Aligned ,
+.Nm Prev_Cyl_Aligned ,
+.Nm Track_Aligned ,
+.Nm Next_Track_Aligned ,
+.Nm Prev_Track_Aligned ,
+.Nm Create_Chunk_DWIM ,
+.Nm MakeDev ,
+.Nm MakeDevDisk ,
+.Nm ShowChunkFlags ,
+.Nm ChunkCanBeRoot ,
+.Nd library interface to slice and partition labels
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <libdisk.h>
+.Ft struct disk *
+.Fn Open_Disk "char *devname"
+.Ft struct disk *
+.Fn Clone_Disk "struct disk *disk"
+.Ft void
+.Fn Free_Disk "struct disk *disk"
+.Ft void
+.Fn Debug_Disk "struct disk *disk"
+.Ft void
+.Fn Set_Bios_Geom "struct disk *disk" "u_long cyl" "u_long heads" "u_long sects"
+.Ft int
+.Fn Delete_Chunk "struct disk *disk" "struct chunk *"
+.Ft void
+.Fn Collapse_Disk "struct disk *disk"
+.Ft int
+.Fn Collapse_Chunk "struct disk *disk" "struct chunk *chunk"
+.Ft int
+.Fn Create_Chunk "struct disk *disk" "u_long offset" "u_long size" "chunk_e type" "int subtype" "u_long flags"
+.Ft void
+.Fn All_FreeBSD "struct disk *d" "int force_all"
+.Ft char *
+.Fn CheckRules "struct disk *"
+.Ft char **
+.Fn Disk_Names "void"
+.Ft void
+.Fn Set_Boot_Mgr "struct disk *d" "u_char *bootmgr"
+.Ft void
+.Fn Set_Boot_Blocks "struct disk *d" "u_char *boot1" "u_char *boot2"
+.Ft int
+.Fn Write_Disk "struct disk *d"
+.Ft int
+.Fn Cyl_Aligned "struct disk *d" "u_long offset"
+.Ft u_long
+.Fn Next_Cyl_Aligned "struct disk *d" "u_long offset"
+.Ft u_long
+.Fn Prev_Cyl_Aligned "struct disk *d" "u_long offset"
+.Ft int
+.Fn Track_Aligned "struct disk *d" "u_long offset"
+.Ft u_long
+.Fn Next_Track_Aligned "struct disk *d" "u_long offset"
+.Ft u_long
+.Fn Prev_Track_Aligned "struct disk *d" "u_long offset"
+.Ft struct chunk *
+.Fn Create_Chunk_DWIM "struct disk *d" "struct chunk *parent" "u_long size" "chunk_e type" "int subtype" "u_long flags"
+.Ft int
+.Fn MakeDev "struct chunk *c" "char *path"
+.Ft int
+.Fn MakeDevDisk "struct disk *d,char *path"
+.Ft char *
+.Fn ShowChunkFlags "struct chunk *c"
+.Ft char *
+.Fn ChunkCanBeRoot "struct chunk *c"
+.Sh DESCRIPTION
+.Nm Libdisk
+provides an interface to the low-level disk slice and partition labels.
+Most functions operate with arguments of the types
+.Ql struct disk ,
+or
+.Ql struct chunk .
+.Pp
+While both types are mostly opaque to the programmer, the internal
+structure is mentioned below for the sake of completeness.
+.Bd -literal -offset indent
+struct disk {
+	char		*name;
+	u_long		flags;
+	u_long		bios_cyl;
+	u_long		bios_hd;
+	u_long		bios_sect;
+	u_char		*bootmgr;
+	u_char		*boot1;
+	u_char		*boot2;
+	struct chunk	*chunks;
+};
+.Ed
+The only flag value by now is
+.Ql DISK_ON_TRACK ,
+meaning that this disk is handled by the On-Track Disk Manager.
+.Pp
+.Bd -literal -offset indent
+struct chunk {
+	struct chunk	*next;
+	struct chunk	*part;
+	struct disk	*disk;
+	long		offset;
+	u_long		size;
+	u_long		end;
+	char		*name;
+	char		*oname;
+	chunk_e		type;
+	int		subtype;
+	u_long		flags;
+	void		(*private_free)(void*);
+	void		*(*private_clone)(void*);
+	void		*private;
+};
+.Ed
+The
+.Ql type
+field can be one of the following values:
+.Ql whole, unknown, fat, freebsd, extended, part, unused .
+.Pp
+These are the valid
+.Ql flag
+values for a
+.Ql struct chunk .
+.Bl -tag -offset indent -width CHUNK_BSD_COMPATXX
+.It CHUNK_PAST_1024
+This chunk cannot be booted from because it extends past cylinder 1024.
+.It CHUNK_BSD_COMPAT
+This chunk is in the BSD-compatibility, and has a short name too, i.e.
+.Ql wd0s4f -> wd0f .
+.It CHUNK_BAD144
+This chunk has bad144 mapping.
+.It CHUNK_ALIGN
+This chunk should be aligned.
+.It CHUNK_IS_ROOT
+This
+.Ql part
+is a rootfs, allocate partition
+.Sq a .
+.It CHUNK_ACTIVE
+This is the active slice in the MBR.
+.It CHUNK_FORCE_ALL
+Force a dedicated disk for FreeBSD, bypassing all BIOS geometry
+considerations.
+.El
+.Pp
+The
+.Ql private ,
+.Ql private_free ,
+and
+.Ql private_clone
+fields are for data private to the application, and the management
+thereof.  If the functions are not provided, no storage management is
+done, cloning will just copy the pointer and freeing will just forget
+it.
+.Pp
+.Fn Open_Disk
+will open the named disk, and return populated tree.
+.Pp
+.Fn Clone_Disk
+clones a copy of a tree.  Useful for
+.Dq Undo
+functionality.
+.Pp
+.Fn Free_Disk
+frees a tree made with
+.Fn Open_Disk
+or
+.Fn Clone_Disk .
+.Pp
+.Fn Debug_Disk
+prints the content of the tree to stdout.
+.Pp
+.Fn Set_Bios_Geom
+sets the geometry the bios uses.
+.Pp
+.Fn Delete_Chunk
+frees a chunk of disk_space.
+.Pp
+.Fn Collapse_Disk,
+and
+.Fn Collapse_Chunk
+are experimental, do not use.
+.Pp
+.Fn Create_Chunk
+creates a chunk with the specified paramters.
+.Pp
+.Fn All_FreeBSD
+makes one FreeBSD chunk covering the entire disk; if
+.Ql force_all
+is set, bypass all BIOS geometry considerations.
+.Pp
+.Fn CheckRules
+returns
+.Ql char*
+to warnings about broken design rules in this disklayout.
+.Pp
+.Fn Disk_Names
+returns
+.Ql char**
+with all disk's names (wd0, wd1 ...).  You must free each pointer, as
+well as the array by hand.
+.Pp
+.Fn Set_Boot_Mgr
+sets this boot-manager for use on this disk.  Gets written when
+.Fn Write_Disk
+is called.
+.Pp
+.Fn Set_Boot_Blocks
+sets the boot-blocks for use on this disk.  Gets written when
+.Fn Write_Disk
+is called.
+.Pp
+.Fn Write_Disk
+writes all the MBRs, disklabels, bootblocks and boot managers.
+.Pp
+.Fn Cyl_Aligned
+checks if
+.Ql offset
+is aligned on a cylinder according to the BIOS.
+geometry.
+.Pp
+.Fn Next_Cyl_Aligned
+rounds
+.Ql offset
+up to next cylinder according to the BIOS geometry.
+.Pp
+.Fn Prev_Cyl_Aligned
+rounds
+.Ql offset
+down to previous cylinder according to the BIOS geometry.
+.Pp
+.Fn Track_Aligned
+checks if
+.Ql offset
+is aligned on a track according to the BIOS geometry.
+.Pp
+.Fn Next_Track_Aligned
+rounds
+.Ql offset
+up to next track according to the BIOS geometry.
+.Pp
+.Fn Prev_Track_Aligned
+checks if
+.Ql offset
+is aligned on a track according to the BIOS geometry.
+.Pp
+.Fn Create_Chunk_DWIM
+creates a partition inside the given parent of the given size, and
+returns a pointer to it.  The first unused chunk big enough is used.
+.Pp
+.Fn MakeDev
+makes the device nodes for this chunk.
+.Pp
+.Fn MakeDevDisk
+makes the device nodes for all chunks on this disk.
+.Pp
+.Fn ShowChunkFlags
+returns a string to show flags.
+.Pp
+.Fn ChunkCanBeRoot
+returns NULL if chunk can be
+.Ql / .
+.Sh AUTHOR
+.Nm Libdisk
+has been written by Poul-Henning Kamp.
+.Pp
+This man page by
+.ie t J\(:org Wunsch.
+.el Joerg Wunsch.