path: root/include/ntfs-3g/logfile.h (plain)
blob: 798d562d17ce720873756a765dbfc514d6b80b8b

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	*/
64	typedef 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	*/
111	enum {
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
116	typedef 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	*/
125	typedef 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	*/
265	typedef 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	*/
308	typedef 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	*/
338	typedef 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	*/
348	typedef 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	*/
358	typedef 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
390	extern BOOL ntfs_check_logfile(ntfs_attr *log_na, RESTART_PAGE_HEADER **rp);
391	extern BOOL ntfs_is_logfile_clean(ntfs_attr *log_na, RESTART_PAGE_HEADER *rp);
392	extern int ntfs_empty_logfile(ntfs_attr *na);
393
394	#endif /* defined _NTFS_LOGFILE_H */
395