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 File position*/
89 /*****************************DIRECTORY DESCRIPTOR***************************/
91 /**@brief Directory entry descriptor. Copy from ext4_types.h*/
92 typedef struct ext4_direntry {
94 uint16_t entry_length;
100 typedef struct ext4_dir {
101 /**@brief File descriptor*/
103 /**@brief Current directory entry.*/
105 /**@brief Next entry offset*/
109 /********************************MOUNT OPERATIONS****************************/
111 /**@brief Register a block device to a name.
112 * @warning Block device has to be filled by
113 * Block cache may by created automatically when bc parameter is NULL.
114 * @param bd block device
115 * @param bd block device cache
116 * @param dev_name register name
117 * @param standard error code*/
118 int ext4_device_register(struct ext4_blockdev *bd, struct ext4_bcache *bc,
119 const char *dev_name);
121 /**@brief Mount a block device with EXT4 partition to the mount point.
122 * @param dev_name block device name (@ref ext4_device_register)
123 * @param mount_point mount point, for example
126 * - /my_second_partition/
127 * @param read_only mount as read-only mode.
129 * @return standard error code */
130 int ext4_mount(const char *dev_name,
131 const char *mount_point,
134 /**@brief Umount operation.
135 * @param mount_point mount name
136 * @return standard error code */
137 int ext4_umount(const char *mount_point);
139 /**@brief Start journaling. Journaling start/stop functions are transparent
140 * and might be used on filesystems without journaling support.
142 * ext4_mount("sda1", "/");
143 * ext4_journal_start("/");
145 * //File operations here...
147 * ext4_journal_stop("/");
149 * @param mount_point mount name
150 * @return standard error code */
151 int ext4_journal_start(const char *mount_point);
153 /**@brief Stop journaling. Journaling start/stop functions are transparent
154 * and might be used on filesystems without journaling support.
155 * @param mount_point mount name
156 * @return standard error code */
157 int ext4_journal_stop(const char *mount_point);
159 /**@brief Journal recovery.
160 * @param mount_point mount point
161 * @warning Must be called after @ref ext4_mount
162 * @return standard error code */
163 int ext4_recover(const char *mount_point);
165 /**@brief Some of the filesystem stats.*/
166 struct ext4_mount_stats {
167 uint32_t inodes_count;
168 uint32_t free_inodes_count;
169 uint64_t blocks_count;
170 uint64_t free_blocks_count;
173 uint32_t block_group_count;
174 uint32_t blocks_per_group;
175 uint32_t inodes_per_group;
177 char volume_name[16];
180 /**@brief Get file system params.
181 * @param mount_point mount path
182 * @param stats ext fs stats
183 * @return standard error code */
184 int ext4_mount_point_stats(const char *mount_point,
185 struct ext4_mount_stats *stats);
187 /**@brief Setup OS lock routines.
188 * @param mount_point mount path
189 * @param locks - lock and unlock functions
190 * @return standard error code */
191 int ext4_mount_setup_locks(const char *mount_point,
192 const struct ext4_lock *locks);
194 /**@brief Acquire the filesystem superblock pointer of a mp.
195 * @param mount_point mount path
196 * @param superblock pointer
197 * @return standard error code */
198 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
200 /**@brief Enable/disable write back cache mode.
201 * @warning Default model of cache is write trough. It means that when You do:
205 * < --- data is flushed to physical drive
208 * ext4_cache_write_back(..., 1);
211 * < --- data is NOT flushed to physical drive
212 * ext4_cache_write_back(..., 0);
213 * < --- when write back mode is disabled all
214 * cache data will be flushed
215 * To enable write back mode permanently just call this function
216 * once after ext4_mount (and disable before ext4_umount).
218 * Some of the function use write back cache mode internally.
219 * If you enable write back mode twice you have to disable it twice
222 * ext4_cache_write_back(..., 1);
223 * ext4_cache_write_back(..., 1);
225 * ext4_cache_write_back(..., 0);
226 * ext4_cache_write_back(..., 0);
228 * Write back mode is useful when you want to create a lot of empty
231 * @param path mount point path
232 * @param on enable/disable
234 * @return standard error code */
235 int ext4_cache_write_back(const char *path, bool on);
238 /**@brief Force cache flush.
240 * @param path mount point path
242 * @return standard error code */
243 int ext4_cache_flush(const char *path);
245 /********************************FILE OPERATIONS*****************************/
247 /**@brief Remove file by path.
248 * @param path path to file
249 * @return standard error code */
250 int ext4_fremove(const char *path);
252 /**@brief create a hardlink for a file.
253 * @param path path to file
254 * @param hardlink_path path of hardlink
255 * @return standard error code */
256 int ext4_flink(const char *path, const char *hardlink_path);
258 /**@brief Rename file
260 * @param new_path destination
261 * @return standard error code */
262 int ext4_frename(const char *path, const char *new_path);
264 /**@brief File open function.
265 * @param path filename (has to start from mount point)
266 * /my_partition/my_file
267 * @param flags open file flags
268 * |---------------------------------------------------------------|
269 * | r or rb O_RDONLY |
270 * |---------------------------------------------------------------|
271 * | w or wb O_WRONLY|O_CREAT|O_TRUNC |
272 * |---------------------------------------------------------------|
273 * | a or ab O_WRONLY|O_CREAT|O_APPEND |
274 * |---------------------------------------------------------------|
275 * | r+ or rb+ or r+b O_RDWR |
276 * |---------------------------------------------------------------|
277 * | w+ or wb+ or w+b O_RDWR|O_CREAT|O_TRUNC |
278 * |---------------------------------------------------------------|
279 * | a+ or ab+ or a+b O_RDWR|O_CREAT|O_APPEND |
280 * |---------------------------------------------------------------|
282 * @return standard error code*/
283 int ext4_fopen(ext4_file *f, const char *path, const char *flags);
285 /**@brief Alternate file open function.
286 * @param filename, (has to start from mount point)
287 * /my_partition/my_file
288 * @param flags open file flags
289 * @return standard error code*/
290 int ext4_fopen2(ext4_file *f, const char *path, int flags);
292 /**@brief File close function.
293 * @param f file handle
294 * @return standard error code*/
295 int ext4_fclose(ext4_file *f);
297 /**@brief Fill in the ext4_inode buffer.
298 * @param path fetch inode data of the path
299 * @param ret_ino the inode id of the path
300 * @param ext4_inode buffer
301 * @return standard error code*/
302 int ext4_fill_raw_inode(const char *path, uint32_t *ret_ino,
303 struct ext4_inode *inode);
305 /**@brief File truncate function.
306 * @param f file handle
307 * @param new file size
308 * @return standard error code*/
309 int ext4_ftruncate(ext4_file *f, uint64_t size);
311 /**@brief Read data from file.
312 * @param f file handle
313 * @param buf output buffer
314 * @param size bytes to read
315 * @param rcnt bytes read (may be NULL)
316 * @return standard error code*/
317 int ext4_fread(ext4_file *f, void *buf, size_t size, size_t *rcnt);
319 /**@brief Write data to file.
320 * @param f file handle
321 * @param buf data to write
322 * @param size write length
323 * @param wcnt bytes written (may be NULL)
324 * @return standard error code*/
325 int ext4_fwrite(ext4_file *f, const void *buf, size_t size, size_t *wcnt);
327 /**@brief File seek operation.
328 * @param f file handle
329 * @param offset offset to seek
330 * @param origin seek type:
334 * @return standard error code*/
335 int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);
337 /**@brief Get file position.
338 * @param f file handle
339 * @return actual file position */
340 uint64_t ext4_ftell(ext4_file *f);
342 /**@brief Get file size.
343 * @param f file handle
344 * @return file size */
345 uint64_t ext4_fsize(ext4_file *f);
347 /**@brief Change file/directory/link mode bits
348 * @param path to file/dir/link
349 * @param mode new mode bits (for example 0777)
350 * @return standard error code*/
351 int ext4_mode_set(const char *path, uint32_t mode);
354 /**@brief Get file/directory/link mode bits
355 * @param path to file/dir/link
356 * @param mode new mode bits (for example 0777)
357 * @return standard error code*/
358 int ext4_mode_get(const char *path, uint32_t *mode);
360 /**@brief Change file owner and group
361 * @param path to file/dir/link
363 * @param gid group id
364 * @return standard error code*/
365 int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
367 /**@brief Get file/directory/link owner and group
368 * @param path to file/dir/link
370 * @param gid group id
371 * @return standard error code*/
372 int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
374 /**@brief Set file/directory/link access time
375 * @param path to file/dir/link
376 * @param atime access timestamp
377 * @return standard error code*/
378 int ext4_atime_set(const char *path, uint32_t atime);
380 /**@brief Set file/directory/link modify time
381 * @param path to file/dir/link
382 * @param mtime modify timestamp
383 * @return standard error code*/
384 int ext4_mtime_set(const char *path, uint32_t mtime);
386 /**@brief Set file/directory/link change time
387 * @param path to file/dir/link
388 * @param ctime change timestamp
389 * @return standard error code*/
390 int ext4_ctime_set(const char *path, uint32_t ctime);
392 /**@brief Get file/directory/link access time
393 * @param path to file/dir/link
394 * @param atime access timestamp
395 * @return standard error code*/
396 int ext4_atime_get(const char *path, uint32_t *atime);
398 /**@brief Get file/directory/link modify time
399 * @param path to file/dir/link
400 * @param mtime modify timestamp
401 * @return standard error code*/
402 int ext4_mtime_get(const char *path, uint32_t *mtime);
404 /**@brief Get file/directory/link change time
405 * @param path to file/dir/link
406 * @param ctime change timestamp
407 * @return standard error code*/
408 int ext4_ctime_get(const char *path, uint32_t *ctime);
410 /**@brief Create symbolic link
411 * @param target destination path
412 * @param path source entry
413 * @return standard error code*/
414 int ext4_fsymlink(const char *target, const char *path);
416 /**@brief Create special file
417 * @param path path to new file
418 * @param filetype The filetype of the new special file
419 * (that must not be regular file, directory, or unknown type)
420 * @param dev if filetype is char device or block device,
421 * the device number will become the payload in the inode
422 * @return standard error code*/
423 int ext4_mknod(const char *path, int filetype, uint32_t dev);
425 /**@brief Read symbolic link payload
426 * @param path to symlink
427 * @param buf output buffer
428 * @param bufsize output buffer max size
429 * @param rcnt bytes read
430 * @return standard error code*/
431 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
433 /**@brief Set extended attribute
434 * @param path to file/directory
435 * @param name name of the entry to add
436 * @param name_len length of @name in bytes
437 * @param data data of the entry to add
438 * @param data_size size of data to add
439 * @param replace this boolean is deprecated.
440 * @return standard error code*/
441 int ext4_setxattr(const char *path, const char *name, size_t name_len,
442 const void *data, size_t data_size, bool replace);
444 /**@brief Get extended attribute
445 * @param path to file/directory
446 * @param name name of the entry to get
447 * @param name_len length of @name in bytes
448 * @param data data of the entry to get
449 * @param data_size size of data to get
450 * @return standard error code*/
451 int ext4_getxattr(const char *path, const char *name, size_t name_len,
452 void *buf, size_t buf_size, size_t *data_size);
454 /**@brief List extended attributes
455 * @param path to file/directory
456 * @param list list to hold the name of entries
457 * @param size size of @list in bytes
458 * @param ret_size used bytes of @list
459 * @return standard error code*/
460 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
462 /**@brief Remove extended attribute
463 * @param path to file/directory
464 * @param name name of the entry to remove
465 * @param name_len length of @name in bytes
466 * @return standard error code*/
467 int ext4_removexattr(const char *path, const char *name, size_t name_len);
470 /*********************************DIRECTORY OPERATION***********************/
472 /**@brief Recursive directory remove.
473 * @param path directory path to remove
474 * @return standard error code*/
475 int ext4_dir_rm(const char *path);
477 /**@brief Rename/move directory
479 * @param new_path destination
480 * @return standard error code */
481 int ext4_dir_mv(const char *path, const char *new_path);
483 /**@brief Create new directory.
484 * @param name new directory name
485 * @return standard error code*/
486 int ext4_dir_mk(const char *path);
488 /**@brief Directory open.
489 * @param d directory handle
490 * @param path directory path
491 * @return standard error code*/
492 int ext4_dir_open(ext4_dir *d, const char *path);
494 /**@brief Directory close.
495 * @param d directory handle
496 * @return standard error code*/
497 int ext4_dir_close(ext4_dir *d);
499 /**@brief Return next directory entry.
500 * @param d directory handle
502 * @return directory entry id (NULL if no entry)*/
503 const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);
505 /**@brief Rewine directory entry offset.
506 * @param d directory handle*/
507 void ext4_dir_entry_rewind(ext4_dir *d);