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_errno.h"
  50 #include "ext4_oflags.h"
  51 #include "ext4_types.h"
  52 #include "ext4_blockdev.h"
  53
  54 /********************************OS LOCK INFERFACE***************************/
  55
  56 /**@brief   OS dependent lock interface.*/
  57 struct ext4_lock {
  58
  59         /**@brief   Lock access to mount point*/
  60         void (*lock)(void);
  61
  62         /**@brief   Unlock access to mount point*/
  63         void (*unlock)(void);
  64 };
  65
  66 /********************************FILE DESCRIPTOR*****************************/
  67
  68 /**@brief   File descriptor*/
  69 typedef struct ext4_file {
  70
  71         /**@brief   Mount point handle.*/
  72         struct ext4_mountpoint *mp;
  73
  74         /**@brief   File inode id*/
  75         uint32_t inode;
  76
  77         /**@brief   Open flags.*/
  78         uint32_t flags;
  79
  80         /**@brief   File size.*/
  81         uint64_t fsize;
  82
  83         /**@brief   File position*/
  84         uint64_t fpos;
  85 } ext4_file;
  86
  87 /*****************************DIRECTORY DESCRIPTOR***************************/
  88
  89 /**@brief   Directory entry descriptor. Copy from ext4_types.h*/
  90 typedef struct ext4_direntry {
  91         uint32_t inode;
  92         uint16_t entry_length;
  93         uint8_t name_length;
  94         uint8_t inode_type;
  95         uint8_t name[255];
  96 } ext4_direntry;
  97
  98 typedef struct ext4_dir {
  99         /**@brief   File descriptor*/
 100         ext4_file f;
 101         /**@brief   Current directory entry.*/
 102         ext4_direntry de;
 103         /**@brief   Next entry offset*/
 104         uint64_t next_off;
 105 } ext4_dir;
 106
 107 /********************************MOUNT OPERATIONS****************************/
 108
 109 /**@brief   Register a block device to a name.
 110  *          @warning Block device has to be filled by
 111  *          Block cache may by created automatically when bc parameter is NULL.
 112  * @param   bd block device
 113  * @param   bd block device cache
 114  * @param   dev_name register name
 115  * @param   standard error code*/
 116 int ext4_device_register(struct ext4_blockdev *bd, struct ext4_bcache *bc,
 117                          const char *dev_name);
 118
 119 /**@brief   Mount a block device with EXT4 partition to the mount point.
 120  * @param   dev_name block device name (@ref ext4_device_register)
 121  * @param   mount_point mount point, for example
 122  *          -   /
 123  *          -   /my_partition/
 124  *          -   /my_second_partition/
 125  * @param   read_only mount as read-only mode.
 126  *
 127  * @return standard error code */
 128 int ext4_mount(const char *dev_name,
 129                const char *mount_point,
 130                bool read_only);
 131
 132 /**@brief   Umount operation.
 133  * @param   mount_point mount name
 134  * @return  standard error code */
 135 int ext4_umount(const char *mount_point);
 136
 137 /**@brief   Start journaling. Journaling start/stop functions are transparent
 138  *          and might be used on filesystems without journaling support.
 139  * @warning Usage:
 140  *              ext4_mount("sda1", "/");
 141  *              ext4_journal_start("/");
 142  *
 143  *              //File operations here...
 144  *
 145  *              ext4_journal_stop("/");
 146  *              ext4_umount("/");
 147  * @param   mount_point mount name
 148  * @return  standard error code */
 149 int ext4_journal_start(const char *mount_point);
 150
 151 /**@brief   Stop journaling. Journaling start/stop functions are transparent
 152  *          and might be used on filesystems without journaling support.
 153  * @param   mount_point mount name
 154  * @return  standard error code */
 155 int ext4_journal_stop(const char *mount_point);
 156
 157 /**@brief   Journal recovery.
 158  * @param   mount_point mount point
 159  * @warning Must be called after @ref ext4_mount
 160  * @return standard error code */
 161 int ext4_recover(const char *mount_point);
 162
 163 /**@brief   Some of the filesystem stats.*/
 164 struct ext4_mount_stats {
 165         uint32_t inodes_count;
 166         uint32_t free_inodes_count;
 167         uint64_t blocks_count;
 168         uint64_t free_blocks_count;
 169
 170         uint32_t block_size;
 171         uint32_t block_group_count;
 172         uint32_t blocks_per_group;
 173         uint32_t inodes_per_group;
 174
 175         char volume_name[16];
 176 };
 177
 178 /**@brief   Get file system params.
 179  * @param   mount_point mount path
 180  * @param   stats ext fs stats
 181  * @return  standard error code */
 182 int ext4_mount_point_stats(const char *mount_point,
 183                            struct ext4_mount_stats *stats);
 184
 185 /**@brief   Setup OS lock routines.
 186  * @param   mount_point mount path
 187  * @param   locks - lock and unlock functions
 188  * @return  standard error code */
 189 int ext4_mount_setup_locks(const char *mount_point,
 190                            const struct ext4_lock *locks);
 191
 192 /**@brief   Acquire the filesystem superblock pointer of a mp.
 193  * @param   mount_point mount path
 194  * @param   superblock pointer
 195  * @return  standard error code */
 196 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
 197
 198 /**@brief   Enable/disable write back cache mode.
 199  * @warning Default model of cache is write trough. It means that when You do:
 200  *
 201  *          ext4_fopen(...);
 202  *          ext4_fwrie(...);
 203  *                           < --- data is flushed to physical drive
 204  *
 205  *          When you do:
 206  *          ext4_cache_write_back(..., 1);
 207  *          ext4_fopen(...);
 208  *          ext4_fwrie(...);
 209  *                           < --- data is NOT flushed to physical drive
 210  *          ext4_cache_write_back(..., 0);
 211  *                           < --- when write back mode is disabled all
 212  *                                 cache data will be flushed
 213  * To enable write back mode permanently just call this function
 214  * once after ext4_mount (and disable before ext4_umount).
 215  *
 216  * Some of the function use write back cache mode internally.
 217  * If you enable write back mode twice you have to disable it twice
 218  * to flush all data:
 219  *
 220  *      ext4_cache_write_back(..., 1);
 221  *      ext4_cache_write_back(..., 1);
 222  *
 223  *      ext4_cache_write_back(..., 0);
 224  *      ext4_cache_write_back(..., 0);
 225  *
 226  * Write back mode is useful when you want to create a lot of empty
 227  * files/directories.
 228  *
 229  * @param   path mount point path
 230  * @param   on enable/disable
 231  *
 232  * @return  standard error code */
 233 int ext4_cache_write_back(const char *path, bool on);
 234
 235 /********************************FILE OPERATIONS*****************************/
 236
 237 /**@brief   Remove file by path.
 238  * @param   path path to file
 239  * @return  standard error code */
 240 int ext4_fremove(const char *path);
 241
 242 /**@brief   create a hardlink for a file.
 243  * @param   path path to file
 244  * @param   hardlink_path path of hardlink
 245  * @return  standard error code */
 246 int ext4_flink(const char *path, const char *hardlink_path);
 247
 248 /**@brief Rename file
 249  * @param path source
 250  * @param new_path destination
 251  * @return  standard error code */
 252 int ext4_frename(const char *path, const char *new_path);
 253
 254 /**@brief   File open function.
 255  * @param   path filename (has to start from mount point)
 256  *          /my_partition/my_file
 257  * @param   flags open file flags
 258  *  |---------------------------------------------------------------|
 259  *  |   r or rb                 O_RDONLY                            |
 260  *  |---------------------------------------------------------------|
 261  *  |   w or wb                 O_WRONLY|O_CREAT|O_TRUNC            |
 262  *  |---------------------------------------------------------------|
 263  *  |   a or ab                 O_WRONLY|O_CREAT|O_APPEND           |
 264  *  |---------------------------------------------------------------|
 265  *  |   r+ or rb+ or r+b        O_RDWR                              |
 266  *  |---------------------------------------------------------------|
 267  *  |   w+ or wb+ or w+b        O_RDWR|O_CREAT|O_TRUNC              |
 268  *  |---------------------------------------------------------------|
 269  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |
 270  *  |---------------------------------------------------------------|
 271  *
 272  * @return  standard error code*/
 273 int ext4_fopen(ext4_file *f, const char *path, const char *flags);
 274
 275 /**@brief   Alternate file open function.
 276  * @param   filename, (has to start from mount point)
 277  *          /my_partition/my_file
 278  * @param   flags open file flags
 279  * @return  standard error code*/
 280 int ext4_fopen2(ext4_file *f, const char *path, int flags);
 281
 282 /**@brief   File close function.
 283  * @param   f file handle
 284  * @return  standard error code*/
 285 int ext4_fclose(ext4_file *f);
 286
 287 /**@brief   Fill in the ext4_inode buffer.
 288  * @param   path fetch inode data of the path
 289  * @param   ret_ino the inode id of the path
 290  * @param   ext4_inode buffer
 291  * @return  standard error code*/
 292 int ext4_fill_raw_inode(const char *path, uint32_t *ret_ino,
 293                         struct ext4_inode *inode);
 294
 295 /**@brief   File truncate function.
 296  * @param   f file handle
 297  * @param   new file size
 298  * @return  standard error code*/
 299 int ext4_ftruncate(ext4_file *f, uint64_t size);
 300
 301 /**@brief   Read data from file.
 302  * @param   f file handle
 303  * @param   buf output buffer
 304  * @param   size bytes to read
 305  * @param   rcnt bytes read (may be NULL)
 306  * @return  standard error code*/
 307 int ext4_fread(ext4_file *f, void *buf, size_t size, size_t *rcnt);
 308
 309 /**@brief   Write data to file.
 310  * @param   f file handle
 311  * @param   buf data to write
 312  * @param   size write length
 313  * @param   wcnt bytes written (may be NULL)
 314  * @return  standard error code*/
 315 int ext4_fwrite(ext4_file *f, const void *buf, size_t size, size_t *wcnt);
 316
 317 /**@brief   File seek operation.
 318  * @param   f file handle
 319  * @param   offset offset to seek
 320  * @param   origin seek type:
 321  *              @ref SEEK_SET
 322  *              @ref SEEK_CUR
 323  *              @ref SEEK_END
 324  * @return  standard error code*/
 325 int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);
 326
 327 /**@brief   Get file position.
 328  * @param   f file handle
 329  * @return  actual file position */
 330 uint64_t ext4_ftell(ext4_file *f);
 331
 332 /**@brief   Get file size.
 333  * @param   f file handle
 334  * @return  file size */
 335 uint64_t ext4_fsize(ext4_file *f);
 336
 337 /**@brief Change file/directory/link mode bits
 338  * @param path to file/dir/link
 339  * @param mode new mode bits (for example 0777)
 340  * @return  standard error code*/
 341 int ext4_chmod(const char *path, uint32_t mode);
 342
 343 /**@brief Change file owner and group
 344  * @param path to file/dir/link
 345  * @param uid user id
 346  * @param gid group id
 347  * @return  standard error code*/
 348 int ext4_chown(const char *path, uint32_t uid, uint32_t gid);
 349
 350 /**@brief Set file access time
 351  * @param path to file/dir/link
 352  * @param atime access timestamp
 353  * @return  standard error code*/
 354 int ext4_file_set_atime(const char *path, uint32_t atime);
 355
 356 /**@brief Set file modify time
 357  * @param path to file/dir/link
 358  * @param mtime modify timestamp
 359  * @return  standard error code*/
 360 int ext4_file_set_mtime(const char *path, uint32_t mtime);
 361
 362 /**@brief Set file change time
 363  * @param path to file/dir/link
 364  * @param ctime change timestamp
 365  * @return  standard error code*/
 366 int ext4_file_set_ctime(const char *path, uint32_t ctime);
 367
 368 /**@brief Create symbolic link
 369  * @param target destination path
 370  * @param path source entry
 371  * @return standard error code*/
 372 int ext4_fsymlink(const char *target, const char *path);
 373
 374
 375 /**@brief Read symbolic link payload
 376  * @param path to symlink
 377  * @param buf output buffer
 378  * @param bufsize output buffer max size
 379  * @param rcnt bytes read
 380  * @return standard error code*/
 381 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
 382
 383 /**@brief Set extended attribute
 384  * @param path to file/directory
 385  * @param name name of the entry to add
 386  * @param name_len length of @name in bytes
 387  * @param data data of the entry to add
 388  * @param data_size size of data to add
 389  * @param replace whether existing entries should be replaced
 390  * @return standard error code*/
 391 int ext4_setxattr(const char *path, const char *name, size_t name_len,
 392                   const void *data, size_t data_size, bool replace);
 393
 394 /**@brief Get extended attribute
 395  * @param path to file/directory
 396  * @param name name of the entry to get
 397  * @param name_len length of @name in bytes
 398  * @param data data of the entry to get
 399  * @param data_size size of data to get
 400  * @return standard error code*/
 401 int ext4_getxattr(const char *path, const char *name, size_t name_len,
 402                   void *buf, size_t buf_size, size_t *data_size);
 403
 404 /**@brief List extended attributes
 405  * @param path to file/directory
 406  * @param list list to hold the name of entries
 407  * @param size size of @list in bytes
 408  * @param ret_size used bytes of @list
 409  * @return standard error code*/
 410 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
 411
 412 /**@brief Remove extended attribute
 413  * @param path to file/directory
 414  * @param name name of the entry to remove
 415  * @param name_len length of @name in bytes
 416  * @return standard error code*/
 417 int ext4_removexattr(const char *path, const char *name, size_t name_len);
 418
 419
 420 /*********************************DIRECTORY OPERATION***********************/
 421
 422 /**@brief   Recursive directory remove.
 423  * @param   path directory path to remove
 424  * @return  standard error code*/
 425 int ext4_dir_rm(const char *path);
 426
 427 /**@brief   Create new directory.
 428  * @param   name new directory name
 429  * @return  standard error code*/
 430 int ext4_dir_mk(const char *path);
 431
 432 /**@brief   Directory open.
 433  * @param   d directory handle
 434  * @param   path directory path
 435  * @return  standard error code*/
 436 int ext4_dir_open(ext4_dir *d, const char *path);
 437
 438 /**@brief   Directory close.
 439  * @param   d directory handle
 440  * @return  standard error code*/
 441 int ext4_dir_close(ext4_dir *d);
 442
 443 /**@brief   Return next directory entry.
 444  * @param   d directory handle
 445  * @param   id entry id
 446  * @return  directory entry id (NULL if no entry)*/
 447 const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);
 448
 449 /**@brief   Rewine directory entry offset.
 450  * @param   d directory handle*/
 451 void ext4_dir_entry_rewind(ext4_dir *d);
 452
 453
 454 #ifdef __cplusplus
 455 }
 456 #endif
 457
 458 #endif /* EXT4_H_ */
 459
 460 /**
 461  * @}
 462  */