include/ext4.h

   1 /*
   2  * Copyright (c) 2013 Grzegorz Kostka (kostka.grzegorz@gmail.com)
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright
  10  *   notice, this list of conditions and the following disclaimer.
  11  * - Redistributions in binary form must reproduce the above copyright
  12  *   notice, this list of conditions and the following disclaimer in the
  13  *   documentation and/or other materials provided with the distribution.
  14  * - The name of the author may not be used to endorse or promote products
  15  *   derived from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /** @addtogroup lwext4
  30  * @{
  31  */
  32 /**
  33  * @file  ext4.h
  34  * @brief Ext4 high level operations (files, directories, mount points...).
  35  *        Client has to include only this file.
  36  */
  37
  38 #ifndef EXT4_H_
  39 #define EXT4_H_
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include <stdint.h>
  46 #include <stddef.h>
  47
  48 #include <ext4_config.h>
  49 #include <ext4_types.h>
  50 #include <ext4_errno.h>
  51 #include <ext4_oflags.h>
  52 #include <ext4_debug.h>
  53
  54 #include <ext4_blockdev.h>
  55
  56 /********************************OS LOCK INFERFACE***************************/
  57
  58 /**@brief   OS dependent lock interface.*/
  59 struct ext4_lock {
  60
  61         /**@brief   Lock access to mount point.*/
  62         void (*lock)(void);
  63
  64         /**@brief   Unlock access to mount point.*/
  65         void (*unlock)(void);
  66 };
  67
  68 /********************************FILE DESCRIPTOR*****************************/
  69
  70 /**@brief   File descriptor. */
  71 typedef struct ext4_file {
  72
  73         /**@brief   Mount point handle.*/
  74         struct ext4_mountpoint *mp;
  75
  76         /**@brief   File inode id.*/
  77         uint32_t inode;
  78
  79         /**@brief   Open flags.*/
  80         uint32_t flags;
  81
  82         /**@brief   File size.*/
  83         uint64_t fsize;
  84
  85         /**@brief   Actual file position.*/
  86         uint64_t fpos;
  87 } ext4_file;
  88
  89 /*****************************DIRECTORY DESCRIPTOR***************************/
  90
  91 /**@brief   Directory entry descriptor. */
  92 typedef struct ext4_direntry {
  93         uint32_t inode;
  94         uint16_t entry_length;
  95         uint8_t name_length;
  96         uint8_t inode_type;
  97         uint8_t name[255];
  98 } ext4_direntry;
  99
 100 /**@brief   Directory descriptor. */
 101 typedef struct ext4_dir {
 102         /**@brief   File descriptor.*/
 103         ext4_file f;
 104         /**@brief   Current directory entry.*/
 105         ext4_direntry de;
 106         /**@brief   Next entry offset.*/
 107         uint64_t next_off;
 108 } ext4_dir;
 109
 110 /********************************MOUNT OPERATIONS****************************/
 111
 112 /**@brief   Register block device.
 113  *
 114  * @param   bd Block device.
 115  * @param   dev_name Block device name.
 116  *
 117  * @return  Standard error code.*/
 118 int ext4_device_register(struct ext4_blockdev *bd,
 119                          const char *dev_name);
 120
 121 /**@brief   Un-register block device.
 122  *
 123  * @param   dev_name Block device name.
 124  *
 125  * @return  Standard error code.*/
 126 int ext4_device_unregister(const char *dev_name);
 127
 128 /**@brief   Un-register all block devices.
 129  *
 130  * @return  Standard error code.*/
 131 int ext4_device_unregister_all(void);
 132
 133 /**@brief   Mount a block device with EXT4 partition to the mount point.
 134  *
 135  * @param   dev_name Block device name (@ref ext4_device_register).
 136  * @param   mount_point Mount point, for example:
 137  *          -   /
 138  *          -   /my_partition/
 139  *          -   /my_second_partition/
 140  * @param   read_only mount as read-only mode.
 141  *
 142  * @return Standard error code */
 143 int ext4_mount(const char *dev_name,
 144                const char *mount_point,
 145                bool read_only);
 146
 147 /**@brief   Umount operation.
 148  *
 149  * @param   mount_pount Mount point.
 150  *
 151  * @return  Standard error code */
 152 int ext4_umount(const char *mount_point);
 153
 154 /**@brief   Starts journaling. Journaling start/stop functions are transparent
 155  *          and might be used on filesystems without journaling support.
 156  * @warning Usage:
 157  *              ext4_mount("sda1", "/");
 158  *              ext4_journal_start("/");
 159  *
 160  *              //File operations here...
 161  *
 162  *              ext4_journal_stop("/");
 163  *              ext4_umount("/");
 164  * @param   mount_pount Mount point.
 165  *
 166  * @return  Standard error code. */
 167 int ext4_journal_start(const char *mount_point);
 168
 169 /**@brief   Stops journaling. Journaling start/stop functions are transparent
 170  *          and might be used on filesystems without journaling support.
 171  *
 172  * @param   mount_pount Mount point name.
 173  *
 174  * @return  Standard error code. */
 175 int ext4_journal_stop(const char *mount_point);
 176
 177 /**@brief   Journal recovery.
 178  * @warning Must be called after @ref ext4_mount.
 179  *
 180  * @param   mount_pount Mount point.
 181  *
 182  * @return Standard error code. */
 183 int ext4_recover(const char *mount_point);
 184
 185 /**@brief   Some of the filesystem stats. */
 186 struct ext4_mount_stats {
 187         uint32_t inodes_count;
 188         uint32_t free_inodes_count;
 189         uint64_t blocks_count;
 190         uint64_t free_blocks_count;
 191
 192         uint32_t block_size;
 193         uint32_t block_group_count;
 194         uint32_t blocks_per_group;
 195         uint32_t inodes_per_group;
 196
 197         char volume_name[16];
 198 };
 199
 200 /**@brief   Get file mount point stats.
 201  *
 202  * @param   mount_pount Mount point.
 203  * @param   stats Filesystem stats.
 204  *
 205  * @return Standard error code. */
 206 int ext4_mount_point_stats(const char *mount_point,
 207                            struct ext4_mount_stats *stats);
 208
 209 /**@brief   Setup OS lock routines.
 210  *
 211  * @param   mount_pount Mount point.
 212  * @param   locks  Lock and unlock functions
 213  *
 214  * @return Standard error code. */
 215 int ext4_mount_setup_locks(const char *mount_point,
 216                            const struct ext4_lock *locks);
 217
 218 /**@brief   Acquire the filesystem superblock pointer of a mp.
 219  *
 220  * @param   mount_pount Mount point.
 221  * @param   sb Superblock handle
 222  *
 223  * @return Standard error code. */
 224 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
 225
 226 /**@brief   Enable/disable write back cache mode.
 227  * @warning Default model of cache is write trough. It means that when You do:
 228  *
 229  *          ext4_fopen(...);
 230  *          ext4_fwrite(...);
 231  *                           < --- data is flushed to physical drive
 232  *
 233  *          When you do:
 234  *          ext4_cache_write_back(..., 1);
 235  *          ext4_fopen(...);
 236  *          ext4_fwrite(...);
 237  *                           < --- data is NOT flushed to physical drive
 238  *          ext4_cache_write_back(..., 0);
 239  *                           < --- when write back mode is disabled all
 240  *                                 cache data will be flushed
 241  * To enable write back mode permanently just call this function
 242  * once after ext4_mount (and disable before ext4_umount).
 243  *
 244  * Some of the function use write back cache mode internally.
 245  * If you enable write back mode twice you have to disable it twice
 246  * to flush all data:
 247  *
 248  *      ext4_cache_write_back(..., 1);
 249  *      ext4_cache_write_back(..., 1);
 250  *
 251  *      ext4_cache_write_back(..., 0);
 252  *      ext4_cache_write_back(..., 0);
 253  *
 254  * Write back mode is useful when you want to create a lot of empty
 255  * files/directories.
 256  *
 257  * @param   mount_pount Mount point.
 258  * @param   on Enable/disable cache writeback mode.
 259  *
 260  * @return Standard error code. */
 261 int ext4_cache_write_back(const char *path, bool on);
 262
 263
 264 /**@brief   Force cache flush.
 265  *
 266  * @param   mount_pount Mount point.
 267  *
 268  * @return  Standard error code. */
 269 int ext4_cache_flush(const char *path);
 270
 271 /********************************FILE OPERATIONS*****************************/
 272
 273 /**@brief   Remove file by path.
 274  *
 275  * @param   path Path to file.
 276  *
 277  * @return  Standard error code. */
 278 int ext4_fremove(const char *path);
 279
 280 /**@brief   Create a hardlink for a file.
 281  *
 282  * @param   path Path to file.
 283  * @param   hardlink_path Path of hardlink.
 284  *
 285  * @return  Standard error code. */
 286 int ext4_flink(const char *path, const char *hardlink_path);
 287
 288 /**@brief Rename file.
 289  * @param path Source.
 290  * @param new_path Destination.
 291  * @return  Standard error code. */
 292 int ext4_frename(const char *path, const char *new_path);
 293
 294 /**@brief   File open function.
 295  *
 296  * @param   file  File handle.
 297  * @param   path  File path, has to start from mount point:/my_partition/file.
 298  * @param   flags File open flags.
 299  *  |---------------------------------------------------------------|
 300  *  |   r or rb                 O_RDONLY                            |
 301  *  |---------------------------------------------------------------|
 302  *  |   w or wb                 O_WRONLY|O_CREAT|O_TRUNC            |
 303  *  |---------------------------------------------------------------|
 304  *  |   a or ab                 O_WRONLY|O_CREAT|O_APPEND           |
 305  *  |---------------------------------------------------------------|
 306  *  |   r+ or rb+ or r+b        O_RDWR                              |
 307  *  |---------------------------------------------------------------|
 308  *  |   w+ or wb+ or w+b        O_RDWR|O_CREAT|O_TRUNC              |
 309  *  |---------------------------------------------------------------|
 310  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |
 311  *  |---------------------------------------------------------------|
 312  *
 313  * @return  Standard error code.*/
 314 int ext4_fopen(ext4_file *file, const char *path, const char *flags);
 315
 316 /**@brief   Alternate file open function.
 317  *
 318  * @param   file  File handle.
 319  * @param   path  File path, has to start from mount point:/my_partition/file.
 320  * @param   flags File open flags.
 321  *
 322  * @return  Standard error code.*/
 323 int ext4_fopen2(ext4_file *file, const char *path, int flags);
 324
 325 /**@brief   File close function.
 326  *
 327  * @param   file File handle.
 328  *
 329  * @return  Standard error code.*/
 330 int ext4_fclose(ext4_file *file);
 331
 332
 333 /**@brief   File truncate function.
 334  *
 335  * @param   file File handle.
 336  * @param   size New file size.
 337  *
 338  * @return  Standard error code.*/
 339 int ext4_ftruncate(ext4_file *file, uint64_t size);
 340
 341 /**@brief   Read data from file.
 342  *
 343  * @param   file File handle.
 344  * @param   buf  Output buffer.
 345  * @param   size Bytes to read.
 346  * @param   rcnt Bytes read (NULL allowed).
 347  *
 348  * @return  Standard error code.*/
 349 int ext4_fread(ext4_file *file, void *buf, size_t size, size_t *rcnt);
 350
 351 /**@brief   Write data to file.
 352  *
 353  * @param   file File handle.
 354  * @param   buf  Data to write
 355  * @param   size Write length..
 356  * @param   wcnt Bytes written (NULL allowed).
 357  *
 358  * @return  Standard error code.*/
 359 int ext4_fwrite(ext4_file *file, const void *buf, size_t size, size_t *wcnt);
 360
 361 /**@brief   File seek operation.
 362  *
 363  * @param   file File handle.
 364  * @param   offset Offset to seek.
 365  * @param   origin Seek type:
 366  *              @ref SEEK_SET
 367  *              @ref SEEK_CUR
 368  *              @ref SEEK_END
 369  *
 370  * @return  Standard error code.*/
 371 int ext4_fseek(ext4_file *file, int64_t offset, uint32_t origin);
 372
 373 /**@brief   Get file position.
 374  *
 375  * @param   file File handle.
 376  *
 377  * @return  Actual file position */
 378 uint64_t ext4_ftell(ext4_file *file);
 379
 380 /**@brief   Get file size.
 381  *
 382  * @param   file File handle.
 383  *
 384  * @return  File size. */
 385 uint64_t ext4_fsize(ext4_file *file);
 386
 387
 388 /**@brief Get inode of file/directory/link.
 389  *
 390  * @param path    Parh to file/dir/link.
 391  * @param ret_ino Inode number.
 392  * @param inode   Inode internals.
 393  *
 394  * @return  Standard error code.*/
 395 int ext4_raw_inode_fill(const char *path, uint32_t *ret_ino,
 396                         struct ext4_inode *inode);
 397
 398 /**@brief Check if inode exists.
 399  *
 400  * @param path    Parh to file/dir/link.
 401  * @param type    Inode type.
 402  *                @ref EXT4_DIRENTRY_UNKNOWN
 403  *                @ref EXT4_DE_REG_FILE
 404  *                @ref EXT4_DE_DIR
 405  *                @ref EXT4_DE_CHRDEV
 406  *                @ref EXT4_DE_BLKDEV
 407  *                @ref EXT4_DE_FIFO
 408  *                @ref EXT4_DE_SOCK
 409  *                @ref EXT4_DE_SYMLINK
 410  *
 411  * @return  Standard error code.*/
 412 int ext4_inode_exist(const char *path, int type);
 413
 414 /**@brief Change file/directory/link mode bits.
 415  *
 416  * @param path Path to file/dir/link.
 417  * @param mode New mode bits (for example 0777).
 418  *
 419  * @return  Standard error code.*/
 420 int ext4_mode_set(const char *path, uint32_t mode);
 421
 422
 423 /**@brief Get file/directory/link mode bits.
 424  *
 425  * @param path Path to file/dir/link.
 426  * @param mode New mode bits (for example 0777).
 427  *
 428  * @return  Standard error code.*/
 429 int ext4_mode_get(const char *path, uint32_t *mode);
 430
 431 /**@brief Change file owner and group.
 432  *
 433  * @param path Path to file/dir/link.
 434  * @param uid  User id.
 435  * @param gid  Group id.
 436  *
 437  * @return  Standard error code.*/
 438 int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
 439
 440 /**@brief Get file/directory/link owner and group.
 441  *
 442  * @param path Path to file/dir/link.
 443  * @param uid  User id.
 444  * @param gid  Group id.
 445  *
 446  * @return  Standard error code.*/
 447 int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
 448
 449 /**@brief Set file/directory/link access time.
 450  *
 451  * @param path  Path to file/dir/link.
 452  * @param atime Access timestamp.
 453  *
 454  * @return  Standard error code.*/
 455 int ext4_atime_set(const char *path, uint32_t atime);
 456
 457 /**@brief Set file/directory/link modify time.
 458  *
 459  * @param path  Path to file/dir/link.
 460  * @param mtime Modify timestamp.
 461  *
 462  * @return  Standard error code.*/
 463 int ext4_mtime_set(const char *path, uint32_t mtime);
 464
 465 /**@brief Set file/directory/link change time.
 466  *
 467  * @param path  Path to file/dir/link.
 468  * @param ctime Change timestamp.
 469  *
 470  * @return  Standard error code.*/
 471 int ext4_ctime_set(const char *path, uint32_t ctime);
 472
 473 /**@brief Get file/directory/link access time.
 474  *
 475  * @param path  Path to file/dir/link.
 476  * @param atime Access timestamp.
 477  *
 478  * @return  Standard error code.*/
 479 int ext4_atime_get(const char *path, uint32_t *atime);
 480
 481 /**@brief Get file/directory/link modify time.
 482  *
 483  * @param path  Path to file/dir/link.
 484  * @param mtime Modify timestamp.
 485  *
 486  * @return  Standard error code.*/
 487 int ext4_mtime_get(const char *path, uint32_t *mtime);
 488
 489 /**@brief Get file/directory/link change time.
 490  *
 491  * @param path  Pathto file/dir/link.
 492  * @param ctime Change timestamp.
 493  *
 494  * @return  standard error code*/
 495 int ext4_ctime_get(const char *path, uint32_t *ctime);
 496
 497 /**@brief Create symbolic link.
 498  *
 499  * @param target Destination entry path.
 500  * @param path   Source entry path.
 501  *
 502  * @return  Standard error code.*/
 503 int ext4_fsymlink(const char *target, const char *path);
 504
 505 /**@brief Create special file.
 506  * @param path     Path to new special file.
 507  * @param filetype Filetype of the new special file.
 508  *                 (that must not be regular file, directory, or unknown type)
 509  * @param dev      If filetype is char device or block device,
 510  *                 the device number will become the payload in the inode.
 511  * @return  Standard error code.*/
 512 int ext4_mknod(const char *path, int filetype, uint32_t dev);
 513
 514 /**@brief Read symbolic link payload.
 515  *
 516  * @param path    Path to symlink.
 517  * @param buf     Output buffer.
 518  * @param bufsize Output buffer max size.
 519  * @param rcnt    Bytes read.
 520  *
 521  * @return  Standard error code.*/
 522 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
 523
 524 /**@brief Set extended attribute.
 525  *
 526  * @param path      Path to file/directory
 527  * @param name      Name of the entry to add.
 528  * @param name_len  Length of @name in bytes.
 529  * @param data      Data of the entry to add.
 530  * @param data_size Size of data to add.
 531  *
 532  * @return  Standard error code.*/
 533 int ext4_setxattr(const char *path, const char *name, size_t name_len,
 534                   const void *data, size_t data_size);
 535
 536 /**@brief Get extended attribute.
 537  *
 538  * @param path      Path to file/directory.
 539  * @param name      Name of the entry to get.
 540  * @param name_len  Length of @name in bytes.
 541  * @param data      Data of the entry to get.
 542  * @param data_size Size of data to get.
 543  *
 544  * @return  Standard error code.*/
 545 int ext4_getxattr(const char *path, const char *name, size_t name_len,
 546                   void *buf, size_t buf_size, size_t *data_size);
 547
 548 /**@brief List extended attributes.
 549  *
 550  * @param path     Path to file/directory.
 551  * @param list     List to hold the name of entries.
 552  * @param size     Size of @list in bytes.
 553  * @param ret_size Used bytes of @list.
 554  *
 555  * @return  Standard error code.*/
 556 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
 557
 558 /**@brief Remove extended attribute.
 559  *
 560  * @param path     Path to file/directory.
 561  * @param name     Name of the entry to remove.
 562  * @param name_len Length of @name in bytes.
 563  *
 564  * @return  Standard error code.*/
 565 int ext4_removexattr(const char *path, const char *name, size_t name_len);
 566
 567
 568 /*********************************DIRECTORY OPERATION***********************/
 569
 570 /**@brief   Recursive directory remove.
 571  *
 572  * @param   path Directory path to remove
 573  *
 574  * @return  Standard error code.*/
 575 int ext4_dir_rm(const char *path);
 576
 577 /**@brief Rename/move directory.
 578  *
 579  * @param path     Source path.
 580  * @param new_path Destination path.
 581  *
 582  * @return  Standard error code. */
 583 int ext4_dir_mv(const char *path, const char *new_path);
 584
 585 /**@brief   Create new directory.
 586  *
 587  * @param   path Directory name.
 588  *
 589  * @return  Standard error code.*/
 590 int ext4_dir_mk(const char *path);
 591
 592 /**@brief   Directory open.
 593  *
 594  * @param   dir  Directory handle.
 595  * @param   path Directory path.
 596  *
 597  * @return  Standard error code.*/
 598 int ext4_dir_open(ext4_dir *dir, const char *path);
 599
 600 /**@brief   Directory close.
 601  *
 602  * @param   dir directory handle.
 603  *
 604  * @return  Standard error code.*/
 605 int ext4_dir_close(ext4_dir *dir);
 606
 607 /**@brief   Return next directory entry.
 608  *
 609  * @param   dir Directory handle.
 610  *
 611  * @return  Directory entry id (NULL if no entry)*/
 612 const ext4_direntry *ext4_dir_entry_next(ext4_dir *dir);
 613
 614 /**@brief   Rewine directory entry offset.
 615  *
 616  * @param   dir Directory handle.*/
 617 void ext4_dir_entry_rewind(ext4_dir *dir);
 618
 619
 620 #ifdef __cplusplus
 621 }
 622 #endif
 623
 624 #endif /* EXT4_H_ */
 625
 626 /**
 627  * @}
 628  */