Commit rudimentary libufs manual pages, except for that for

getino(3)/putino(3), inode.c has been reworked in Perforce to the point
where a manual page may not be accurate.  Certainly putino(3) has not
even been merged back yet.

These will need a lot of improvement for most applications, but they
document the API enough to get someone on their feet, most likely.  The
best documentation still exists in the form of libufs(3) consumers in the
base system.

7 files changed, 560 insertions, 0 deletions

diff --git a/lib/libufs/Makefile b/lib/libufs/Makefile
index 64b0bca..d6552e8 100644
--- a/lib/libufs/Makefile
+++ b/lib/libufs/Makefile
@@ -3,6 +3,13 @@
 LIB=	ufs
 SRCS=	block.c cgroup.c inode.c sblock.c type.c
 INCS=	libufs.h
+MAN=	bread.3 cgread.3 libufs.3 sbread.3 ufs_disk_close.3
+MLINKS+= bread.3 bwrite.3
+MLINKS+= cgread.3 cgread1.3
+MLINKS+= sbread.3 sbwrite.3
+MLINKS+= ufs_disk_close.3 ufs_disk_fillout.3
+MLINKS+= ufs_disk_close.3 ufs_disk_fillout_blank.3
+MLINKS+= ufs_disk_close.3 ufs_disk_write.3
 CFLAGS+= -I${.CURDIR} -D_LIBUFS
 .if defined(LIBUFS_DEBUG)
 CFLAGS+= -D_LIBUFS_DEBUGGING
diff --git a/lib/libufs/bread.3 b/lib/libufs/bread.3
new file mode 100644
index 0000000..7b0f5a1
--- /dev/null
+++ b/lib/libufs/bread.3
@@ -0,0 +1,82 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs functions:
+.\"		bread(3)
+.\"		bwrite(3)
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt BREAD 3
+.Os
+.Sh NAME
+.Nm bread , bwrite
+.Nd read and write blocks of a UFS filesystem
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Ft ssize_t
+.Fn bread "struct uufsd *disk" "ufs2_daddr_t blockno" "void *data" "size_t size"
+.Ft ssize_t
+.Fn bwrite "struct uufsd *disk" "ufs2_daddr_t blockno" "const void *data" "size_t size"
+.Sh DESCRIPTION
+The
+.Fn bread
+and
+.Fn bwrite
+functions provide a block read and write api for
+.Xr libufs 3
+consumers.
+They operate on a userland UFS disk structure, and perform the read
+and write at a given block address, which uses the current
+.Fa d_bsize
+value of the structure.
+.Pp
+The
+.Fn bread
+and
+.Fn bwrite
+functions return the amount written, or -1 in case of any error,
+including short read.
+.Sh ERRORS
+The function
+.Fn bread
+may fail and set
+.Va errno
+for any of the errors specified for the library functions
+.Xr ufs_disk_write
+or
+.Xr pread 2 .
+Additionally, it may follow the
+.Xr libufs 3
+error methodologies in situations where the amount of data read
+is not equal to the amount requested, or in case of device error.
+.Pp
+The function
+.Fn bwrite
+may fail and set
+.Va errno
+for any of the errors specified for the library function
+.Xr pwrite 2 .
+Additionally, it may follow the
+.Xr libufs 3
+error methodologies in situations where the amount of data written
+is not equal to the amount requested, or in case of a device error.
+.Sh SEE ALSO
+.Xr libufs 3 ,
+.Xr ufs_disk_write 3
+.Sh HISTORY
+These functions first appeared as part of
+.Xr libufs 3
+in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org
diff --git a/lib/libufs/cgread.3 b/lib/libufs/cgread.3
new file mode 100644
index 0000000..0169cba
--- /dev/null
+++ b/lib/libufs/cgread.3
@@ -0,0 +1,86 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs functions:
+.\"		cgread(3)
+.\"		cgread1(3)
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt CGREAD 3
+.Os
+.Sh NAME
+.Nm cgread , cgread1
+.Nd read cylinder groups of UFS disks
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Ft int
+.Fn cgread "struct uufsd *disk"
+.Ft int
+.Fn cgread1 "struct uufsd *disk" "int c"
+.Sh DESCRIPTION
+The
+.Fn cgread
+and
+.Fn cgread1
+functions provide cylinder group reads for
+.Xr libufs 3
+consumers.
+The
+.Fn cgread1
+function reads from one cylinder group, specified by
+.Fa c
+into the
+.Fa d_cg
+field of a userland UFS disk structure.
+It sets the
+.Fa d_lcg
+field to the cylinger group number
+.Fa c .
+.Pp
+The
+.Fn cgread
+function operates on sequential cylinder groups.
+Calling the
+.Fn cgread
+function is equivalent to calling
+.Nm cgread1
+with a cylinder group specifier equivalent to the value of the current
+.Fa d_ccg
+field, and then incrementing the
+.Fa d_ccg
+field.
+.Pp
+Both functions return 0 if there are no more cylinder groups to read,
+1 if there are more cylinder groups, and -1 on error.
+.Sh ERRORS
+The function
+.Fn cgread
+may fail and set
+.Va errno
+for any of the errors specified for the library function
+.Xr bread 3 .
+.Pp
+The function
+.Fn cgread1
+has semantically identical failure conditions to those of
+.Fn cgread .
+.Sh SEE ALSO
+.Xr bread 3 ,
+.Xr libufs 3
+.Sh HISTORY
+These functions first appeared as part of
+.Xr libufs 3
+in
+.Fx 5.1 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org
diff --git a/lib/libufs/getino.3 b/lib/libufs/getino.3
new file mode 100644
index 0000000..98b7d76
--- /dev/null
+++ b/lib/libufs/getino.3
@@ -0,0 +1,115 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs functions:
+.\"		getino(3)
+.\"		putino(3)
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt GETINO 3
+.Os
+.Sh NAME
+.Nm getino , putino
+.Nd get and put inodes to and from UFS disks
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Ft int
+.Fn getino "struct uufsd *disk" "void *dino" "ino_t inode"
+.Ft int
+.Fn putino "struct uufsd *disk" "void *dino" "ino_t inode"
+.Sh DESCRIPTION
+The
+.Fn getino
+and
+.Fn putino
+functions provide the ability to put an inode to disk or read an
+inode from disk for
+.Xr libufs 3
+consumers.
+The
+.Fn getino
+function reads the inode specified by
+.Fa inode ,
+and puts a pointer to an inode with the correct type into the memory
+pointed to by
+.Fa dino .
+It maintains a cache of nearby inodes, and may simply return pointers
+into memory that are in said cache.
+The pointer it returns may be modified as if it were of the type
+.Dq struct ufs1_dinode
+or
+.Dq struct ufs2_dinode
+depending on whether the disk being operated on is UFS1 or UFS2,
+respectively.
+.Pp
+The
+.Fn putino
+function puts an inode specified to be
+.Fa inode
+to disk, given memory passed in the
+.Fa dino
+pointer, in exactly the same manner as an inode is retrieved into
+.Fa dino
+by
+.Fn getino .
+Calls to
+.Fn putino
+immediately invalidate the inode cache.
+.Pp
+Both functions return 0 on success and -1 on error.
+.Sh ERRORS
+The function
+.Fn getino
+may fail and set
+.Va errno
+for any of the errors specified for the library functions
+.Xr bread 3
+and
+.Xr malloc 3 .
+Additionally, error may be returned if the inode format cannot be
+determined.
+Error reporting conventions for
+.Xr libufs 3
+functions are followed.
+.Pp
+The function
+.Fn putino
+may fail and set
+.Va errno
+for any of the errors specified for the library functions
+.Xr bwrite 3 .
+Additionally, error may be returned if the inode format cannot be
+determined, or if the
+.Fa dino
+parameter is
+.Dv NULL .
+In the latter case, where
+.Fa dino
+is unusable,
+.Va errno
+is set to
+.Er EDOOFUS .
+Error reporting conventions for
+.Xr libufs 3
+functions are followed.
+.Sh SEE ALSO
+.Xr bread 3 ,
+.Xr bwrite 3 ,
+.Xr libufs 3
+.Sh HISTORY
+These functions first appeared as part of
+.Xr libufs 3
+in
+.Fx 5.1 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org
diff --git a/lib/libufs/libufs.3 b/lib/libufs/libufs.3
new file mode 100644
index 0000000..68a3198
--- /dev/null
+++ b/lib/libufs/libufs.3
@@ -0,0 +1,75 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt SBREAD 3
+.Os
+.Sh NAME
+.Nm libufs
+.Nd operate on UFS disks from userland
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Sh DESCRIPTION
+The
+.Nm
+library and the functions it provides are used for implementing
+utilities which need to access a UFS filesystem at a low level from
+userland.
+Facilities provided are used to implement utilities such as
+.Xr newfs 8
+and
+.Xr dumpfs 8 .
+The
+.Nm
+library is designed to be simple, and provide functions that are
+traditionally useful to have.
+.Pp
+A disk is represented as the type
+.Dq struct uufsd
+as defined in
+.Pa libufs.h .
+The structure is filled out, operations are performed, and the disk
+is closed.
+.Sh ERRORS
+Functions provided by
+.Nm 
+return -1 in every functional error situation.
+They also set the
+.Fa d_error
+field to a string describing the error.
+.Sh SEE ALSO
+.Xr bread 3 ,
+.Xr bwrite 3 ,
+.Xr cgread 3 ,
+.Xr cgread1 3 ,
+.Xr getino 3 ,
+.Xr putino 3 ,
+.Xr sbread 3 ,
+.Xr sbwrite 3 ,
+.Xr ufs_disk_close 3 ,
+.Xr ufs_disk_fillout 3 ,
+.Xr ufs_disk_fillout_blank 3 ,
+.Xr ufs_disk_write 3 ,
+.Xr ffs 7 .
+.Sh HISTORY
+The
+.Xr libufs 3
+library first appeared in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org
+.Pp
+Additional design, feedback, and ideas were provided by
+.An Poul-Henning Kamp Aq phk@FreeBSD.org .
diff --git a/lib/libufs/sbread.3 b/lib/libufs/sbread.3
new file mode 100644
index 0000000..d7d93da
--- /dev/null
+++ b/lib/libufs/sbread.3
@@ -0,0 +1,84 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs functions:
+.\"		sbread(3)
+.\"		sbwrite(3)
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt SBREAD 3
+.Os
+.Sh NAME
+.Nm sbread , sbwrite
+.Nd read and write superblocks of a UFS filesystem
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Ft int
+.Fn sbread "struct uufsd *disk"
+.Ft int
+.Fn sbwrite "struct uufsd *disk" "int all"
+.Sh DESCRIPTION
+The
+.Fn sbread
+and
+.Fn sbwrite
+functions provide superblock reads and writes for
+.Xr libufs 3
+consumers.
+The
+.Fn sbread
+and
+.Fn sbwrite
+functions operate on the superblock field,
+.Fa d_sb ,
+associated with a given userland UFS disk structure.
+Additionally, the
+.Fn sbwrite
+function will write to all superblock locations if the
+.Fa all
+value is non-zero.
+.Pp
+The
+.Fn sbread
+and
+.Fn sbwrite
+functions return 0 on success or -1 on error.
+.Sh ERRORS
+The function
+.Fn sbread
+may fail and set
+.Va errno
+for any of the errors specified for the library function
+.Xr bread 3 .
+Additionally, it may follow the
+.Xr libufs 3
+error methodologies in situations where no usable superblock could be
+found.
+.Pp
+The function
+.Fn sbwrite
+may fail and set
+.Va errno
+for any of the errors specified for the library function
+.Xr bwrite 3 .
+.Sh SEE ALSO
+.Xr bread 3 ,
+.Xr bwrite 3 ,
+.Xr libufs 3
+.Sh HISTORY
+These functions first appeared as part of
+.Xr libufs 3
+in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org
diff --git a/lib/libufs/ufs_disk_close.3 b/lib/libufs/ufs_disk_close.3
new file mode 100644
index 0000000..bda8db5
--- /dev/null
+++ b/lib/libufs/ufs_disk_close.3
@@ -0,0 +1,111 @@
+.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
+.\" Date:	June 04, 2003
+.\" Description:
+.\" 	Manual page for libufs functions:
+.\"		ufs_disk_close(3)
+.\"		ufs_disk_fillout(3)
+.\"		ufs_disk_fillout_blank(3)
+.\"		ufs_disk_write(3)
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 04, 2003
+.Dt UFS_DISK_CLOSE 3
+.Os
+.Sh NAME
+.Nm ufs_disk_close , ufs_disk_fillout , ufs_disk_fillout_blank, ufs_disk_write
+.Nd open and close userland UFS disks
+.Sh LIBRARY
+.Lb libufs
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/param.h
+.In sys/mount.h
+.In ufs/ufs/ufsmount.h
+.In ufs/ufs/dinode.h
+.In ufs/ffs/fs.h
+.In libufs.h
+.Ft int
+.Fn ufs_disk_close "struct uufsd *disk"
+.Ft int
+.Fn ufs_disk_fillout "struct uufsd *disk" "const char *name"
+.Ft int
+.Fn ufs_disk_fillout_blank "struct uufsd *disk" "const char *name"
+.Ft int
+.Fn ufs_disk_write "struct uufsd *disk"
+.Sh DESCRIPTION
+The
+.Fn ufs_disk_close
+function closes a disk and frees internal memory related to it.
+It does not free the
+.Fa disk
+structure.
+.Pp
+The
+.Fn ufs_disk_fillout
+and
+.Fn ufs_disk_fillout_blank
+functions open a disk specified by
+.Fa name
+and populate the structure pointed to by
+.Fa disk .
+The disk is opened read-only.
+The specified
+.Fa name
+may be either a mountpoint, or a device name.
+The
+.Fn ufs_disk_fillout
+function assumes there is a valid superblock and will fail if not,
+whereas the
+.Fn ufs_disk_fillout_blank
+function makes no assumptions of that sort.
+.Pp
+The
+.Fn ufs_disk_write
+function attempts to re-open a disk as writable if it is not currently.
+.Sh ERRORS
+The function
+.Fn ufs_disk_close
+has no failure points.
+.Pp
+The function
+.Fn ufs_disk_fillout
+may fail for any of the reasons
+.Fn ufs_disk_fillout_blank
+might, as well as for any reason
+.Xr sbread 3
+might.
+.Pp
+The
+.Fn ufs_disk_fillout_blank
+may fail and set
+.Va errno
+for any of the errors specified for the library functions
+.Xr open 2 ,
+.Xr strdup 3 
+Additionally, it may follow the
+.Xr libufs 3
+error methodologies in situations where no device could be found to
+open.
+.Pp
+The function
+.Fn ufs_disk_write
+may fail and set
+.Va errno
+for any of the errors specified for the library functions
+.Xr open 3
+and
+.Xr stat 3 .
+Namely, it will fail if the disk in question may not be written to.
+.Sh SEE ALSO
+.Xr getfsfile 3 ,
+.Xr libufs 3 ,
+.Xr open 3 ,
+.Xr sbread 3
+.Sh HISTORY
+These functions first appeared as part of
+.Xr libufs 3
+in
+.Fx 5.0 .
+.Sh AUTHORS
+.An Juli Mallett Aq jmallett@FreeBSD.org