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   File position*/
  86         uint64_t fpos;
  87 } ext4_file;
  88
  89 /*****************************DIRECTORY DESCRIPTOR***************************/
  90
  91 /**@brief   Directory entry descriptor. Copy from ext4_types.h*/
  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 typedef struct ext4_dir {
 101         /**@brief   File descriptor*/
 102         ext4_file f;
 103         /**@brief   Current directory entry.*/
 104         ext4_direntry de;
 105         /**@brief   Next entry offset*/
 106         uint64_t next_off;
 107 } ext4_dir;
 108
 109 /********************************MOUNT OPERATIONS****************************/
 110
 111 /**@brief   Register block device.
 112  *
 113  * @param   bd Block device.
 114  * @param   bd Block device cache.
 115  * @param   dev_name Block device name.
 116  *
 117  * @return  Standard error code.*/
 118 int ext4_device_register(struct ext4_blockdev *bd, struct ext4_bcache *bc,
 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  * @param   mount_point mount name
 149  * @return  standard error code */
 150 int ext4_umount(const char *mount_point);
 151
 152 /**@brief   Start journaling. Journaling start/stop functions are transparent
 153  *          and might be used on filesystems without journaling support.
 154  * @warning Usage:
 155  *              ext4_mount("sda1", "/");
 156  *              ext4_journal_start("/");
 157  *
 158  *              //File operations here...
 159  *
 160  *              ext4_journal_stop("/");
 161  *              ext4_umount("/");
 162  * @param   mount_point mount name
 163  * @return  standard error code */
 164 int ext4_journal_start(const char *mount_point);
 165
 166 /**@brief   Stop journaling. Journaling start/stop functions are transparent
 167  *          and might be used on filesystems without journaling support.
 168  * @param   mount_point mount name
 169  * @return  standard error code */
 170 int ext4_journal_stop(const char *mount_point);
 171
 172 /**@brief   Journal recovery.
 173  * @param   mount_point mount point
 174  * @warning Must be called after @ref ext4_mount
 175  * @return standard error code */
 176 int ext4_recover(const char *mount_point);
 177
 178 /**@brief   Some of the filesystem stats.*/
 179 struct ext4_mount_stats {
 180         uint32_t inodes_count;
 181         uint32_t free_inodes_count;
 182         uint64_t blocks_count;
 183         uint64_t free_blocks_count;
 184
 185         uint32_t block_size;
 186         uint32_t block_group_count;
 187         uint32_t blocks_per_group;
 188         uint32_t inodes_per_group;
 189
 190         char volume_name[16];
 191 };
 192
 193 /**@brief   Get file system params.
 194  * @param   mount_point mount path
 195  * @param   stats ext fs stats
 196  * @return  standard error code */
 197 int ext4_mount_point_stats(const char *mount_point,
 198                            struct ext4_mount_stats *stats);
 199
 200 /**@brief   Setup OS lock routines.
 201  * @param   mount_point mount path
 202  * @param   locks - lock and unlock functions
 203  * @return  standard error code */
 204 int ext4_mount_setup_locks(const char *mount_point,
 205                            const struct ext4_lock *locks);
 206
 207 /**@brief   Acquire the filesystem superblock pointer of a mp.
 208  * @param   mount_point mount path
 209  * @param   superblock pointer
 210  * @return  standard error code */
 211 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
 212
 213 /**@brief   Enable/disable write back cache mode.
 214  * @warning Default model of cache is write trough. It means that when You do:
 215  *
 216  *          ext4_fopen(...);
 217  *          ext4_fwrie(...);
 218  *                           < --- data is flushed to physical drive
 219  *
 220  *          When you do:
 221  *          ext4_cache_write_back(..., 1);
 222  *          ext4_fopen(...);
 223  *          ext4_fwrie(...);
 224  *                           < --- data is NOT flushed to physical drive
 225  *          ext4_cache_write_back(..., 0);
 226  *                           < --- when write back mode is disabled all
 227  *                                 cache data will be flushed
 228  * To enable write back mode permanently just call this function
 229  * once after ext4_mount (and disable before ext4_umount).
 230  *
 231  * Some of the function use write back cache mode internally.
 232  * If you enable write back mode twice you have to disable it twice
 233  * to flush all data:
 234  *
 235  *      ext4_cache_write_back(..., 1);
 236  *      ext4_cache_write_back(..., 1);
 237  *
 238  *      ext4_cache_write_back(..., 0);
 239  *      ext4_cache_write_back(..., 0);
 240  *
 241  * Write back mode is useful when you want to create a lot of empty
 242  * files/directories.
 243  *
 244  * @param   path mount point path
 245  * @param   on enable/disable
 246  *
 247  * @return  standard error code */
 248 int ext4_cache_write_back(const char *path, bool on);
 249
 250
 251 /**@brief   Force cache flush.
 252  *
 253  * @param   path mount point path
 254  *
 255  * @return  standard error code */
 256 int ext4_cache_flush(const char *path);
 257
 258 /********************************FILE OPERATIONS*****************************/
 259
 260 /**@brief   Remove file by path.
 261  * @param   path path to file
 262  * @return  standard error code */
 263 int ext4_fremove(const char *path);
 264
 265 /**@brief   create a hardlink for a file.
 266  * @param   path path to file
 267  * @param   hardlink_path path of hardlink
 268  * @return  standard error code */
 269 int ext4_flink(const char *path, const char *hardlink_path);
 270
 271 /**@brief Rename file
 272  * @param path source
 273  * @param new_path destination
 274  * @return  standard error code */
 275 int ext4_frename(const char *path, const char *new_path);
 276
 277 /**@brief   File open function.
 278  * @param   path filename (has to start from mount point)
 279  *          /my_partition/my_file
 280  * @param   flags open file flags
 281  *  |---------------------------------------------------------------|
 282  *  |   r or rb                 O_RDONLY                            |
 283  *  |---------------------------------------------------------------|
 284  *  |   w or wb                 O_WRONLY|O_CREAT|O_TRUNC            |
 285  *  |---------------------------------------------------------------|
 286  *  |   a or ab                 O_WRONLY|O_CREAT|O_APPEND           |
 287  *  |---------------------------------------------------------------|
 288  *  |   r+ or rb+ or r+b        O_RDWR                              |
 289  *  |---------------------------------------------------------------|
 290  *  |   w+ or wb+ or w+b        O_RDWR|O_CREAT|O_TRUNC              |
 291  *  |---------------------------------------------------------------|
 292  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |
 293  *  |---------------------------------------------------------------|
 294  *
 295  * @return  standard error code*/
 296 int ext4_fopen(ext4_file *f, const char *path, const char *flags);
 297
 298 /**@brief   Alternate file open function.
 299  * @param   filename, (has to start from mount point)
 300  *          /my_partition/my_file
 301  * @param   flags open file flags
 302  * @return  standard error code*/
 303 int ext4_fopen2(ext4_file *f, const char *path, int flags);
 304
 305 /**@brief   File close function.
 306  * @param   f file handle
 307  * @return  standard error code*/
 308 int ext4_fclose(ext4_file *f);
 309
 310 /**@brief   Fill in the ext4_inode buffer.
 311  * @param   path fetch inode data of the path
 312  * @param   ret_ino the inode id of the path
 313  * @param   ext4_inode buffer
 314  * @return  standard error code*/
 315 int ext4_fill_raw_inode(const char *path, uint32_t *ret_ino,
 316                         struct ext4_inode *inode);
 317
 318 /**@brief   File truncate function.
 319  * @param   f file handle
 320  * @param   new file size
 321  * @return  standard error code*/
 322 int ext4_ftruncate(ext4_file *f, uint64_t size);
 323
 324 /**@brief   Read data from file.
 325  * @param   f file handle
 326  * @param   buf output buffer
 327  * @param   size bytes to read
 328  * @param   rcnt bytes read (may be NULL)
 329  * @return  standard error code*/
 330 int ext4_fread(ext4_file *f, void *buf, size_t size, size_t *rcnt);
 331
 332 /**@brief   Write data to file.
 333  * @param   f file handle
 334  * @param   buf data to write
 335  * @param   size write length
 336  * @param   wcnt bytes written (may be NULL)
 337  * @return  standard error code*/
 338 int ext4_fwrite(ext4_file *f, const void *buf, size_t size, size_t *wcnt);
 339
 340 /**@brief   File seek operation.
 341  * @param   f file handle
 342  * @param   offset offset to seek
 343  * @param   origin seek type:
 344  *              @ref SEEK_SET
 345  *              @ref SEEK_CUR
 346  *              @ref SEEK_END
 347  * @return  standard error code*/
 348 int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);
 349
 350 /**@brief   Get file position.
 351  * @param   f file handle
 352  * @return  actual file position */
 353 uint64_t ext4_ftell(ext4_file *f);
 354
 355 /**@brief   Get file size.
 356  * @param   f file handle
 357  * @return  file size */
 358 uint64_t ext4_fsize(ext4_file *f);
 359
 360 /**@brief Change file/directory/link mode bits
 361  * @param path to file/dir/link
 362  * @param mode new mode bits (for example 0777)
 363  * @return  standard error code*/
 364 int ext4_mode_set(const char *path, uint32_t mode);
 365
 366
 367 /**@brief Get file/directory/link mode bits
 368  * @param path to file/dir/link
 369  * @param mode new mode bits (for example 0777)
 370  * @return  standard error code*/
 371 int ext4_mode_get(const char *path, uint32_t *mode);
 372
 373 /**@brief Change file owner and group
 374  * @param path to file/dir/link
 375  * @param uid user id
 376  * @param gid group id
 377  * @return  standard error code*/
 378 int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
 379
 380 /**@brief Get file/directory/link owner and group
 381  * @param path to file/dir/link
 382  * @param uid user id
 383  * @param gid group id
 384  * @return  standard error code*/
 385 int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
 386
 387 /**@brief Set file/directory/link access time
 388  * @param path to file/dir/link
 389  * @param atime access timestamp
 390  * @return  standard error code*/
 391 int ext4_atime_set(const char *path, uint32_t atime);
 392
 393 /**@brief Set file/directory/link modify time
 394  * @param path to file/dir/link
 395  * @param mtime modify timestamp
 396  * @return  standard error code*/
 397 int ext4_mtime_set(const char *path, uint32_t mtime);
 398
 399 /**@brief Set file/directory/link change time
 400  * @param path to file/dir/link
 401  * @param ctime change timestamp
 402  * @return  standard error code*/
 403 int ext4_ctime_set(const char *path, uint32_t ctime);
 404
 405 /**@brief Get file/directory/link access time
 406  * @param path to file/dir/link
 407  * @param atime access timestamp
 408  * @return  standard error code*/
 409 int ext4_atime_get(const char *path, uint32_t *atime);
 410
 411 /**@brief Get file/directory/link modify time
 412  * @param path to file/dir/link
 413  * @param mtime modify timestamp
 414  * @return  standard error code*/
 415 int ext4_mtime_get(const char *path, uint32_t *mtime);
 416
 417 /**@brief Get file/directory/link change time
 418  * @param path to file/dir/link
 419  * @param ctime change timestamp
 420  * @return  standard error code*/
 421 int ext4_ctime_get(const char *path, uint32_t *ctime);
 422
 423 /**@brief Create symbolic link
 424  * @param target destination path
 425  * @param path source entry
 426  * @return standard error code*/
 427 int ext4_fsymlink(const char *target, const char *path);
 428
 429 /**@brief Create special file
 430  * @param path path to new file
 431  * @param filetype The filetype of the new special file
 432  *        (that must not be regular file, directory, or unknown type)
 433  * @param dev if filetype is char device or block device,
 434  *        the device number will become the payload in the inode
 435  * @return standard error code*/
 436 int ext4_mknod(const char *path, int filetype, uint32_t dev);
 437
 438 /**@brief Read symbolic link payload
 439  * @param path to symlink
 440  * @param buf output buffer
 441  * @param bufsize output buffer max size
 442  * @param rcnt bytes read
 443  * @return standard error code*/
 444 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
 445
 446 /**@brief Set extended attribute
 447  * @param path to file/directory
 448  * @param name name of the entry to add
 449  * @param name_len length of @name in bytes
 450  * @param data data of the entry to add
 451  * @param data_size size of data to add
 452  * @param replace this boolean is deprecated.
 453  * @return standard error code*/
 454 int ext4_setxattr(const char *path, const char *name, size_t name_len,
 455                   const void *data, size_t data_size, bool replace);
 456
 457 /**@brief Get extended attribute
 458  * @param path to file/directory
 459  * @param name name of the entry to get
 460  * @param name_len length of @name in bytes
 461  * @param data data of the entry to get
 462  * @param data_size size of data to get
 463  * @return standard error code*/
 464 int ext4_getxattr(const char *path, const char *name, size_t name_len,
 465                   void *buf, size_t buf_size, size_t *data_size);
 466
 467 /**@brief List extended attributes
 468  * @param path to file/directory
 469  * @param list list to hold the name of entries
 470  * @param size size of @list in bytes
 471  * @param ret_size used bytes of @list
 472  * @return standard error code*/
 473 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
 474
 475 /**@brief Remove extended attribute
 476  * @param path to file/directory
 477  * @param name name of the entry to remove
 478  * @param name_len length of @name in bytes
 479  * @return standard error code*/
 480 int ext4_removexattr(const char *path, const char *name, size_t name_len);
 481
 482
 483 /*********************************DIRECTORY OPERATION***********************/
 484
 485 /**@brief   Recursive directory remove.
 486  * @param   path directory path to remove
 487  * @return  standard error code*/
 488 int ext4_dir_rm(const char *path);
 489
 490 /**@brief Rename/move directory
 491  * @param path source
 492  * @param new_path destination
 493  * @return  standard error code */
 494 int ext4_dir_mv(const char *path, const char *new_path);
 495
 496 /**@brief   Create new directory.
 497  * @param   name new directory name
 498  * @return  standard error code*/
 499 int ext4_dir_mk(const char *path);
 500
 501 /**@brief   Directory open.
 502  * @param   d directory handle
 503  * @param   path directory path
 504  * @return  standard error code*/
 505 int ext4_dir_open(ext4_dir *d, const char *path);
 506
 507 /**@brief   Directory close.
 508  * @param   d directory handle
 509  * @return  standard error code*/
 510 int ext4_dir_close(ext4_dir *d);
 511
 512 /**@brief   Return next directory entry.
 513  * @param   d directory handle
 514  * @param   id entry id
 515  * @return  directory entry id (NULL if no entry)*/
 516 const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);
 517
 518 /**@brief   Rewine directory entry offset.
 519  * @param   d directory handle*/
 520 void ext4_dir_entry_rewind(ext4_dir *d);
 521
 522
 523 #ifdef __cplusplus
 524 }
 525 #endif
 526
 527 #endif /* EXT4_H_ */
 528
 529 /**
 530  * @}
 531  */