MySQL 8.2.0
Source Code Documentation
fsp0file.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 2013, 2023, Oracle and/or its affiliates.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License, version 2.0, as published by the
7Free Software Foundation.
8
9This program is also distributed with certain software (including but not
10limited to OpenSSL) that is licensed under separate terms, as designated in a
11particular file or component or in included license documentation. The authors
12of MySQL hereby grant you an additional permission to link the program and
13your derivative works with the separately licensed software that they have
14included with MySQL.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/fsp0file.h
28 Tablespace data file implementation.
29
30 Created 2013-7-26 by Kevin Lewis
31 *******************************************************/
32
33#ifndef fsp0file_h
34#define fsp0file_h
35
36#include <vector>
37#include "fil0fil.h" /* SPACE_UNKNOWN */
38#include "ha_prototypes.h"
39#include "mem0mem.h"
40#include "os0file.h"
41
42#ifdef UNIV_HOTBACKUP
43#include "fil0fil.h"
44#include "fsp0types.h"
45
46/** MEB routine to get the master key. MEB will extract
47the key from the keyring encrypted file stored in backup.
48@param[in] key_id the id of the master key
49@param[in] key_type master key type
50@param[out] key the master key being returned
51@param[out] key_length the length of the returned key
52@retval 0 if the key is being returned, 1 otherwise. */
53extern int meb_key_fetch(const char *key_id, char **key_type,
54 const char *user_id, void **key, size_t *key_length);
55#endif /* UNIV_HOTBACKUP */
56
57/** Types of raw partitions in innodb_data_file_path */
59
60 /** Not a raw partition */
62
63 /** A 'newraw' partition, only to be initialized */
65
66 /** An initialized raw partition */
68};
69
70/** Data file control information. */
71class Datafile {
72 friend class Tablespace;
73 friend class SysTablespace;
74
75 public:
77 : m_name(),
78 m_filename(),
80 m_size(),
81 m_order(),
84 m_flags(),
85 m_exists(),
86 m_is_valid(),
89 m_filepath(),
97 }
98
99 Datafile(const char *name, uint32_t flags, page_no_t size, ulint order)
101 m_filename(),
103 m_size(size),
104 m_order(order),
107 m_flags(flags),
108 m_exists(),
109 m_is_valid(),
110 m_first_page(),
112 m_filepath(),
114 m_file_info(),
119 ut_ad(m_name != nullptr);
121 /* No op */
122 }
123
134 m_first_page(),
137 m_file_info(),
142 m_name = mem_strdup(file.m_name);
143 ut_ad(m_name != nullptr);
144
145 if (file.m_filepath != nullptr) {
146 m_filepath = mem_strdup(file.m_filepath);
147 ut_a(m_filepath != nullptr);
148 set_filename();
149 } else {
150 m_filepath = nullptr;
151 m_filename = nullptr;
152 }
153 }
154
156
158 ut_a(this != &file);
159
160 ut_ad(m_name == nullptr);
161 m_name = mem_strdup(file.m_name);
162 ut_a(m_name != nullptr);
163
164 m_size = file.m_size;
165 m_order = file.m_order;
166 m_type = file.m_type;
167
169 m_handle = file.m_handle;
170
171 m_exists = file.m_exists;
172 m_is_valid = file.m_is_valid;
173 m_open_flags = file.m_open_flags;
174 m_space_id = file.m_space_id;
175 m_flags = file.m_flags;
176 m_last_os_error = 0;
177
178 if (m_filepath != nullptr) {
180 m_filepath = nullptr;
181 m_filename = nullptr;
182 }
183
184 if (file.m_filepath != nullptr) {
185 m_filepath = mem_strdup(file.m_filepath);
186 ut_a(m_filepath != nullptr);
187 set_filename();
188 }
189
190 /* Do not make a copy of the first page,
191 it should be reread if needed */
192 m_first_page = nullptr;
193 m_encryption_key = nullptr;
194 m_encryption_iv = nullptr;
197
198 m_atomic_write = file.m_atomic_write;
199
200 return (*this);
201 }
202
203 /** Initialize the name and flags of this datafile.
204 @param[in] name tablespace name, will be copied
205 @param[in] flags tablespace flags */
206 void init(const char *name, uint32_t flags);
207
208 /** Release the resources. */
209 void shutdown();
210
211 /** Open a data file in read-only mode to check if it exists
212 so that it can be validated.
213 @param[in] strict whether to issue error messages
214 @return DB_SUCCESS or error code */
215 [[nodiscard]] dberr_t open_read_only(bool strict);
216
217 /** Open a data file in read-write mode during start-up so that
218 doublewrite pages can be restored and then it can be validated.
219 @param[in] read_only_mode if true, then readonly mode checks
220 are enforced.
221 @return DB_SUCCESS or error code */
222 [[nodiscard]] dberr_t open_read_write(bool read_only_mode);
223
224 /** Initialize OS specific file info. */
225 void init_file_info();
226
227 /** Close a data file.
228 @return DB_SUCCESS or error code */
229 dberr_t close();
230
231 /** Returns if the Datafile is created in raw partition
232 @return true if partition used is raw , false otherwise */
233 bool is_raw_type() {
234 return (m_type == SRV_NEW_RAW || m_type == SRV_OLD_RAW);
235 }
236
237 /** Make a full filepath from a directory path and a filename.
238 Prepend the dirpath to filename using the extension given.
239 If dirpath is nullptr, prepend the default datadir to filepath.
240 Store the result in m_filepath.
241 @param[in] dirpath directory path
242 @param[in] filename filename or filepath
243 @param[in] ext filename extension */
244 void make_filepath(const char *dirpath, const char *filename,
246
247 /** Set the filepath by duplicating the filepath sent in */
248 void set_filepath(const char *filepath);
249
250 /** Allocate and set the datafile or tablespace name in m_name.
251 If a name is provided, use it; else if the datafile is file-per-table,
252 extract a file-per-table tablespace name from m_filepath; else it is a
253 general tablespace, so just call it that for now. The value of m_name
254 will be freed in the destructor.
255 @param[in] name Tablespace Name if known, nullptr if not */
256 void set_name(const char *name);
257
258 /** Validates the datafile and checks that it conforms with the expected
259 space ID and flags. The file should exist and be successfully opened
260 in order for this function to validate it.
261 @param[in] space_id The expected tablespace ID.
262 @param[in] flags The expected tablespace flags.
263 @param[in] for_import if it is for importing
264 @retval DB_SUCCESS if tablespace is valid, DB_ERROR if not.
265 m_is_valid is also set true on success, else false. */
266 [[nodiscard]] dberr_t validate_to_dd(space_id_t space_id, uint32_t flags,
267 bool for_import);
268
269 /** Validates this datafile for the purpose of recovery. The file should
270 exist and be successfully opened. We initially open it in read-only mode
271 because we just want to read the SpaceID. However, if the first page is
272 corrupt and needs to be restored from the doublewrite buffer, we will reopen
273 it in write mode and try to restore that page. The file will be closed when
274 returning from this method.
275 @param[in] space_id Expected space ID
276 @retval DB_SUCCESS on success
277 m_is_valid is also set true on success, else false. */
279
280 /** Checks the consistency of the first page of a datafile when the
281 tablespace is opened. This occurs before the fil_space_t is created so the
282 Space ID found here must not already be open. m_is_valid is set true on
283 success, else false. The datafile is always closed when returning from this
284 method.
285 @param[in] space_id Expected space ID
286 @param[out] flush_lsn contents of FIL_PAGE_FILE_FLUSH_LSN
287 @param[in] for_import if it is for importing
288 (only valid for the first file of the system tablespace)
289 @retval DB_WRONG_FILE_NAME tablespace in file header doesn't match
290 expected value
291 @retval DB_SUCCESS on if the datafile is valid
292 @retval DB_CORRUPTION if the datafile is not readable
293 @retval DB_INVALID_ENCRYPTION_META if the encryption meta data
294 is not readable
295 @retval DB_TABLESPACE_EXISTS if there is a duplicate space_id */
297 lsn_t *flush_lsn, bool for_import);
298
299 /** Get LSN of first page */
301 ut_ad(m_first_page != nullptr);
303 }
304
305 /** Get Datafile::m_name.
306 @return m_name */
307 const char *name() const { return (m_name); }
308
309 /** Get Datafile::m_filepath.
310 @return m_filepath */
311 const char *filepath() const { return (m_filepath); }
312
313 /** Get Datafile::m_handle.
314 @return m_handle */
316 ut_ad(is_open());
317 return (m_handle);
318 }
319
320 /** Get Datafile::m_order.
321 @return m_order */
322 ulint order() const { return (m_order); }
323
324 /** Get Datafile::m_server_version.
325 @return m_server_version */
327
328 /** Get Datafile::m_space_version.
329 @return m_space_version */
330 ulint space_version() const { return (m_space_version); }
331
332 /** Get Datafile::m_space_id.
333 @return m_space_id */
334 space_id_t space_id() const { return (m_space_id); }
335
336 /** Get Datafile::m_flags.
337 @return m_flags */
338 uint32_t flags() const { return (m_flags); }
339
340 /**
341 @return true if m_handle is open, false if not */
342 bool is_open() const { return (m_handle.m_file != OS_FILE_CLOSED); }
343
344 /** Get Datafile::m_is_valid.
345 @return m_is_valid */
346 bool is_valid() const { return (m_is_valid); }
347
348 /** Get the last OS error reported
349 @return m_last_os_error */
350 ulint last_os_error() const { return (m_last_os_error); }
351
352 /** Do a quick test if the filepath provided looks the same as this filepath
353 byte by byte. If they are two different looking paths to the same file,
354 same_as() will be used to show that after the files are opened.
355 @param[in] other filepath to compare with
356 @retval true if it is the same filename by byte comparison
357 @retval false if it looks different */
358 bool same_filepath_as(const char *other) const;
359
360 /** Test if another opened datafile is the same file as this object.
361 @param[in] other Datafile to compare with
362 @return true if it is the same file, else false */
363 bool same_as(const Datafile &other) const;
364
365 /** Determine the space id of the given file descriptor by reading
366 a few pages from the beginning of the .ibd file.
367 @return DB_SUCCESS if space id was successfully identified,
368 else DB_ERROR. */
370
371 /** @return file size in number of pages */
372 page_no_t size() const { return (m_size); }
373
374#ifdef UNIV_HOTBACKUP
375 /** Set the tablespace ID.
376 @param[in] space_id Tablespace ID to set */
378 ut_ad(space_id <= 0xFFFFFFFFU);
380 }
381
382 /** Set th tablespace flags
383 @param[in] flags Tablespace flags */
384 void set_flags(uint32_t flags) { m_flags = flags; }
385#endif /* UNIV_HOTBACKUP */
386
387 private:
388 /** Free the filepath buffer. */
389 void free_filepath();
390
391 /** Set the filename pointer to the start of the file name
392 in the filepath. */
394 if (m_filepath == nullptr) {
395 return;
396 }
397
398 char *last_slash = strrchr(m_filepath, OS_PATH_SEPARATOR);
399
400 m_filename = last_slash ? last_slash + 1 : m_filepath;
401 }
402
403 /** Create/open a data file.
404 @param[in] read_only_mode if true, then readonly mode checks
405 are enforced.
406 @return DB_SUCCESS or error code */
407 [[nodiscard]] dberr_t open_or_create(bool read_only_mode);
408
409 /** Reads a few significant fields from the first page of the
410 datafile, which must already be open.
411 @param[in] read_only_mode If true, then readonly mode checks
412 are enforced.
413 @return DB_SUCCESS or DB_IO_ERROR if page cannot be read */
414 [[nodiscard]] dberr_t read_first_page(bool read_only_mode);
415
416 /** Free the first page from memory when it is no longer needed. */
417 void free_first_page();
418
419 /** Set the Datafile::m_open_flags.
420 @param open_flags The Open flags to set. */
422 m_open_flags = open_flags;
423 }
424
425 /** Finds a given page of the given space id from the double write buffer
426 and copies it to the corresponding .ibd file.
427 @param[in] restore_page_no Page number to restore
428 @return DB_SUCCESS if page was restored from doublewrite, else DB_ERROR */
430
431 private:
432 /** Datafile name at the tablespace location.
433 This is either the basename of the file if an absolute path
434 was entered, or it is the relative path to the datadir or
435 Tablespace::m_path. */
436 char *m_name;
437
438 /** Points into m_filepath to the file name with extension */
440
441 /** Open file handle */
443
444 /** Flags to use for opening the data file */
446
447 /** size in pages */
449
450 /** ordinal position of this datafile in the tablespace */
452
453 /** The type of the data file */
455
456 /** Tablespace ID. Contained in the datafile header.
457 If this is a system tablespace, FSP_SPACE_ID is only valid
458 in the first datafile. */
460
461 /** Server version */
463
464 /** Space version */
466
467 /** Tablespace flags. Contained in the datafile header.
468 If this is a system tablespace, FSP_SPACE_FLAGS are only valid
469 in the first datafile. */
470 uint32_t m_flags;
471
472 /** true if file already existed on startup */
474
475 /* true if the tablespace is valid */
477
478 /** Buffer to hold first page */
480
481 /** true if atomic writes enabled for this file */
483
484 protected:
485 /** Physical file path with base name and extension */
487
488 /** Last OS error received so it can be reported if needed. */
490
491 public:
492 /** Use the following to determine the uniqueness of this datafile. */
493#ifdef _WIN32
494 using WIN32_FILE_INFO = BY_HANDLE_FILE_INFORMATION;
495
496 /** Use fields dwVolumeSerialNumber, nFileIndexLow, nFileIndexHigh. */
497 WIN32_FILE_INFO m_file_info;
498#else
499 /** Use field st_ino. */
500 struct stat m_file_info;
501#endif /* WIN32 */
502
503 /** Encryption key read from first page */
505
506 /** Encryption iv read from first page */
508
509 /** Encryption operation in progress */
511
512 /** Master key id read from first page */
514};
515#endif /* fsp0file_h */
uint32_t space_id_t
Tablespace identifier.
Definition: api0api.h:50
uint32_t page_no_t
Page number.
Definition: api0api.h:48
Data file control information.
Definition: fsp0file.h:71
Datafile()
Definition: fsp0file.h:76
space_id_t space_id() const
Get Datafile::m_space_id.
Definition: fsp0file.h:334
byte * m_encryption_iv
Encryption iv read from first page.
Definition: fsp0file.h:507
byte * m_encryption_key
Encryption key read from first page.
Definition: fsp0file.h:504
dberr_t find_space_id()
Determine the space id of the given file descriptor by reading a few pages from the beginning of the ...
Definition: fsp0file.cc:722
dberr_t open_read_write(bool read_only_mode)
Open a data file in read-write mode during start-up so that doublewrite pages can be restored and the...
Definition: fsp0file.cc:147
uint32_t m_server_version
Server version.
Definition: fsp0file.h:462
bool is_valid() const
Get Datafile::m_is_valid.
Definition: fsp0file.h:346
space_id_t m_space_id
Tablespace ID.
Definition: fsp0file.h:459
const char * filepath() const
Get Datafile::m_filepath.
Definition: fsp0file.h:311
void free_first_page()
Free the first page from memory when it is no longer needed.
Definition: fsp0file.cc:373
bool m_atomic_write
true if atomic writes enabled for this file
Definition: fsp0file.h:482
dberr_t validate_for_recovery(space_id_t space_id)
Validates this datafile for the purpose of recovery.
Definition: fsp0file.cc:460
ulint m_last_os_error
Last OS error received so it can be reported if needed.
Definition: fsp0file.h:489
bool m_exists
true if file already existed on startup
Definition: fsp0file.h:473
bool is_raw_type()
Returns if the Datafile is created in raw partition.
Definition: fsp0file.h:233
Datafile(const Datafile &file)
Definition: fsp0file.h:124
void make_filepath(const char *dirpath, const char *filename, ib_file_suffix ext)
Make a full filepath from a directory path and a filename.
Definition: fsp0file.cc:205
ulint m_order
ordinal position of this datafile in the tablespace
Definition: fsp0file.h:451
uint32_t flags() const
Get Datafile::m_flags.
Definition: fsp0file.h:338
void set_open_flags(os_file_create_t open_flags)
Set the Datafile::m_open_flags.
Definition: fsp0file.h:421
bool same_filepath_as(const char *other) const
Do a quick test if the filepath provided looks the same as this filepath byte by byte.
Definition: fsp0file.cc:253
dberr_t validate_to_dd(space_id_t space_id, uint32_t flags, bool for_import)
Validates the datafile and checks that it conforms with the expected space ID and flags.
Definition: fsp0file.cc:386
dberr_t restore_from_doublewrite(page_no_t restore_page_no)
Finds a given page of the given space id from the double write buffer and copies it to the correspond...
Definition: fsp0file.cc:876
void set_filename()
Set the filename pointer to the start of the file name in the filepath.
Definition: fsp0file.h:393
page_no_t m_size
size in pages
Definition: fsp0file.h:448
device_t m_type
The type of the data file.
Definition: fsp0file.h:454
pfs_os_file_t handle() const
Get Datafile::m_handle.
Definition: fsp0file.h:315
dberr_t validate_first_page(space_id_t space_id, lsn_t *flush_lsn, bool for_import)
Checks the consistency of the first page of a datafile when the tablespace is opened.
Definition: fsp0file.cc:523
lsn_t get_flush_lsn()
Get LSN of first page.
Definition: fsp0file.h:300
dberr_t read_first_page(bool read_only_mode)
Reads a few significant fields from the first page of the datafile, which must already be open.
Definition: fsp0file.cc:317
dberr_t open_or_create(bool read_only_mode)
Create/open a data file.
Definition: fsp0file.cc:90
void init_file_info()
Initialize OS specific file info.
Definition: fsp0file.cc:177
void shutdown()
Release the resources.
Definition: fsp0file.cc:66
ulint order() const
Get Datafile::m_order.
Definition: fsp0file.h:322
~Datafile()
Definition: fsp0file.h:155
struct stat m_file_info
Use the following to determine the uniqueness of this datafile.
Definition: fsp0file.h:500
dberr_t open_read_only(bool strict)
Open a data file in read-only mode to check if it exists so that it can be validated.
Definition: fsp0file.cc:112
Datafile(const char *name, uint32_t flags, page_no_t size, ulint order)
Definition: fsp0file.h:99
Datafile & operator=(const Datafile &file)
Definition: fsp0file.h:157
void free_filepath()
Free the filepath buffer.
Definition: fsp0file.cc:239
void init(const char *name, uint32_t flags)
Initialize the name and flags of this datafile.
Definition: fsp0file.cc:55
ulint server_version() const
Get Datafile::m_server_version.
Definition: fsp0file.h:326
bool same_as(const Datafile &other) const
Test if another opened datafile is the same file as this object.
Definition: fsp0file.cc:260
char * m_name
Datafile name at the tablespace location.
Definition: fsp0file.h:436
byte * m_first_page
Buffer to hold first page.
Definition: fsp0file.h:479
pfs_os_file_t m_handle
Open file handle.
Definition: fsp0file.h:442
bool is_open() const
Definition: fsp0file.h:342
uint32_t m_encryption_master_key_id
Master key id read from first page.
Definition: fsp0file.h:513
uint32_t m_space_version
Space version.
Definition: fsp0file.h:465
void set_filepath(const char *filepath)
Set the filepath by duplicating the filepath sent in.
Definition: fsp0file.cc:230
uint32_t m_flags
Tablespace flags.
Definition: fsp0file.h:470
dberr_t close()
Close a data file.
Definition: fsp0file.cc:187
Encryption::Progress m_encryption_op_in_progress
Encryption operation in progress.
Definition: fsp0file.h:510
ulint last_os_error() const
Get the last OS error reported.
Definition: fsp0file.h:350
os_file_create_t m_open_flags
Flags to use for opening the data file.
Definition: fsp0file.h:445
ulint space_version() const
Get Datafile::m_space_version.
Definition: fsp0file.h:330
char * m_filepath
Physical file path with base name and extension.
Definition: fsp0file.h:486
const char * name() const
Get Datafile::m_name.
Definition: fsp0file.h:307
char * m_filename
Points into m_filepath to the file name with extension.
Definition: fsp0file.h:439
bool m_is_valid
Definition: fsp0file.h:476
page_no_t size() const
Definition: fsp0file.h:372
void set_name(const char *name)
Allocate and set the datafile or tablespace name in m_name.
Definition: fsp0file.cc:278
Encryption algorithm.
Definition: os0enc.h:53
Progress
Encryption progress type.
Definition: os0enc.h:79
Data structure that contains the information about shared tablespaces.
Definition: fsp0sysspace.h:57
Data structure that contains the information about shared tablespaces.
Definition: fsp0space.h:46
void set_space_id(space_id_t space_id)
Set the space id of the tablespace.
Definition: fsp0space.h:115
void set_flags(uint32_t fsp_flags)
Set the tablespace flags.
Definition: fsp0space.h:126
dberr_t
Definition: db0err.h:38
The low-level file system.
constexpr space_id_t SPACE_UNKNOWN
Unknown space id.
Definition: fil0fil.h:1152
ib_file_suffix
Common InnoDB file extensions.
Definition: fil0fil.h:582
constexpr uint32_t FIL_PAGE_LSN
lsn of the end of the newest modification log record to the page
Definition: fil0types.h:66
device_t
Types of raw partitions in innodb_data_file_path.
Definition: fsp0file.h:58
@ SRV_NOT_RAW
Not a raw partition.
Definition: fsp0file.h:61
@ SRV_NEW_RAW
A 'newraw' partition, only to be initialized.
Definition: fsp0file.h:64
@ SRV_OLD_RAW
An initialized raw partition.
Definition: fsp0file.h:67
Prototypes for global functions in ha_innodb.cc that are called by InnoDB C code.
uint64_t lsn_t
Type used for all log sequence number storage and arithmetic.
Definition: log0types.h:62
static uint64_t mach_read_from_8(const byte *b)
The following function is used to fetch data from 8 consecutive bytes.
The memory management.
static char * mem_strdup(const char *str)
Duplicates a NUL-terminated string.
int key_type
Definition: http_request.h:49
Definition: os0file.h:88
Json_data_extension ext
Definition: backend.cc:50
void free(void *ptr) noexcept
Releases storage which has been dynamically allocated through any of the ut::malloc*(),...
Definition: ut0new.h:716
The interface to the operating system file io.
os_file_create_t
Options for os_file_create_func.
Definition: os0file.h:198
@ OS_FILE_OPEN
to open an existing file (if doesn't exist, error)
Definition: os0file.h:199
static constexpr os_fd_t OS_FILE_CLOSED
Definition: os0file.h:154
const char * filename
Definition: pfs_example_component_population.cc:66
required string key
Definition: replication_asynchronous_connection_failover.proto:59
Common file descriptor for file IO instrumentation with PFS on windows and other platforms.
Definition: os0file.h:175
os_file_t m_file
Definition: os0file.h:185
#define OS_PATH_SEPARATOR
Definition: univ.i:537
unsigned long int ulint
Definition: univ.i:405
#define ut_ad(EXPR)
Debug assertion.
Definition: ut0dbg.h:68
#define ut_a(EXPR)
Abort execution if EXPR does not evaluate to nonzero.
Definition: ut0dbg.h:56