diff --git a/lib/libufs/Makefile b/lib/libufs/Makefile index 64b0bca83b01..d6552e8fa7c3 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 000000000000..7b0f5a189ad9 --- /dev/null +++ b/lib/libufs/bread.3 @@ -0,0 +1,82 @@ +.\" Author: Juli Mallett +.\" 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 000000000000..0169cba1a24e --- /dev/null +++ b/lib/libufs/cgread.3 @@ -0,0 +1,86 @@ +.\" Author: Juli Mallett +.\" 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 000000000000..98b7d76c6500 --- /dev/null +++ b/lib/libufs/getino.3 @@ -0,0 +1,115 @@ +.\" Author: Juli Mallett +.\" 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 000000000000..68a3198d923d --- /dev/null +++ b/lib/libufs/libufs.3 @@ -0,0 +1,75 @@ +.\" Author: Juli Mallett +.\" 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 000000000000..d7d93dab95c2 --- /dev/null +++ b/lib/libufs/sbread.3 @@ -0,0 +1,84 @@ +.\" Author: Juli Mallett +.\" 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 000000000000..bda8db55ec0e --- /dev/null +++ b/lib/libufs/ufs_disk_close.3 @@ -0,0 +1,111 @@ +.\" Author: Juli Mallett +.\" 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