2 * attrib.h - Exports for attribute handling. Originated from the Linux-NTFS project.
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
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.
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.
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
25 #ifndef _NTFS_ATTRIB_H
26 #define _NTFS_ATTRIB_H
28 /* Forward declarations */
29 typedef struct _ntfs_attr ntfs_attr
;
30 typedef struct _ntfs_attr_search_ctx ntfs_attr_search_ctx
;
40 extern ntfschar AT_UNNAMED
[];
41 extern ntfschar STREAM_SDS
[];
43 /* The little endian Unicode string $TXF_DATA as a global constant. */
44 extern ntfschar TXF_DATA
[10];
47 * enum ntfs_lcn_special_values - special return values for ntfs_*_vcn_to_lcn()
49 * Special return values for ntfs_rl_vcn_to_lcn() and ntfs_attr_vcn_to_lcn().
51 * TODO: Describe them.
54 LCN_HOLE
= -1, /* Keep this as highest value or die! */
55 LCN_RL_NOT_MAPPED
= -2,
59 } ntfs_lcn_special_values
;
61 typedef enum { /* ways of processing holes when expanding */
68 * struct ntfs_attr_search_ctx - search context used in attribute search functions
69 * @mrec: buffer containing mft record to search
70 * @attr: attribute record in @mrec where to begin/continue search
71 * @is_first: if true lookup_attr() begins search with @attr, else after @attr
73 * Structure must be initialized to zero before the first call to one of the
74 * attribute search functions. Initialize @mrec to point to the mft record to
75 * search, and @attr to point to the first attribute within @mrec (not necessary
76 * if calling the _first() functions), and set @is_first to TRUE (not necessary
77 * if calling the _first() functions).
79 * If @is_first is TRUE, the search begins with @attr. If @is_first is FALSE,
80 * the search begins after @attr. This is so that, after the first call to one
81 * of the search attribute functions, we can call the function again, without
82 * any modification of the search context, to automagically get the next
85 struct _ntfs_attr_search_ctx
{
90 ATTR_LIST_ENTRY
*al_entry
;
91 ntfs_inode
*base_ntfs_ino
;
92 MFT_RECORD
*base_mrec
;
93 ATTR_RECORD
*base_attr
;
96 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx
*ctx
);
97 extern ntfs_attr_search_ctx
*ntfs_attr_get_search_ctx(ntfs_inode
*ni
,
99 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx
*ctx
);
101 extern int ntfs_attr_lookup(const ATTR_TYPES type
, const ntfschar
*name
,
102 const u32 name_len
, const IGNORE_CASE_BOOL ic
,
103 const VCN lowest_vcn
, const u8
*val
, const u32 val_len
,
104 ntfs_attr_search_ctx
*ctx
);
106 extern int ntfs_attr_position(const ATTR_TYPES type
, ntfs_attr_search_ctx
*ctx
);
108 extern ATTR_DEF
*ntfs_attr_find_in_attrdef(const ntfs_volume
*vol
,
109 const ATTR_TYPES type
);
112 * ntfs_attrs_walk - syntactic sugar for walking all attributes in an inode
113 * @ctx: initialised attribute search context
115 * Syntactic sugar for walking attributes in an inode.
117 * Return 0 on success and -1 on error with errno set to the error code from
118 * ntfs_attr_lookup().
120 * Example: When you want to enumerate all attributes in an open ntfs inode
121 * @ni, you can simply do:
124 * ntfs_attr_search_ctx *ctx = ntfs_attr_get_search_ctx(ni, NULL);
126 * // Error code is in errno. Handle this case.
127 * while (!(err = ntfs_attrs_walk(ctx))) {
128 * ATTR_RECORD *attr = ctx->attr;
129 * // attr now contains the next attribute. Do whatever you want
130 * // with it and then just continue with the while loop.
132 * if (err && errno != ENOENT)
133 * // Ooops. An error occurred! You should handle this case.
134 * // Now finished with all attributes in the inode.
136 static __inline__
int ntfs_attrs_walk(ntfs_attr_search_ctx
*ctx
)
138 return ntfs_attr_lookup(AT_UNUSED
, NULL
, 0, CASE_SENSITIVE
, 0,
143 * struct ntfs_attr - ntfs in memory non-resident attribute structure
144 * @rl: if not NULL, the decompressed runlist
145 * @ni: base ntfs inode to which this attribute belongs
146 * @type: attribute type
147 * @name: Unicode name of the attribute
148 * @name_len: length of @name in Unicode characters
149 * @state: NTFS attribute specific flags describing this attribute
150 * @allocated_size: copy from the attribute record
151 * @data_size: copy from the attribute record
152 * @initialized_size: copy from the attribute record
153 * @compressed_size: copy from the attribute record
154 * @compression_block_size: size of a compression block (cb)
155 * @compression_block_size_bits: log2 of the size of a cb
156 * @compression_block_clusters: number of clusters per cb
158 * This structure exists purely to provide a mechanism of caching the runlist
159 * of an attribute. If you want to operate on a particular attribute extent,
160 * you should not be using this structure at all. If you want to work with a
161 * resident attribute, you should not be using this structure at all. As a
162 * fail-safe check make sure to test NAttrNonResident() and if it is false, you
163 * know you shouldn't be using this structure.
165 * If you want to work on a resident attribute or on a specific attribute
166 * extent, you should use ntfs_lookup_attr() to retrieve the attribute (extent)
167 * record, edit that, and then write back the mft record (or set the
168 * corresponding ntfs inode dirty for delayed write back).
170 * @rl is the decompressed runlist of the attribute described by this
171 * structure. Obviously this only makes sense if the attribute is not resident,
172 * i.e. NAttrNonResident() is true. If the runlist hasn't been decompressed yet
173 * @rl is NULL, so be prepared to cope with @rl == NULL.
175 * @ni is the base ntfs inode of the attribute described by this structure.
177 * @type is the attribute type (see layout.h for the definition of ATTR_TYPES),
178 * @name and @name_len are the little endian Unicode name and the name length
179 * in Unicode characters of the attribute, respectively.
181 * @state contains NTFS attribute specific flags describing this attribute
182 * structure. See ntfs_attr_state_bits above.
188 ATTR_FLAGS data_flags
;
194 s64 initialized_size
;
196 u32 compression_block_size
;
197 u8 compression_block_size_bits
;
198 u8 compression_block_clusters
;
199 s8 unused_runs
; /* pre-reserved entries available */
203 * enum ntfs_attr_state_bits - bits for the state field in the ntfs_attr
207 NA_Initialized
, /* 1: structure is initialized. */
208 NA_NonResident
, /* 1: Attribute is not resident. */
209 NA_BeingNonResident
, /* 1: Attribute is being made not resident. */
210 NA_FullyMapped
, /* 1: Attribute has been fully mapped */
211 NA_DataAppending
, /* 1: Attribute is being appended to */
212 NA_ComprClosing
, /* 1: Compressed attribute is being closed */
213 } ntfs_attr_state_bits
;
215 #define test_nattr_flag(na, flag) test_bit(NA_##flag, (na)->state)
216 #define set_nattr_flag(na, flag) set_bit(NA_##flag, (na)->state)
217 #define clear_nattr_flag(na, flag) clear_bit(NA_##flag, (na)->state)
219 #define NAttrInitialized(na) test_nattr_flag(na, Initialized)
220 #define NAttrSetInitialized(na) set_nattr_flag(na, Initialized)
221 #define NAttrClearInitialized(na) clear_nattr_flag(na, Initialized)
223 #define NAttrNonResident(na) test_nattr_flag(na, NonResident)
224 #define NAttrSetNonResident(na) set_nattr_flag(na, NonResident)
225 #define NAttrClearNonResident(na) clear_nattr_flag(na, NonResident)
227 #define NAttrBeingNonResident(na) test_nattr_flag(na, BeingNonResident)
228 #define NAttrSetBeingNonResident(na) set_nattr_flag(na, BeingNonResident)
229 #define NAttrClearBeingNonResident(na) clear_nattr_flag(na, BeingNonResident)
231 #define NAttrFullyMapped(na) test_nattr_flag(na, FullyMapped)
232 #define NAttrSetFullyMapped(na) set_nattr_flag(na, FullyMapped)
233 #define NAttrClearFullyMapped(na) clear_nattr_flag(na, FullyMapped)
235 #define NAttrDataAppending(na) test_nattr_flag(na, DataAppending)
236 #define NAttrSetDataAppending(na) set_nattr_flag(na, DataAppending)
237 #define NAttrClearDataAppending(na) clear_nattr_flag(na, DataAppending)
239 #define NAttrComprClosing(na) test_nattr_flag(na, ComprClosing)
240 #define NAttrSetComprClosing(na) set_nattr_flag(na, ComprClosing)
241 #define NAttrClearComprClosing(na) clear_nattr_flag(na, ComprClosing)
243 #define GenNAttrIno(func_name, flag) \
244 extern int NAttr##func_name(ntfs_attr *na); \
245 extern void NAttrSet##func_name(ntfs_attr *na); \
246 extern void NAttrClear##func_name(ntfs_attr *na);
248 GenNAttrIno(Compressed
, FILE_ATTR_COMPRESSED
)
249 GenNAttrIno(Encrypted
, FILE_ATTR_ENCRYPTED
)
250 GenNAttrIno(Sparse
, FILE_ATTR_SPARSE_FILE
)
254 * union attr_val - Union of all known attribute values
256 * For convenience. Used in the attr structure.
259 u8 _default
; /* Unnamed u8 to serve as default when just using
260 a_val without specifying any of the below. */
261 STANDARD_INFORMATION std_inf
;
262 ATTR_LIST_ENTRY al_entry
;
263 FILE_NAME_ATTR filename
;
264 OBJECT_ID_ATTR obj_id
;
265 SECURITY_DESCRIPTOR_ATTR sec_desc
;
266 VOLUME_NAME vol_name
;
267 VOLUME_INFORMATION vol_inf
;
269 INDEX_ROOT index_root
;
270 INDEX_BLOCK index_blk
;
272 REPARSE_POINT reparse
;
273 EA_INFORMATION ea_inf
;
275 PROPERTY_SET property_set
;
276 LOGGED_UTILITY_STREAM logged_util_stream
;
280 extern void ntfs_attr_init(ntfs_attr
*na
, const BOOL non_resident
,
281 const ATTR_FLAGS data_flags
, const BOOL encrypted
,
283 const s64 allocated_size
, const s64 data_size
,
284 const s64 initialized_size
, const s64 compressed_size
,
285 const u8 compression_unit
);
287 /* warning : in the following "name" has to be freeable */
288 /* or one of constants AT_UNNAMED, NTFS_INDEX_I30 or STREAM_SDS */
289 extern ntfs_attr
*ntfs_attr_open(ntfs_inode
*ni
, const ATTR_TYPES type
,
290 ntfschar
*name
, u32 name_len
);
291 extern void ntfs_attr_close(ntfs_attr
*na
);
293 extern s64
ntfs_attr_pread(ntfs_attr
*na
, const s64 pos
, s64 count
,
295 extern s64
ntfs_attr_pwrite(ntfs_attr
*na
, const s64 pos
, s64 count
,
297 extern int ntfs_attr_pclose(ntfs_attr
*na
);
299 extern void *ntfs_attr_readall(ntfs_inode
*ni
, const ATTR_TYPES type
,
300 ntfschar
*name
, u32 name_len
, s64
*data_size
);
302 extern s64
ntfs_attr_mst_pread(ntfs_attr
*na
, const s64 pos
,
303 const s64 bk_cnt
, const u32 bk_size
, void *dst
);
304 extern s64
ntfs_attr_mst_pwrite(ntfs_attr
*na
, const s64 pos
,
305 s64 bk_cnt
, const u32 bk_size
, void *src
);
307 extern int ntfs_attr_map_runlist(ntfs_attr
*na
, VCN vcn
);
308 extern int ntfs_attr_map_whole_runlist(ntfs_attr
*na
);
310 extern LCN
ntfs_attr_vcn_to_lcn(ntfs_attr
*na
, const VCN vcn
);
311 extern runlist_element
*ntfs_attr_find_vcn(ntfs_attr
*na
, const VCN vcn
);
313 extern int ntfs_attr_size_bounds_check(const ntfs_volume
*vol
,
314 const ATTR_TYPES type
, const s64 size
);
315 extern int ntfs_attr_can_be_resident(const ntfs_volume
*vol
,
316 const ATTR_TYPES type
);
317 int ntfs_attr_make_non_resident(ntfs_attr
*na
,
318 ntfs_attr_search_ctx
*ctx
);
319 int ntfs_attr_force_non_resident(ntfs_attr
*na
);
320 extern int ntfs_make_room_for_attr(MFT_RECORD
*m
, u8
*pos
, u32 size
);
322 extern int ntfs_resident_attr_record_add(ntfs_inode
*ni
, ATTR_TYPES type
,
323 ntfschar
*name
, u8 name_len
, u8
*val
, u32 size
,
325 extern int ntfs_non_resident_attr_record_add(ntfs_inode
*ni
, ATTR_TYPES type
,
326 ntfschar
*name
, u8 name_len
, VCN lowest_vcn
, int dataruns_size
,
328 extern int ntfs_attr_record_rm(ntfs_attr_search_ctx
*ctx
);
330 extern int ntfs_attr_add(ntfs_inode
*ni
, ATTR_TYPES type
,
331 ntfschar
*name
, u8 name_len
, u8
*val
, s64 size
);
332 extern int ntfs_attr_set_flags(ntfs_inode
*ni
, ATTR_TYPES type
,
333 ntfschar
*name
, u8 name_len
, ATTR_FLAGS flags
, ATTR_FLAGS mask
);
334 extern int ntfs_attr_rm(ntfs_attr
*na
);
336 extern int ntfs_attr_record_resize(MFT_RECORD
*m
, ATTR_RECORD
*a
, u32 new_size
);
338 extern int ntfs_resident_attr_value_resize(MFT_RECORD
*m
, ATTR_RECORD
*a
,
341 extern int ntfs_attr_record_move_to(ntfs_attr_search_ctx
*ctx
, ntfs_inode
*ni
);
342 extern int ntfs_attr_record_move_away(ntfs_attr_search_ctx
*ctx
, int extra
);
344 extern int ntfs_attr_update_mapping_pairs(ntfs_attr
*na
, VCN from_vcn
);
346 extern int ntfs_attr_truncate(ntfs_attr
*na
, const s64 newsize
);
347 extern int ntfs_attr_truncate_solid(ntfs_attr
*na
, const s64 newsize
);
350 * get_attribute_value_length - return the length of the value of an attribute
351 * @a: pointer to a buffer containing the attribute record
353 * Return the byte size of the attribute value of the attribute @a (as it
354 * would be after eventual decompression and filling in of holes if sparse).
355 * If we return 0, check errno. If errno is 0 the actual length was 0,
356 * otherwise errno describes the error.
358 * FIXME: Describe possible errnos.
360 extern s64
ntfs_get_attribute_value_length(const ATTR_RECORD
*a
);
363 * get_attribute_value - return the attribute value of an attribute
364 * @vol: volume on which the attribute is present
365 * @a: attribute to get the value of
366 * @b: destination buffer for the attribute value
368 * Make a copy of the attribute value of the attribute @a into the destination
369 * buffer @b. Note, that the size of @b has to be at least equal to the value
370 * returned by get_attribute_value_length(@a).
372 * Return number of bytes copied. If this is zero check errno. If errno is 0
373 * then nothing was read due to a zero-length attribute value, otherwise
374 * errno describes the error.
376 extern s64
ntfs_get_attribute_value(const ntfs_volume
*vol
,
377 const ATTR_RECORD
*a
, u8
*b
);
379 extern void ntfs_attr_name_free(char **name
);
380 extern char *ntfs_attr_name_get(const ntfschar
*uname
, const int uname_len
);
381 extern int ntfs_attr_exist(ntfs_inode
*ni
, const ATTR_TYPES type
,
382 ntfschar
*name
, u32 name_len
);
383 extern int ntfs_attr_remove(ntfs_inode
*ni
, const ATTR_TYPES type
,
384 ntfschar
*name
, u32 name_len
);
385 extern s64
ntfs_attr_get_free_bits(ntfs_attr
*na
);
386 extern int ntfs_attr_data_read(ntfs_inode
*ni
,
387 ntfschar
*stream_name
, int stream_name_len
,
388 char *buf
, size_t size
, off_t offset
);
389 extern int ntfs_attr_data_write(ntfs_inode
*ni
,
390 ntfschar
*stream_name
, int stream_name_len
,
391 char *buf
, size_t size
, off_t offset
);
393 #endif /* defined _NTFS_ATTRIB_H */