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