lib/libufs/getinode.3

   1 .\" Author:     Marshall Kirk McKusick <mckusick@freebsd.org>
   2 .\" Date:       January 19, 2018
   3 .\" Description:
   4 .\"     Manual page for libufs functions:
   5 .\"             getinode(3)
   6 .\"             putinode(3)
   7 .\"
   8 .\" This file is in the public domain.
   9 .\"
  10 .\" $FreeBSD$
  11 .\"
  12 .Dd September 2, 2020
  13 .Dt GETINODE 3
  14 .Os
  15 .Sh NAME
  16 .Nm getinode , putinode
  17 .Nd fetch and store inodes on a UFS file system
  18 .Sh LIBRARY
  19 .Lb libufs
  20 .Sh SYNOPSIS
  21 .In ufs/ufs/dinode.h
  22 .In ufs/ffs/fs.h
  23 .In libufs.h
  24 .Ft int
  25 .Fn getinode "struct uufsd *disk" "union dinodep *dp" "ino_t inumber"
  26 .Ft int
  27 .Fn putinode "struct uufsd *disk"
  28 .Sh DESCRIPTION
  29 The
  30 .Fn getinode
  31 and
  32 .Fn putinode
  33 functions provide an inode fetch and store API for
  34 .Xr libufs 3
  35 consumers.
  36 They operate on a userland UFS disk structure.
  37 The
  38 .Fn getinode
  39 function fetches the specified inode from the filesystem.
  40 The
  41 .Fn putinode
  42 function stores the most recently fetched inode to the filesystem.
  43 .Pp
  44 The
  45 .Va dinodep
  46 union is defined as:
  47 .Bd -literal -offset indent
  48 union dinodep {
  49         struct ufs1_dinode *dp1;
  50         struct ufs2_dinode *dp2;
  51 };
  52 .Ed
  53 .Pp
  54 Sample code to clear write permissions for inode number
  55 .Fa inumber
  56 stored on the filesystem described by
  57 .Fa diskp .
  58 .Bd -literal -offset indent
  59 #include <sys/stat.h>
  60 #include <err.h>
  61
  62 #include <ufs/ufs/dinode.h>
  63 #include <ufs/ffs/fs.h>
  64 #include <libufs.h>
  65
  66 void
  67 clearwrite(struct uufsd *diskp, ino_t inumber)
  68 {
  69         union dinodep dp;
  70
  71         if (getinode(diskp, &dp, inumber) == -1)
  72                 err(1, "getinode: %s", diskp->d_error);
  73         switch (diskp->d_ufs) {
  74         case 1: /* UFS 1 filesystem */
  75                 dp.dp1->di_mode &= ~(S_IWUSR | S_IWGRP | S_IWOTH);
  76                 break;
  77         case 2: /* UFS 2 filesystem */
  78                 dp.dp2->di_mode &= ~(S_IWUSR | S_IWGRP | S_IWOTH);
  79                 break;
  80         default:
  81                 errx(1, "unknown filesystem type");
  82         }
  83         if (putinode(diskp) == -1)
  84                 err(1, "putinode: %s", diskp->d_error);
  85 }
  86 .Ed
  87 .Sh RETURN VALUES
  88 The
  89 .Fn getinode
  90 and
  91 .Fn putinode
  92 functions return 0 on success, or \-1 in case of any error.
  93 A string describing the error is stored in
  94 .Fa diskp->d_error .
  95 The global
  96 .Fa errno
  97 often provides additional information.
  98 .Sh ERRORS
  99 The function
 100 .Fn getinode
 101 may fail and set
 102 .Va errno
 103 for any of the errors specified for the library function
 104 .Xr pread 2 .
 105 It can also fail if the inode number is out of the range of inodes
 106 in the filesystem.
 107 .Pp
 108 The function
 109 .Fn putinode
 110 may fail and set
 111 .Va errno
 112 for any of the errors specified for the library functions
 113 .Xr ufs_disk_write 3
 114 or
 115 .Xr pwrite 2 .
 116 .Pp
 117 Additionally both functions may follow the
 118 .Xr libufs 3
 119 error methodologies in case of a device error.
 120 .Sh SEE ALSO
 121 .Xr pread 2 ,
 122 .Xr pwrite 2 ,
 123 .Xr libufs 3 ,
 124 .Xr ufs_disk_write 3
 125 .Sh HISTORY
 126 These functions first appeared as part of
 127 .Xr libufs 3
 128 in
 129 .Fx 13.0 .
 130 .Sh AUTHORS
 131 .An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org