include/attrib.h

   1 /*
   2  * attrib.h - Exports for attribute handling. Part of the Linux-NTFS project.
   3  *
   4  * Copyright (c) 2000-2003 Anton Altaparmakov
   5  *
   6  * This program/include file is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as published
   8  * by the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program/include file is distributed in the hope that it will be
  12  * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program (in the main directory of the Linux-NTFS
  18  * distribution in the file COPYING); if not, write to the Free Software
  19  * Foundation,Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20  */
  21
  22 #ifndef _NTFS_ATTRIB_H
  23 #define _NTFS_ATTRIB_H
  24
  25 /* Forward declarations */
  26 typedef struct _ntfs_attr ntfs_attr;
  27 typedef struct _ntfs_attr_search_ctx ntfs_attr_search_ctx;
  28
  29 #include "types.h"
  30 #include "unistr.h"
  31 #include "runlist.h"
  32 #include "volume.h"
  33
  34 extern uchar_t AT_UNNAMED[];
  35
  36 /**
  37  * ntfs_lcn_special_values - special return values for ntfs_*_vcn_to_lcn()
  38  *
  39  * Special return values for ntfs_rl_vcn_to_lcn() and ntfs_attr_vcn_to_lcn().
  40  *
  41  * TODO: Describe them.
  42  */
  43 typedef enum {
  44         LCN_HOLE                = -1,   /* Keep this as highest value or die! */
  45         LCN_RL_NOT_MAPPED       = -2,
  46         LCN_ENOENT              = -3,
  47         LCN_EINVAL              = -4,
  48         LCN_EIO                 = -5,
  49 } ntfs_lcn_special_values;
  50
  51 /**
  52  * ntfs_attr_search_ctx - search context used in attribute search functions
  53  * @mrec:       buffer containing mft record to search
  54  * @attr:       attribute record in @mrec where to begin/continue search
  55  * @is_first:   if true lookup_attr() begins search with @attr, else after @attr
  56  *
  57  * Structure must be initialized to zero before the first call to one of the
  58  * attribute search functions. Initialize @mrec to point to the mft record to
  59  * search, and @attr to point to the first attribute within @mrec (not necessary
  60  * if calling the _first() functions), and set @is_first to TRUE (not necessary
  61  * if calling the _first() functions).
  62  *
  63  * If @is_first is TRUE, the search begins with @attr. If @is_first is FALSE,
  64  * the search begins after @attr. This is so that, after the first call to one
  65  * of the search attribute functions, we can call the function again, without
  66  * any modification of the search context, to automagically get the next
  67  * matching attribute.
  68  */
  69 struct _ntfs_attr_search_ctx {
  70         MFT_RECORD *mrec;
  71         ATTR_RECORD *attr;
  72         BOOL is_first;
  73         ntfs_inode *ntfs_ino;
  74         ATTR_LIST_ENTRY *al_entry;
  75         ntfs_inode *base_ntfs_ino;
  76         MFT_RECORD *base_mrec;
  77         ATTR_RECORD *base_attr;
  78 };
  79
  80 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx *ctx);
  81 extern ntfs_attr_search_ctx *ntfs_attr_get_search_ctx(ntfs_inode *ni,
  82                 MFT_RECORD *mrec);
  83 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx *ctx);
  84
  85 extern int ntfs_attr_lookup(const ATTR_TYPES type, const uchar_t *name,
  86                 const u32 name_len, const IGNORE_CASE_BOOL ic,
  87                 const VCN lowest_vcn, const u8 *val, const u32 val_len,
  88                 ntfs_attr_search_ctx *ctx);
  89
  90 extern ATTR_DEF *ntfs_attr_find_in_attrdef(const ntfs_volume *vol,
  91                 const ATTR_TYPES type);
  92
  93 /**
  94  * ntfs_attrs_walk - syntactic sugar for walking all attributes in an inode
  95  * @ctx:        initialised attribute search context
  96  *
  97  * Syntactic sugar for walking attributes in an inode.
  98  *
  99  * Return 0 on success and -1 on error with errno set to the error code from
 100  * ntfs_attr_lookup().
 101  *
 102  * Example: When you want to enumerate all attributes in an open ntfs inode
 103  *          @ni, you can simply do:
 104  *
 105  *      int err;
 106  *      ntfs_attr_search_ctx *ctx = ntfs_attr_get_search_ctx(ni, NULL);
 107  *      if (!ctx)
 108  *              // Error code is in errno. Handle this case.
 109  *      while (!(err = ntfs_attrs_walk(ctx))) {
 110  *              ATTR_RECORD *attr = ctx->attr;
 111  *              // attr now contains the next attribute. Do whatever you want
 112  *              // with it and then just continue with the while loop.
 113  *      }
 114  *      if (err && errno != ENOENT)
 115  *              // Ooops. An error occured! You should handle this case.
 116  *      // Now finished with all attributes in the inode.
 117  */
 118 static __inline__ int ntfs_attrs_walk(ntfs_attr_search_ctx *ctx)
 119 {
 120         return ntfs_attr_lookup(0, NULL, 0, 0, 0, NULL, 0, ctx);
 121 }
 122
 123 /**
 124  * ntfs_attr_state_bits - bits for the state field in the ntfs_attr structure
 125  */
 126 typedef enum {
 127         NA_Initialized,         /* 1: structure is initialized. */
 128         NA_NonResident,         /* 1: Attribute is not resident. */
 129         NA_Compressed,          /* 1: Attribute is compressed. */
 130         NA_Encrypted,           /* 1: Attribute is encrypted. */
 131         NA_Sparse,              /* 1: Attribute is sparse. */
 132 } ntfs_attr_state_bits;
 133
 134 #define  test_nattr_flag(na, flag)       test_bit(NA_##flag, (na)->state)
 135 #define   set_nattr_flag(na, flag)        set_bit(NA_##flag, (na)->state)
 136 #define clear_nattr_flag(na, flag)      clear_bit(NA_##flag, (na)->state)
 137
 138 #define NAttrInitialized(na)             test_nattr_flag(na, Initialized)
 139 #define NAttrSetInitialized(na)           set_nattr_flag(na, Initialized)
 140 #define NAttrClearInitialized(na)       clear_nattr_flag(na, Initialized)
 141
 142 #define NAttrNonResident(na)             test_nattr_flag(na, NonResident)
 143 #define NAttrSetNonResident(na)           set_nattr_flag(na, NonResident)
 144 #define NAttrClearNonResident(na)       clear_nattr_flag(na, NonResident)
 145
 146 #define NAttrCompressed(na)              test_nattr_flag(na, Compressed)
 147 #define NAttrSetCompressed(na)            set_nattr_flag(na, Compressed)
 148 #define NAttrClearCompressed(na)        clear_nattr_flag(na, Compressed)
 149
 150 #define NAttrEncrypted(na)               test_nattr_flag(na, Encrypted)
 151 #define NAttrSetEncrypted(na)             set_nattr_flag(na, Encrypted)
 152 #define NAttrClearEncrypted(na)         clear_nattr_flag(na, Encrypted)
 153
 154 #define NAttrSparse(na)                  test_nattr_flag(na, Sparse)
 155 #define NAttrSetSparse(na)                set_nattr_flag(na, Sparse)
 156 #define NAttrClearSparse(na)            clear_nattr_flag(na, Sparse)
 157
 158 /**
 159  * ntfs_attr - ntfs in memory non-resident attribute structure
 160  * @rl:         if not NULL, the decompressed runlist
 161  * @ni:         base ntfs inode to which this attribute belongs
 162  * @type:       attribute type
 163  * @name:       Unicode name of the attribute
 164  * @name_len:   length of @name in Unicode characters
 165  * @state:      NTFS attribute specific flags descibing this attribute
 166  *
 167  * This structure exists purely to provide a mechanism of caching the runlist
 168  * of an attribute. If you want to operate on a particular attribute extent,
 169  * you should not be using this structure at all. If you want to work with a
 170  * resident attribute, you should not be using this structure at all. As a
 171  * fail-safe check make sure to test NAttrNonResident() and if it is false, you
 172  * know you shouldn't be using this structure.
 173  *
 174  * If you want to work on a resident attribute or on a specific attribute
 175  * extent, you should use ntfs_lookup_attr() to retrieve the attribute (extent)
 176  * record, edit that, and then write back the mft record (or set the
 177  * corresponding ntfs inode dirty for delayed write back).
 178  *
 179  * @rl is the decompressed runlist of the attribute described by this
 180  * structure. Obviously this only makes sense if the attribute is not resident,
 181  * i.e. NAttrNonResident() is true. If the runlist hasn't been decomressed yet
 182  * @rl is NULL, so be prepared to cope with @rl == NULL.
 183  *
 184  * @ni is the base ntfs inode of the attribute described by this structure.
 185  *
 186  * @type is the attribute type (see layout.h for the definition of ATTR_TYPES),
 187  * @name and @name_len are the little endian Unicode name and the name length
 188  * in Unicode characters of the attribute, respecitvely.
 189  *
 190  * @state contains NTFS attribute specific flags descibing this attribute
 191  * structure. See ntfs_attr_state_bits above.
 192  */
 193 struct _ntfs_attr {
 194         runlist_element *rl;
 195         ntfs_inode *ni;
 196         ATTR_TYPES type;
 197         uchar_t *name;
 198         u32 name_len;
 199         unsigned long state;
 200         s64 allocated_size;
 201         s64 data_size;
 202         s64 initialized_size;
 203         s64 compressed_size;
 204         u32 compression_block_size;
 205         u8 compression_block_size_bits;
 206         u8 compression_block_clusters;
 207 };
 208
 209 /*
 210  * Union of all known attribute values. For convenience. Used in the attr
 211  * structure.
 212  */
 213 typedef union {
 214         u8 _default;    /* Unnamed u8 to serve as default when just using
 215                            a_val without specifying any of the below. */
 216         STANDARD_INFORMATION std_inf;
 217         ATTR_LIST_ENTRY al_entry;
 218         FILE_NAME_ATTR filename;
 219         OBJECT_ID_ATTR obj_id;
 220         SECURITY_DESCRIPTOR_ATTR sec_desc;
 221         VOLUME_NAME vol_name;
 222         VOLUME_INFORMATION vol_inf;
 223         DATA_ATTR data;
 224         INDEX_ROOT index_root;
 225         INDEX_BLOCK index_blk;
 226         BITMAP_ATTR bmp;
 227         REPARSE_POINT reparse;
 228         EA_INFORMATION ea_inf;
 229         EA_ATTR ea;
 230         PROPERTY_SET property_set;
 231         LOGGED_UTILITY_STREAM logged_util_stream;
 232         EFS_ATTR efs;
 233 } attr_val;
 234
 235 extern void ntfs_attr_init(ntfs_attr *na, const BOOL non_resident,
 236                 const BOOL compressed, const BOOL encrypted, const BOOL sparse,
 237                 const s64 allocated_size, const s64 data_size,
 238                 const s64 initialized_size, const s64 compressed_size,
 239                 const u8 compression_unit);
 240
 241 extern ntfs_attr *ntfs_attr_open(ntfs_inode *ni, const ATTR_TYPES type,
 242                 uchar_t *name, const u32 name_len);
 243 extern void ntfs_attr_close(ntfs_attr *na);
 244
 245 extern s64 ntfs_attr_pread(ntfs_attr *na, const s64 pos, s64 count,
 246                 void *b);
 247 extern s64 ntfs_attr_pwrite(ntfs_attr *na, const s64 pos, s64 count,
 248                 void *b);
 249
 250 extern s64 ntfs_attr_mst_pread(ntfs_attr *na, const s64 pos,
 251                 const s64 bk_cnt, const u32 bk_size, void *dst);
 252 extern s64 ntfs_attr_mst_pwrite(ntfs_attr *na, const s64 pos,
 253                 s64 bk_cnt, const u32 bk_size, void *src);
 254
 255 extern int ntfs_attr_map_runlist(ntfs_attr *na, VCN vcn);
 256
 257 extern LCN ntfs_attr_vcn_to_lcn(ntfs_attr *na, const VCN vcn);
 258 extern runlist_element *ntfs_attr_find_vcn(ntfs_attr *na, const VCN vcn);
 259
 260 extern int ntfs_attr_size_bounds_check(const ntfs_volume *vol,
 261                 const ATTR_TYPES type, const s64 size);
 262 extern int ntfs_attr_can_be_non_resident(const ntfs_volume *vol,
 263                 const ATTR_TYPES type);
 264
 265 extern int ntfs_resident_attr_value_resize(MFT_RECORD *m, ATTR_RECORD *a,
 266                 const u32 newsize);
 267
 268 extern int ntfs_attr_truncate(ntfs_attr *na, const s64 newsize);
 269
 270 // FIXME / TODO: Above here the file is cleaned up. (AIA)
 271 /**
 272  * get_attribute_value_length - return the length of the value of an attribute
 273  * @a:  pointer to a buffer containing the attribute record
 274  *
 275  * Return the byte size of the attribute value of the attribute @a (as it
 276  * would be after eventual decompression and filling in of holes if sparse).
 277  * If we return 0, check errno. If errno is 0 the actual length was 0,
 278  * otherwise errno describes the error.
 279  *
 280  * FIXME: Describe possible errnos.
 281  */
 282 s64 ntfs_get_attribute_value_length(const ATTR_RECORD *a);
 283
 284 /**
 285  * get_attribute_value - return the attribute value of an attribute
 286  * @vol:        volume on which the attribute is present
 287  * @a:          attribute to get the value of
 288  * @b:          destination buffer for the attribute value
 289  *
 290  * Make a copy of the attribute value of the attribute @a into the destination
 291  * buffer @b. Note, that the size of @b has to be at least equal to the value
 292  * returned by get_attribute_value_length(@a).
 293  *
 294  * Return number of bytes copied. If this is zero check errno. If errno is 0
 295  * then nothing was read due to a zero-length attribute value, otherwise
 296  * errno describes the error.
 297  */
 298 s64 ntfs_get_attribute_value(const ntfs_volume *vol, const MFT_RECORD *m,
 299                 const ATTR_RECORD *a, u8 *b);
 300
 301 #endif /* defined _NTFS_ATTRIB_H */
 302