1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename libext2fs.info 4@settitle The EXT2FS Library (version 1.42.9) 5@synindex tp fn 6@comment %**end of header 7 8@ifinfo 9@dircategory Development 10@direntry 11* libext2fs: (libext2fs). The EXT2FS library. 12@end direntry 13@end ifinfo 14 15@c smallbook 16 17@iftex 18@finalout 19@end iftex 20 21@c Note: the edition number is listed in *three* places; please update 22@c all three. Also, update the month and year where appropriate. 23 24@c ==> Update edition number for settitle and subtitle, and in the 25@c ==> following paragraph; update date, too. 26 27 28@ifinfo 29This file documents the ext2fs library, a library for manipulating the 30ext2 filesystem. 31 32Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 332006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 by Theodore Ts'o 34 35Permission is granted to make and distribute verbatim copies of 36this manual provided the copyright notice and this permission notice 37are preserved on all copies. 38 39@ignore 40Permission is granted to process this file through TeX and print the 41results, provided the printed document carries copying permission 42notice identical to this one except for the removal of this paragraph 43(this paragraph not being relevant to the printed manual). 44 45@end ignore 46Permission is granted to copy and distribute modified versions of this 47manual under the conditions for verbatim copying, provided that the entire 48resulting derived work is distributed under the terms of a permission 49notice identical to this one. 50 51Permission is granted to copy and distribute translations of this manual 52into another language, under the above conditions for modified versions, 53except that this permission notice may be stated in a translation approved 54by the author. 55@end ifinfo 56 57@setchapternewpage on 58@titlepage 59@c use the new format for titles 60 61@title The EXT2FS Library 62@subtitle The EXT2FS Library 63@subtitle Version 1.42.9 64@subtitle December 2013 65 66@author by Theodore Ts'o 67 68@c Include the Distribution inside the titlepage so 69@c that headings are turned off. 70 71@tex 72\global\parindent=0pt 73\global\parskip=8pt 74\global\baselineskip=13pt 75@end tex 76 77@page 78@vskip 0pt plus 1filll 79Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 802005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 Theodore Ts'o 81 82@sp 2 83 84Permission is granted to make and distribute verbatim copies of 85this manual provided the copyright notice and this permission notice 86are preserved on all copies. 87 88Permission is granted to copy and distribute modified versions of this 89manual under the conditions for verbatim copying, provided that the entire 90resulting derived work is distributed under the terms of a permission 91notice identical to this one. 92 93Permission is granted to copy and distribute translations of this manual 94into another language, under the above conditions for modified versions, 95except that this permission notice may be stated in a translation approved 96by the Foundation. 97@end titlepage 98@headings double 99 100@node Top, Introduction to the EXT2FS Library, (dir), (dir) 101 102@top The EXT2FS Library 103 104This manual documents the EXT2FS Library, version 1.42.9. 105 106@menu 107* Introduction to the EXT2FS Library:: 108* EXT2FS Library Functions:: 109* Concept Index:: 110* Function Index:: 111@end menu 112 113@c ---------------------------------------------------------------------- 114 115@node Introduction to the EXT2FS Library, EXT2FS Library Functions, Top, Top 116@comment node-name, next, previous, up 117@chapter Introduction to the EXT2FS Library 118 119The EXT2FS library is designed to allow user-level programs to 120manipulate an ext2 filesystem. 121 122@node EXT2FS Library Functions, Concept Index, Introduction to the EXT2FS Library, Top 123@comment node-name, next, previous, up 124@chapter EXT2FS Library Functions 125 126@menu 127* Filesystem-level functions:: 128* File I/O Functions:: 129* Inode Functions:: 130* Directory functions:: 131* Bitmap Functions:: 132* EXT2 data abstractions:: 133* Byte-swapping functions:: 134* Other functions:: 135@end menu 136 137@c ---------------------------------------------------------------------- 138 139@node Filesystem-level functions, File I/O Functions, EXT2FS Library Functions, EXT2FS Library Functions 140@comment node-name, next, previous, up 141@section Filesystem-level functions 142 143The following functions operate on a filesystem handle. Most EXT2FS 144Library functions require a filesystem handle as their first argument. 145There are two functions which create a filesystem handle, 146@code{ext2fs_open} and @code{ext2fs_initialize}. 147 148The filesystem can also be closed using @code{ext2fs_close}, and any 149changes to the superblock and group descripts can be written out to disk 150using @code{ext2fs_flush}. 151 152@menu 153* Opening an ext2 filesystem:: 154* Closing and flushing out changes:: 155* Initializing a filesystem:: 156* Filesystem flag functions:: 157@end menu 158 159@c ---------------------------------------------------------------------- 160 161@node Opening an ext2 filesystem, Closing and flushing out changes, Filesystem-level functions, Filesystem-level functions 162@comment node-name, next, previous, up 163@subsection Opening an ext2 filesystem 164 165Most libext2fs functions take a filesystem handle of type 166@code{ext2_filsys}. A filesystem handle is created either by opening 167an existing function using @code{ext2fs_open}, or by initializing a new 168filesystem using @code{ext2fs_initialize}. 169 170@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}) 171 172Opens a filesystem named @var{name}, using the the io_manager 173@var{manager} to define the input/output routines needed to read and 174write the filesystem. In the case of the @code{unix_io} io_manager, 175@var{name} is interpreted as the Unix filename of the filesystem image. 176This is often a device file, such as @file{/dev/hda1}. 177 178The @var{superblock} parameter specifies the block number of the 179superblock which should be used when opening the filesystem. 180If @var{superblock} is zero, @code{ext2fs_open} will use the primary 181superblock located at offset 1024 bytes from the start of the filesystem 182image. 183 184The @var{block_size} parameter specifies the block size used by the 185filesystem. Normally this is determined automatically from the 186filesystem uperblock. If @var{block_size} is non-zero, it must match 187the block size found in the superblock, or the error 188@code{EXT2_ET_UNEXPECTED_BLOCK_SIZE} will be returned. The 189@var{block_size} parameter is also used to help fund the superblock when 190@var{superblock} is non-zero. 191 192The @var{flags} argument contains a bitmask of flags which control how 193the filesystem open should be handled. 194 195@table @code 196@item EXT2_FLAG_RW 197Open the filesystem for reading and writing. Without this flag, the 198filesystem is opened for reading only. 199 200@item EXT2_FLAG_FORCE 201Open the filesystem regardless of the feature sets listed in the 202superblock. 203 204@end table 205@end deftypefun 206 207@c ---------------------------------------------------------------------- 208 209@node Closing and flushing out changes, Initializing a filesystem, Opening an ext2 filesystem, Filesystem-level functions 210@comment node-name, next, previous, up 211@subsection Closing and flushing out changes 212 213@deftypefun errcode_t ext2fs_flush (ext2_filsys @var{fs}) 214 215Write any changes to the high-level filesystem data structures in the 216@var{fs} filesystem. The following data structures will be written out: 217 218@itemize @bullet 219@item The filesystem superblock 220@item The filesystem group descriptors 221@item The filesystem bitmaps, if read in via @code{ext2fs_read_bitmaps}. 222@end itemize 223 224@end deftypefun 225 226@deftypefun void ext2fs_free (ext2_filsys @var{fs}) 227 228Close the io_manager abstraction for @var{fs} and release all memory 229associated with the filesystem handle. 230@end deftypefun 231 232@deftypefun errcode_t ext2fs_close (ext2_filsys @var{fs}) 233 234Flush out any changes to the high-level filesystem data structures using 235@code{ext2fs_flush} if the filesystem is marked dirty; then close and 236free the filesystem using @code{ext2fs_free}. 237 238@end deftypefun 239 240@c ---------------------------------------------------------------------- 241 242@node Initializing a filesystem, Filesystem flag functions, Closing and flushing out changes, Filesystem-level functions 243@comment node-name, next, previous, up 244@subsection Initializing a filesystem 245 246An ext2 filesystem is initializing by the @code{mke2fs} program. The 247two functions described here, @code{ext2fs_initialize} and 248@code{ext2fs_allocate_tables} do much of the initial work for setting up 249a filesystem. However, they don't do the whole job. @code{mke2fs} 250calls @code{ext2fs_initialize} to set up the filesystem superblock, and 251calls @code{ext2fs_allocate_tables} to allocate space for the inode 252table, and the inode and block bitmaps. In addition, @code{mke2fs} must 253also initialize the inode tables by clearing them with zeros, create the 254root and lost+found directories, and reserve the reserved inodes. 255 256@deftypefun errcode_t ext2fs_initialize (const char *@var{name}, int @var{flags}, struct ext2_super_block *@var{param}, io_manager @var{manager}, ext2_filsys *@var{ret_fs}) 257 258This function is used by the @code{mke2fs} program to initialize a 259filesystem. The @code{ext2fs_initialize} function creates a filesystem 260handle which is returned in @var{ret_fs} that has been properly setup 261for a filesystem to be located in @var{name}, using the io_manager 262@var{manager}. The prototype superblock in @var{param} is used to 263supply parameters such as the number of blocks in the filesystem, the 264block size, etc. 265 266The @code{ext2fs_initialize} function does not actually do any I/O; that 267will be done when the application program calls @code{ext2fs_close} or 268@code{ext2fs_flush}. Also, this function only initializes the 269superblock and group descriptor structures. It does not create the 270inode table or the root directory. This must be done by the calling 271application, such as @code{mke2fs}. 272 273The following values may be set in the @var{param} prototype superblock; 274if a value of 0 is found in a field, @code{ext2fs_initialize} will use a 275default value. The calling application should zero out the prototype 276entire superblock, and then fill in any appropriate values. 277 278@table @code 279 280@item s_blocks_count 281The number of blocks in the filesystem. This parameter is mandatory and 282must be set by the calling application. 283 284@item s_inodes_count 285The number of inodes in the filesystem. The 286default value is determined by calculating the size of the filesystem, 287and creating one inode for every 4096 bytes. 288 289@item s_r_blocks_count 290The number of blocks which should be reserved for the superuser. The 291default value is zero blocks. 292 293@item s_log_block_size 294The blocksize of the filesystem. Valid values are 0 (1024 bytes), 1 295(2048 bytes), or 2 (4096 bytes). The default blocksize is 1024 bytes. 296 297@item s_log_frag_size 298The size of fragments. The ext2 filesystem does not support fragments 299(and may never support fragments). Currently this field must be the 300same as @code{s_log_block_size}. 301 302@item s_first_data_block 303The first data block for the filesystem. For filesystem with a 304blocksize of 1024 bytes, this value must be at least 1, since the 305superblock is located in block number 1. For filesystems with larger 306blocksizes, the superblock is still located at an offset of 1024 bytes, 307so the superblock is located in block number 0. By default, this value 308is set to 1 for filesystems with a block size of 1024 bytes, or 0 for 309filesystems with larger blocksizes. 310 311@item s_max_mnt_count 312This field defines the number of times that the filesystem can be 313mounted before it should be checked using @code{e2fsck}. When 314@code{e2fsck} is run without the @samp{-f} option, @code{e2fsck} will 315skip the filesystem check if the number of times that the filesystem has 316been mounted is less than @code{s_max_mnt_count} and if the interval 317between the last time a filesystem check was performed and the current 318time is less than @code{s_checkinterval} (see below). The default value 319of @code{s_max_mnt_count} is 20. 320 321@item s_checkinterval 322This field defines the minimal interval between filesystem checks. See 323the previous entry for a discussion of how this field is used by 324@code{e2fsck}. The default value of this field is 180 days (six 325months). 326 327@item s_errors 328This field defines the behavior which should be used by the kernel of 329errors are detected in the filesystem. Possible values include: 330 331@table @samp 332@item EXT2_ERRORS_CONTINUE 333Continue execution when errors are detected. 334 335@item EXT2_ERRORS_RO 336Remount the filesystem read-only. 337 338@item EXT2_ERRORS_PANIC 339Panic. 340 341@end table 342 343The default behavior is @samp{EXT2_ERRORS_CONTINUE}. 344 345@end table 346 347@end deftypefun 348 349@deftypefun errcode_t ext2fs_allocate_tables (ext2_filsys @var{fs}) 350Allocate space for the inode table and the block and inode bitmaps. The 351inode tables and block and inode bitmaps aren't actually initialized; 352this function just allocates the space for them. 353@end deftypefun 354 355@c ---------------------------------------------------------------------- 356 357@node Filesystem flag functions, , Initializing a filesystem, Filesystem-level functions 358@comment node-name, next, previous, up 359@subsection Filesystem flag functions 360 361The filesystem handle has a number of flags which can be manipulated 362using the following function. Some of these flags affect how the 363libext2fs filesystem behaves; others are provided solely for the 364application's convenience. 365 366@deftypefun void ext2fs_mark_changed (ext2_filsys @var{fs}) 367@deftypefunx int ext2fs_test_changed (ext2_filsys @var{fs}) 368This flag indicates whether or not the filesystem has been changed. 369It is not used by the ext2fs library. 370@end deftypefun 371 372@deftypefun void ext2fs_mark_super_dirty (ext2_filsys @var{fs}) 373Mark the filesystem @var{fs} as being dirty; this will cause 374the superblock information to be flushed out when @code{ext2fs_close} is 375called. @code{ext2fs_mark_super_dirty} will also set the filesystem 376changed flag. The dirty flag is automatically cleared by 377@code{ext2fs_flush} when the superblock is written to disk. 378@end deftypefun 379 380@deftypefun void ext2fs_mark_valid (ext2_filsys @var{fs}) 381@deftypefunx void ext2fs_unmark_valid (ext2_filsys @var{fs}) 382@deftypefunx int ext2fs_test_valid (ext2_filsys @var{fs}) 383This flag indicates whether or not the filesystem is free of errors. 384It is not used by libext2fs, and is solely for the application's 385convenience. 386@end deftypefun 387 388@deftypefun void ext2fs_mark_ib_dirty (ext2_filsys @var{fs}) 389@deftypefunx void ext2fs_mark_bb_dirty (ext2_filsys @var{fs}) 390@deftypefunx int ext2fs_test_ib_dirty (ext2_filsys @var{fs}) 391@deftypefunx int ext2fs_test_bb_dirty (ext2_filsys @var{fs}) 392These flags indicate whether or not the inode or block bitmaps have been 393modified. If the flag is set, it will cause the appropriate bitmap 394to be written when the filesystem is closed or flushed. 395@end deftypefun 396 397@c ---------------------------------------------------------------------- 398 399@node File I/O Functions, Inode Functions, Filesystem-level functions, EXT2FS Library Functions 400@comment node-name, next, previous, up 401@section File I/O Functions 402 403The following functions provide a convenient abstraction to read or 404write a file in an filesystem. The interface is similar in spirit to 405the Linux/POSIX file I/O system calls. 406 407@menu 408* File handle manipulation:: 409* Reading and writing data:: 410* Changing the file offset :: 411* Getting the file size:: 412@end menu 413 414@c ---------------------------------------------------------------------- 415 416@node File handle manipulation, Reading and writing data, File I/O Functions, File I/O Functions 417@comment node-name, next, previous, up 418@subsection File handle manipulation 419 420The file handle functions much like a file descriptor in the Linux/POSIX 421file I/O system calls. Unlike the Linux/POSIX system calls, files are 422opened via inode numbers instead of via pathnames. To resolve a 423pathname to an inode number, use the function @code{ext2fs_namei} or to 424create a new file, use @code{ext2fs_new_inode} and @code{ext2fs_link}. 425 426@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}) 427@deftypefunx errcode_t ext2fs_file_open (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, int @var{flags}, ext2_file_t *@var{ret}) 428 429Opens a file identified by inode number @var{ino} in filesystem @var{fs} 430and returns a file handle in @var{ret}. If an inode structure is 431provided in @var{inode}, then it is used instead of reading the inode 432from the filesystem. 433 434The @var{flags} argument contains a bitmask of flags which control how 435the file should be opened. 436 437@table @code 438@item EXT2_FILE_WRITE 439Open the file for reading and writing. Without this flag, the file is 440opened for writing only. 441 442@item EXT2_FILE_CREATE 443Create the file if it is not already present. 444 445@end table 446@end deftypefun 447 448@deftypefun ext2_filsys ext2fs_file_get_fs (ext2_file_t @var{file}) 449Return the filesystem handle where the open file @var{file} was opened. 450@end deftypefun 451 452@deftypefun errcode_t ext2fs_file_close (ext2_file_t @var{file}) 453Close the file handle @var{file}. 454@end deftypefun 455 456@deftypefun errcode_t ext2fs_file_flush (ext2_file_t @var{file}) 457Force any data written via @code{ext2fs_file_write} to disk. 458@end deftypefun 459 460@c ---------------------------------------------------------------------- 461 462@node Reading and writing data, Changing the file offset , File handle manipulation, File I/O Functions 463@comment node-name, next, previous, up 464@subsection Reading and writing data 465 466@deftypefun errcode_t ext2fs_file_read (ext2_file_t @var{file}, void *@var{buf}, unsigned int @var{wanted}, unsigned int *@var{got}) 467Read @var{wanted} bytes of data from @var{file} store it in the buffer 468@var{buf}. The number of bytes that was actually read is returned 469via @var{got}. 470@end deftypefun 471 472@deftypefun errcode_t ext2fs_file_write (ext2_file_t @var{file}, const void *@var{buf}, unsigned int @var{nbytes}, unsigned int *@var{written}) 473Write @var{wanted} bytes of data from the buffer @var{buf} to the 474current file position of @var{file}. The number of bytes that was 475actually written is returned via @var{got}. 476@end deftypefun 477 478@c ---------------------------------------------------------------------- 479 480@node Changing the file offset , Getting the file size, Reading and writing data, File I/O Functions 481@comment node-name, next, previous, up 482@subsection Changing the file offset 483 484@deftypefun errcode_t ext2fs_file_llseek (ext2_file_t @var{file}, __u64 @var{offset}, int @var{whence}, __u64 *@var{ret_pos}) 485@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}) 486Change the current file position of @var{file} according to the 487directive @var{whence} as follows: 488 489@table @code 490@item EXT2_SEEK_SET 491The file position is set to @var{offset} bytes from the beginning of the 492file. 493 494@item EXT2_SEEK_CUR 495The file position set to its current location plus @var{offset} bytes. 496 497@item EXT2_SEEK_END 498The file position is set to the size of the file plus @var{offset} 499bytes. 500@end table 501 502The current offset is returned via @var{ret_pos}. 503@end deftypefun 504 505@c ---------------------------------------------------------------------- 506 507@node Getting the file size, , Changing the file offset , File I/O Functions 508@comment node-name, next, previous, up 509@subsection Getting the file size 510 511@deftypefun errcode_t ext2fs_file_get_lsize (ext2_file_t @var{file}, __u64 *@var{ret_size}) 512Return the size of the file @var{file} in @var{ret_size}. 513@end deftypefun 514 515@deftypefun ext2_off_t ext2fs_file_get_size (ext2_file_t @var{file}) 516Return the size of the file @var{file}. 517@end deftypefun 518 519@c ---------------------------------------------------------------------- 520 521@node Inode Functions, Directory functions, File I/O Functions, EXT2FS Library Functions 522@comment node-name, next, previous, up 523@section Inode Functions 524 525@menu 526* Reading and writing inodes:: 527* Iterating over inodes in a filesystem:: 528* Iterating over blocks in an inode:: 529* Inode Convenience Functions:: 530@end menu 531 532@c ---------------------------------------------------------------------- 533 534@node Reading and writing inodes, Iterating over inodes in a filesystem, Inode Functions, Inode Functions 535@comment node-name, next, previous, up 536@subsection Reading and writing inodes 537 538@deftypefun errcode_t ext2fs_read_inode (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, struct ext2_inode *@var{inode}) 539Read the inode number @var{ino} into @var{inode}. 540@end deftypefun 541 542@deftypefun errcode_t ext2fs_write_inode (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, struct ext2_inode *@var{inode}) 543Write @var{inode} to inode @var{ino}. 544@end deftypefun 545 546 547@c ---------------------------------------------------------------------- 548 549@node Iterating over inodes in a filesystem, Iterating over blocks in an inode, Reading and writing inodes, Inode Functions 550@comment node-name, next, previous, up 551@subsection Iterating over inodes in a filesystem 552 553The inode_scan abstraction is useful for iterating over all the inodes 554in a filesystem. 555 556@deftypefun errcode_t ext2fs_open_inode_scan (ext2_filsys @var{fs}, int @var{buffer_blocks}, ext2_inode_scan *@var{scan}) 557Initialize the iteration variable @var{scan}. This variable is used by 558@code{ext2fs_get_next_inode}. The @var{buffer_blocks} parameter 559controls how many blocks of the inode table are read in at a time. A 560large number of blocks requires more memory, but reduces the overhead in 561seeking and reading from the disk. If @var{buffer_blocks} is zero, a 562suitable default value will be used. 563@end deftypefun 564 565@deftypefun void ext2fs_close_inode_scan (ext2_inode_scan @var{scan}) 566Release the memory associated with @var{scan} and invalidate it. 567@end deftypefun 568 569@deftypefun errcode_t ext2fs_get_next_inode (ext2_inode_scan @var{scan}, ext2_ino_t *@var{ino}, struct ext2_inode *@var{inode}) 570 571This function returns the next inode from the filesystem; the inode 572number of the inode is stored in @var{ino}, and the inode is stored in 573@var{inode}. 574 575If the inode is located in a block that has been marked as bad, 576@code{ext2fs_get_next_inode} will return the error 577@code{EXT2_ET_BAD_BLOCK_IN_INODE_TABLE}. 578@end deftypefun 579 580@deftypefun errcode_t ext2fs_inode_scan_goto_blockgroup (ext2_inode_scan @var{scan}, int @var{group}) 581Start the inode scan at a particular ext2 blockgroup, @var{group}. 582This function may be safely called at any time while @var{scan} is valid. 583@end deftypefun 584 585@deftypefun void ext2fs_set_inode_callback (ext2_inode_scan @var{scan}, errcode_t (*done_group)(ext2_filsys @var{fs}, ext2_inode_scan @var{scan}, dgrp_t @var{group}, void * @var{private}), void *@var{done_group_data}) 586Register a callback function which will be called by 587@code{ext2_get_next_inode} when all of the inodes in a block group have 588been processed. 589@end deftypefun 590 591@deftypefun int ext2fs_inode_scan_flags (ext2_inode_scan @var{scan}, int @var{set_flags}, int @var{clear_flags}) 592 593Set the scan_flags @var{set_flags} and clear the scan_flags @var{clear_flags}. 594The following flags can be set using this interface: 595 596@table @samp 597 598@item EXT2_SF_SKIP_MISSING_ITABLE 599When a block group is missing an inode table, skip it. If this flag is 600not set @code{ext2fs_get_next_inode} will return the error 601EXT2_ET_MISSING_INODE_TABLE. 602 603@end table 604 605@end deftypefun 606 607@c ---------------------------------------------------------------------- 608 609@node Iterating over blocks in an inode, Inode Convenience Functions, Iterating over inodes in a filesystem, Inode Functions 610@comment node-name, next, previous, up 611@subsection Iterating over blocks in an inode 612 613@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}) 614 615Iterate over all of the blocks in inode number @var{ino} in filesystem 616@var{fs}, by calling the function @var{func} for each block in the 617inode. The @var{block_buf} parameter should either be NULL, or if the 618@code{ext2fs_block_iterate} function is called repeatedly, the overhead 619of allocating and freeing scratch memory can be avoided by passing a 620pointer to a scratch buffer which must be at least as big as three times the 621filesystem's blocksize. 622 623The @var{flags} parameter controls how the iterator will function: 624 625@table @samp 626 627@item BLOCK_FLAG_HOLE 628This flag indiciates that the interator function should be called on 629blocks where the block number is zero (also known as ``holes''.) It is 630also known as BLOCK_FLAG_APPEND, since it is also used by functions 631such as ext2fs_expand_dir() to add a new block to an inode. 632 633@item BLOCK_FLAG_DEPTH_TRAVERSE 634This flag indicates that the iterator function for the 635indirect, doubly indirect, etc. blocks should be called after all 636of the blocks containined in the indirect blocks are processed. 637This is useful if you are going to be deallocating blocks from an 638inode. 639 640@item BLOCK_FLAG_DATA_ONLY 641This flag indicates that the iterator function should be 642called for data blocks only. 643 644@end table 645 646The callback function @var{func} is called with a number of parameters; 647the @var{fs} and @var{private} parameters are self-explanatory, and 648their values are taken from the parameters to 649@code{ext2fs_block_iterate}. (The @var{private} data structure is 650generally used by callers to @code{ext2fs_block_iterate} so that some 651private data structure can be passed to the callback function. The 652@var{blockcnt} parameter, if non-negative, indicates the logical block 653number of a data block in the inode. If @var{blockcnt} is less than 654zero, then @var{func} was called on a metadata block, and @var{blockcnt} 655will be one of the following values: BLOCK_COUNT_IND, BLOCK_COUNT_DIND, 656BLOCK_COUNT_TIND, or BLOCK_COUNT_TRANSLATOR. The @var{blocknr} is a 657pointer to the inode or indirect block entry listing physical block 658number. The callback function may modify the physical block number, if 659it returns the @var{BLOCK_CHANGED} flag. 660 661 662The callback function @var{func} returns a result code which is composed of 663the logical OR of the following flags: 664 665@table @samp 666 667@item BLOCK_CHANGED 668 669This flag indicates that callback function has modified the physical 670block number pointed to by @var{blocknr}. 671 672@item BLOCK_ABORT 673 674This flag requests that @code{ext2fs_block_iterate} to stop immediately 675and return to the caller. 676 677@end table 678 679@end deftypefun 680 681@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}) 682 683This function is much like @code{ext2fs_block_iterate}, except that the 684@var{blockcnt} type is a 64-bit signed quantity, to support larger 685files, and the addition of the @var{ref_blk} and @var{ref_offset} 686arguments passed to the callback function, which identify the location 687of the physical block pointed to by pointer @var{blocknr}. If 688@var{ref_blk} is zero, then @var{ref_offset} contains the offset into 689the @code{i_blocks} array. If @var{ref_blk} is non-zero, then the physical 690block location is contained inside an indirect block group, and 691@var{ref_offset} contains the offset into the indirect block. 692 693@end deftypefun 694 695@c ---------------------------------------------------------------------- 696 697@node Inode Convenience Functions, , Iterating over blocks in an inode, Inode Functions 698@comment node-name, next, previous, up 699@subsection Convenience functions for Inodes 700 701@deftypefun errcode_t ext2fs_get_blocks (ext2_filsys @var{fs}, ext2_ino_t @var{ino}, blk_t *@var{blocks}) 702 703Returns an array of blocks corresponding to the direct, 704indirect, doubly indirect, and triply indirect blocks as stored in the 705inode structure. 706@end deftypefun 707 708@deftypefun errcode_t ext2fs_check_directory (ext2_filsys @var{fs}, ext2_ino_t @var{ino}) 709Returns 0 if @var{ino} is a directory, and @code{ENOTDIR} if it is not. 710@end deftypefun 711 712@deftypefun int ext2fs_inode_has_valid_blocks (struct ext2_inode *@var{inode}) 713 714Returns 1 if the inode's block entries actually valid block entries, and 7150 if not. Inodes which represent devices and fast symbolic links do not 716contain valid block entries. 717@end deftypefun 718 719@c ---------------------------------------------------------------------- 720 721@node Directory functions, Bitmap Functions, Inode Functions, EXT2FS Library Functions 722@comment node-name, next, previous, up 723@section Directory functions 724 725@menu 726* Directory block functions:: 727* Iterating over a directory:: 728* Creating and expanding directories:: 729* Creating and removing directory entries:: 730* Looking up filenames:: 731* Translating inode numbers to filenames:: 732@end menu 733 734@c ---------------------------------------------------------------------- 735 736@node Directory block functions, Iterating over a directory, Directory functions, Directory functions 737@comment node-name, next, previous, up 738@subsection Directory block functions 739 740@deftypefun errcode_t ext2fs_read_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf}) 741 742This function reads a directory block, performing any necessary 743byte swapping if necessary. 744@end deftypefun 745 746@deftypefun errcode_t ext2fs_write_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf}) 747 748This function writes a directory block, performing any necessary 749byte swapping if necessary. 750@end deftypefun 751 752@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}) 753 754This function creates a new directory block in @var{block}. If 755@var{dir_ino} is non-zero, then @var{dir_info} and @var{parent_ino} is used 756to initialize directory entries for @file{.} and @file{..}, respectively. 757@end deftypefun 758 759@c ---------------------------------------------------------------------- 760 761@node Iterating over a directory, Creating and expanding directories, Directory block functions, Directory functions 762@comment node-name, next, previous, up 763@subsection Iterating over a directory 764 765@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}) 766 767This function iterates over all of the directory entries in the 768directory @var{dir}, calling the callback function @var{func} for each 769directory entry in the directory. The @var{block_buf} parameter should 770either be NULL, or if the @code{ext2fs_dir_iterate} function is 771called repeatedly, the overhead of allocating and freeing 772scratch memory can be avoided by passing a pointer to a scratch buffer 773which must be at least as big as the filesystem's blocksize. 774 775The @var{flags} parameter controls how the iterator will function: 776 777@table @samp 778 779@item DIRENT_FLAG_INCLUDE_EMPTY 780 781This flag indicates that the callback function should be called even 782for deleted or empty directory entries. 783 784@end table 785 786@end deftypefun 787 788@c ---------------------------------------------------------------------- 789 790@node Creating and expanding directories, Creating and removing directory entries, Iterating over a directory, Directory functions 791@comment node-name, next, previous, up 792@subsection Creating and expanding directories 793 794@deftypefun errcode_t ext2fs_mkdir (ext2_filsys @var{fs}, ext2_ino_t @var{parent}, ext2_ino_t @var{inum}, const char *@var{name}) 795 796This function creates a new directory. If @var{inum} is zero, then a 797new inode will be allocated; otherwise, the directory will be created in 798the inode specified by @var{inum}. If @var{name} specifies the name of 799the new directory; if it is non-NULL, then the new directory will be 800linked into the parent directory @var{parent}. 801@end deftypefun 802 803@deftypefun errcode_t ext2fs_expand_dir (ext2_filsys @var{fs}, ext2_ino_t @var{dir}) 804 805This function adds a new empty directory block and appends it to 806the directory @var{dir}. This allows functions such as 807@code{ext2fs_link} to add new directory entries to a directory which is full. 808 809@end deftypefun 810 811@c ---------------------------------------------------------------------- 812 813@node Creating and removing directory entries, Looking up filenames, Creating and expanding directories, Directory functions 814@comment node-name, next, previous, up 815@subsection Creating and removing directory entries 816 817@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) 818 819This function adds a new directory entry to the directory @var{dir}, 820with @var{name} and @var{ino} specifying the name and inode number in 821the directory entry, respectively. 822 823The low 3 bits of the flags field is used to specify the file type of 824inode: (No other flags are currently defined.) 825 826@table @samp 827 828@item EXT2_FT_UNKNOWN 829 830The file type is unknown. 831 832@item EXT2_FT_REG_FILE 833 834The file type is a normal file. 835 836@item EXT2_FT_DIR 837 838The file type is a directory. 839 840@item EXT2_FT_CHRDEV 841 842The file type is a character device. 843 844@item EXT2_FT_BLKDEV 845 846The file type is a block device. 847 848@item EXT2_FT_FIFO 849 850The file type is a named pipe. 851 852@item EXT2_FT_SOCK 853 854The file type is a unix domain socket. 855 856@item EXT2_FT_SYMLINK 857 858The file type is a symbolic link. 859@end table 860 861@end deftypefun 862 863@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}) 864 865This function removes a directory entry from @var{dir}. 866The directory entry to be removed is the first one which is 867matched by @var{name} and @var{ino}. If @var{name} is non-NULL, 868the directory entry's name must match @var{name}. If @var{ino} is 869non-zero, the directory entry's inode number must match @var{ino}. 870No flags are currently defined for @code{ext2fs_unlink}; callers should 871pass in zero to this parameter. 872 873@end deftypefun 874 875@c ---------------------------------------------------------------------- 876 877@node Looking up filenames, Translating inode numbers to filenames, Creating and removing directory entries, Directory functions 878@comment node-name, next, previous, up 879@subsection Looking up filenames 880 881@deftypefun errcode_t ext2fs_lookup (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, const char *@var{name}, int @var{namelen}, char *@var{buf}, ext2_ino_t *@var{inode}) 882@end deftypefun 883 884@deftypefun errcode_t ext2fs_namei (ext2_filsys @var{fs}, ext2_ino_t @var{root}, ext2_ino_t @var{cwd}, const char *@var{name}, ext2_ino_t *@var{inode}) 885@end deftypefun 886 887@deftypefun errcode_t ext2fs_namei_follow (ext2_filsys @var{fs}, ext2_ino_t @var{root}, ext2_ino_t @var{cwd}, const char *@var{name}, ext2_ino_t *@var{inode}) 888@end deftypefun 889 890@deftypefun errcode_t ext2fs_follow_link (ext2_filsys @var{fs}, ext2_ino_t @var{root}, ext2_ino_t @var{cwd}, ext2_ino_t @var{inode}, ext2_ino_t *@var{res}_inode) 891@end deftypefun 892 893@c ---------------------------------------------------------------------- 894 895@node Translating inode numbers to filenames, , Looking up filenames, Directory functions 896@comment node-name, next, previous, up 897@subsection Translating inode numbers to filenames 898 899@deftypefun errcode_t ext2fs_get_pathname (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, ext2_ino_t @var{ino}, char **@var{name}) 900@end deftypefun 901 902 903@c ---------------------------------------------------------------------- 904 905@node Bitmap Functions, EXT2 data abstractions, Directory functions, EXT2FS Library Functions 906@comment node-name, next, previous, up 907@section Bitmap Functions 908 909@menu 910* Reading and Writing Bitmaps:: 911* Allocating Bitmaps:: 912* Free bitmaps:: 913* Bitmap Operations:: 914* Comparing bitmaps:: 915* Modifying Bitmaps:: 916* Resizing Bitmaps:: 917* Clearing Bitmaps:: 918@end menu 919 920@c ---------------------------------------------------------------------- 921 922@node Reading and Writing Bitmaps, Allocating Bitmaps, Bitmap Functions, Bitmap Functions 923@comment node-name, next, previous, up 924@subsection Reading and Writing Bitmaps 925 926@deftypefun errcode_t ext2fs_write_inode_bitmap (ext2_filsys @var{fs}) 927@end deftypefun 928 929@deftypefun errcode_t ext2fs_write_block_bitmap (ext2_filsys @var{fs}) 930@end deftypefun 931 932@deftypefun errcode_t ext2fs_read_inode_bitmap (ext2_filsys @var{fs}) 933@end deftypefun 934 935@deftypefun errcode_t ext2fs_read_block_bitmap (ext2_filsys @var{fs}) 936@end deftypefun 937 938@deftypefun errcode_t ext2fs_read_bitmaps (ext2_filsys @var{fs}) 939@end deftypefun 940 941@deftypefun errcode_t ext2fs_write_bitmaps (ext2_filsys @var{fs}) 942@end deftypefun 943 944@c ---------------------------------------------------------------------- 945 946@node Allocating Bitmaps, Free bitmaps, Reading and Writing Bitmaps, Bitmap Functions 947@comment node-name, next, previous, up 948@subsection Allocating Bitmaps 949 950@deftypefun errcode_t ext2fs_allocate_generic_bitmap (__u32 @var{start}, __u32 @var{end}, _u32 @var{real_end}, const char *@var{descr}, ext2fs_generic_bitmap *@var{ret}) 951@end deftypefun 952 953@deftypefun errcode_t ext2fs_allocate_block_bitmap (ext2_filsys @var{fs}, const char *@var{descr}, ext2fs_block_bitmap *@var{ret}) 954@end deftypefun 955 956@deftypefun errcode_t ext2fs_allocate_inode_bitmap (ext2_filsys @var{fs}, const char *@var{descr}, ext2fs_inode_bitmap *@var{ret}) 957@end deftypefun 958 959@c ---------------------------------------------------------------------- 960 961@node Free bitmaps, Bitmap Operations, Allocating Bitmaps, Bitmap Functions 962@comment node-name, next, previous, up 963@subsection Freeing bitmaps 964 965 966@deftypefun void ext2fs_free_generic_bitmap (ext2fs_inode_bitmap @var{bitmap}) 967@end deftypefun 968 969@deftypefun void ext2fs_free_block_bitmap (ext2fs_block_bitmap @var{bitmap}) 970@end deftypefun 971 972@deftypefun void ext2fs_free_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}) 973@end deftypefun 974 975 976@c ---------------------------------------------------------------------- 977 978@node Bitmap Operations, Comparing bitmaps, Free bitmaps, Bitmap Functions 979@comment node-name, next, previous, up 980@subsection Bitmap Operations 981 982@deftypefun void ext2fs_mark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 983 984@deftypefunx void ext2fs_unmark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 985 986@deftypefunx int ext2fs_test_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 987 988These functions set, clear, and test bits in a block bitmap @var{bitmap}. 989@end deftypefun 990 991 992@deftypefun void ext2fs_mark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 993 994@deftypefunx void ext2fs_unmark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 995 996@deftypefunx int ext2fs_test_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 997 998These functions set, clear, and test bits in an inode bitmap @var{bitmap}. 999@end deftypefun 1000 1001@deftypefun void ext2fs_fast_mark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 1002 1003@deftypefunx void ext2fs_fast_unmark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 1004 1005@deftypefunx int ext2fs_fast_test_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 1006 1007@deftypefunx void ext2fs_fast_mark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 1008 1009@deftypefunx void ext2fs_fast_unmark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 1010 1011@deftypefunx int ext2fs_fast_test_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{inode}) 1012 1013These ``fast'' functions are like their normal counterparts; however, 1014they are implemented as inline functions and do not perform bounds 1015checks on the inode number or block number; they are assumed to be 1016correct. They should only be used in speed-critical applications, where 1017the inode or block number has already been validated by other means. 1018@end deftypefun 1019 1020@deftypefun blk_t ext2fs_get_block_bitmap_start (ext2fs_block_bitmap @var{bitmap}) 1021@deftypefunx ext2_ino_t ext2fs_get_inode_bitmap_start (ext2fs_inode_bitmap @var{bitmap}) 1022Return the first inode or block which is stored in the bitmap. 1023@end deftypefun 1024 1025@deftypefun blk_t ext2fs_get_block_bitmap_end (ext2fs_block_bitmap @var{bitmap}) 1026@deftypefunx ext2_ino_t ext2fs_get_inode_bitmap_end (ext2fs_inode_bitmap @var{bitmap}) 1027 1028Return the last inode or block which is stored in the bitmap. 1029@end deftypefun 1030 1031 1032@c ---------------------------------------------------------------------- 1033 1034@node Comparing bitmaps, Modifying Bitmaps, Bitmap Operations, Bitmap Functions 1035@comment node-name, next, previous, up 1036@subsection Comparing bitmaps 1037 1038@deftypefun errcode_t ext2fs_compare_block_bitmap (ext2fs_block_bitmap @var{bm1}, ext2fs_block_bitmap @var{bm2}) 1039@end deftypefun 1040 1041@deftypefun errcode_t ext2fs_compare_inode_bitmap (ext2fs_inode_bitmap @var{bm1}, ext2fs_inode_bitmap @var{bm2}) 1042@end deftypefun 1043 1044 1045@c ---------------------------------------------------------------------- 1046 1047@node Modifying Bitmaps, Resizing Bitmaps, Comparing bitmaps, Bitmap Functions 1048@comment node-name, next, previous, up 1049@subsection Modifying Bitmaps 1050 1051@deftypefun errcode_t ext2fs_fudge_inode_bitmap_end (ext2fs_inode_bitmap @var{bitmap}, ext2_ino_t @var{end}, ext2_ino_t *@var{oend}) 1052@end deftypefun 1053 1054@deftypefun errcode_t ext2fs_fudge_block_bitmap_end (ext2fs_block_bitmap @var{bitmap}, blk_t @var{end}, blk_t *@var{oend}) 1055@end deftypefun 1056 1057@c ---------------------------------------------------------------------- 1058 1059@node Resizing Bitmaps, Clearing Bitmaps, Modifying Bitmaps, Bitmap Functions 1060@comment node-name, next, previous, up 1061@subsection Resizing Bitmaps 1062 1063@deftypefun errcode_t ext2fs_resize_generic_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_generic_bitmap @var{bmap}) 1064@end deftypefun 1065 1066@deftypefun errcode_t ext2fs_resize_inode_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_inode_bitmap @var{bmap}) 1067@end deftypefun 1068 1069@deftypefun errcode_t ext2fs_resize_block_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_block_bitmap @var{bmap}) 1070@end deftypefun 1071 1072 1073@c ---------------------------------------------------------------------- 1074 1075@node Clearing Bitmaps, , Resizing Bitmaps, Bitmap Functions 1076@comment node-name, next, previous, up 1077@subsection Clearing Bitmaps 1078 1079@deftypefun void ext2fs_clear_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}) 1080 1081This function sets all of the bits in the inode bitmap @var{bitmap} to 1082be zero. 1083 1084@end deftypefun 1085 1086@deftypefun void ext2fs_clear_block_bitmap (ext2fs_block_bitmap @var{bitmap}) 1087 1088This function sets all of the bits in the block bitmap @var{bitmap} to 1089be zero. 1090@end deftypefun 1091 1092 1093@c ---------------------------------------------------------------------- 1094 1095@node EXT2 data abstractions, Byte-swapping functions, Bitmap Functions, EXT2FS Library Functions 1096@comment node-name, next, previous, up 1097@section EXT2 data abstractions 1098 1099The ext2 library has a number of abstractions which are useful for ext2 1100utility programs. 1101 1102@menu 1103* Badblocks list management:: 1104* Directory-block list management:: 1105* Inode count functions:: 1106@end menu 1107 1108@c ---------------------------------------------------------------------- 1109 1110@node Badblocks list management, Directory-block list management, EXT2 data abstractions, EXT2 data abstractions 1111@comment node-name, next, previous, up 1112@subsection Badblocks list management 1113 1114 1115@deftypefun errcode_t ext2fs_badblocks_list_create (ext2_badblocks_list *@var{ret}, int @var{size}) 1116@end deftypefun 1117 1118@deftypefun void ext2fs_badblocks_list_free (ext2_badblocks_list @var{bb}) 1119@end deftypefun 1120 1121@deftypefun errcode_t ext2fs_badblocks_list_add (ext2_badblocks_list @var{bb}, blk_t @var{blk}) 1122@end deftypefun 1123 1124@deftypefun int ext2fs_badblocks_list_test (ext2_badblocks_list @var{bb}, blk_t @var{blk}) 1125@end deftypefun 1126 1127@deftypefun errcode_t ext2fs_badblocks_list_iterate_begin (ext2_badblocks_list @var{bb}, ext2_badblocks_iterate *@var{ret}) 1128@end deftypefun 1129 1130@deftypefun int ext2fs_badblocks_list_iterate (ext2_badblocks_iterate iter, blk_t *@var{blk}) 1131@end deftypefun 1132 1133@deftypefun void ext2fs_badblocks_list_iterate_end (ext2_badblocks_iterate @var{iter}) 1134@end deftypefun 1135 1136@deftypefun errcode_t ext2fs_update_bb_inode (ext2_filsys @var{fs}, ext2_badblocks_list @var{bb_list}) 1137@end deftypefun 1138 1139@deftypefun errcode_t ext2fs_read_bb_inode (ext2_filsys @var{fs}, ext2_badblocks_list *@var{bb_list}) 1140@end deftypefun 1141 1142@deftypefun errcode_t ext2fs_read_bb_FILE (ext2_filsys @var{fs}, FILE *f, ext2_badblocks_list *@var{bb_list}, void (*invalid)(ext2_filsys @var{fs}, blk_t @var{blk})) 1143@end deftypefun 1144 1145 1146@c ---------------------------------------------------------------------- 1147 1148@node Directory-block list management, Inode count functions, Badblocks list management, EXT2 data abstractions 1149@comment node-name, next, previous, up 1150@subsection Directory-block list management 1151 1152The dblist abstraction stores a list of blocks belonging to 1153directories. This list can be useful when a program needs to interate 1154over all directory entries in a filesystem; @code{e2fsck} does this in 1155pass 2 of its operations, and @code{debugfs} needs to do this when it is 1156trying to turn an inode number into a pathname. 1157 1158@deftypefun errcode_t ext2fs_init_dblist (ext2_filsys @var{fs}, ext2_dblist *@var{ret_dblist}) 1159 1160Creates a dblist data structure and return it in @var{ret_dblist}. 1161@end deftypefun 1162 1163@deftypefun void ext2fs_free_dblist (ext2_dblist @var{dblist}) 1164 1165Free a dblist data structure. 1166@end deftypefun 1167 1168@deftypefun errcode_t ext2fs_add_dir_block (ext2_dblist @var{dblist}, ext2_ino_t @var{ino}, blk_t @var{blk}, int @var{blockcnt}) 1169 1170Add an entry to the dblist data structure. This call records the fact 1171that block number @var{blockcnt} of directory inode @var{ino} is stored 1172in block @var{blk}. 1173@end deftypefun 1174 1175@deftypefun errcode_t ext2fs_set_dir_block (ext2_dblist @var{dblist}, ext2_ino_t @var{ino}, blk_t @var{blk}, int @var{blockcnt}) 1176 1177Change an entry in the dblist data structure; this changes the location 1178of block number @var{blockcnt} of directory indoe @var{ino} to be block 1179@var{blk}. 1180@end deftypefun 1181 1182@deftypefun errcode_t ext2fs_dblist_iterate (ext2_dblist @var{dblist}, int (*func)(ext2_filsys @var{fs}, struct ext2_db_entry *@var{db_info}, void *@var{private}), void *@var{private}) 1183 1184This iterator calls @var{func} for every entry in the dblist data structure. 1185@end deftypefun 1186 1187@deftypefun errcode_t ext2fs_dblist_dir_iterate (ext2_dblist @var{dblist}, int flags, char *@var{block_buf}, int (*func)(ext2_ino_t @var{dir}, int @var{entry}, struct ext2_dir_entry *@var{dirent}, int @var{offset}, int @var{blocksize}, char *@var{buf}, void *@var{private}), void *@var{private}) 1188 1189This iterator takes reads in the directory block indicated in each 1190dblist entry, and calls @var{func} for each directory entry in each 1191directory block. If @var{dblist} contains all the directory blocks in a 1192filesystem, this function provides a convenient way to iterate over all 1193directory entries for that filesystem. 1194@end deftypefun 1195 1196@c ---------------------------------------------------------------------- 1197 1198@node Inode count functions, , Directory-block list management, EXT2 data abstractions 1199@comment node-name, next, previous, up 1200@subsection Inode count functions 1201 1202The icount abstraction is a specialized data type used by @code{e2fsck} 1203to store how many times a particular inode is referenced by the 1204filesystem. This is used twice; once to store the actual number of times 1205that the inode is reference; and once to store the claimed number of times 1206the inode is referenced according to the inode structure. 1207 1208This abstraction is designed to be extremely efficient for storing this 1209sort of information, by taking advantage of the following properties of 1210inode counts, namely (1) inode counts are very often zero (because 1211the inode is currrently not in use), and (2) many files have a inode 1212count of 1 (because they are a file which has no additional hard links). 1213 1214@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}) 1215 1216Creates an icount stucture for a filesystem @var{fs}, with initial space 1217for @var{size} inodes whose count is greater than 1. The @var{flags} 1218parameter is either 0 or @code{EXT2_ICOUNT_OPT_INCREMENT}, which 1219indicates that icount structure should be able to increment inode counts 1220quickly. The icount structure is returned in @var{ret}. The returned 1221icount structure initially has a count of zero for all inodes. 1222 1223The @var{hint} parameter allows the caller to optionally pass in another 1224icount structure which is used to initialize the array of inodes whose 1225count is greater than 1. It is used purely as a speed optimization so 1226that the icount structure can determine in advance which inodes are 1227likely to contain a count grater than 1. 1228@end deftypefun 1229 1230@deftypefun void ext2fs_free_icount (ext2_icount_t @var{icount}) 1231 1232Frees an icount structure. 1233@end deftypefun 1234 1235@deftypefun errcode_t ext2fs_icount_fetch (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 *@var{ret}) 1236 1237Returns in @var{ret} fetches the count for a particular inode @var{ino}. 1238@end deftypefun 1239 1240@deftypefun errcode_t ext2fs_icount_increment (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 *@var{ret}) 1241 1242Increments the ref count for inode @var{ino}. 1243@end deftypefun 1244 1245@deftypefun errcode_t ext2fs_icount_decrement (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 *@var{ret}) 1246 1247Decrements the ref count for inode @var{ino}. 1248@end deftypefun 1249 1250@deftypefun errcode_t ext2fs_icount_store (ext2_icount_t @var{icount}, ext2_ino_t @var{ino}, __u16 @var{count}) 1251 1252Sets the reference count for inode @var{ino} to be @var{count}. 1253@end deftypefun 1254 1255@deftypefun ext2_ino_t ext2fs_get_icount_size (ext2_icount_t @var{icount}) 1256 1257Returns the current number of inodes in @var{icount} which has a count 1258greater than 1. 1259@end deftypefun 1260 1261@deftypefun errcode_t ext2fs_icount_validate (ext2_icount_t @var{icount}, FILE *@var{f}) 1262 1263Validates the internal rep invariant of @var{icount}; if there are any 1264problems, print out debugging information to @var{f}. This function is 1265intended for debugging and testing use only. 1266@end deftypefun 1267 1268 1269@c ---------------------------------------------------------------------- 1270 1271@node Byte-swapping functions, Other functions, EXT2 data abstractions, EXT2FS Library Functions 1272@comment node-name, next, previous, up 1273@section Byte-swapping functions 1274 1275@deftypefun void ext2fs_swap_super (struct ext2_super_block * @var{super}) 1276@end deftypefun 1277 1278@deftypefun void ext2fs_swap_group_desc (struct ext2_group_desc *@var{gdp}) 1279@end deftypefun 1280 1281@deftypefun void ext2fs_swap_inode (ext2_filsys @var{fs}, struct ext2_inode *@var{to}, struct ext2_inode *@var{from}, int @var{hostorder}) 1282@end deftypefun 1283 1284@deftypefun int ext2fs_native_flag (void) 1285@end deftypefun 1286 1287 1288@c ---------------------------------------------------------------------- 1289 1290@node Other functions, , Byte-swapping functions, EXT2FS Library Functions 1291@comment node-name, next, previous, up 1292@section Other functions 1293 1294/* alloc.c */ 1295@deftypefun errcode_t ext2fs_new_inode (ext2_filsys @var{fs}, ext2_ino_t @var{dir}, int @var{mode}, ext2fs_inode_bitmap @var{map}, ext2_ino_t *@var{ret}) 1296@end deftypefun 1297 1298@deftypefun errcode_t ext2fs_new_block (ext2_filsys @var{fs}, blk_t @var{goal}, ext2fs_block_bitmap @var{map}, blk_t *@var{ret}) 1299@end deftypefun 1300 1301@deftypefun errcode_t ext2fs_get_free_blocks (ext2_filsys @var{fs}, blk_t @var{start}, blk_t @var{finish}, int @var{num}, ext2fs_block_bitmap @var{map}, blk_t *@var{ret}) 1302@end deftypefun 1303 1304/* check_desc.c */ 1305@deftypefun errcode_t ext2fs_check_desc (ext2_filsys @var{fs}) 1306@end deftypefun 1307 1308@deftypefun errcode_t ext2fs_get_num_dirs (ext2_filsys @var{fs}, ext2_ino_t *@var{ret_num_dirs}) 1309@end deftypefun 1310 1311 1312/* getsize.c */ 1313@deftypefun errcode_t ext2fs_get_device_size (const char *@var{file}, int @var{blocksize}, blk_t *@var{retblocks}) 1314@end deftypefun 1315 1316 1317/* ismounted.c */ 1318@deftypefun errcode_t ext2fs_check_if_mounted (const char *@var{file}, int *@var{mount_flags}) 1319@end deftypefun 1320 1321/* version.c */ 1322 1323@deftypefun int ext2fs_get_library_version (const char **@var{ver_string}, const char **@var{date_string}) 1324 1325This function returns the current version of the ext2 library. The 1326return value contains an integer version code, which consists of the 1327major version number of the library multiplied by 100, plus the minor 1328version number of the library. Hence, if the library version is 1.08, 1329the returned value will be 108. 1330 1331If @var{ver_string} and/or @var{date_string} are non-NULL, they will be 1332set to point at a constant string containing the library version and/or 1333release date, respectively. 1334@end deftypefun 1335 1336@deftypefun int ext2fs_parse_version_string (const char *@var{ver_string}) 1337 1338This function takes a version string which may included in an 1339application and returns a version code using the same algorithm used by 1340@code{ext2fs_get_library_version}. It can be used by programs included 1341in the @code{e2fsprogs} distribution to assure that they are using an 1342up-to-date ext2 shared library. 1343@end deftypefun 1344 1345/* inline functions */ 1346@deftypefun int ext2fs_group_of_blk (ext2_filsys @var{fs}, blk_t @var{blk}) 1347 1348This function returns the block group which contains the block @var{blk}. 1349 1350@end deftypefun 1351 1352@deftypefun int ext2fs_group_of_ino (ext2_filsys @var{fs}, ext2_ino_t @var{ino}) 1353 1354This function returns the block group which contains the inode @var{ino}. 1355@end deftypefun 1356 1357 1358@c ---------------------------------------------------------------------- 1359 1360@node Concept Index, Function Index, EXT2FS Library Functions, Top 1361@comment node-name, next, previous, up 1362@unnumbered Concept Index 1363@printindex cp 1364 1365@c ---------------------------------------------------------------------- 1366 1367@node Function Index, , Concept Index, Top 1368@comment node-name, next, previous, up 1369@unnumbered Function and Type Index 1370@printindex fn 1371 1372 1373@contents 1374@bye 1375