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
42extern "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#include <ext4_journal.h>
56
57/********************************OS LOCK INFERFACE***************************/
58
59/**@brief OS dependent lock interface.*/
60struct ext4_lock {
61
62 /**@brief Lock access to mount point.*/
63 void (*lock)(void);
64
65 /**@brief Unlock access to mount point.*/
66 void (*unlock)(void);
67};
68
69/********************************FILE DESCRIPTOR*****************************/
70
71/**@brief File descriptor. */
72typedef struct ext4_file {
73
74 /**@brief Mount point handle.*/
75 struct ext4_mountpoint *mp;
76
77 /**@brief File inode id.*/
78 uint32_t inode;
79
80 /**@brief Open flags.*/
81 uint32_t flags;
82
83 /**@brief File size.*/
84 uint64_t fsize;
85
86 /**@brief Actual file position.*/
87 uint64_t fpos;
88} ext4_file;
89
90/*****************************DIRECTORY DESCRIPTOR***************************/
91
92/**@brief Directory entry descriptor. */
93typedef struct ext4_direntry {
94 uint32_t inode;
95 uint16_t entry_length;
96 uint8_t name_length;
97 uint8_t inode_type;
98 uint8_t name[255];
99} ext4_direntry;
100
101/**@brief Directory descriptor. */
102typedef struct ext4_dir {
103 /**@brief File descriptor.*/
104 ext4_file f;
105 /**@brief Current directory entry.*/
106 ext4_direntry de;
107 /**@brief Next entry offset.*/
108 uint64_t next_off;
109} ext4_dir;
110
111/********************************MOUNT OPERATIONS****************************/
112
113/**@brief Register block device.
114 *
115 * @param bd Block device.
116 * @param dev_name Block device name.
117 *
118 * @return Standard error code.*/
119int ext4_device_register(struct ext4_blockdev *bd,
120 const char *dev_name);
121
122/**@brief Un-register block device.
123 *
124 * @param dev_name Block device name.
125 *
126 * @return Standard error code.*/
127int ext4_device_unregister(const char *dev_name);
128
129/**@brief Un-register all block devices.
130 *
131 * @return Standard error code.*/
132int ext4_device_unregister_all(void);
133
134/**@brief Mount a block device with EXT4 partition to the mount point.
135 *
136 * @param dev_name Block device name (@ref ext4_device_register).
137 * @param mount_point Mount point, for example:
138 * - /
139 * - /my_partition/
140 * - /my_second_partition/
141 * @param read_only mount as read-only mode.
142 *
143 * @return Standard error code */
144int ext4_mount(const char *dev_name,
145 const char *mount_point,
146 bool read_only);
147
148/**@brief Umount operation.
149 *
150 * @param mount_point Mount point.
151 *
152 * @return Standard error code */
153int ext4_umount(const char *mount_point);
154
155/**@brief Mount point descriptor.*/
156struct ext4_mountpoint {
157
158 /**@brief Mount done flag.*/
159 bool mounted;
160
161 /**@brief Mount point name (@ref ext4_mount)*/
162 char name[CONFIG_EXT4_MAX_MP_NAME + 1];
163
164 /**@brief OS dependent lock/unlock functions.*/
165 const struct ext4_lock *os_locks;
166
167 /**@brief Ext4 filesystem internals.*/
168 struct ext4_fs fs;
169
170 /**@brief JBD fs.*/
171 struct jbd_fs jbd_fs;
172
173 /**@brief Journal.*/
174 struct jbd_journal jbd_journal;
175
176 /**@brief Block cache.*/
177 struct ext4_bcache bc;
178};
179/**@brief Get mountpoint for a path
180 *
181 * @param path Path to file/directory
182 * @return Mountpoint structure, or NULL if not found
183 */
184struct ext4_mountpoint *ext4_get_mount(const char *path);
185
186/**
187 * @brief Link an item to a directory
188 *
189 * @param mp the mountpoint
190 * @param parent parent dir inode ref
191 * @param ch child inode ref
192 * @param n name
193 * @param len length of name
194 * @param rename rename flag
195 * @return int
196 */
197int ext4_link(struct ext4_mountpoint *mp, struct ext4_inode_ref *parent,
198 struct ext4_inode_ref *ch, const char *n,
199 uint32_t len, bool rename);
200
201/**
202 * @brief Unlink an item from a directory
203 *
204 * @param mp the mountpoint
205 * @param parent parent dir inode ref
206 * @param child child inode ref
207 * @param name name
208 * @param name_len length of name
209 * @return int
210 */
211int ext4_unlink(struct ext4_mountpoint *mp,
212 struct ext4_inode_ref *parent,
213 struct ext4_inode_ref *child, const char *name,
214 uint32_t name_len);
215
216
217/**@brief Starts journaling. Journaling start/stop functions are transparent
218 * and might be used on filesystems without journaling support.
219 * @warning Usage:
220 * ext4_mount("sda1", "/");
221 * ext4_journal_start("/");
222 *
223 * //File operations here...
224 *
225 * ext4_journal_stop("/");
226 * ext4_umount("/");
227 * @param mount_point Mount point.
228 *
229 * @return Standard error code. */
230int ext4_journal_start(const char *mount_point);
231
232/**@brief Stops journaling. Journaling start/stop functions are transparent
233 * and might be used on filesystems without journaling support.
234 *
235 * @param mount_point Mount point name.
236 *
237 * @return Standard error code. */
238int ext4_journal_stop(const char *mount_point);
239
240/**@brief Journal recovery.
241 * @warning Must be called after @ref ext4_mount.
242 *
243 * @param mount_point Mount point.
244 *
245 * @return Standard error code. */
246int ext4_recover(const char *mount_point);
247
248/**@brief Some of the filesystem stats. */
249struct ext4_mount_stats {
250 uint32_t inodes_count;
251 uint32_t free_inodes_count;
252 uint64_t blocks_count;
253 uint64_t free_blocks_count;
254
255 uint32_t block_size;
256 uint32_t block_group_count;
257 uint32_t blocks_per_group;
258 uint32_t inodes_per_group;
259
260 char volume_name[16];
261};
262
263/**@brief Get file mount point stats.
264 *
265 * @param mount_point Mount point.
266 * @param stats Filesystem stats.
267 *
268 * @return Standard error code. */
269int ext4_mount_point_stats(const char *mount_point,
270 struct ext4_mount_stats *stats);
271
272/**@brief Setup OS lock routines.
273 *
274 * @param mount_point Mount point.
275 * @param locks Lock and unlock functions
276 *
277 * @return Standard error code. */
278int ext4_mount_setup_locks(const char *mount_point,
279 const struct ext4_lock *locks);
280
281/**@brief Acquire the filesystem superblock pointer of a mp.
282 *
283 * @param mount_point Mount point.
284 * @param sb Superblock handle
285 *
286 * @return Standard error code. */
287int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
288
289/**@brief Enable/disable write back cache mode.
290 * @warning Default model of cache is write trough. It means that when You do:
291 *
292 * ext4_fopen(...);
293 * ext4_fwrite(...);
294 * < --- data is flushed to physical drive
295 *
296 * When you do:
297 * ext4_cache_write_back(..., 1);
298 * ext4_fopen(...);
299 * ext4_fwrite(...);
300 * < --- data is NOT flushed to physical drive
301 * ext4_cache_write_back(..., 0);
302 * < --- when write back mode is disabled all
303 * cache data will be flushed
304 * To enable write back mode permanently just call this function
305 * once after ext4_mount (and disable before ext4_umount).
306 *
307 * Some of the function use write back cache mode internally.
308 * If you enable write back mode twice you have to disable it twice
309 * to flush all data:
310 *
311 * ext4_cache_write_back(..., 1);
312 * ext4_cache_write_back(..., 1);
313 *
314 * ext4_cache_write_back(..., 0);
315 * ext4_cache_write_back(..., 0);
316 *
317 * Write back mode is useful when you want to create a lot of empty
318 * files/directories.
319 *
320 * @param path Mount point.
321 * @param on Enable/disable cache writeback mode.
322 *
323 * @return Standard error code. */
324int ext4_cache_write_back(const char *path, bool on);
325
326
327/**@brief Force cache flush.
328 *
329 * @param path Mount point.
330 *
331 * @return Standard error code. */
332int ext4_cache_flush(const char *path);
333
334/********************************FILE OPERATIONS*****************************/
335
336/**@brief Remove file by path.
337 *
338 * @param path Path to file.
339 *
340 * @return Standard error code. */
341int ext4_fremove(const char *path);
342
343/**@brief Create a hardlink for a file.
344 *
345 * @param path Path to file.
346 * @param hardlink_path Path of hardlink.
347 *
348 * @return Standard error code. */
349int ext4_flink(const char *path, const char *hardlink_path);
350
351/**@brief Rename file.
352 * @param path Source.
353 * @param new_path Destination.
354 * @return Standard error code. */
355int ext4_frename(const char *path, const char *new_path);
356
357/**@brief File open function.
358 *
359 * @param file File handle.
360 * @param path File path, has to start from mount point:/my_partition/file.
361 * @param flags File open flags.
362 * |---------------------------------------------------------------|
363 * | r or rb O_RDONLY |
364 * |---------------------------------------------------------------|
365 * | w or wb O_WRONLY|O_CREAT|O_TRUNC |
366 * |---------------------------------------------------------------|
367 * | a or ab O_WRONLY|O_CREAT|O_APPEND |
368 * |---------------------------------------------------------------|
369 * | r+ or rb+ or r+b O_RDWR |
370 * |---------------------------------------------------------------|
371 * | w+ or wb+ or w+b O_RDWR|O_CREAT|O_TRUNC |
372 * |---------------------------------------------------------------|
373 * | a+ or ab+ or a+b O_RDWR|O_CREAT|O_APPEND |
374 * |---------------------------------------------------------------|
375 *
376 * @return Standard error code.*/
377int ext4_fopen(ext4_file *file, const char *path, const char *flags);
378
379/**@brief Alternate file open function.
380 *
381 * @param file File handle.
382 * @param path File path, has to start from mount point:/my_partition/file.
383 * @param flags File open flags.
384 *
385 * @return Standard error code.*/
386int ext4_fopen2(ext4_file *file, const char *path, int flags);
387
388/**@brief File close function.
389 *
390 * @param file File handle.
391 *
392 * @return Standard error code.*/
393int ext4_fclose(ext4_file *file);
394
395
396/**@brief File truncate function.
397 *
398 * @param file File handle.
399 * @param size New file size.
400 *
401 * @return Standard error code.*/
402int ext4_ftruncate(ext4_file *file, uint64_t size);
403
404/**@brief Read data from file.
405 *
406 * @param file File handle.
407 * @param buf Output buffer.
408 * @param size Bytes to read.
409 * @param rcnt Bytes read (NULL allowed).
410 *
411 * @return Standard error code.*/
412int ext4_fread(ext4_file *file, void *buf, size_t size, size_t *rcnt);
413
414/**@brief Write data to file.
415 *
416 * @param file File handle.
417 * @param buf Data to write
418 * @param size Write length..
419 * @param wcnt Bytes written (NULL allowed).
420 *
421 * @return Standard error code.*/
422int ext4_fwrite(ext4_file *file, const void *buf, size_t size, size_t *wcnt);
423
424/**@brief File seek operation.
425 *
426 * @param file File handle.
427 * @param offset Offset to seek.
428 * @param origin Seek type:
429 * @ref SEEK_SET
430 * @ref SEEK_CUR
431 * @ref SEEK_END
432 *
433 * @return Standard error code.*/
434int ext4_fseek(ext4_file *file, int64_t offset, uint32_t origin);
435
436/**@brief Get file position.
437 *
438 * @param file File handle.
439 *
440 * @return Actual file position */
441uint64_t ext4_ftell(ext4_file *file);
442
443/**@brief Get file size.
444 *
445 * @param file File handle.
446 *
447 * @return File size. */
448uint64_t ext4_fsize(ext4_file *file);
449
450
451/**@brief Get inode of file/directory/link.
452 *
453 * @param path Parh to file/dir/link.
454 * @param ret_ino Inode number.
455 * @param inode Inode internals.
456 *
457 * @return Standard error code.*/
458int ext4_raw_inode_fill(const char *path, uint32_t *ret_ino,
459 struct ext4_inode *inode);
460
461/**@brief Check if inode exists.
462 *
463 * @param path Parh to file/dir/link.
464 * @param type Inode type.
465 * @ref EXT4_DIRENTRY_UNKNOWN
466 * @ref EXT4_DE_REG_FILE
467 * @ref EXT4_DE_DIR
468 * @ref EXT4_DE_CHRDEV
469 * @ref EXT4_DE_BLKDEV
470 * @ref EXT4_DE_FIFO
471 * @ref EXT4_DE_SOCK
472 * @ref EXT4_DE_SYMLINK
473 *
474 * @return Standard error code.*/
475int ext4_inode_exist(const char *path, int type);
476
477/**@brief Change file/directory/link mode bits.
478 *
479 * @param path Path to file/dir/link.
480 * @param mode New mode bits (for example 0777).
481 *
482 * @return Standard error code.*/
483int ext4_mode_set(const char *path, uint32_t mode);
484
485
486/**@brief Get file/directory/link mode bits.
487 *
488 * @param path Path to file/dir/link.
489 * @param mode New mode bits (for example 0777).
490 *
491 * @return Standard error code.*/
492int ext4_mode_get(const char *path, uint32_t *mode);
493
494/**@brief Change file owner and group.
495 *
496 * @param path Path to file/dir/link.
497 * @param uid User id.
498 * @param gid Group id.
499 *
500 * @return Standard error code.*/
501int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
502
503/**@brief Get file/directory/link owner and group.
504 *
505 * @param path Path to file/dir/link.
506 * @param uid User id.
507 * @param gid Group id.
508 *
509 * @return Standard error code.*/
510int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
511
512/**@brief Set file/directory/link access time.
513 *
514 * @param path Path to file/dir/link.
515 * @param atime Access timestamp.
516 *
517 * @return Standard error code.*/
518int ext4_atime_set(const char *path, uint32_t atime);
519
520/**@brief Set file/directory/link modify time.
521 *
522 * @param path Path to file/dir/link.
523 * @param mtime Modify timestamp.
524 *
525 * @return Standard error code.*/
526int ext4_mtime_set(const char *path, uint32_t mtime);
527
528/**@brief Set file/directory/link change time.
529 *
530 * @param path Path to file/dir/link.
531 * @param ctime Change timestamp.
532 *
533 * @return Standard error code.*/
534int ext4_ctime_set(const char *path, uint32_t ctime);
535
536/**@brief Get file/directory/link access time.
537 *
538 * @param path Path to file/dir/link.
539 * @param atime Access timestamp.
540 *
541 * @return Standard error code.*/
542int ext4_atime_get(const char *path, uint32_t *atime);
543
544/**@brief Get file/directory/link modify time.
545 *
546 * @param path Path to file/dir/link.
547 * @param mtime Modify timestamp.
548 *
549 * @return Standard error code.*/
550int ext4_mtime_get(const char *path, uint32_t *mtime);
551
552/**@brief Get file/directory/link change time.
553 *
554 * @param path Pathto file/dir/link.
555 * @param ctime Change timestamp.
556 *
557 * @return standard error code*/
558int ext4_ctime_get(const char *path, uint32_t *ctime);
559
560/**@brief Create symbolic link.
561 *
562 * @param target Destination entry path.
563 * @param path Source entry path.
564 *
565 * @return Standard error code.*/
566int ext4_fsymlink(const char *target, const char *path);
567
568/**@brief Create special file.
569 * @param path Path to new special file.
570 * @param filetype Filetype of the new special file.
571 * (that must not be regular file, directory, or unknown type)
572 * @param dev If filetype is char device or block device,
573 * the device number will become the payload in the inode.
574 * @return Standard error code.*/
575int ext4_mknod(const char *path, int filetype, uint32_t dev);
576
577/**@brief Read symbolic link payload.
578 *
579 * @param path Path to symlink.
580 * @param buf Output buffer.
581 * @param bufsize Output buffer max size.
582 * @param rcnt Bytes read.
583 *
584 * @return Standard error code.*/
585int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
586
587/**@brief Set extended attribute.
588 *
589 * @param path Path to file/directory
590 * @param name Name of the entry to add.
591 * @param name_len Length of @name in bytes.
592 * @param data Data of the entry to add.
593 * @param data_size Size of data to add.
594 *
595 * @return Standard error code.*/
596int ext4_setxattr(const char *path, const char *name, size_t name_len,
597 const void *data, size_t data_size);
598
599/**@brief Get extended attribute.
600 *
601 * @param path Path to file/directory.
602 * @param name Name of the entry to get.
603 * @param name_len Length of @name in bytes.
604 * @param buf Data of the entry to get.
605 * @param buf_size Size of data to get.
606 *
607 * @return Standard error code.*/
608int ext4_getxattr(const char *path, const char *name, size_t name_len,
609 void *buf, size_t buf_size, size_t *data_size);
610
611/**@brief List extended attributes.
612 *
613 * @param path Path to file/directory.
614 * @param list List to hold the name of entries.
615 * @param size Size of @list in bytes.
616 * @param ret_size Used bytes of @list.
617 *
618 * @return Standard error code.*/
619int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
620
621/**@brief Remove extended attribute.
622 *
623 * @param path Path to file/directory.
624 * @param name Name of the entry to remove.
625 * @param name_len Length of @name in bytes.
626 *
627 * @return Standard error code.*/
628int ext4_removexattr(const char *path, const char *name, size_t name_len);
629
630
631/*********************************DIRECTORY OPERATION***********************/
632
633/**@brief Recursive directory remove.
634 *
635 * @param path Directory path to remove
636 *
637 * @return Standard error code.*/
638int ext4_dir_rm(const char *path);
639
640/**@brief Rename/move directory.
641 *
642 * @param path Source path.
643 * @param new_path Destination path.
644 *
645 * @return Standard error code. */
646int ext4_dir_mv(const char *path, const char *new_path);
647
648/**@brief Create new directory.
649 *
650 * @param path Directory name.
651 *
652 * @return Standard error code.*/
653int ext4_dir_mk(const char *path);
654
655/**@brief Directory open.
656 *
657 * @param dir Directory handle.
658 * @param path Directory path.
659 *
660 * @return Standard error code.*/
661int ext4_dir_open(ext4_dir *dir, const char *path);
662
663/**@brief Directory close.
664 *
665 * @param dir directory handle.
666 *
667 * @return Standard error code.*/
668int ext4_dir_close(ext4_dir *dir);
669
670/**@brief Return next directory entry.
671 *
672 * @param dir Directory handle.
673 *
674 * @return Directory entry id (NULL if no entry)*/
675const ext4_direntry *ext4_dir_entry_next(ext4_dir *dir);
676
677/**@brief Rewine directory entry offset.
678 *
679 * @param dir Directory handle.*/
680void ext4_dir_entry_rewind(ext4_dir *dir);
681
682
683#ifdef __cplusplus
684}
685#endif
686
687#endif /* EXT4_H_ */
688
689/**
690 * @}
691 */
692