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 */
29 typedef struct _ntfs_attr ntfs_attr;
30 typedef 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
40 extern ntfschar AT_UNNAMED[];
41 extern ntfschar STREAM_SDS[];
42
43 /* The little endian Unicode string $TXF_DATA as a global constant. */
44 extern 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 */
53 typedef 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
61 typedef 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 */
86 struct _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
97 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx *ctx);
98 extern ntfs_attr_search_ctx *ntfs_attr_get_search_ctx(ntfs_inode *ni,
99 MFT_RECORD *mrec);
100 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx *ctx);
101
102 extern 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
107 extern int ntfs_attr_position(const ATTR_TYPES type, ntfs_attr_search_ctx *ctx);
108
109 extern 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 */
ntfs_attrs_walk(ntfs_attr_search_ctx * ctx)137 static __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 */
185 struct _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 */
207 typedef 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) \
250 extern int NAttr##func_name(ntfs_attr *na); \
251 extern void NAttrSet##func_name(ntfs_attr *na); \
252 extern void NAttrClear##func_name(ntfs_attr *na);
253
254 GenNAttrIno(Compressed, FILE_ATTR_COMPRESSED)
255 GenNAttrIno(Encrypted, FILE_ATTR_ENCRYPTED)
256 GenNAttrIno(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 */
264 typedef 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
286 extern 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 */
295 extern ntfs_attr *ntfs_attr_open(ntfs_inode *ni, const ATTR_TYPES type,
296 ntfschar *name, u32 name_len);
297 extern void ntfs_attr_close(ntfs_attr *na);
298
299 extern s64 ntfs_attr_pread(ntfs_attr *na, const s64 pos, s64 count,
300 void *b);
301 extern s64 ntfs_attr_pwrite(ntfs_attr *na, const s64 pos, s64 count,
302 const void *b);
303 extern int ntfs_attr_pclose(ntfs_attr *na);
304
305 extern void *ntfs_attr_readall(ntfs_inode *ni, const ATTR_TYPES type,
306 ntfschar *name, u32 name_len, s64 *data_size);
307
308 extern s64 ntfs_attr_mst_pread(ntfs_attr *na, const s64 pos,
309 const s64 bk_cnt, const u32 bk_size, void *dst);
310 extern s64 ntfs_attr_mst_pwrite(ntfs_attr *na, const s64 pos,
311 s64 bk_cnt, const u32 bk_size, void *src);
312
313 extern int ntfs_attr_map_runlist(ntfs_attr *na, VCN vcn);
314 extern int ntfs_attr_map_whole_runlist(ntfs_attr *na);
315
316 extern LCN ntfs_attr_vcn_to_lcn(ntfs_attr *na, const VCN vcn);
317 extern runlist_element *ntfs_attr_find_vcn(ntfs_attr *na, const VCN vcn);
318
319 extern int ntfs_attr_size_bounds_check(const ntfs_volume *vol,
320 const ATTR_TYPES type, const s64 size);
321 extern int ntfs_attr_can_be_resident(const ntfs_volume *vol,
322 const ATTR_TYPES type);
323 int ntfs_attr_make_non_resident(ntfs_attr *na,
324 ntfs_attr_search_ctx *ctx);
325 int ntfs_attr_force_non_resident(ntfs_attr *na);
326 extern int ntfs_make_room_for_attr(MFT_RECORD *m, u8 *pos, u32 size);
327
328 extern 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);
331 extern 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);
334 extern int ntfs_attr_record_rm(ntfs_attr_search_ctx *ctx);
335
336 extern int ntfs_attr_add(ntfs_inode *ni, ATTR_TYPES type,
337 ntfschar *name, u8 name_len, const u8 *val, s64 size);
338 extern 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);
341 extern int ntfs_attr_rm(ntfs_attr *na);
342
343 extern int ntfs_attr_record_resize(MFT_RECORD *m, ATTR_RECORD *a, u32 new_size);
344
345 extern int ntfs_resident_attr_value_resize(MFT_RECORD *m, ATTR_RECORD *a,
346 const u32 new_size);
347
348 extern int ntfs_attr_record_move_to(ntfs_attr_search_ctx *ctx, ntfs_inode *ni);
349 extern int ntfs_attr_record_move_away(ntfs_attr_search_ctx *ctx, int extra);
350
351 extern int ntfs_attr_update_mapping_pairs(ntfs_attr *na, VCN from_vcn);
352
353 extern int ntfs_attr_truncate(ntfs_attr *na, const s64 newsize);
354 extern 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 */
367 extern 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 */
383 extern s64 ntfs_get_attribute_value(const ntfs_volume *vol,
384 const ATTR_RECORD *a, u8 *b);
385
386 extern void ntfs_attr_name_free(char **name);
387 extern char *ntfs_attr_name_get(const ntfschar *uname, const int uname_len);
388 extern int ntfs_attr_exist(ntfs_inode *ni, const ATTR_TYPES type,
389 const ntfschar *name, u32 name_len);
390 extern int ntfs_attr_remove(ntfs_inode *ni, const ATTR_TYPES type,
391 ntfschar *name, u32 name_len);
392 extern s64 ntfs_attr_get_free_bits(ntfs_attr *na);
393 extern 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);
396 extern 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);
399 extern int ntfs_attr_shrink_size(ntfs_inode *ni, ntfschar *stream_name,
400 int stream_name_len, off_t offset);
401
402 #endif /* defined _NTFS_ATTRIB_H */
403
404