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