lwext4/ext4.h

   1 /*\r
   2  * Copyright (c) 2013 Grzegorz Kostka (kostka.grzegorz@gmail.com)\r
   3  * All rights reserved.\r
   4  *\r
   5  * Redistribution and use in source and binary forms, with or without\r
   6  * modification, are permitted provided that the following conditions\r
   7  * are met:\r
   8  *\r
   9  * - Redistributions of source code must retain the above copyright\r
  10  *   notice, this list of conditions and the following disclaimer.\r
  11  * - Redistributions in binary form must reproduce the above copyright\r
  12  *   notice, this list of conditions and the following disclaimer in the\r
  13  *   documentation and/or other materials provided with the distribution.\r
  14  * - The name of the author may not be used to endorse or promote products\r
  15  *   derived from this software without specific prior written permission.\r
  16  *\r
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR\r
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES\r
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\r
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT\r
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF\r
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  27  */\r
  28 \r
  29 /** @addtogroup lwext4\r
  30  * @{\r
  31  */\r
  32 /**\r
  33  * @file  ext4.h\r
  34  * @brief Ext4 high level operations (files, directories, mount points...).\r
  35  *        Client has to include only this file.\r
  36  */\r
  37 \r
  38 #ifndef EXT4_H_\r
  39 #define EXT4_H_\r
  40 \r
  41 #include "ext4_config.h"\r
  42 #include "ext4_types.h"\r
  43 #include "ext4_blockdev.h"\r
  44 \r
  45 #include <stdint.h>\r
  46 \r
  47 /********************************FILE OPEN FLAGS*****************************/\r
  48 \r
  49 #ifndef O_RDONLY\r
  50 #define O_RDONLY 00\r
  51 #endif\r
  52 \r
  53 #ifndef O_WRONLY\r
  54 #define O_WRONLY 01\r
  55 #endif\r
  56 \r
  57 #ifndef O_RDWR\r
  58 #define O_RDWR 02\r
  59 #endif\r
  60 \r
  61 #ifndef O_CREAT\r
  62 #define O_CREAT 0100\r
  63 #endif\r
  64 \r
  65 #ifndef O_EXCL\r
  66 #define O_EXCL 0200\r
  67 #endif\r
  68 \r
  69 #ifndef O_TRUNC\r
  70 #define O_TRUNC 01000\r
  71 #endif\r
  72 \r
  73 #ifndef O_APPEND\r
  74 #define O_APPEND 02000\r
  75 #endif\r
  76 \r
  77 /********************************FILE SEEK FLAGS*****************************/\r
  78 \r
  79 #ifndef SEEK_SET\r
  80 #define SEEK_SET 0\r
  81 #endif\r
  82 \r
  83 #ifndef SEEK_CUR\r
  84 #define SEEK_CUR 1\r
  85 #endif\r
  86 \r
  87 #ifndef SEEK_END\r
  88 #define SEEK_END 2\r
  89 #endif\r
  90 \r
  91 /********************************OS LOCK INFERFACE***************************/\r
  92 \r
  93 /**@brief   OS dependent lock interface.*/\r
  94 struct ext4_lock {\r
  95 \r
  96         /**@brief   Lock access to mount point*/\r
  97         void (*lock)(void);\r
  98 \r
  99         /**@brief   Unlock access to mount point*/\r
 100         void (*unlock)(void);\r
 101 };\r
 102 \r
 103 /********************************FILE DESCRIPTOR*****************************/\r
 104 \r
 105 /**@brief   File descriptor*/\r
 106 typedef struct ext4_file {\r
 107 \r
 108         /**@brief   Mount point handle.*/\r
 109         struct ext4_mountpoint *mp;\r
 110 \r
 111         /**@brief   File inode id*/\r
 112         uint32_t inode;\r
 113 \r
 114         /**@brief   Open flags.*/\r
 115         uint32_t flags;\r
 116 \r
 117         /**@brief   File size.*/\r
 118         uint64_t fsize;\r
 119 \r
 120         /**@brief   File position*/\r
 121         uint64_t fpos;\r
 122 } ext4_file;\r
 123 \r
 124 /*****************************DIRECTORY DESCRIPTOR***************************/\r
 125 /**@brief   Directory entry types. Copy from ext4_types.h*/\r
 126 enum { EXT4_DIRENTRY_UNKNOWN = 0,\r
 127        EXT4_DIRENTRY_REG_FILE,\r
 128        EXT4_DIRENTRY_DIR,\r
 129        EXT4_DIRENTRY_CHRDEV,\r
 130        EXT4_DIRENTRY_BLKDEV,\r
 131        EXT4_DIRENTRY_FIFO,\r
 132        EXT4_DIRENTRY_SOCK,\r
 133        EXT4_DIRENTRY_SYMLINK };\r
 134 \r
 135 /**@brief   Directory entry descriptor. Copy from ext4_types.h*/\r
 136 typedef struct {\r
 137         uint32_t inode;\r
 138         uint16_t entry_length;\r
 139         uint8_t name_length;\r
 140         uint8_t inode_type;\r
 141         uint8_t name[255];\r
 142 } ext4_direntry;\r
 143 \r
 144 typedef struct {\r
 145         /**@brief   File descriptor*/\r
 146         ext4_file f;\r
 147         /**@brief   Current directory entry.*/\r
 148         ext4_direntry de;\r
 149         /**@brief   Next entry offset*/\r
 150         uint64_t next_off;\r
 151 } ext4_dir;\r
 152 \r
 153 /********************************MOUNT OPERATIONS****************************/\r
 154 \r
 155 /**@brief   Register a block device to a name.\r
 156  *          @warning Block device has to be filled by\r
 157  *          @ref EXT4_BLOCKDEV_STATIC_INSTANCE. Block cache may be created\r
 158  *          @ref EXT4_BCACHE_STATIC_INSTANCE.\r
 159  *          Block cache may by created automatically when bc parameter is 0.\r
 160  * @param   bd block device\r
 161  * @param   bd block device cache (0 = automatic cache mode)\r
 162  * @param   dev_name register name\r
 163  * @param   standard error code*/\r
 164 int ext4_device_register(struct ext4_blockdev *bd, struct ext4_bcache *bc,\r
 165                          const char *dev_name);\r
 166 \r
 167 /**@brief   Mount a block device with EXT4 partition to the mount point.\r
 168  * @param   dev_name block device name (@ref ext4_device_register)\r
 169  * @param   mount_point mount point, for example\r
 170  *          -   /\r
 171  *          -   /my_partition/\r
 172  *          -   /my_second_partition/\r
 173  *\r
 174  * @return standard error code */\r
 175 int ext4_mount(const char *dev_name, const char *mount_point);\r
 176 \r
 177 /**@brief   Umount operation.\r
 178  * @param   mount_point mount name\r
 179  * @return  standard error code */\r
 180 int ext4_umount(const char *mount_point);\r
 181 \r
 182 /**@brief   Some of the filesystem stats.*/\r
 183 struct ext4_mount_stats {\r
 184         uint32_t inodes_count;\r
 185         uint32_t free_inodes_count;\r
 186         uint64_t blocks_count;\r
 187         uint64_t free_blocks_count;\r
 188 \r
 189         uint32_t block_size;\r
 190         uint32_t block_group_count;\r
 191         uint32_t blocks_per_group;\r
 192         uint32_t inodes_per_group;\r
 193 \r
 194         char volume_name[16];\r
 195 };\r
 196 \r
 197 /**@brief   Get file system params.\r
 198  * @param   mount_point mount path\r
 199  * @param   stats ext fs stats\r
 200  * @return  standard error code */\r
 201 int ext4_mount_point_stats(const char *mount_point,\r
 202                            struct ext4_mount_stats *stats);\r
 203 \r
 204 /**@brief   Setup OS lock routines.\r
 205  * @param   mount_point mount path\r
 206  * @param   locks - lock and unlock functions\r
 207  * @return  standard error code */\r
 208 int ext4_mount_setup_locks(const char *mount_point,\r
 209                            const struct ext4_lock *locks);\r
 210 \r
 211 /**@brief   Acquire the filesystem superblock pointer of a mp.\r
 212  * @param   mount_point mount path\r
 213  * @param   superblock pointer\r
 214  * @return  standard error code */\r
 215 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);\r
 216 \r
 217 /**@brief   Enable/disable write back cache mode.\r
 218  * @warning Default model of cache is write trough. It means that when You do:\r
 219  *\r
 220  *          ext4_fopen(...);\r
 221  *          ext4_fwrie(...);\r
 222  *                           < --- data is flushed to physical drive\r
 223  *\r
 224  *          When you do:\r
 225  *          ext4_cache_write_back(..., 1);\r
 226  *          ext4_fopen(...);\r
 227  *          ext4_fwrie(...);\r
 228  *                           < --- data is NOT flushed to physical drive\r
 229  *          ext4_cache_write_back(..., 0);\r
 230  *                           < --- when write back mode is disabled all\r
 231  *                                 cache data will be flushed\r
 232  * To enable write back mode permanently just call this function\r
 233  * once after ext4_mount (and disable before ext4_umount).\r
 234  *\r
 235  * Some of the function use write back cache mode internally.\r
 236  * If you enable write back mode twice you have to disable it twice\r
 237  * to flush all data:\r
 238  *\r
 239  *      ext4_cache_write_back(..., 1);\r
 240  *      ext4_cache_write_back(..., 1);\r
 241  *\r
 242  *      ext4_cache_write_back(..., 0);\r
 243  *      ext4_cache_write_back(..., 0);\r
 244  *\r
 245  * Write back mode is useful when you want to create a lot of empty\r
 246  * files/directories.\r
 247  *\r
 248  * @param   path mount point path\r
 249  * @param   on enable/disable\r
 250  *\r
 251  * @return  standard error code */\r
 252 int ext4_cache_write_back(const char *path, bool on);\r
 253 \r
 254 /********************************FILE OPERATIONS*****************************/\r
 255 \r
 256 /**@brief   Remove file by path.\r
 257  * @param   path path to file\r
 258  * @return  standard error code */\r
 259 int ext4_fremove(const char *path);\r
 260 \r
 261 /**@brief Rename file\r
 262  * @param path source\r
 263  * @param new_path destination\r
 264  * @return  standard error code */\r
 265 int ext4_frename(const char *path, const char *new_path);\r
 266 \r
 267 /**@brief   File open function.\r
 268  * @param   filename, (has to start from mount point)\r
 269  *          /my_partition/my_file\r
 270  * @param   flags open file flags\r
 271  *  |---------------------------------------------------------------|\r
 272  *  |   r or rb                 O_RDONLY                            |\r
 273  *  |---------------------------------------------------------------|\r
 274  *  |   w or wb                 O_WRONLY|O_CREAT|O_TRUNC            |\r
 275  *  |---------------------------------------------------------------|\r
 276  *  |   a or ab                 O_WRONLY|O_CREAT|O_APPEND           |\r
 277  *  |---------------------------------------------------------------|\r
 278  *  |   r+ or rb+ or r+b        O_RDWR                              |\r
 279  *  |---------------------------------------------------------------|\r
 280  *  |   w+ or wb+ or w+b        O_RDWR|O_CREAT|O_TRUNC              |\r
 281  *  |---------------------------------------------------------------|\r
 282  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |\r
 283  *  |---------------------------------------------------------------|\r
 284  *\r
 285  * @return  standard error code*/\r
 286 int ext4_fopen(ext4_file *f, const char *path, const char *flags);\r
 287 \r
 288 /**@brief   Alternate file open function.\r
 289  * @param   filename, (has to start from mount point)\r
 290  *          /my_partition/my_file\r
 291  * @param   flags open file flags\r
 292  * @return  standard error code*/\r
 293 int ext4_fopen2(ext4_file *f, const char *path, int flags, bool file_expect);\r
 294 \r
 295 /**@brief   File close function.\r
 296  * @param   f file handle\r
 297  * @return  standard error code*/\r
 298 int ext4_fclose(ext4_file *f);\r
 299 \r
 300 /**@brief   Fill in the ext4_inode buffer.\r
 301  * @param   mount_point\r
 302  * @param   inode no.\r
 303  * @param   ext4_inode buffer\r
 304  * @return  standard error code*/\r
 305 int ext4_fill_raw_inode(const char *mount_point, uint32_t ino,\r
 306                         struct ext4_inode *inode);\r
 307 \r
 308 /**@brief   File truncate function.\r
 309  * @param   f file handle\r
 310  * @param   new file size\r
 311  * @return  standard error code*/\r
 312 int ext4_ftruncate(ext4_file *f, uint64_t size);\r
 313 \r
 314 /**@brief   Read data from file.\r
 315  * @param   f file handle\r
 316  * @param   buf output buffer\r
 317  * @param   size bytes to read\r
 318  * @param   rcnt bytes read (may be NULL)\r
 319  * @return  standard error code*/\r
 320 int ext4_fread(ext4_file *f, void *buf, uint32_t size, uint32_t *rcnt);\r
 321 \r
 322 /**@brief   Write data to file.\r
 323  * @param   f file handle\r
 324  * @param   buf data to write\r
 325  * @param   size write length\r
 326  * @param   wcnt bytes written (may be NULL)\r
 327  * @return  standard error code*/\r
 328 int ext4_fwrite(ext4_file *f, const void *buf, uint32_t size, uint32_t *wcnt);\r
 329 \r
 330 /**@brief   File seek operation.\r
 331  * @param   f file handle\r
 332  * @param   offset offset to seek\r
 333  * @param   origin seek type:\r
 334  *              @ref SEEK_SET\r
 335  *              @ref SEEK_CUR\r
 336  *              @ref SEEK_END\r
 337  * @return  standard error code*/\r
 338 int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);\r
 339 \r
 340 /**@brief   Get file position.\r
 341  * @param   f file handle\r
 342  * @return  actual file position */\r
 343 uint64_t ext4_ftell(ext4_file *f);\r
 344 \r
 345 /**@brief   Get file size.\r
 346  * @param   f file handle\r
 347  * @return  file size */\r
 348 uint64_t ext4_fsize(ext4_file *f);\r
 349 \r
 350 int ext4_fchmod(ext4_file *f, uint32_t mode);\r
 351 int ext4_fchown(ext4_file *f, uint32_t uid, uint32_t gid);\r
 352 int ext4_file_set_atime(ext4_file *f, uint32_t atime);\r
 353 int ext4_file_set_mtime(ext4_file *f, uint32_t mtime);\r
 354 int ext4_file_set_ctime(ext4_file *f, uint32_t ctime);\r
 355 \r
 356 /*********************************DIRECTORY OPERATION***********************/\r
 357 \r
 358 /**@brief   Recursive directory remove.\r
 359  * @param   path directory path to remove\r
 360  * @return  standard error code*/\r
 361 int ext4_dir_rm(const char *path);\r
 362 \r
 363 /**@brief   Create new directory.\r
 364  * @param   name new directory name\r
 365  * @return  standard error code*/\r
 366 int ext4_dir_mk(const char *path);\r
 367 \r
 368 /**@brief   Directory open.\r
 369  * @param   d directory handle\r
 370  * @param   path directory path\r
 371  * @return  standard error code*/\r
 372 int ext4_dir_open(ext4_dir *d, const char *path);\r
 373 \r
 374 /**@brief   Directory close.\r
 375  * @param   d directory handle\r
 376  * @return  standard error code*/\r
 377 int ext4_dir_close(ext4_dir *d);\r
 378 \r
 379 /**@brief   Return next directory entry.\r
 380  * @param   d directory handle\r
 381  * @param   id entry id\r
 382  * @return  directory entry id (NULL if no entry)*/\r
 383 const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);\r
 384 \r
 385 #endif /* EXT4_H_ */\r
 386 \r
 387 /**\r
 388  * @}\r
 389  */\r