fs/xfs/libxfs/xfs_attr.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * Copyright (c) 2000,2002-2003,2005 Silicon Graphics, Inc.
   4  * All Rights Reserved.
   5  */
   6 #ifndef __XFS_ATTR_H__
   7 #define __XFS_ATTR_H__
   8
   9 struct xfs_inode;
  10 struct xfs_da_args;
  11 struct xfs_attr_list_context;
  12
  13 /*
  14  * Large attribute lists are structured around Btrees where all the data
  15  * elements are in the leaf nodes.  Attribute names are hashed into an int,
  16  * then that int is used as the index into the Btree.  Since the hashval
  17  * of an attribute name may not be unique, we may have duplicate keys.
  18  * The internal links in the Btree are logical block offsets into the file.
  19  *
  20  * Small attribute lists use a different format and are packed as tightly
  21  * as possible so as to fit into the literal area of the inode.
  22  */
  23
  24 /*
  25  * The maximum size (into the kernel or returned from the kernel) of an
  26  * attribute value or the buffer used for an attr_list() call.  Larger
  27  * sizes will result in an ERANGE return code.
  28  */
  29 #define ATTR_MAX_VALUELEN       (64*1024)       /* max length of a value */
  30
  31 /*
  32  * Kernel-internal version of the attrlist cursor.
  33  */
  34 struct xfs_attrlist_cursor_kern {
  35         __u32   hashval;        /* hash value of next entry to add */
  36         __u32   blkno;          /* block containing entry (suggestion) */
  37         __u32   offset;         /* offset in list of equal-hashvals */
  38         __u16   pad1;           /* padding to match user-level */
  39         __u8    pad2;           /* padding to match user-level */
  40         __u8    initted;        /* T/F: cursor has been initialized */
  41 };
  42
  43
  44 /*========================================================================
  45  * Structure used to pass context around among the routines.
  46  *========================================================================*/
  47
  48
  49 /* void; state communicated via *context */
  50 typedef void (*put_listent_func_t)(struct xfs_attr_list_context *, int,
  51                               unsigned char *, int, int);
  52
  53 struct xfs_attr_list_context {
  54         struct xfs_trans        *tp;
  55         struct xfs_inode        *dp;            /* inode */
  56         struct xfs_attrlist_cursor_kern cursor; /* position in list */
  57         void                    *buffer;        /* output buffer */
  58
  59         /*
  60          * Abort attribute list iteration if non-zero.  Can be used to pass
  61          * error values to the xfs_attr_list caller.
  62          */
  63         int                     seen_enough;
  64         bool                    allow_incomplete;
  65
  66         ssize_t                 count;          /* num used entries */
  67         int                     dupcnt;         /* count dup hashvals seen */
  68         int                     bufsize;        /* total buffer size */
  69         int                     firstu;         /* first used byte in buffer */
  70         unsigned int            attr_filter;    /* XFS_ATTR_{ROOT,SECURE} */
  71         int                     resynch;        /* T/F: resynch with cursor */
  72         put_listent_func_t      put_listent;    /* list output fmt function */
  73         int                     index;          /* index into output buffer */
  74 };
  75
  76
  77 /*
  78  * ========================================================================
  79  * Structure used to pass context around among the delayed routines.
  80  * ========================================================================
  81  */
  82
  83 /*
  84  * Below is a state machine diagram for attr remove operations. The  XFS_DAS_*
  85  * states indicate places where the function would return -EAGAIN, and then
  86  * immediately resume from after being called by the calling function. States
  87  * marked as a "subroutine state" indicate that they belong to a subroutine, and
  88  * so the calling function needs to pass them back to that subroutine to allow
  89  * it to finish where it left off. But they otherwise do not have a role in the
  90  * calling function other than just passing through.
  91  *
  92  * xfs_attr_remove_iter()
  93  *              │
  94  *              v
  95  *        have attr to remove? ──n──> done
  96  *              │
  97  *              y
  98  *              │
  99  *              v
 100  *        are we short form? ──y──> xfs_attr_shortform_remove ──> done
 101  *              │
 102  *              n
 103  *              │
 104  *              V
 105  *        are we leaf form? ──y──> xfs_attr_leaf_removename ──> done
 106  *              │
 107  *              n
 108  *              │
 109  *              V
 110  *   ┌── need to setup state?
 111  *   │          │
 112  *   n          y
 113  *   │          │
 114  *   │          v
 115  *   │ find attr and get state
 116  *   │ attr has remote blks? ──n─┐
 117  *   │          │                v
 118  *   │          │         find and invalidate
 119  *   │          y         the remote blocks.
 120  *   │          │         mark attr incomplete
 121  *   │          ├────────────────┘
 122  *   └──────────┤
 123  *              │
 124  *              v
 125  *   Have remote blks to remove? ───y─────┐
 126  *              │        ^          remove the blks
 127  *              │        │                │
 128  *              │        │                v
 129  *              │  XFS_DAS_RMTBLK <─n── done?
 130  *              │  re-enter with          │
 131  *              │  one less blk to        y
 132  *              │      remove             │
 133  *              │                         V
 134  *              │                  refill the state
 135  *              n                         │
 136  *              │                         v
 137  *              │                   XFS_DAS_RM_NAME
 138  *              │                         │
 139  *              ├─────────────────────────┘
 140  *              │
 141  *              v
 142  *       remove leaf and
 143  *       update hash with
 144  *   xfs_attr_node_remove_cleanup
 145  *              │
 146  *              v
 147  *           need to
 148  *        shrink tree? ─n─┐
 149  *              │         │
 150  *              y         │
 151  *              │         │
 152  *              v         │
 153  *          join leaf     │
 154  *              │         │
 155  *              v         │
 156  *      XFS_DAS_RM_SHRINK │
 157  *              │         │
 158  *              v         │
 159  *       do the shrink    │
 160  *              │         │
 161  *              v         │
 162  *          free state <──┘
 163  *              │
 164  *              v
 165  *            done
 166  *
 167  */
 168
 169 /*
 170  * Enum values for xfs_delattr_context.da_state
 171  *
 172  * These values are used by delayed attribute operations to keep track  of where
 173  * they were before they returned -EAGAIN.  A return code of -EAGAIN signals the
 174  * calling function to roll the transaction, and then call the subroutine to
 175  * finish the operation.  The enum is then used by the subroutine to jump back
 176  * to where it was and resume executing where it left off.
 177  */
 178 enum xfs_delattr_state {
 179         XFS_DAS_UNINIT          = 0,  /* No state has been set yet */
 180         XFS_DAS_RMTBLK,               /* Removing remote blks */
 181         XFS_DAS_RM_NAME,              /* Remove attr name */
 182         XFS_DAS_RM_SHRINK,            /* We are shrinking the tree */
 183 };
 184
 185 /*
 186  * Defines for xfs_delattr_context.flags
 187  */
 188 #define XFS_DAC_DEFER_FINISH            0x01 /* finish the transaction */
 189
 190 /*
 191  * Context used for keeping track of delayed attribute operations
 192  */
 193 struct xfs_delattr_context {
 194         struct xfs_da_args      *da_args;
 195
 196         /* Used in xfs_attr_node_removename to roll through removing blocks */
 197         struct xfs_da_state     *da_state;
 198
 199         /* Used to keep track of current state of delayed operation */
 200         unsigned int            flags;
 201         enum xfs_delattr_state  dela_state;
 202 };
 203
 204 /*========================================================================
 205  * Function prototypes for the kernel.
 206  *========================================================================*/
 207
 208 /*
 209  * Overall external interface routines.
 210  */
 211 int xfs_attr_inactive(struct xfs_inode *dp);
 212 int xfs_attr_list_ilocked(struct xfs_attr_list_context *);
 213 int xfs_attr_list(struct xfs_attr_list_context *);
 214 int xfs_inode_hasattr(struct xfs_inode *ip);
 215 bool xfs_attr_is_leaf(struct xfs_inode *ip);
 216 int xfs_attr_get_ilocked(struct xfs_da_args *args);
 217 int xfs_attr_get(struct xfs_da_args *args);
 218 int xfs_attr_set(struct xfs_da_args *args);
 219 int xfs_attr_set_args(struct xfs_da_args *args);
 220 int xfs_has_attr(struct xfs_da_args *args);
 221 int xfs_attr_remove_args(struct xfs_da_args *args);
 222 int xfs_attr_remove_iter(struct xfs_delattr_context *dac);
 223 int xfs_attr_trans_roll(struct xfs_delattr_context *dac);
 224 bool xfs_attr_namecheck(const void *name, size_t length);
 225 void xfs_delattr_context_init(struct xfs_delattr_context *dac,
 226                               struct xfs_da_args *args);
 227
 228 #endif  /* __XFS_ATTR_H__ */