2 * Copyright (c) 2013 Grzegorz Kostka (kostka.grzegorz@gmail.com)
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
29 /** @addtogroup lwext4
34 * @brief Ext4 high level operations (files, directories, mount points...).
35 * Client has to include only this file.
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"
54 #include "ext4_blockdev.h"
56 /********************************OS LOCK INFERFACE***************************/
58 /**@brief OS dependent lock interface.*/
61 /**@brief Lock access to mount point.*/
64 /**@brief Unlock access to mount point.*/
68 /********************************FILE DESCRIPTOR*****************************/
70 /**@brief File descriptor. */
71 typedef struct ext4_file {
73 /**@brief Mount point handle.*/
74 struct ext4_mountpoint *mp;
76 /**@brief File inode id.*/
79 /**@brief Open flags.*/
82 /**@brief File size.*/
85 /**@brief Actual file position.*/
89 /*****************************DIRECTORY DESCRIPTOR***************************/
91 /**@brief Directory entry descriptor. */
92 typedef struct ext4_direntry {
94 uint16_t entry_length;
100 /**@brief Directory descriptor. */
101 typedef struct ext4_dir {
102 /**@brief File descriptor.*/
104 /**@brief Current directory entry.*/
106 /**@brief Next entry offset.*/
110 /********************************MOUNT OPERATIONS****************************/
112 /**@brief Register block device.
114 * @param bd Block device.
115 * @param dev_name Block device name.
117 * @return Standard error code.*/
118 int ext4_device_register(struct ext4_blockdev *bd,
119 const char *dev_name);
121 /**@brief Un-register block device.
123 * @param dev_name Block device name.
125 * @return Standard error code.*/
126 int ext4_device_unregister(const char *dev_name);
128 /**@brief Un-register all block devices.
130 * @return Standard error code.*/
131 int ext4_device_unregister_all(void);
133 /**@brief Mount a block device with EXT4 partition to the mount point.
135 * @param dev_name Block device name (@ref ext4_device_register).
136 * @param mount_point Mount point, for example:
139 * - /my_second_partition/
140 * @param read_only mount as read-only mode.
142 * @return Standard error code */
143 int ext4_mount(const char *dev_name,
144 const char *mount_point,
147 /**@brief Umount operation.
149 * @param mount_pount Mount point.
151 * @return Standard error code */
152 int ext4_umount(const char *mount_point);
154 /**@brief Starts journaling. Journaling start/stop functions are transparent
155 * and might be used on filesystems without journaling support.
157 * ext4_mount("sda1", "/");
158 * ext4_journal_start("/");
160 * //File operations here...
162 * ext4_journal_stop("/");
164 * @param mount_pount Mount point.
166 * @return Standard error code. */
167 int ext4_journal_start(const char *mount_point);
169 /**@brief Stops journaling. Journaling start/stop functions are transparent
170 * and might be used on filesystems without journaling support.
172 * @param mount_pount Mount point name.
174 * @return Standard error code. */
175 int ext4_journal_stop(const char *mount_point);
177 /**@brief Journal recovery.
178 * @warning Must be called after @ref ext4_mount.
180 * @param mount_pount Mount point.
182 * @return Standard error code. */
183 int ext4_recover(const char *mount_point);
185 /**@brief Some of the filesystem stats. */
186 struct ext4_mount_stats {
187 uint32_t inodes_count;
188 uint32_t free_inodes_count;
189 uint64_t blocks_count;
190 uint64_t free_blocks_count;
193 uint32_t block_group_count;
194 uint32_t blocks_per_group;
195 uint32_t inodes_per_group;
197 char volume_name[16];
200 /**@brief Get file mount point stats.
202 * @param mount_pount Mount point.
203 * @param stats Filesystem stats.
205 * @return Standard error code. */
206 int ext4_mount_point_stats(const char *mount_point,
207 struct ext4_mount_stats *stats);
209 /**@brief Setup OS lock routines.
211 * @param mount_pount Mount point.
212 * @param locks Lock and unlock functions
214 * @return Standard error code. */
215 int ext4_mount_setup_locks(const char *mount_point,
216 const struct ext4_lock *locks);
218 /**@brief Acquire the filesystem superblock pointer of a mp.
220 * @param mount_pount Mount point.
221 * @param sb Superblock handle
223 * @return Standard error code. */
224 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
226 /**@brief Enable/disable write back cache mode.
227 * @warning Default model of cache is write trough. It means that when You do:
231 * < --- data is flushed to physical drive
234 * ext4_cache_write_back(..., 1);
237 * < --- data is NOT flushed to physical drive
238 * ext4_cache_write_back(..., 0);
239 * < --- when write back mode is disabled all
240 * cache data will be flushed
241 * To enable write back mode permanently just call this function
242 * once after ext4_mount (and disable before ext4_umount).
244 * Some of the function use write back cache mode internally.
245 * If you enable write back mode twice you have to disable it twice
248 * ext4_cache_write_back(..., 1);
249 * ext4_cache_write_back(..., 1);
251 * ext4_cache_write_back(..., 0);
252 * ext4_cache_write_back(..., 0);
254 * Write back mode is useful when you want to create a lot of empty
257 * @param mount_pount Mount point.
258 * @param on Enable/disable cache writeback mode.
260 * @return Standard error code. */
261 int ext4_cache_write_back(const char *path, bool on);
264 /**@brief Force cache flush.
266 * @param mount_pount Mount point.
268 * @return Standard error code. */
269 int ext4_cache_flush(const char *path);
271 /********************************FILE OPERATIONS*****************************/
273 /**@brief Remove file by path.
275 * @param path Path to file.
277 * @return Standard error code. */
278 int ext4_fremove(const char *path);
280 /**@brief Create a hardlink for a file.
282 * @param path Path to file.
283 * @param hardlink_path Path of hardlink.
285 * @return Standard error code. */
286 int ext4_flink(const char *path, const char *hardlink_path);
288 /**@brief Rename file.
289 * @param path Source.
290 * @param new_path Destination.
291 * @return Standard error code. */
292 int ext4_frename(const char *path, const char *new_path);
294 /**@brief File open function.
296 * @param file File handle.
297 * @param path File path, has to start from mount point:/my_partition/file.
298 * @param flags File open flags.
299 * |---------------------------------------------------------------|
300 * | r or rb O_RDONLY |
301 * |---------------------------------------------------------------|
302 * | w or wb O_WRONLY|O_CREAT|O_TRUNC |
303 * |---------------------------------------------------------------|
304 * | a or ab O_WRONLY|O_CREAT|O_APPEND |
305 * |---------------------------------------------------------------|
306 * | r+ or rb+ or r+b O_RDWR |
307 * |---------------------------------------------------------------|
308 * | w+ or wb+ or w+b O_RDWR|O_CREAT|O_TRUNC |
309 * |---------------------------------------------------------------|
310 * | a+ or ab+ or a+b O_RDWR|O_CREAT|O_APPEND |
311 * |---------------------------------------------------------------|
313 * @return Standard error code.*/
314 int ext4_fopen(ext4_file *file, const char *path, const char *flags);
316 /**@brief Alternate file open function.
318 * @param file File handle.
319 * @param path File path, has to start from mount point:/my_partition/file.
320 * @param flags File open flags.
322 * @return Standard error code.*/
323 int ext4_fopen2(ext4_file *file, const char *path, int flags);
325 /**@brief File close function.
327 * @param file File handle.
329 * @return Standard error code.*/
330 int ext4_fclose(ext4_file *file);
333 /**@brief File truncate function.
335 * @param file File handle.
336 * @param size New file size.
338 * @return Standard error code.*/
339 int ext4_ftruncate(ext4_file *file, uint64_t size);
341 /**@brief Read data from file.
343 * @param file File handle.
344 * @param buf Output buffer.
345 * @param size Bytes to read.
346 * @param rcnt Bytes read (NULL allowed).
348 * @return Standard error code.*/
349 int ext4_fread(ext4_file *file, void *buf, size_t size, size_t *rcnt);
351 /**@brief Write data to file.
353 * @param file File handle.
354 * @param buf Data to write
355 * @param size Write length..
356 * @param wcnt Bytes written (NULL allowed).
358 * @return Standard error code.*/
359 int ext4_fwrite(ext4_file *file, const void *buf, size_t size, size_t *wcnt);
361 /**@brief File seek operation.
363 * @param file File handle.
364 * @param offset Offset to seek.
365 * @param origin Seek type:
370 * @return Standard error code.*/
371 int ext4_fseek(ext4_file *file, uint64_t offset, uint32_t origin);
373 /**@brief Get file position.
375 * @param file File handle.
377 * @return Actual file position */
378 uint64_t ext4_ftell(ext4_file *file);
380 /**@brief Get file size.
382 * @param file File handle.
384 * @return File size. */
385 uint64_t ext4_fsize(ext4_file *file);
388 /**@brief Get inode of file/directory/link.
390 * @param path Parh to file/dir/link.
391 * @param ret_ino Inode number.
392 * @param inode Inode internals.
394 * @return Standard error code.*/
395 int ext4_raw_inode_fill(const char *path, uint32_t *ret_ino,
396 struct ext4_inode *inode);
398 /**@brief Change file/directory/link mode bits.
400 * @param path Path to file/dir/link.
401 * @param mode New mode bits (for example 0777).
403 * @return Standard error code.*/
404 int ext4_mode_set(const char *path, uint32_t mode);
407 /**@brief Get file/directory/link mode bits.
409 * @param path Path to file/dir/link.
410 * @param mode New mode bits (for example 0777).
412 * @return Standard error code.*/
413 int ext4_mode_get(const char *path, uint32_t *mode);
415 /**@brief Change file owner and group.
417 * @param path Path to file/dir/link.
418 * @param uid User id.
419 * @param gid Group id.
421 * @return Standard error code.*/
422 int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
424 /**@brief Get file/directory/link owner and group.
426 * @param path Path to file/dir/link.
427 * @param uid User id.
428 * @param gid Group id.
430 * @return Standard error code.*/
431 int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
433 /**@brief Set file/directory/link access time.
435 * @param path Path to file/dir/link.
436 * @param atime Access timestamp.
438 * @return Standard error code.*/
439 int ext4_atime_set(const char *path, uint32_t atime);
441 /**@brief Set file/directory/link modify time.
443 * @param path Path to file/dir/link.
444 * @param mtime Modify timestamp.
446 * @return Standard error code.*/
447 int ext4_mtime_set(const char *path, uint32_t mtime);
449 /**@brief Set file/directory/link change time.
451 * @param path Path to file/dir/link.
452 * @param ctime Change timestamp.
454 * @return Standard error code.*/
455 int ext4_ctime_set(const char *path, uint32_t ctime);
457 /**@brief Get file/directory/link access time.
459 * @param path Path to file/dir/link.
460 * @param atime Access timestamp.
462 * @return Standard error code.*/
463 int ext4_atime_get(const char *path, uint32_t *atime);
465 /**@brief Get file/directory/link modify time.
467 * @param path Path to file/dir/link.
468 * @param mtime Modify timestamp.
470 * @return Standard error code.*/
471 int ext4_mtime_get(const char *path, uint32_t *mtime);
473 /**@brief Get file/directory/link change time.
475 * @param path Pathto file/dir/link.
476 * @param ctime Change timestamp.
478 * @return standard error code*/
479 int ext4_ctime_get(const char *path, uint32_t *ctime);
481 /**@brief Create symbolic link.
483 * @param target Destination entry path.
484 * @param path Source entry path.
486 * @return Standard error code.*/
487 int ext4_fsymlink(const char *target, const char *path);
489 /**@brief Create special file.
490 * @param path Path to new special file.
491 * @param filetype Filetype of the new special file.
492 * (that must not be regular file, directory, or unknown type)
493 * @param dev If filetype is char device or block device,
494 * the device number will become the payload in the inode.
495 * @return Standard error code.*/
496 int ext4_mknod(const char *path, int filetype, uint32_t dev);
498 /**@brief Read symbolic link payload.
500 * @param path Path to symlink.
501 * @param buf Output buffer.
502 * @param bufsize Output buffer max size.
503 * @param rcnt Bytes read.
505 * @return Standard error code.*/
506 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
508 /**@brief Set extended attribute.
510 * @param path Path to file/directory
511 * @param name Name of the entry to add.
512 * @param name_len Length of @name in bytes.
513 * @param data Data of the entry to add.
514 * @param data_size Size of data to add.
516 * @return Standard error code.*/
517 int ext4_setxattr(const char *path, const char *name, size_t name_len,
518 const void *data, size_t data_size);
520 /**@brief Get extended attribute.
522 * @param path Path to file/directory.
523 * @param name Name of the entry to get.
524 * @param name_len Length of @name in bytes.
525 * @param data Data of the entry to get.
526 * @param data_size Size of data to get.
528 * @return Standard error code.*/
529 int ext4_getxattr(const char *path, const char *name, size_t name_len,
530 void *buf, size_t buf_size, size_t *data_size);
532 /**@brief List extended attributes.
534 * @param path Path to file/directory.
535 * @param list List to hold the name of entries.
536 * @param size Size of @list in bytes.
537 * @param ret_size Used bytes of @list.
539 * @return Standard error code.*/
540 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
542 /**@brief Remove extended attribute.
544 * @param path Path to file/directory.
545 * @param name Name of the entry to remove.
546 * @param name_len Length of @name in bytes.
548 * @return Standard error code.*/
549 int ext4_removexattr(const char *path, const char *name, size_t name_len);
552 /*********************************DIRECTORY OPERATION***********************/
554 /**@brief Recursive directory remove.
556 * @param path Directory path to remove
558 * @return Standard error code.*/
559 int ext4_dir_rm(const char *path);
561 /**@brief Rename/move directory.
563 * @param path Source path.
564 * @param new_path Destination path.
566 * @return Standard error code. */
567 int ext4_dir_mv(const char *path, const char *new_path);
569 /**@brief Create new directory.
571 * @param path Directory name.
573 * @return Standard error code.*/
574 int ext4_dir_mk(const char *path);
576 /**@brief Directory open.
578 * @param dir Directory handle.
579 * @param path Directory path.
581 * @return Standard error code.*/
582 int ext4_dir_open(ext4_dir *dir, const char *path);
584 /**@brief Directory close.
586 * @param dir directory handle.
588 * @return Standard error code.*/
589 int ext4_dir_close(ext4_dir *dir);
591 /**@brief Return next directory entry.
593 * @param dir Directory handle.
595 * @return Directory entry id (NULL if no entry)*/
596 const ext4_direntry *ext4_dir_entry_next(ext4_dir *dir);
598 /**@brief Rewine directory entry offset.
600 * @param dir Directory handle.*/
601 void ext4_dir_entry_rewind(ext4_dir *dir);