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