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