\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename libext2fs.info
-@settitle The EXT2FS Library (version 1.40.6)
+@settitle The EXT2FS Library (version 1.46.5)
@synindex tp fn
@comment %**end of header
@ifinfo
@dircategory Development
-@format
-START-INFO-DIR-ENTRY
-* libext2fs: (libext2fs.info). The EXT2FS library.
-END-INFO-DIR-ENTRY
-@end format
+@direntry
+* libext2fs: (libext2fs). The EXT2FS library.
+@end direntry
@end ifinfo
@c smallbook
This file documents the ext2fs library, a library for manipulating the
ext2 filesystem.
-Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Theodore Ts'o
+Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 by Theodore Ts'o
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@title The EXT2FS Library
@subtitle The EXT2FS Library
-@subtitle Version 1.40.6
-@subtitle February 2008
+@subtitle Version 1.46.5
+@subtitle December 2021
@author by Theodore Ts'o
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-2005 Theodore Ts'o
+2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Theodore Ts'o
@sp 2
@end titlepage
@headings double
-@ifinfo
@node Top, Introduction to the EXT2FS Library, (dir), (dir)
@top The EXT2FS Library
-This manual documents the EXT2FS Library, version 1.40.6.
-
-@end ifinfo
+This manual documents the EXT2FS Library, version 1.46.5.
@menu
* Introduction to the EXT2FS Library::
@menu
* Filesystem-level functions::
+* File I/O Functions::
* Inode Functions::
* Directory functions::
* Bitmap Functions::
@c ----------------------------------------------------------------------
-@node Filesystem-level functions, Inode Functions, EXT2FS Library Functions, EXT2FS Library Functions
+@node Filesystem-level functions, File I/O Functions, EXT2FS Library Functions, EXT2FS Library Functions
@comment node-name, next, previous, up
@section Filesystem-level functions
@code{ext2fs_open} and @code{ext2fs_initialize}.
The filesystem can also be closed using @code{ext2fs_close}, and any
-changes to the superblock and group descripts can be written out to disk
+changes to the superblock and group descriptors can be written out to disk
using @code{ext2fs_flush}.
@menu
Most libext2fs functions take a filesystem handle of type
@code{ext2_filsys}. A filesystem handle is created either by opening
-an existing function using @code{ext2fs_open}, or by initializing a new
+an existing filesystem using @code{ext2fs_open}, or by initializing a new
filesystem using @code{ext2fs_initialize}.
@deftypefun errcode_t ext2fs_open (const char *@var{name}, int @var{flags}, int @var{superblock}, int @var{block_size}, io_manager @var{manager}, ext2_filsys *@var{ret_fs})
The @var{block_size} parameter specifies the block size used by the
filesystem. Normally this is determined automatically from the
-filesystem uperblock. If @var{block_size} is non-zero, it must match
+filesystem superblock. If @var{block_size} is non-zero, it must match
the block size found in the superblock, or the error
@code{EXT2_ET_UNEXPECTED_BLOCK_SIZE} will be returned. The
-@var{block_size} parameter is also used to help fund the superblock when
+@var{block_size} parameter is also used to help find the superblock when
@var{superblock} is non-zero.
The @var{flags} argument contains a bitmask of flags which control how
to be written when the filesystem is closed or flushed.
@end deftypefun
+@c ----------------------------------------------------------------------
+
+@node File I/O Functions, Inode Functions, Filesystem-level functions, EXT2FS Library Functions
+@comment node-name, next, previous, up
+@section File I/O Functions
+
+The following functions provide a convenient abstraction to read or
+write a file in an filesystem. The interface is similar in spirit to
+the Linux/POSIX file I/O system calls.
+
+@menu
+* File handle manipulation::
+* Reading and writing data::
+* Changing the file offset ::
+* Getting the file size::
+@end menu
+
+@c ----------------------------------------------------------------------
+
+@node File handle manipulation, Reading and writing data, File I/O Functions, File I/O Functions
+@comment node-name, next, previous, up
+@subsection File handle manipulation
+
+The file handle functions much like a file descriptor in the Linux/POSIX
+file I/O system calls. Unlike the Linux/POSIX system calls, files are
+opened via inode numbers instead of via pathnames. To resolve a
+pathname to an inode number, use the function @code{ext2fs_namei} or to
+create a new file, use @code{ext2fs_new_inode} and @code{ext2fs_link}.
+
+@deftypefun errcode_t ext2fs_file_open2 (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, struct ext2_inode *@var{inode}, int @var{flags}, ext2_file_t *@var{ret})
+@deftypefunx errcode_t ext2fs_file_open (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, int @var{flags}, ext2_file_t *@var{ret})
+
+Opens a file identified by inode number @var{ino} in filesystem @var{fs}
+and returns a file handle in @var{ret}. If an inode structure is
+provided in @var{inode}, then it is used instead of reading the inode
+from the filesystem.
+
+The @var{flags} argument contains a bitmask of flags which control how
+the file should be opened.
+
+@table @code
+@item EXT2_FILE_WRITE
+Open the file for reading and writing. Without this flag, the file is
+opened for writing only.
+
+@item EXT2_FILE_CREATE
+Create the file if it is not already present.
+
+@end table
+@end deftypefun
+
+@deftypefun ext2_filsys ext2fs_file_get_fs (ext2_file_t @var{file})
+Return the filesystem handle where the open file @var{file} was opened.
+@end deftypefun
+
+@deftypefun errcode_t ext2fs_file_close (ext2_file_t @var{file})
+Close the file handle @var{file}.
+@end deftypefun
+
+@deftypefun errcode_t ext2fs_file_flush (ext2_file_t @var{file})
+Force any data written via @code{ext2fs_file_write} to disk.
+@end deftypefun
+
+@c ----------------------------------------------------------------------
+
+@node Reading and writing data, Changing the file offset , File handle manipulation, File I/O Functions
+@comment node-name, next, previous, up
+@subsection Reading and writing data
+
+@deftypefun errcode_t ext2fs_file_read (ext2_file_t @var{file}, void *@var{buf}, unsigned int @var{wanted}, unsigned int *@var{got})
+Read @var{wanted} bytes of data from @var{file} store it in the buffer
+@var{buf}. The number of bytes that was actually read is returned
+via @var{got}.
+@end deftypefun
+
+@deftypefun errcode_t ext2fs_file_write (ext2_file_t @var{file}, const void *@var{buf}, unsigned int @var{nbytes}, unsigned int *@var{written})
+Write @var{wanted} bytes of data from the buffer @var{buf} to the
+current file position of @var{file}. The number of bytes that was
+actually written is returned via @var{written}.
+@end deftypefun
+
+@c ----------------------------------------------------------------------
+
+@node Changing the file offset , Getting the file size, Reading and writing data, File I/O Functions
+@comment node-name, next, previous, up
+@subsection Changing the file offset
+
+@deftypefun errcode_t ext2fs_file_llseek (ext2_file_t @var{file}, __u64 @var{offset}, int @var{whence}, __u64 *@var{ret_pos})
+@deftypefunx errcode_t ext2fs_file_lseek (ext2_file_t @var{file}, ext2_off_t @var{offset}, int @var{whence}, ext2_off_t *@var{ret_pos})
+Change the current file position of @var{file} according to the
+directive @var{whence} as follows:
+@table @code
+@item EXT2_SEEK_SET
+The file position is set to @var{offset} bytes from the beginning of the
+file.
+
+@item EXT2_SEEK_CUR
+The file position set to its current location plus @var{offset} bytes.
+
+@item EXT2_SEEK_END
+The file position is set to the size of the file plus @var{offset}
+bytes.
+@end table
+
+The current offset is returned via @var{ret_pos}.
+@end deftypefun
+
+@c ----------------------------------------------------------------------
+
+@node Getting the file size, , Changing the file offset , File I/O Functions
+@comment node-name, next, previous, up
+@subsection Getting the file size
+
+@deftypefun errcode_t ext2fs_file_get_lsize (ext2_file_t @var{file}, __u64 *@var{ret_size})
+Return the size of the file @var{file} in @var{ret_size}.
+@end deftypefun
+
+@deftypefun ext2_off_t ext2fs_file_get_size (ext2_file_t @var{file})
+Return the size of the file @var{file}.
+@end deftypefun
@c ----------------------------------------------------------------------
-@node Inode Functions, Directory functions, Filesystem-level functions, EXT2FS Library Functions
+@node Inode Functions, Directory functions, File I/O Functions, EXT2FS Library Functions
@comment node-name, next, previous, up
@section Inode Functions
@comment node-name, next, previous, up
@subsection Iterating over blocks in an inode
-@deftypefun errcode_t ext2fs_block_iterate (ext2_filsys @var{fs},
-ext2_ino_t @var{ino}, int @var{flags}, char *block_buf, int
-(*func)(ext2_filsys @var{fs}, blk_t *@var{blocknr}, int @var{blockcnt},
-void *@var{private}), void *@var{private})
+@deftypefun errcode_t ext2fs_block_iterate (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, int @var{flags}, char *block_buf, int (*func)(ext2_filsys @var{fs}, blk_t *@var{blocknr}, int @var{blockcnt}, void *@var{private}), void *@var{private})
Iterate over all of the blocks in inode number @var{ino} in filesystem
@var{fs}, by calling the function @var{func} for each block in the
@table @samp
@item BLOCK_FLAG_HOLE
-This flag indiciates that the interator function should be called on
+This flag indicates that the interator function should be called on
blocks where the block number is zero (also known as ``holes''.) It is
also known as BLOCK_FLAG_APPEND, since it is also used by functions
such as ext2fs_expand_dir() to add a new block to an inode.
@item BLOCK_FLAG_DEPTH_TRAVERSE
This flag indicates that the iterator function for the
indirect, doubly indirect, etc. blocks should be called after all
-of the blocks containined in the indirect blocks are processed.
+of the blocks contained in the indirect blocks are processed.
This is useful if you are going to be deallocating blocks from an
inode.
@deftypefun errcode_t ext2fs_block_iterate2 (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, int @var{flags}, char *@var{block}_buf, int (*func)(ext2_filsys @var{fs}, blk_t *@var{blocknr}, e2_blkcnt_t @var{blockcnt}, blk_t @var{ref_blk}, int @var{ref_offset}, void *@var{private}), void *@var{private})
-This function is much like @code{ext2fs_block_iterate2}, except that the
+This function is much like @code{ext2fs_block_iterate}, except that the
@var{blockcnt} type is a 64-bit signed quantity, to support larger
files, and the addition of the @var{ref_blk} and @var{ref_offset}
arguments passed to the callback function, which identify the location
Returns 0 if @var{ino} is a directory, and @code{ENOTDIR} if it is not.
@end deftypefun
-@deftypefun int ext2_inode_has_valid_blocks (struct ext2_inode *@var{inode})
+@deftypefun int ext2fs_inode_has_valid_blocks (struct ext2_inode *@var{inode})
Returns 1 if the inode's block entries actually valid block entries, and
0 if not. Inodes which represent devices and fast symbolic links do not
@deftypefun errcode_t ext2fs_read_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf})
-This function reads a directory block, performing any necessary
+This function reads a directory block, performing
byte swapping if necessary.
@end deftypefun
@deftypefun errcode_t ext2fs_write_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf})
-This function writes a directory block, performing any necessary
+This function writes a directory block, performing
byte swapping if necessary.
@end deftypefun
-@deftypefun errcode_t ext2fs_new_dir_block (ext2_filsys @var{fs},
-ext2_ino_t @var{dir_ino}, ext2_ino_t @var{parent_ino}, char
-**@var{block})
+@deftypefun errcode_t ext2fs_new_dir_block (ext2_filsys @var{fs}, ext2_ino_t @var{dir_ino}, ext2_ino_t @var{parent_ino}, char **@var{block})
This function creates a new directory block in @var{block}. If
-@var{dir_ino} is non-zero, then @var{dir_info} and @var{parent_ino} is used
+@var{dir_ino} is non-zero, then @var{dir_ino} and @var{parent_ino} are used
to initialize directory entries for @file{.} and @file{..}, respectively.
@end deftypefun
@deftypefun errcode_t ext2fs_dir_iterate (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, int @var{flags}, char *@var{block_buf}, int (*@var{func})(struct ext2_dir_entry *@var{dirent}, int @var{offset}, int @var{blocksize}, char *@var{buf}, void *@var{private}), void *@var{private})
-This function interates over all of the directory entries in the
+This function iterates over all of the directory entries in the
directory @var{dir}, calling the callback function @var{func} for each
directory entry in the directory. The @var{block_buf} parameter should
either be NULL, or if the @code{ext2fs_dir_iterate} function is
@deftypefun errcode_t ext2fs_init_dblist (ext2_filsys @var{fs}, ext2_dblist *@var{ret_dblist})
-Creates a dblist data structure and return it in @var{ret_dblist}.
+Creates a dblist data structure and returns it in @var{ret_dblist}.
@end deftypefun
@deftypefun void ext2fs_free_dblist (ext2_dblist @var{dblist})
@deftypefun errcode_t ext2fs_set_dir_block (ext2_dblist @var{dblist}, ext2_ino_t @var{ino}, blk_t @var{blk}, int @var{blockcnt})
Change an entry in the dblist data structure; this changes the location
-of block number @var{blockcnt} of directory indoe @var{ino} to be block
+of block number @var{blockcnt} of directory inode @var{ino} to be block
@var{blk}.
@end deftypefun
This abstraction is designed to be extremely efficient for storing this
sort of information, by taking advantage of the following properties of
inode counts, namely (1) inode counts are very often zero (because
-the inode is currrently not in use), and (2) many files have a inode
+the inode is currently not in use), and (2) many files have a inode
count of 1 (because they are a file which has no additional hard links).
@deftypefun errcode_t ext2fs_create_icount2 (ext2_filsys @var{fs}, int @var{flags}, int @var{size}, ext2_icount_t @var{hint}, ext2_icount_t *@var{ret})
-Creates an icount stucture for a filesystem @var{fs}, with initial space
+Creates an icount structure for a filesystem @var{fs}, with initial space
for @var{size} inodes whose count is greater than 1. The @var{flags}
parameter is either 0 or @code{EXT2_ICOUNT_OPT_INCREMENT}, which
indicates that icount structure should be able to increment inode counts
@deftypefun errcode_t ext2fs_icount_fetch (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 *@var{ret})
-Returns in @var{ret} fetches the count for a particular inode @var{ino}.
+Returns in @var{ret} the count for a particular inode @var{ino}.
@end deftypefun
@deftypefun errcode_t ext2fs_icount_increment (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 *@var{ret})
@deftypefun errcode_t ext2fs_check_desc (ext2_filsys @var{fs})
@end deftypefun
-@deftypefun errcode_t ext2_get_num_dirs (ext2_filsys @var{fs}, ext2_ino_t *@var{ret_num_dirs})
+@deftypefun errcode_t ext2fs_get_num_dirs (ext2_filsys @var{fs}, ext2_ino_t *@var{ret_num_dirs})
@end deftypefun
git://git.whamcloud.com / tools / e2fsprogs.git / blobdiff