freebsd-dev/lib/libufs/getinode.3
Kirk McKusick 9fc5d538fc In preparation for adding inode check-hashes, clean up and
document the libufs interface for fetching and storing inodes.
The undocumented getino / putino interface has been replaced
with a new getinode / putinode interface.

Convert the utilities that had been using the undocumented
interface to use the new documented interface.

No functional change (as for now the libufs library does not
do inode check-hashes).

Reviewed by:  kib
Tested by:    Peter Holm
Sponsored by: Netflix
2018-11-13 21:40:56 +00:00

132 lines
2.7 KiB
Groff

.\" Author: Marshall Kirk McKusick <mckusick@freebsd.org>
.\" Date: January 19, 2018
.\" Description:
.\" Manual page for libufs functions:
.\" getinode(3)
.\" putinode(3)
.\"
.\" This file is in the public domain.
.\"
.\" $FreeBSD$
.\"
.Dd November 10, 2018
.Dt GETINODE 3
.Os
.Sh NAME
.Nm getinode , putinode
.Nd fetch and store inodes on a UFS file system
.Sh LIBRARY
.Lb libufs
.Sh SYNOPSIS
.In ufs/ufs/dinode.h
.In ufs/ffs/fs.h
.In libufs.h
.Ft int
.Fn getinode "struct uufsd *disk" "union dinodep *dp" "ino_t inumber"
.Ft int
.Fn putinode "struct uufsd *disk"
.Sh DESCRIPTION
The
.Fn getinode
and
.Fn putinode
functions provide an inode fetch and store API for
.Xr libufs 3
consumers.
They operate on a userland UFS disk structure.
The
.Fn getinode
function fetches the specified inode from the filesystem.
The
.Fn putinode
function stores the most recently fetched inode to the filesystem.
.Pp
The
.Va dinodep
union is defined as:
.Bd -literal -offset indent
union dinodep {
struct ufs1_dinode *dp1;
struct ufs2_dinode *dp2;
};
.Ed
.Pp
Sample code to clear write permissions for inode number
.Fa inumber
stored on the filesystem described by
.Fa diskp .
.Bd -literal -offset indent
#include <sys/stat.h>
#include <err.h>
#include <ufs/ufs/dinode.h>
#include <ufs/ffs/fs.h>
#include <libufs.h>
void
clearwrite(struct uufsd *diskp, ino_t inumber)
{
union dinodep dp;
if (getinode(diskp, &dp, inumber) == -1)
err(1, "getinode: %s", diskp->d_error);
switch (diskp->d_ufs) {
case 1: /* UFS 1 filesystem */
dp.dp1->di_mode &= ~(S_IWUSR | S_IWGRP | S_IWOTH);
break;
case 2: /* UFS 2 filesystem */
dp.dp2->di_mode &= ~(S_IWUSR | S_IWGRP | S_IWOTH);
break;
default:
errx(1, "unknown filesystem type");
}
if (putinode(diskp) == -1)
err(1, "putinode: %s", diskp->d_error);
}
.Ed
.Sh RETURN VALUES
The
.Fn getinode
and
.Fn putinode
functions return 0 on success, or \-1 in case of any error.
A string describing the error is stored in
.Fa diskp->d_error .
The global
.Fa errno
often provides additional information.
.Sh ERRORS
The function
.Fn getinode
may fail and set
.Va errno
for any of the errors specified for the library function
.Xr pread 2 .
It can also fail if the inode number is out of the range of inodes
in the filesystem.
.Pp
The function
.Fn putinode
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr ufs_disk_write 3
or
.Xr pwrite 2 .
.Pp
Additionally both functions may follow the
.Xr libufs 3
error methodologies in case of a device error.
.Sh SEE ALSO
.Xr pread 2 ,
.Xr pwrite 2 ,
.Xr libufs 3 ,
.Xr ufs_disk_write 3
.Sh HISTORY
These functions first appeared as part of
.Xr libufs 3
in
.Fx 13.0 .
.Sh AUTHORS
.An Marshall Kirk McKusick Aq Mt mckusick@freebsd.org