lwext4/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 #include "ext4_config.h"
  42 #include "ext4_types.h"
  43 #include "ext4_blockdev.h"
  44
  45 #include <stdint.h>
  46 #include <stddef.h>
  47
  48 /********************************FILE OPEN FLAGS*****************************/
  49
  50 #ifndef O_RDONLY
  51 #define O_RDONLY 00
  52 #endif
  53
  54 #ifndef O_WRONLY
  55 #define O_WRONLY 01
  56 #endif
  57
  58 #ifndef O_RDWR
  59 #define O_RDWR 02
  60 #endif
  61
  62 #ifndef O_CREAT
  63 #define O_CREAT 0100
  64 #endif
  65
  66 #ifndef O_EXCL
  67 #define O_EXCL 0200
  68 #endif
  69
  70 #ifndef O_TRUNC
  71 #define O_TRUNC 01000
  72 #endif
  73
  74 #ifndef O_APPEND
  75 #define O_APPEND 02000
  76 #endif
  77
  78 /********************************FILE SEEK FLAGS*****************************/
  79
  80 #ifndef SEEK_SET
  81 #define SEEK_SET 0
  82 #endif
  83
  84 #ifndef SEEK_CUR
  85 #define SEEK_CUR 1
  86 #endif
  87
  88 #ifndef SEEK_END
  89 #define SEEK_END 2
  90 #endif
  91
  92 /********************************OS LOCK INFERFACE***************************/
  93
  94 /**@brief   OS dependent lock interface.*/
  95 struct ext4_lock {
  96
  97         /**@brief   Lock access to mount point*/
  98         void (*lock)(void);
  99
 100         /**@brief   Unlock access to mount point*/
 101         void (*unlock)(void);
 102 };
 103
 104 /********************************FILE DESCRIPTOR*****************************/
 105
 106 /**@brief   File descriptor*/
 107 typedef struct ext4_file {
 108
 109         /**@brief   Mount point handle.*/
 110         struct ext4_mountpoint *mp;
 111
 112         /**@brief   File inode id*/
 113         uint32_t inode;
 114
 115         /**@brief   Open flags.*/
 116         uint32_t flags;
 117
 118         /**@brief   File size.*/
 119         uint64_t fsize;
 120
 121         /**@brief   File position*/
 122         uint64_t fpos;
 123 } ext4_file;
 124
 125 /*****************************DIRECTORY DESCRIPTOR***************************/
 126 /**@brief   Directory entry types. Copy from ext4_types.h*/
 127 enum { EXT4_DIRENTRY_UNKNOWN = 0,
 128        EXT4_DIRENTRY_REG_FILE,
 129        EXT4_DIRENTRY_DIR,
 130        EXT4_DIRENTRY_CHRDEV,
 131        EXT4_DIRENTRY_BLKDEV,
 132        EXT4_DIRENTRY_FIFO,
 133        EXT4_DIRENTRY_SOCK,
 134        EXT4_DIRENTRY_SYMLINK };
 135
 136 /**@brief   Directory entry descriptor. Copy from ext4_types.h*/
 137 typedef struct {
 138         uint32_t inode;
 139         uint16_t entry_length;
 140         uint8_t name_length;
 141         uint8_t inode_type;
 142         uint8_t name[255];
 143 } ext4_direntry;
 144
 145 typedef struct {
 146         /**@brief   File descriptor*/
 147         ext4_file f;
 148         /**@brief   Current directory entry.*/
 149         ext4_direntry de;
 150         /**@brief   Next entry offset*/
 151         uint64_t next_off;
 152 } ext4_dir;
 153
 154 /********************************MOUNT OPERATIONS****************************/
 155
 156 /**@brief   Register a block device to a name.
 157  *          @warning Block device has to be filled by
 158  *          @ref EXT4_BLOCKDEV_STATIC_INSTANCE. Block cache may be created
 159  *          @ref EXT4_BCACHE_STATIC_INSTANCE.
 160  *          Block cache may by created automatically when bc parameter is 0.
 161  * @param   bd block device
 162  * @param   bd block device cache (0 = automatic cache mode)
 163  * @param   dev_name register name
 164  * @param   standard error code*/
 165 int ext4_device_register(struct ext4_blockdev *bd, struct ext4_bcache *bc,
 166                          const char *dev_name);
 167
 168 /**@brief   Mount a block device with EXT4 partition to the mount point.
 169  * @param   dev_name block device name (@ref ext4_device_register)
 170  * @param   mount_point mount point, for example
 171  *          -   /
 172  *          -   /my_partition/
 173  *          -   /my_second_partition/
 174  *
 175  * @return standard error code */
 176 int ext4_mount(const char *dev_name, const char *mount_point);
 177
 178 /**@brief   Umount operation.
 179  * @param   mount_point mount name
 180  * @return  standard error code */
 181 int ext4_umount(const char *mount_point);
 182
 183 /**@brief   Some of the filesystem stats.*/
 184 struct ext4_mount_stats {
 185         uint32_t inodes_count;
 186         uint32_t free_inodes_count;
 187         uint64_t blocks_count;
 188         uint64_t free_blocks_count;
 189
 190         uint32_t block_size;
 191         uint32_t block_group_count;
 192         uint32_t blocks_per_group;
 193         uint32_t inodes_per_group;
 194
 195         char volume_name[16];
 196 };
 197
 198 /**@brief   Get file system params.
 199  * @param   mount_point mount path
 200  * @param   stats ext fs stats
 201  * @return  standard error code */
 202 int ext4_mount_point_stats(const char *mount_point,
 203                            struct ext4_mount_stats *stats);
 204
 205 /**@brief   Setup OS lock routines.
 206  * @param   mount_point mount path
 207  * @param   locks - lock and unlock functions
 208  * @return  standard error code */
 209 int ext4_mount_setup_locks(const char *mount_point,
 210                            const struct ext4_lock *locks);
 211
 212 /**@brief   Acquire the filesystem superblock pointer of a mp.
 213  * @param   mount_point mount path
 214  * @param   superblock pointer
 215  * @return  standard error code */
 216 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
 217
 218 /**@brief   Enable/disable write back cache mode.
 219  * @warning Default model of cache is write trough. It means that when You do:
 220  *
 221  *          ext4_fopen(...);
 222  *          ext4_fwrie(...);
 223  *                           < --- data is flushed to physical drive
 224  *
 225  *          When you do:
 226  *          ext4_cache_write_back(..., 1);
 227  *          ext4_fopen(...);
 228  *          ext4_fwrie(...);
 229  *                           < --- data is NOT flushed to physical drive
 230  *          ext4_cache_write_back(..., 0);
 231  *                           < --- when write back mode is disabled all
 232  *                                 cache data will be flushed
 233  * To enable write back mode permanently just call this function
 234  * once after ext4_mount (and disable before ext4_umount).
 235  *
 236  * Some of the function use write back cache mode internally.
 237  * If you enable write back mode twice you have to disable it twice
 238  * to flush all data:
 239  *
 240  *      ext4_cache_write_back(..., 1);
 241  *      ext4_cache_write_back(..., 1);
 242  *
 243  *      ext4_cache_write_back(..., 0);
 244  *      ext4_cache_write_back(..., 0);
 245  *
 246  * Write back mode is useful when you want to create a lot of empty
 247  * files/directories.
 248  *
 249  * @param   path mount point path
 250  * @param   on enable/disable
 251  *
 252  * @return  standard error code */
 253 int ext4_cache_write_back(const char *path, bool on);
 254
 255 /********************************FILE OPERATIONS*****************************/
 256
 257 /**@brief   Remove file by path.
 258  * @param   path path to file
 259  * @return  standard error code */
 260 int ext4_fremove(const char *path);
 261
 262 /**@brief   create a hardlink for a file.
 263  * @param   path path to file
 264  * @param   hardlink_path path of hardlink
 265  * @return  standard error code */
 266 int ext4_flink(const char *path, const char *hardlink_path);
 267
 268 /**@brief Rename file
 269  * @param path source
 270  * @param new_path destination
 271  * @return  standard error code */
 272 int ext4_frename(const char *path, const char *new_path);
 273
 274 /**@brief   File open function.
 275  * @param   filename, (has to start from mount point)
 276  *          /my_partition/my_file
 277  * @param   flags open file flags
 278  *  |---------------------------------------------------------------|
 279  *  |   r or rb                 O_RDONLY                            |
 280  *  |---------------------------------------------------------------|
 281  *  |   w or wb                 O_WRONLY|O_CREAT|O_TRUNC            |
 282  *  |---------------------------------------------------------------|
 283  *  |   a or ab                 O_WRONLY|O_CREAT|O_APPEND           |
 284  *  |---------------------------------------------------------------|
 285  *  |   r+ or rb+ or r+b        O_RDWR                              |
 286  *  |---------------------------------------------------------------|
 287  *  |   w+ or wb+ or w+b        O_RDWR|O_CREAT|O_TRUNC              |
 288  *  |---------------------------------------------------------------|
 289  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |
 290  *  |---------------------------------------------------------------|
 291  *
 292  * @return  standard error code*/
 293 int ext4_fopen(ext4_file *f, const char *path, const char *flags);
 294
 295 /**@brief   Alternate file open function.
 296  * @param   filename, (has to start from mount point)
 297  *          /my_partition/my_file
 298  * @param   flags open file flags
 299  * @return  standard error code*/
 300 int ext4_fopen2(ext4_file *f, const char *path, int flags, bool file_expect);
 301
 302 /**@brief   File close function.
 303  * @param   f file handle
 304  * @return  standard error code*/
 305 int ext4_fclose(ext4_file *f);
 306
 307 /**@brief   Fill in the ext4_inode buffer.
 308  * @param   mount_point
 309  * @param   inode no.
 310  * @param   ext4_inode buffer
 311  * @return  standard error code*/
 312 int ext4_fill_raw_inode(const char *mount_point, uint32_t ino,
 313                         struct ext4_inode *inode);
 314
 315 /**@brief   File truncate function.
 316  * @param   f file handle
 317  * @param   new file size
 318  * @return  standard error code*/
 319 int ext4_ftruncate(ext4_file *f, uint64_t size);
 320
 321 /**@brief   Read data from file.
 322  * @param   f file handle
 323  * @param   buf output buffer
 324  * @param   size bytes to read
 325  * @param   rcnt bytes read (may be NULL)
 326  * @return  standard error code*/
 327 int ext4_fread(ext4_file *f, void *buf, size_t size, size_t *rcnt);
 328
 329 /**@brief   Write data to file.
 330  * @param   f file handle
 331  * @param   buf data to write
 332  * @param   size write length
 333  * @param   wcnt bytes written (may be NULL)
 334  * @return  standard error code*/
 335 int ext4_fwrite(ext4_file *f, const void *buf, size_t size, size_t *wcnt);
 336
 337 /**@brief   File seek operation.
 338  * @param   f file handle
 339  * @param   offset offset to seek
 340  * @param   origin seek type:
 341  *              @ref SEEK_SET
 342  *              @ref SEEK_CUR
 343  *              @ref SEEK_END
 344  * @return  standard error code*/
 345 int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);
 346
 347 /**@brief   Get file position.
 348  * @param   f file handle
 349  * @return  actual file position */
 350 uint64_t ext4_ftell(ext4_file *f);
 351
 352 /**@brief   Get file size.
 353  * @param   f file handle
 354  * @return  file size */
 355 uint64_t ext4_fsize(ext4_file *f);
 356
 357 int ext4_fchmod(ext4_file *f, uint32_t mode);
 358 int ext4_fchown(ext4_file *f, uint32_t uid, uint32_t gid);
 359 int ext4_file_set_atime(ext4_file *f, uint32_t atime);
 360 int ext4_file_set_mtime(ext4_file *f, uint32_t mtime);
 361 int ext4_file_set_ctime(ext4_file *f, uint32_t ctime);
 362
 363 int ext4_fsymlink(const char *target, const char *path);
 364
 365 /*********************************DIRECTORY OPERATION***********************/
 366
 367 /**@brief   Recursive directory remove.
 368  * @param   path directory path to remove
 369  * @return  standard error code*/
 370 int ext4_dir_rm(const char *path);
 371
 372 /**@brief   Create new directory.
 373  * @param   name new directory name
 374  * @return  standard error code*/
 375 int ext4_dir_mk(const char *path);
 376
 377 /**@brief   Directory open.
 378  * @param   d directory handle
 379  * @param   path directory path
 380  * @return  standard error code*/
 381 int ext4_dir_open(ext4_dir *d, const char *path);
 382
 383 /**@brief   Directory close.
 384  * @param   d directory handle
 385  * @return  standard error code*/
 386 int ext4_dir_close(ext4_dir *d);
 387
 388 /**@brief   Return next directory entry.
 389  * @param   d directory handle
 390  * @param   id entry id
 391  * @return  directory entry id (NULL if no entry)*/
 392 const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);
 393
 394 #endif /* EXT4_H_ */
 395
 396 /**
 397  * @}
 398  */