1/* 2 * logfile.h - Exports for $LogFile handling. Originated from the Linux-NTFS project. 3 * 4 * Copyright (c) 2000-2005 Anton Altaparmakov 5 * 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. 10 * 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. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program (in the main directory of the NTFS-3G 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 20 */ 21 22#ifndef _NTFS_LOGFILE_H 23#define _NTFS_LOGFILE_H 24 25#include "types.h" 26#include "endians.h" 27#include "layout.h" 28 29/* 30 * Journal ($LogFile) organization: 31 * 32 * Two restart areas present in the first two pages (restart pages, one restart 33 * area in each page). When the volume is dismounted they should be identical, 34 * except for the update sequence array which usually has a different update 35 * sequence number. 36 * 37 * These are followed by log records organized in pages headed by a log record 38 * header going up to log file size. Not all pages contain log records when a 39 * volume is first formatted, but as the volume ages, all records will be used. 40 * When the log file fills up, the records at the beginning are purged (by 41 * modifying the oldest_lsn to a higher value presumably) and writing begins 42 * at the beginning of the file. Effectively, the log file is viewed as a 43 * circular entity. 44 * 45 * NOTE: Windows NT, 2000, and XP all use log file version 1.1 but they accept 46 * versions <= 1.x, including 0.-1. (Yes, that is a minus one in there!) We 47 * probably only want to support 1.1 as this seems to be the current version 48 * and we don't know how that differs from the older versions. The only 49 * exception is if the journal is clean as marked by the two restart pages 50 * then it doesn't matter whether we are on an earlier version. We can just 51 * reinitialize the logfile and start again with version 1.1. 52 */ 53 54/* Some $LogFile related constants. */ 55#define MaxLogFileSize 0x100000000ULL 56#define DefaultLogPageSize 4096 57#define MinLogRecordPages 48 58 59/** 60 * struct RESTART_PAGE_HEADER - Log file restart page header. 61 * 62 * Begins the restart area. 63 */ 64typedef struct { 65/*Ofs*/ 66/* 0 NTFS_RECORD; -- Unfolded here as gcc doesn't like unnamed structs. */ 67/* 0*/ NTFS_RECORD_TYPES magic;/* The magic is "RSTR". */ 68/* 4*/ le16 usa_ofs; /* See NTFS_RECORD definition in layout.h. 69 When creating, set this to be immediately 70 after this header structure (without any 71 alignment). */ 72/* 6*/ le16 usa_count; /* See NTFS_RECORD definition in layout.h. */ 73 74/* 8*/ leLSN chkdsk_lsn; /* The last log file sequence number found by 75 chkdsk. Only used when the magic is changed 76 to "CHKD". Otherwise this is zero. */ 77/* 16*/ le32 system_page_size; /* Byte size of system pages when the log file 78 was created, has to be >= 512 and a power of 79 2. Use this to calculate the required size 80 of the usa (usa_count) and add it to usa_ofs. 81 Then verify that the result is less than the 82 value of the restart_area_offset. */ 83/* 20*/ le32 log_page_size; /* Byte size of log file pages, has to be >= 84 512 and a power of 2. The default is 4096 85 and is used when the system page size is 86 between 4096 and 8192. Otherwise this is 87 set to the system page size instead. */ 88/* 24*/ le16 restart_area_offset;/* Byte offset from the start of this header to 89 the RESTART_AREA. Value has to be aligned 90 to 8-byte boundary. When creating, set this 91 to be after the usa. */ 92/* 26*/ sle16 minor_ver; /* Log file minor version. Only check if major 93 version is 1. */ 94/* 28*/ sle16 major_ver; /* Log file major version. We only support 95 version 1.1. */ 96/* sizeof() = 30 (0x1e) bytes */ 97} __attribute__((__packed__)) RESTART_PAGE_HEADER; 98 99/* 100 * Constant for the log client indices meaning that there are no client records 101 * in this particular client array. Also inside the client records themselves, 102 * this means that there are no client records preceding or following this one. 103 */ 104#define LOGFILE_NO_CLIENT const_cpu_to_le16(0xffff) 105#define LOGFILE_NO_CLIENT_CPU 0xffff 106 107/* 108 * These are the so far known RESTART_AREA_* flags (16-bit) which contain 109 * information about the log file in which they are present. 110 */ 111enum { 112 RESTART_VOLUME_IS_CLEAN = const_cpu_to_le16(0x0002), 113 RESTART_SPACE_FILLER = 0xffff, /* gcc: Force enum bit width to 16. */ 114} __attribute__((__packed__)); 115 116typedef le16 RESTART_AREA_FLAGS; 117 118/** 119 * struct RESTART_AREA - Log file restart area record. 120 * 121 * The offset of this record is found by adding the offset of the 122 * RESTART_PAGE_HEADER to the restart_area_offset value found in it. 123 * See notes at restart_area_offset above. 124 */ 125typedef struct { 126/*Ofs*/ 127/* 0*/ leLSN current_lsn; /* The current, i.e. last LSN inside the log 128 when the restart area was last written. 129 This happens often but what is the interval? 130 Is it just fixed time or is it every time a 131 check point is written or something else? 132 On create set to 0. */ 133/* 8*/ le16 log_clients; /* Number of log client records in the array of 134 log client records which follows this 135 restart area. Must be 1. */ 136/* 10*/ le16 client_free_list; /* The index of the first free log client record 137 in the array of log client records. 138 LOGFILE_NO_CLIENT means that there are no 139 free log client records in the array. 140 If != LOGFILE_NO_CLIENT, check that 141 log_clients > client_free_list. On Win2k 142 and presumably earlier, on a clean volume 143 this is != LOGFILE_NO_CLIENT, and it should 144 be 0, i.e. the first (and only) client 145 record is free and thus the logfile is 146 closed and hence clean. A dirty volume 147 would have left the logfile open and hence 148 this would be LOGFILE_NO_CLIENT. On WinXP 149 and presumably later, the logfile is always 150 open, even on clean shutdown so this should 151 always be LOGFILE_NO_CLIENT. */ 152/* 12*/ le16 client_in_use_list;/* The index of the first in-use log client 153 record in the array of log client records. 154 LOGFILE_NO_CLIENT means that there are no 155 in-use log client records in the array. If 156 != LOGFILE_NO_CLIENT check that log_clients 157 > client_in_use_list. On Win2k and 158 presumably earlier, on a clean volume this 159 is LOGFILE_NO_CLIENT, i.e. there are no 160 client records in use and thus the logfile 161 is closed and hence clean. A dirty volume 162 would have left the logfile open and hence 163 this would be != LOGFILE_NO_CLIENT, and it 164 should be 0, i.e. the first (and only) 165 client record is in use. On WinXP and 166 presumably later, the logfile is always 167 open, even on clean shutdown so this should 168 always be 0. */ 169/* 14*/ RESTART_AREA_FLAGS flags;/* Flags modifying LFS behaviour. On Win2k 170 and presumably earlier this is always 0. On 171 WinXP and presumably later, if the logfile 172 was shutdown cleanly, the second bit, 173 RESTART_VOLUME_IS_CLEAN, is set. This bit 174 is cleared when the volume is mounted by 175 WinXP and set when the volume is dismounted, 176 thus if the logfile is dirty, this bit is 177 clear. Thus we don't need to check the 178 Windows version to determine if the logfile 179 is clean. Instead if the logfile is closed, 180 we know it must be clean. If it is open and 181 this bit is set, we also know it must be 182 clean. If on the other hand the logfile is 183 open and this bit is clear, we can be almost 184 certain that the logfile is dirty. */ 185/* 16*/ le32 seq_number_bits; /* How many bits to use for the sequence 186 number. This is calculated as 67 - the 187 number of bits required to store the logfile 188 size in bytes and this can be used in with 189 the specified file_size as a consistency 190 check. */ 191/* 20*/ le16 restart_area_length;/* Length of the restart area including the 192 client array. Following checks required if 193 version matches. Otherwise, skip them. 194 restart_area_offset + restart_area_length 195 has to be <= system_page_size. Also, 196 restart_area_length has to be >= 197 client_array_offset + (log_clients * 198 sizeof(log client record)). */ 199/* 22*/ le16 client_array_offset;/* Offset from the start of this record to 200 the first log client record if versions are 201 matched. When creating, set this to be 202 after this restart area structure, aligned 203 to 8-bytes boundary. If the versions do not 204 match, this is ignored and the offset is 205 assumed to be (sizeof(RESTART_AREA) + 7) & 206 ~7, i.e. rounded up to first 8-byte 207 boundary. Either way, client_array_offset 208 has to be aligned to an 8-byte boundary. 209 Also, restart_area_offset + 210 client_array_offset has to be <= 510. 211 Finally, client_array_offset + (log_clients 212 * sizeof(log client record)) has to be <= 213 system_page_size. On Win2k and presumably 214 earlier, this is 0x30, i.e. immediately 215 following this record. On WinXP and 216 presumably later, this is 0x40, i.e. there 217 are 16 extra bytes between this record and 218 the client array. This probably means that 219 the RESTART_AREA record is actually bigger 220 in WinXP and later. */ 221/* 24*/ sle64 file_size; /* Usable byte size of the log file. If the 222 restart_area_offset + the offset of the 223 file_size are > 510 then corruption has 224 occurred. This is the very first check when 225 starting with the restart_area as if it 226 fails it means that some of the above values 227 will be corrupted by the multi sector 228 transfer protection. The file_size has to 229 be rounded down to be a multiple of the 230 log_page_size in the RESTART_PAGE_HEADER and 231 then it has to be at least big enough to 232 store the two restart pages and 48 (0x30) 233 log record pages. */ 234/* 32*/ le32 last_lsn_data_length;/* Length of data of last LSN, not including 235 the log record header. On create set to 236 0. */ 237/* 36*/ le16 log_record_header_length;/* Byte size of the log record header. 238 If the version matches then check that the 239 value of log_record_header_length is a 240 multiple of 8, i.e. 241 (log_record_header_length + 7) & ~7 == 242 log_record_header_length. When creating set 243 it to sizeof(LOG_RECORD_HEADER), aligned to 244 8 bytes. */ 245/* 38*/ le16 log_page_data_offset;/* Offset to the start of data in a log record 246 page. Must be a multiple of 8. On create 247 set it to immediately after the update 248 sequence array of the log record page. */ 249/* 40*/ le32 restart_log_open_count;/* A counter that gets incremented every 250 time the logfile is restarted which happens 251 at mount time when the logfile is opened. 252 When creating set to a random value. Win2k 253 sets it to the low 32 bits of the current 254 system time in NTFS format (see time.h). */ 255/* 44*/ le32 reserved; /* Reserved/alignment to 8-byte boundary. */ 256/* sizeof() = 48 (0x30) bytes */ 257} __attribute__((__packed__)) RESTART_AREA; 258 259/** 260 * struct LOG_CLIENT_RECORD - Log client record. 261 * 262 * The offset of this record is found by adding the offset of the 263 * RESTART_AREA to the client_array_offset value found in it. 264 */ 265typedef struct { 266/*Ofs*/ 267/* 0*/ leLSN oldest_lsn; /* Oldest LSN needed by this client. On create 268 set to 0. */ 269/* 8*/ leLSN client_restart_lsn;/* LSN at which this client needs to restart 270 the volume, i.e. the current position within 271 the log file. At present, if clean this 272 should = current_lsn in restart area but it 273 probably also = current_lsn when dirty most 274 of the time. At create set to 0. */ 275/* 16*/ le16 prev_client; /* The offset to the previous log client record 276 in the array of log client records. 277 LOGFILE_NO_CLIENT means there is no previous 278 client record, i.e. this is the first one. 279 This is always LOGFILE_NO_CLIENT. */ 280/* 18*/ le16 next_client; /* The offset to the next log client record in 281 the array of log client records. 282 LOGFILE_NO_CLIENT means there are no next 283 client records, i.e. this is the last one. 284 This is always LOGFILE_NO_CLIENT. */ 285/* 20*/ le16 seq_number; /* On Win2k and presumably earlier, this is set 286 to zero every time the logfile is restarted 287 and it is incremented when the logfile is 288 closed at dismount time. Thus it is 0 when 289 dirty and 1 when clean. On WinXP and 290 presumably later, this is always 0. */ 291/* 22*/ u8 reserved[6]; /* Reserved/alignment. */ 292/* 28*/ le32 client_name_length;/* Length of client name in bytes. Should 293 always be 8. */ 294/* 32*/ ntfschar client_name[64];/* Name of the client in Unicode. Should 295 always be "NTFS" with the remaining bytes 296 set to 0. */ 297/* sizeof() = 160 (0xa0) bytes */ 298} __attribute__((__packed__)) LOG_CLIENT_RECORD; 299 300/** 301 * struct RECORD_PAGE_HEADER - Log page record page header. 302 * 303 * Each log page begins with this header and is followed by several LOG_RECORD 304 * structures, starting at offset 0x40 (the size of this structure and the 305 * following update sequence array and then aligned to 8 byte boundary, but is 306 * this specified anywhere?). 307 */ 308typedef struct { 309/* 0 NTFS_RECORD; -- Unfolded here as gcc doesn't like unnamed structs. */ 310 NTFS_RECORD_TYPES magic;/* Usually the magic is "RCRD". */ 311 u16 usa_ofs; /* See NTFS_RECORD definition in layout.h. 312 When creating, set this to be immediately 313 after this header structure (without any 314 alignment). */ 315 u16 usa_count; /* See NTFS_RECORD definition in layout.h. */ 316 317 union { 318 LSN last_lsn; 319 s64 file_offset; 320 } __attribute__((__packed__)) copy; 321 u32 flags; 322 u16 page_count; 323 u16 page_position; 324 union { 325 struct { 326 u16 next_record_offset; 327 u8 reserved[6]; 328 LSN last_end_lsn; 329 } __attribute__((__packed__)) packed; 330 } __attribute__((__packed__)) header; 331} __attribute__((__packed__)) RECORD_PAGE_HEADER; 332 333/** 334 * enum LOG_RECORD_FLAGS - Possible 16-bit flags for log records. 335 * 336 * (Or is it log record pages?) 337 */ 338typedef enum { 339 LOG_RECORD_MULTI_PAGE = const_cpu_to_le16(0x0001), /* ??? */ 340 LOG_RECORD_SIZE_PLACE_HOLDER = 0xffff, 341 /* This has nothing to do with the log record. It is only so 342 gcc knows to make the flags 16-bit. */ 343} __attribute__((__packed__)) LOG_RECORD_FLAGS; 344 345/** 346 * struct LOG_CLIENT_ID - The log client id structure identifying a log client. 347 */ 348typedef struct { 349 u16 seq_number; 350 u16 client_index; 351} __attribute__((__packed__)) LOG_CLIENT_ID; 352 353/** 354 * struct LOG_RECORD - Log record header. 355 * 356 * Each log record seems to have a constant size of 0x70 bytes. 357 */ 358typedef struct { 359 LSN this_lsn; 360 LSN client_previous_lsn; 361 LSN client_undo_next_lsn; 362 u32 client_data_length; 363 LOG_CLIENT_ID client_id; 364 u32 record_type; 365 u32 transaction_id; 366 u16 flags; 367 u16 reserved_or_alignment[3]; 368/* Now are at ofs 0x30 into struct. */ 369 u16 redo_operation; 370 u16 undo_operation; 371 u16 redo_offset; 372 u16 redo_length; 373 u16 undo_offset; 374 u16 undo_length; 375 u16 target_attribute; 376 u16 lcns_to_follow; /* Number of lcn_list entries 377 following this entry. */ 378/* Now at ofs 0x40. */ 379 u16 record_offset; 380 u16 attribute_offset; 381 u32 alignment_or_reserved; 382 VCN target_vcn; 383/* Now at ofs 0x50. */ 384 struct { /* Only present if lcns_to_follow 385 is not 0. */ 386 LCN lcn; 387 } __attribute__((__packed__)) lcn_list[0]; 388} __attribute__((__packed__)) LOG_RECORD; 389 390extern BOOL ntfs_check_logfile(ntfs_attr *log_na, RESTART_PAGE_HEADER **rp); 391extern BOOL ntfs_is_logfile_clean(ntfs_attr *log_na, RESTART_PAGE_HEADER *rp); 392extern int ntfs_empty_logfile(ntfs_attr *na); 393 394#endif /* defined _NTFS_LOGFILE_H */ 395