2 * attrib.h - Exports for attribute handling. Part of the Linux-NTFS project.
4 * Copyright (c) 2000-2003 Anton Altaparmakov
6 * This program/include file is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License as published
8 * by the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program/include file is distributed in the hope that it will be
12 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program (in the main directory of the Linux-NTFS
18 * distribution in the file COPYING); if not, write to the Free Software
19 * Foundation,Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 #ifndef _NTFS_ATTRIB_H
23 #define _NTFS_ATTRIB_H
25 /* Forward declarations */
26 typedef struct _ntfs_attr ntfs_attr;
27 typedef struct _ntfs_attr_search_ctx ntfs_attr_search_ctx;
34 extern uchar_t AT_UNNAMED[];
37 * ntfs_lcn_special_values - special return values for ntfs_*_vcn_to_lcn()
39 * Special return values for ntfs_rl_vcn_to_lcn() and ntfs_attr_vcn_to_lcn().
41 * TODO: Describe them.
44 LCN_HOLE = -1, /* Keep this as highest value or die! */
45 LCN_RL_NOT_MAPPED = -2,
49 } ntfs_lcn_special_values;
52 * ntfs_attr_search_ctx - search context used in attribute search functions
53 * @mrec: buffer containing mft record to search
54 * @attr: attribute record in @mrec where to begin/continue search
55 * @is_first: if true lookup_attr() begins search with @attr, else after @attr
57 * Structure must be initialized to zero before the first call to one of the
58 * attribute search functions. Initialize @mrec to point to the mft record to
59 * search, and @attr to point to the first attribute within @mrec (not necessary
60 * if calling the _first() functions), and set @is_first to TRUE (not necessary
61 * if calling the _first() functions).
63 * If @is_first is TRUE, the search begins with @attr. If @is_first is FALSE,
64 * the search begins after @attr. This is so that, after the first call to one
65 * of the search attribute functions, we can call the function again, without
66 * any modification of the search context, to automagically get the next
69 struct _ntfs_attr_search_ctx {
74 ATTR_LIST_ENTRY *al_entry;
75 ntfs_inode *base_ntfs_ino;
76 MFT_RECORD *base_mrec;
77 ATTR_RECORD *base_attr;
80 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx *ctx);
81 extern ntfs_attr_search_ctx *ntfs_attr_get_search_ctx(ntfs_inode *ni,
83 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx *ctx);
85 extern int ntfs_attr_lookup(const ATTR_TYPES type, const uchar_t *name,
86 const u32 name_len, const IGNORE_CASE_BOOL ic,
87 const VCN lowest_vcn, const u8 *val, const u32 val_len,
88 ntfs_attr_search_ctx *ctx);
90 extern ATTR_DEF *ntfs_attr_find_in_attrdef(const ntfs_volume *vol,
91 const ATTR_TYPES type);
94 * ntfs_attrs_walk - syntactic sugar for walking all attributes in an inode
95 * @ctx: initialised attribute search context
97 * Syntactic sugar for walking attributes in an inode.
99 * Return 0 on success and -1 on error with errno set to the error code from
100 * ntfs_attr_lookup().
102 * Example: When you want to enumerate all attributes in an open ntfs inode
103 * @ni, you can simply do:
106 * ntfs_attr_search_ctx *ctx = ntfs_attr_get_search_ctx(ni, NULL);
108 * // Error code is in errno. Handle this case.
109 * while (!(err = ntfs_attrs_walk(ctx))) {
110 * ATTR_RECORD *attr = ctx->attr;
111 * // attr now contains the next attribute. Do whatever you want
112 * // with it and then just continue with the while loop.
114 * if (err && errno != ENOENT)
115 * // Ooops. An error occured! You should handle this case.
116 * // Now finished with all attributes in the inode.
118 static __inline__ int ntfs_attrs_walk(ntfs_attr_search_ctx *ctx)
120 return ntfs_attr_lookup(0, NULL, 0, 0, 0, NULL, 0, ctx);
124 * ntfs_attr_state_bits - bits for the state field in the ntfs_attr structure
127 NA_Initialized, /* 1: structure is initialized. */
128 NA_NonResident, /* 1: Attribute is not resident. */
129 NA_Compressed, /* 1: Attribute is compressed. */
130 NA_Encrypted, /* 1: Attribute is encrypted. */
131 NA_Sparse, /* 1: Attribute is sparse. */
132 } ntfs_attr_state_bits;
134 #define test_nattr_flag(na, flag) test_bit(NA_##flag, (na)->state)
135 #define set_nattr_flag(na, flag) set_bit(NA_##flag, (na)->state)
136 #define clear_nattr_flag(na, flag) clear_bit(NA_##flag, (na)->state)
138 #define NAttrInitialized(na) test_nattr_flag(na, Initialized)
139 #define NAttrSetInitialized(na) set_nattr_flag(na, Initialized)
140 #define NAttrClearInitialized(na) clear_nattr_flag(na, Initialized)
142 #define NAttrNonResident(na) test_nattr_flag(na, NonResident)
143 #define NAttrSetNonResident(na) set_nattr_flag(na, NonResident)
144 #define NAttrClearNonResident(na) clear_nattr_flag(na, NonResident)
146 #define NAttrCompressed(na) test_nattr_flag(na, Compressed)
147 #define NAttrSetCompressed(na) set_nattr_flag(na, Compressed)
148 #define NAttrClearCompressed(na) clear_nattr_flag(na, Compressed)
150 #define NAttrEncrypted(na) test_nattr_flag(na, Encrypted)
151 #define NAttrSetEncrypted(na) set_nattr_flag(na, Encrypted)
152 #define NAttrClearEncrypted(na) clear_nattr_flag(na, Encrypted)
154 #define NAttrSparse(na) test_nattr_flag(na, Sparse)
155 #define NAttrSetSparse(na) set_nattr_flag(na, Sparse)
156 #define NAttrClearSparse(na) clear_nattr_flag(na, Sparse)
159 * ntfs_attr - ntfs in memory non-resident attribute structure
160 * @rl: if not NULL, the decompressed runlist
161 * @ni: base ntfs inode to which this attribute belongs
162 * @type: attribute type
163 * @name: Unicode name of the attribute
164 * @name_len: length of @name in Unicode characters
165 * @state: NTFS attribute specific flags descibing this attribute
167 * This structure exists purely to provide a mechanism of caching the runlist
168 * of an attribute. If you want to operate on a particular attribute extent,
169 * you should not be using this structure at all. If you want to work with a
170 * resident attribute, you should not be using this structure at all. As a
171 * fail-safe check make sure to test NAttrNonResident() and if it is false, you
172 * know you shouldn't be using this structure.
174 * If you want to work on a resident attribute or on a specific attribute
175 * extent, you should use ntfs_lookup_attr() to retrieve the attribute (extent)
176 * record, edit that, and then write back the mft record (or set the
177 * corresponding ntfs inode dirty for delayed write back).
179 * @rl is the decompressed runlist of the attribute described by this
180 * structure. Obviously this only makes sense if the attribute is not resident,
181 * i.e. NAttrNonResident() is true. If the runlist hasn't been decomressed yet
182 * @rl is NULL, so be prepared to cope with @rl == NULL.
184 * @ni is the base ntfs inode of the attribute described by this structure.
186 * @type is the attribute type (see layout.h for the definition of ATTR_TYPES),
187 * @name and @name_len are the little endian Unicode name and the name length
188 * in Unicode characters of the attribute, respecitvely.
190 * @state contains NTFS attribute specific flags descibing this attribute
191 * structure. See ntfs_attr_state_bits above.
202 s64 initialized_size;
204 u32 compression_block_size;
205 u8 compression_block_size_bits;
206 u8 compression_block_clusters;
210 * Union of all known attribute values. For convenience. Used in the attr
214 u8 _default; /* Unnamed u8 to serve as default when just using
215 a_val without specifying any of the below. */
216 STANDARD_INFORMATION std_inf;
217 ATTR_LIST_ENTRY al_entry;
218 FILE_NAME_ATTR filename;
219 OBJECT_ID_ATTR obj_id;
220 SECURITY_DESCRIPTOR_ATTR sec_desc;
221 VOLUME_NAME vol_name;
222 VOLUME_INFORMATION vol_inf;
224 INDEX_ROOT index_root;
225 INDEX_BLOCK index_blk;
227 REPARSE_POINT reparse;
228 EA_INFORMATION ea_inf;
230 PROPERTY_SET property_set;
231 LOGGED_UTILITY_STREAM logged_util_stream;
235 extern void ntfs_attr_init(ntfs_attr *na, const BOOL non_resident,
236 const BOOL compressed, const BOOL encrypted, const BOOL sparse,
237 const s64 allocated_size, const s64 data_size,
238 const s64 initialized_size, const s64 compressed_size,
239 const u8 compression_unit);
241 extern ntfs_attr *ntfs_attr_open(ntfs_inode *ni, const ATTR_TYPES type,
242 uchar_t *name, const u32 name_len);
243 extern void ntfs_attr_close(ntfs_attr *na);
245 extern s64 ntfs_attr_pread(ntfs_attr *na, const s64 pos, s64 count,
247 extern s64 ntfs_attr_pwrite(ntfs_attr *na, const s64 pos, s64 count,
250 extern s64 ntfs_attr_mst_pread(ntfs_attr *na, const s64 pos,
251 const s64 bk_cnt, const u32 bk_size, void *dst);
252 extern s64 ntfs_attr_mst_pwrite(ntfs_attr *na, const s64 pos,
253 s64 bk_cnt, const u32 bk_size, void *src);
255 extern int ntfs_attr_map_runlist(ntfs_attr *na, VCN vcn);
257 extern LCN ntfs_attr_vcn_to_lcn(ntfs_attr *na, const VCN vcn);
258 extern runlist_element *ntfs_attr_find_vcn(ntfs_attr *na, const VCN vcn);
260 extern int ntfs_attr_size_bounds_check(const ntfs_volume *vol,
261 const ATTR_TYPES type, const s64 size);
262 extern int ntfs_attr_can_be_non_resident(const ntfs_volume *vol,
263 const ATTR_TYPES type);
265 extern int ntfs_resident_attr_value_resize(MFT_RECORD *m, ATTR_RECORD *a,
268 extern int ntfs_attr_truncate(ntfs_attr *na, const s64 newsize);
270 // FIXME / TODO: Above here the file is cleaned up. (AIA)
272 * get_attribute_value_length - return the length of the value of an attribute
273 * @a: pointer to a buffer containing the attribute record
275 * Return the byte size of the attribute value of the attribute @a (as it
276 * would be after eventual decompression and filling in of holes if sparse).
277 * If we return 0, check errno. If errno is 0 the actual length was 0,
278 * otherwise errno describes the error.
280 * FIXME: Describe possible errnos.
282 s64 ntfs_get_attribute_value_length(const ATTR_RECORD *a);
285 * get_attribute_value - return the attribute value of an attribute
286 * @vol: volume on which the attribute is present
287 * @a: attribute to get the value of
288 * @b: destination buffer for the attribute value
290 * Make a copy of the attribute value of the attribute @a into the destination
291 * buffer @b. Note, that the size of @b has to be at least equal to the value
292 * returned by get_attribute_value_length(@a).
294 * Return number of bytes copied. If this is zero check errno. If errno is 0
295 * then nothing was read due to a zero-length attribute value, otherwise
296 * errno describes the error.
298 s64 ntfs_get_attribute_value(const ntfs_volume *vol, const MFT_RECORD *m,
299 const ATTR_RECORD *a, u8 *b);
301 #endif /* defined _NTFS_ATTRIB_H */