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 */
27 typedef struct _ntfs_attr ntfs_attr;
28 typedef 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
40 extern 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 */
49 typedef 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 */
75 struct _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
86 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx *ctx);
87 extern ntfs_attr_search_ctx *ntfs_attr_get_search_ctx(ntfs_inode *ni,
88 MFT_RECORD *mrec);
89 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx *ctx);
90
91 extern 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
96 extern 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 */
124 static __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 */
184 struct _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 */
207 typedef 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) \
225 static 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 } \
231 static 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 } \
239 static 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
245 GenNAttrIno(Compressed, COMPRESSED)
246 GenNAttrIno(Encrypted, ENCRYPTED)
247 GenNAttrIno(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 */
255 typedef 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
278 extern 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
284 extern ntfs_attr *ntfs_attr_open(ntfs_inode *ni, const ATTR_TYPES type,
285 ntfschar *name, u32 name_len);
286 extern void ntfs_attr_close(ntfs_attr *na);
287
288 extern s64 ntfs_attr_pread(ntfs_attr *na, const s64 pos, s64 count,
289 void *b);
290 extern s64 ntfs_attr_pwrite(ntfs_attr *na, const s64 pos, s64 count,
291 const void *b);
292
293 extern void *ntfs_attr_readall(ntfs_inode *ni, const ATTR_TYPES type,
294 ntfschar *name, u32 name_len, s64 *data_size);
295
296 extern s64 ntfs_attr_mst_pread(ntfs_attr *na, const s64 pos,
297 const s64 bk_cnt, const u32 bk_size, void *dst);
298 extern s64 ntfs_attr_mst_pwrite(ntfs_attr *na, const s64 pos,
299 s64 bk_cnt, const u32 bk_size, void *src);
300
301 extern int ntfs_attr_map_runlist(ntfs_attr *na, VCN vcn);
302 extern int ntfs_attr_map_runlist_range(ntfs_attr *na, VCN from_vcn, VCN to_vcn);
303 extern int ntfs_attr_map_whole_runlist(ntfs_attr *na);
304
305 extern LCN ntfs_attr_vcn_to_lcn(ntfs_attr *na, const VCN vcn);
306 extern runlist_element *ntfs_attr_find_vcn(ntfs_attr *na, const VCN vcn);
307
308 extern int ntfs_attr_size_bounds_check(const ntfs_volume *vol,
309 const ATTR_TYPES type, const s64 size);
310 extern int ntfs_attr_can_be_non_resident(const ntfs_volume *vol,
311 const ATTR_TYPES type);
312 extern int ntfs_attr_can_be_resident(const ntfs_volume *vol,
313 const ATTR_TYPES type);
314
315 extern int ntfs_make_room_for_attr(MFT_RECORD *m, u8 *pos, u32 size);
316
317 extern 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);
320 extern 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);
323 extern int ntfs_attr_record_rm(ntfs_attr_search_ctx *ctx);
324
325 extern int ntfs_attr_add(ntfs_inode *ni, ATTR_TYPES type,
326 ntfschar *name, u8 name_len, u8 *val, s64 size);
327 extern int ntfs_attr_rm(ntfs_attr *na);
328
329 extern int ntfs_attr_record_resize(MFT_RECORD *m, ATTR_RECORD *a, u32 new_size);
330
331 extern int ntfs_resident_attr_value_resize(MFT_RECORD *m, ATTR_RECORD *a,
332 const u32 new_size);
333
334 extern int ntfs_attr_record_move_to(ntfs_attr_search_ctx *ctx, ntfs_inode *ni);
335 extern int ntfs_attr_record_move_away(ntfs_attr_search_ctx *ctx, int extra);
336
337 extern int ntfs_attr_update_mapping_pairs(ntfs_attr *na, VCN from_vcn);
338
339 extern int __ntfs_attr_truncate(ntfs_attr *na, const s64 newsize, BOOL sparse);
340 extern int ntfs_attr_truncate(ntfs_attr *na, const s64 newsize);
341
342 extern int ntfs_attr_exist(ntfs_inode *ni, const ATTR_TYPES type,
343 ntfschar *name, u32 name_len);
344
345 static __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 */
362 s64 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 */
378 s64 ntfs_get_attribute_value(const ntfs_volume *vol, const ATTR_RECORD *a,
379 u8 *b);
380
381 #endif /* defined _NTFS_ATTRIB_H */
382