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