X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=doc%2Flibext2fs.texinfo;h=9a66f48f633e1f22a3190478c1d043ef608f0f34;hb=3d66c4b20f09f923078c1e6eb9b549865b549674;hp=88d7bdc5ce860ed2ba0134df86c2f14f3413662e;hpb=d08a4cec6f5c56210e81123d17e8298732c317eb;p=tools%2Fe2fsprogs.git diff --git a/doc/libext2fs.texinfo b/doc/libext2fs.texinfo index 88d7bdc..9a66f48 100644 --- a/doc/libext2fs.texinfo +++ b/doc/libext2fs.texinfo @@ -1,17 +1,15 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename libext2fs.info -@settitle The EXT2FS Library (version 1.25) +@settitle The EXT2FS Library (version 1.43.4) @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 @@ -31,7 +29,8 @@ END-INFO-DIR-ENTRY This file documents the ext2fs library, a library for manipulating the ext2 filesystem. -Copyright (C) 1997, 1998, 1999, 2000, 2001 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 @@ -61,8 +60,8 @@ by the author. @title The EXT2FS Library @subtitle The EXT2FS Library -@subtitle Version 1.25 -@subtitle "September 2001 +@subtitle Version 1.43.4 +@subtitle January 2017 @author by Theodore Ts'o @@ -77,7 +76,8 @@ by the author. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1997, 1998, 1999, 2000, 2001 Theodore Ts'o +Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, +2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Theodore Ts'o @sp 2 @@ -97,14 +97,11 @@ by the Foundation. @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.25. - -@end ifinfo +This manual documents the EXT2FS Library, version 1.43.4. @menu * Introduction to the EXT2FS Library:: @@ -128,6 +125,7 @@ manipulate an ext2 filesystem. @menu * Filesystem-level functions:: +* File I/O Functions:: * Inode Functions:: * Directory functions:: * Bitmap Functions:: @@ -138,7 +136,7 @@ manipulate an ext2 filesystem. @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 @@ -396,11 +394,131 @@ modified. If the flag is set, it will cause the appropriate bitmap 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{got}. +@end deftypefun @c ---------------------------------------------------------------------- -@node Inode Functions, Directory functions, Filesystem-level functions, EXT2FS Library Functions +@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, File I/O Functions, EXT2FS Library Functions @comment node-name, next, previous, up @section Inode Functions @@ -493,9 +611,85 @@ EXT2_ET_MISSING_INODE_TABLE. @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}) + +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 +inode. The @var{block_buf} parameter should either be NULL, or if the +@code{ext2fs_block_iterate} function is called repeatedly, the overhead +of allocating and freeing scratch memory can be avoided by passing a +pointer to a scratch buffer which must be at least as big as three times the +filesystem's blocksize. + +The @var{flags} parameter controls how the iterator will function: + +@table @samp + +@item BLOCK_FLAG_HOLE +This flag indiciates 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. +This is useful if you are going to be deallocating blocks from an +inode. + +@item BLOCK_FLAG_DATA_ONLY +This flag indicates that the iterator function should be +called for data blocks only. + +@end table + +The callback function @var{func} is called with a number of parameters; +the @var{fs} and @var{private} parameters are self-explanatory, and +their values are taken from the parameters to +@code{ext2fs_block_iterate}. (The @var{private} data structure is +generally used by callers to @code{ext2fs_block_iterate} so that some +private data structure can be passed to the callback function. The +@var{blockcnt} parameter, if non-negative, indicates the logical block +number of a data block in the inode. If @var{blockcnt} is less than +zero, then @var{func} was called on a metadata block, and @var{blockcnt} +will be one of the following values: BLOCK_COUNT_IND, BLOCK_COUNT_DIND, +BLOCK_COUNT_TIND, or BLOCK_COUNT_TRANSLATOR. The @var{blocknr} is a +pointer to the inode or indirect block entry listing physical block +number. The callback function may modify the physical block number, if +it returns the @var{BLOCK_CHANGED} flag. + + +The callback function @var{func} returns a result code which is composed of +the logical OR of the following flags: + +@table @samp + +@item BLOCK_CHANGED + +This flag indicates that callback function has modified the physical +block number pointed to by @var{blocknr}. + +@item BLOCK_ABORT + +This flag requests that @code{ext2fs_block_iterate} to stop immediately +and return to the caller. + +@end table + @end deftypefun @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_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 +of the physical block pointed to by pointer @var{blocknr}. If +@var{ref_blk} is zero, then @var{ref_offset} contains the offset into +the @code{i_blocks} array. If @var{ref_blk} is non-zero, then the physical +block location is contained inside an indirect block group, and +@var{ref_offset} contains the offset into the indirect block. + @end deftypefun @c ---------------------------------------------------------------------- @@ -515,7 +709,7 @@ inode structure. 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 @@ -544,12 +738,22 @@ contain valid block entries. @subsection Directory block functions @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 +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 +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 +to initialize directory entries for @file{.} and @file{..}, respectively. @end deftypefun @c ---------------------------------------------------------------------- @@ -559,6 +763,26 @@ contain valid block entries. @subsection Iterating over a directory @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 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 +called repeatedly, the overhead of allocating and freeing +scratch memory can be avoided by passing a pointer to a scratch buffer +which must be at least as big as the filesystem's blocksize. + +The @var{flags} parameter controls how the iterator will function: + +@table @samp + +@item DIRENT_FLAG_INCLUDE_EMPTY + +This flag indicates that the callback function should be called even +for deleted or empty directory entries. + +@end table + @end deftypefun @c ---------------------------------------------------------------------- @@ -568,9 +792,20 @@ contain valid block entries. @subsection Creating and expanding directories @deftypefun errcode_t ext2fs_mkdir (ext2_filsys @var{fs}, ext2_ino_t @var{parent}, ext2_ino_t @var{inum}, const char *@var{name}) + +This function creates a new directory. If @var{inum} is zero, then a +new inode will be allocated; otherwise, the directory will be created in +the inode specified by @var{inum}. If @var{name} specifies the name of +the new directory; if it is non-NULL, then the new directory will be +linked into the parent directory @var{parent}. @end deftypefun @deftypefun errcode_t ext2fs_expand_dir (ext2_filsys @var{fs}, ext2_ino_t @var{dir}) + +This function adds a new empty directory block and appends it to +the directory @var{dir}. This allows functions such as +@code{ext2fs_link} to add new directory entries to a directory which is full. + @end deftypefun @c ---------------------------------------------------------------------- @@ -580,9 +815,61 @@ contain valid block entries. @subsection Creating and removing directory entries @deftypefun errcode_t ext2fs_link (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, const char *@var{name}, ext2_ino_t @var{ino}, int flags) + +This function adds a new directory entry to the directory @var{dir}, +with @var{name} and @var{ino} specifying the name and inode number in +the directory entry, respectively. + +The low 3 bits of the flags field is used to specify the file type of +inode: (No other flags are currently defined.) + +@table @samp + +@item EXT2_FT_UNKNOWN + +The file type is unknown. + +@item EXT2_FT_REG_FILE + +The file type is a normal file. + +@item EXT2_FT_DIR + +The file type is a directory. + +@item EXT2_FT_CHRDEV + +The file type is a character device. + +@item EXT2_FT_BLKDEV + +The file type is a block device. + +@item EXT2_FT_FIFO + +The file type is a named pipe. + +@item EXT2_FT_SOCK + +The file type is a unix domain socket. + +@item EXT2_FT_SYMLINK + +The file type is a symbolic link. +@end table + @end deftypefun @deftypefun errcode_t ext2fs_unlink (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, const char *@var{name}, ext2_ino_t @var{ino}, int @var{flags}) + +This function removes a directory entry from @var{dir}. +The directory entry to be removed is the first one which is +matched by @var{name} and @var{ino}. If @var{name} is non-NULL, +the directory entry's name must match @var{name}. If @var{ino} is +non-zero, the directory entry's inode number must match @var{ino}. +No flags are currently defined for @code{ext2fs_unlink}; callers should +pass in zero to this parameter. + @end deftypefun @c ---------------------------------------------------------------------- @@ -738,7 +1025,7 @@ Return the first inode or block which is stored in the bitmap. @deftypefun blk_t ext2fs_get_block_bitmap_end (ext2fs_block_bitmap @var{bitmap}) @deftypefunx ext2_ino_t ext2fs_get_inode_bitmap_end (ext2fs_inode_bitmap @var{bitmap}) -Return the first inode or block which is stored in the bitmap. +Return the last inode or block which is stored in the bitmap. @end deftypefun @@ -790,9 +1077,16 @@ Return the first inode or block which is stored in the bitmap. @subsection Clearing Bitmaps @deftypefun void ext2fs_clear_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}) + +This function sets all of the bits in the inode bitmap @var{bitmap} to +be zero. + @end deftypefun @deftypefun void ext2fs_clear_block_bitmap (ext2fs_block_bitmap @var{bitmap}) + +This function sets all of the bits in the block bitmap @var{bitmap} to +be zero. @end deftypefun @@ -1011,7 +1305,7 @@ intended for debugging and testing use only. @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 @@ -1050,9 +1344,14 @@ up-to-date ext2 shared library. /* inline functions */ @deftypefun int ext2fs_group_of_blk (ext2_filsys @var{fs}, blk_t @var{blk}) + +This function returns the block group which contains the block @var{blk}. + @end deftypefun @deftypefun int ext2fs_group_of_ino (ext2_filsys @var{fs}, ext2_ino_t @var{ino}) + +This function returns the block group which contains the inode @var{ino}. @end deftypefun