libext2fs.texinfo revision 1e0a221b5d2cb1f82037e469c828c6db772b328e
1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename libext2fs.info 4@settitle The EXT2FS Library (version 1.13) 5@synindex tp fn 6@comment %**end of header 7 8@ifinfo 9@format 10START-INFO-DIR-ENTRY 11* libext2fs: (libext2fs.info). The EXT2FS library. 12END-INFO-DIR-ENTRY 13@end format 14@end ifinfo 15 16@c smallbook 17 18@iftex 19@finalout 20@end iftex 21 22@c Note: the edition number is listed in *three* places; please update 23@c all three. Also, update the month and year where appropriate. 24 25@c ==> Update edition number for settitle and subtitle, and in the 26@c ==> following paragraph; update date, too. 27 28 29@ifinfo 30This file documents the ext2fs library, a library for manipulating the 31ext2 filesystem. 32 33Copyright (C) 1997, 1998 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.13 64@subtitle July 1998 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 Theodore Ts'o 80 81@sp 2 82 83Permission is granted to make and distribute verbatim copies of 84this manual provided the copyright notice and this permission notice 85are preserved on all copies. 86 87Permission is granted to copy and distribute modified versions of this 88manual under the conditions for verbatim copying, provided that the entire 89resulting derived work is distributed under the terms of a permission 90notice identical to this one. 91 92Permission is granted to copy and distribute translations of this manual 93into another language, under the above conditions for modified versions, 94except that this permission notice may be stated in a translation approved 95by the Foundation. 96@end titlepage 97@headings double 98 99@ifinfo 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.13. 105 106@end ifinfo 107 108@menu 109* Introduction to the EXT2FS Library:: 110* EXT2FS Library Functions:: 111* Concept Index:: 112* Function Index:: 113@end menu 114 115@c ---------------------------------------------------------------------- 116 117@node Introduction to the EXT2FS Library, EXT2FS Library Functions, Top, Top 118@comment node-name, next, previous, up 119@chapter Introduction to the EXT2FS Library 120 121The EXT2FS library is designed to allow user-level programs to 122manipulate an ext2 filesystem. 123 124@node EXT2FS Library Functions, Concept Index, Introduction to the EXT2FS Library, Top 125@comment node-name, next, previous, up 126@chapter EXT2FS Library Functions 127 128@menu 129* Filesystem-level functions:: 130* Inode Functions:: 131* Directory functions:: 132* Bitmap Functions:: 133* EXT2 data abstractions:: 134* Byte-swapping functions:: 135* Other functions:: 136@end menu 137 138@c ---------------------------------------------------------------------- 139 140@node Filesystem-level functions, Inode Functions, EXT2FS Library Functions, EXT2FS Library Functions 141@comment node-name, next, previous, up 142@section Filesystem-level functions 143 144The following functions operate on a filesystem handle. Most EXT2FS 145Library functions require a filesystem handle as their first argument. 146There are two functions which create a filesystem handle, 147@code{ext2fs_open} and @code{ext2fs_initialize}. 148 149The filesystem can also be closed using @code{ext2fs_close}, and any 150changes to the superblock and group descripts can be written out to disk 151using @code{ext2fs_flush}. 152 153@menu 154* Opening an ext2 filesystem:: 155* Closing and flushing out changes:: 156* Initializing a filesystem:: 157* Filesystem flag functions:: 158@end menu 159 160@c ---------------------------------------------------------------------- 161 162@node Opening an ext2 filesystem, Closing and flushing out changes, Filesystem-level functions, Filesystem-level functions 163@comment node-name, next, previous, up 164@subsection Opening an ext2 filesystem 165 166Most libext2fs functions take a filesystem handle of type 167@code{ext2_filsys}. A filesystem handle is created either by opening 168an existing function using @code{ext2fs_open}, or by initializing a new 169filesystem using @code{ext2fs_initialize}. 170 171@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}) 172 173Opens a filesystem named @var{name}, using the the io_manager 174@var{manager} to define the input/output routines needed to read and 175write the filesystem. In the case of the @code{unix_io} io_manager, 176@var{name} is interpreted as the Unix filename of the filesystem image. 177This is often a device file, such as @file{/dev/hda1}. 178 179The @var{superblock} parameter specifies the block number of the 180superblock which should be used when opening the filesystem. 181If @var{superblock} is zero, @code{ext2fs_open} will use the primary 182superblock located at offset 1024 bytes from the start of the filesystem 183image. 184 185The @var{block_size} parameter specifies the block size used by the 186filesystem. Normally this is determined automatically from the 187filesystem uperblock. If @var{block_size} is non-zero, it must match 188the block size found in the superblock, or the error 189@code{EXT2_ET_UNEXPECTED_BLOCK_SIZE} will be returned. The 190@var{block_size} parameter is also used to help fund the superblock when 191@var{superblock} is non-zero. 192 193The @var{flags} argument contains a bitmask of flags which control how 194the filesystem open should be handled. 195 196@table @code 197@item EXT2_FLAG_RW 198Open the filesystem for reading and writing. Without this flag, the 199filesystem is opened for reading only. 200 201@item EXT2_FLAG_FORCE 202Open the filesystem regardless of the feature sets listed in the 203superblock. 204 205@end table 206@end deftypefun 207 208@c ---------------------------------------------------------------------- 209 210@node Closing and flushing out changes, Initializing a filesystem, Opening an ext2 filesystem, Filesystem-level functions 211@comment node-name, next, previous, up 212@subsection Closing and flushing out changes 213 214@deftypefun errcode_t ext2fs_flush (ext2_filsys @var{fs}) 215 216Write any changes to the high-level filesystem data structures in the 217@var{fs} filesystem. The following data structures will be written out: 218 219@itemize @bullet 220@item The filesystem superblock 221@item The filesystem group descriptors 222@item The filesystem bitmaps, if read in via @code{ext2fs_read_bitmaps}. 223@end itemize 224 225@end deftypefun 226 227@deftypefun void ext2fs_free (ext2_filsys @var{fs}) 228 229Close the io_manager abstraction for @var{fs} and release all memory 230associated with the filesystem handle. 231@end deftypefun 232 233@deftypefun errcode_t ext2fs_close (ext2_filsys @var{fs}) 234 235Flush out any changes to the high-level filesystem data structures using 236@code{ext2fs_flush} if the filesystem is marked dirty; then close and 237free the filesystem using @code{ext2fs_free}. 238 239@end deftypefun 240 241@c ---------------------------------------------------------------------- 242 243@node Initializing a filesystem, Filesystem flag functions, Closing and flushing out changes, Filesystem-level functions 244@comment node-name, next, previous, up 245@subsection Initializing a filesystem 246 247An ext2 filesystem is initializing by the @code{mke2fs} program. The 248two functions described here, @code{ext2fs_initialize} and 249@code{ext2fs_allocate_tables} do much of the initial work for setting up 250a filesystem. However, they don't do the whole job. @code{mke2fs} 251calls @code{ext2fs_initialize} to set up the filesystem superblock, and 252calls @code{ext2fs_allocate_tables} to allocate space for the inode 253table, and the inode and block bitmaps. In addition, @code{mke2fs} must 254also initialize the inode tables by clearing them with zeros, create the 255root and lost+found directories, and reserve the reserved inodes. 256 257@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}) 258 259This function is used by the @code{mke2fs} program to initialize a 260filesystem. The @code{ext2fs_initialize} function creates a filesystem 261handle which is returned in @var{ret_fs} that has been properly setup 262for a filesystem to be located in @var{name}, using the io_manager 263@var{manager}. The prototype superblock in @var{param} is used to 264supply parameters such as the number of blocks in the filesystem, the 265block size, etc. 266 267The @code{ext2fs_initialize} function does not actually do any I/O; that 268will be done when the application program calls @code{ext2fs_close} or 269@code{ext2fs_flush}. Also, this function only initializes the 270superblock and group descriptor structures. It does not create the 271inode table or the root directory. This must be done by the calling 272application, such as @code{mke2fs}. 273 274The following values may be set in the @var{param} prototype superblock; 275if a value of 0 is found in a field, @code{ext2fs_initialize} will use a 276default value. The calling application should zero out the prototype 277entire superblock, and then fill in any appropriate values. 278 279@table @code 280 281@item s_blocks_count 282The number of blocks in the filesystem. This parameter is mandatory and 283must be set by the calling application. 284 285@item s_inodes_count 286The number of inodes in the filesystem. The 287default value is determined by calculating the size of the filesystem, 288and creating one inode for every 4096 bytes. 289 290@item s_r_blocks_count 291The number of blocks which should be reserved for the superuser. The 292default value is zero blocks. 293 294@item s_log_block_size 295The blocksize of the filesystem. Valid values are 0 (1024 bytes), 1 296(2048 bytes), or 2 (4096 bytes). The default blocksize is 1024 bytes. 297 298@item s_log_frag_size 299The size of fragments. The ext2 filesystem does not support fragments 300(and may never support fragments). Currently this field must be the 301same as @code{s_log_block_size}. 302 303@item s_first_data_block 304The first data block for the filesystem. For filesystem with a 305blocksize of 1024 bytes, this value must be at least 1, since the 306superblock is located in block number 1. For filesystems with larger 307blocksizes, the superblock is still located at an offset of 1024 bytes, 308so the superblock is located in block number 0. By default, this value 309is set to 1 for filesystems with a block size of 1024 bytes, or 0 for 310filesystems with larger blocksizes. 311 312@item s_max_mnt_count 313This field defines the number of times that the filesystem can be 314mounted before it should be checked using @code{e2fsck}. When 315@code{e2fsck} is run without the @samp{-f} option, @code{e2fsck} will 316skip the filesystem check if the number of times that the filesystem has 317been mounted is less than @code{s_max_mnt_count} and if the interval 318between the last time a filesystem check was performed and the current 319time is less than @code{s_checkinterval} (see below). The default value 320of @code{s_max_mnt_count} is 20. 321 322@item s_checkinterval 323This field defines the minimal interval between filesystem checks. See 324the previous entry for a discussion of how this field is used by 325@code{e2fsck}. The default value of this field is 180 days (six 326months). 327 328@item s_errors 329This field defines the behavior which should be used by the kernel of 330errors are detected in the filesystem. Possible values include: 331 332@table @samp 333@item EXT2_ERRORS_CONTINUE 334Continue execution when errors are detected. 335 336@item EXT2_ERRORS_RO 337Remount the filesystem read-only. 338 339@item EXT2_ERRORS_PANIC 340Panic. 341 342@end table 343 344The default behavior is @samp{EXT2_ERRORS_CONTINUE}. 345 346@end table 347 348@end deftypefun 349 350@deftypefun errcode_t ext2fs_allocate_tables (ext2_filsys @var{fs}) 351Allocate space for the inode table and the block and inode bitmaps. The 352inode tables and block and inode bitmaps aren't actually initialized; 353this function just allocates the space for them. 354@end deftypefun 355 356@c ---------------------------------------------------------------------- 357 358@node Filesystem flag functions, , Initializing a filesystem, Filesystem-level functions 359@comment node-name, next, previous, up 360@subsection Filesystem flag functions 361 362The filesystem handle has a number of flags which can be manipulated 363using the following function. Some of these flags affect how the 364libext2fs filesystem behaves; others are provided solely for the 365application's convenience. 366 367@deftypefun void ext2fs_mark_changed (ext2_filsys @var{fs}) 368@deftypefunx int ext2fs_test_changed (ext2_filsys @var{fs}) 369This flag indicates whether or not the filesystem has been changed. 370It is not used by the ext2fs library. 371@end deftypefun 372 373@deftypefun void ext2fs_mark_super_dirty (ext2_filsys @var{fs}) 374Mark the filesystem @var{fs} as being dirty; this will cause 375the superblock information to be flushed out when @code{ext2fs_close} is 376called. @code{ext2fs_mark_super_dirty} will also set the filesystem 377changed flag. The dirty flag is automatically cleared by 378@code{ext2fs_flush} when the superblock is written to disk. 379@end deftypefun 380 381@deftypefun void ext2fs_mark_valid (ext2_filsys @var{fs}) 382@deftypefunx void ext2fs_unmark_valid (ext2_filsys @var{fs}) 383@deftypefunx int ext2fs_test_valid (ext2_filsys @var{fs}) 384This flag indicates whether or not the filesystem is free of errors. 385It is not used by libext2fs, and is solely for the application's 386convenience. 387@end deftypefun 388 389@deftypefun void ext2fs_mark_ib_dirty (ext2_filsys @var{fs}) 390@deftypefunx void ext2fs_mark_bb_dirty (ext2_filsys @var{fs}) 391@deftypefunx int ext2fs_test_ib_dirty (ext2_filsys @var{fs}) 392@deftypefunx int ext2fs_test_bb_dirty (ext2_filsys @var{fs}) 393These flags indicate whether or not the inode or block bitmaps have been 394modified. If the flag is set, it will cause the appropriate bitmap 395to be written when the filesystem is closed or flushed. 396@end deftypefun 397 398 399 400@c ---------------------------------------------------------------------- 401 402@node Inode Functions, Directory functions, Filesystem-level functions, EXT2FS Library Functions 403@comment node-name, next, previous, up 404@section Inode Functions 405 406@menu 407* Reading and writing inodes:: 408* Iterating over inodes in a filesystem:: 409* Iterating over blocks in an inode:: 410* Inode Convenience Functions:: 411@end menu 412 413@c ---------------------------------------------------------------------- 414 415@node Reading and writing inodes, Iterating over inodes in a filesystem, Inode Functions, Inode Functions 416@comment node-name, next, previous, up 417@subsection Reading and writing inodes 418 419@deftypefun errcode_t ext2fs_read_inode (ext2_filsys @var{fs}, ino_t @var{ino}, struct ext2_inode *@var{inode}) 420Read the inode number @var{ino} into @var{inode}. 421@end deftypefun 422 423@deftypefun errcode_t ext2fs_write_inode(ext2_filsys @var{fs}, ino_t @var{ino}, struct ext2_inode *@var{inode}) 424Write @var{inode} to inode @var{ino}. 425@end deftypefun 426 427 428@c ---------------------------------------------------------------------- 429 430@node Iterating over inodes in a filesystem, Iterating over blocks in an inode, Reading and writing inodes, Inode Functions 431@comment node-name, next, previous, up 432@subsection Iterating over inodes in a filesystem 433 434The inode_scan abstraction is useful for iterating over all the inodes 435in a filesystem. 436 437@deftypefun errcode_t ext2fs_open_inode_scan (ext2_filsys @var{fs}, int @var{buffer_blocks}, ext2_inode_scan *@var{scan}) 438Initialize the iteration variable @var{scan}. This variable is used by 439@code{ext2fs_get_next_inode}. The @var{buffer_blocks} parameter 440controls how many blocks of the inode table are read in at a time. A 441large number of blocks requires more memory, but reduces the overhead in 442seeking and reading from the disk. If @var{buffer_blocks} is zero, a 443suitable default value will be used. 444@end deftypefun 445 446@deftypefun void ext2fs_close_inode_scan (ext2_inode_scan @var{scan}) 447Release the memory associated with @var{scan} and invalidate it. 448@end deftypefun 449 450@deftypefun errcode_t ext2fs_get_next_inode (ext2_inode_scan @var{scan}, ino_t *@var{ino}, struct ext2_inode *@var{inode}) 451 452This function returns the next inode from the filesystem; the inode 453number of the inode is stored in @var{ino}, and the inode is stored in 454@var{inode}. 455 456If the inode is located in a block that has been marked as bad, 457@code{ext2fs_get_next_inode} will return the error 458@code{EXT2_ET_BAD_BLOCK_IN_INODE_TABLE}. 459@end deftypefun 460 461@deftypefun errcode_t ext2fs_inode_scan_goto_blockgroup (ext2_inode_scan @var{scan}, int @var{group}) 462Start the inode scan at a particular ext2 blockgroup, @var{group}. 463This function may be safely called at any time while @var{scan} is valid. 464@end deftypefun 465 466@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}) 467Register a callback function which will be called by 468@code{ext2_get_next_inode} when all of the inodes in a block group have 469been processed. 470@end deftypefun 471 472@deftypefun int ext2fs_inode_scan_flags (ext2_inode_scan @var{scan}, int @var{set_flags}, int @var{clear_flags}) 473 474Set the scan_flags @var{set_flags} and clear the scan_flags @var{clear_flags}. 475The following flags can be set using this interface: 476 477@table @samp 478 479@item EXT2_SF_SKIP_MISSING_ITABLE 480When a block group is missing an inode table, skip it. If this flag is 481not set @code{ext2fs_get_next_inode} will return the error 482EXT2_ET_MISSING_INODE_TABLE. 483 484@end table 485 486@end deftypefun 487 488@c ---------------------------------------------------------------------- 489 490@node Iterating over blocks in an inode, Inode Convenience Functions, Iterating over inodes in a filesystem, Inode Functions 491@comment node-name, next, previous, up 492@subsection Iterating over blocks in an inode 493 494@deftypefun errcode_t ext2fs_block_iterate (ext2_filsys @var{fs}, 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}) 495@end deftypefun 496 497@deftypefun errcode_t ext2fs_block_iterate2 (ext2_filsys @var{fs}, 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}) 498@end deftypefun 499 500@c ---------------------------------------------------------------------- 501 502@node Inode Convenience Functions, , Iterating over blocks in an inode, Inode Functions 503@comment node-name, next, previous, up 504@subsection Convenience functions for Inodes 505 506@deftypefun errcode_t ext2fs_get_blocks (ext2_filsys @var{fs}, ino_t @var{ino}, blk_t *@var{blocks}) 507 508Returns an array of blocks corresponding to the direct, 509indirect, doubly indirect, and triply indirect blocks as stored in the 510inode structure. 511@end deftypefun 512 513@deftypefun errcode_t ext2fs_check_directory (ext2_filsys @var{fs}, ino_t @var{ino}) 514Returns 0 if @var{ino} is a directory, and @code{ENOTDIR} if it is not. 515@end deftypefun 516 517@deftypefun int ext2_inode_has_valid_blocks (struct ext2_inode *@var{inode}) 518 519Returns 1 if the inode's block entries actually valid block entries, and 5200 if not. Inodes which represent devices and fast symbolic links do not 521contain valid block entries. 522@end deftypefun 523 524@c ---------------------------------------------------------------------- 525 526@node Directory functions, Bitmap Functions, Inode Functions, EXT2FS Library Functions 527@comment node-name, next, previous, up 528@section Directory functions 529 530@menu 531* Directory block functions:: 532* Iterating over a directory:: 533* Creating and expanding directories:: 534* Creating and removing directory entries:: 535* Looking up filenames:: 536* Translating inode numbers to filenames:: 537@end menu 538 539@c ---------------------------------------------------------------------- 540 541@node Directory block functions, Iterating over a directory, Directory functions, Directory functions 542@comment node-name, next, previous, up 543@subsection Directory block functions 544 545@deftypefun errcode_t ext2fs_read_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf}) 546@end deftypefun 547 548@deftypefun errcode_t ext2fs_write_dir_block (ext2_filsys @var{fs}, blk_t @var{block}, void *@var{buf}) 549@end deftypefun 550 551@deftypefun errcode_t ext2fs_new_dir_block (ext2_filsys @var{fs}, ino_t @var{dir}_ino, ino_t @var{parent_ino}, char **@var{block}) 552@end deftypefun 553 554@c ---------------------------------------------------------------------- 555 556@node Iterating over a directory, Creating and expanding directories, Directory block functions, Directory functions 557@comment node-name, next, previous, up 558@subsection Iterating over a directory 559 560@deftypefun errcode_t ext2fs_dir_iterate (ext2_filsys @var{fs}, 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}) 561@end deftypefun 562 563@c ---------------------------------------------------------------------- 564 565@node Creating and expanding directories, Creating and removing directory entries, Iterating over a directory, Directory functions 566@comment node-name, next, previous, up 567@subsection Creating and expanding directories 568 569@deftypefun errcode_t ext2fs_mkdir (ext2_filsys @var{fs}, ino_t @var{parent}, ino_t @var{inum}, const char *@var{name}) 570@end deftypefun 571 572@deftypefun errcode_t ext2fs_expand_dir (ext2_filsys @var{fs}, ino_t @var{dir}) 573@end deftypefun 574 575@c ---------------------------------------------------------------------- 576 577@node Creating and removing directory entries, Looking up filenames, Creating and expanding directories, Directory functions 578@comment node-name, next, previous, up 579@subsection Creating and removing directory entries 580 581@deftypefun errcode_t ext2fs_link (ext2_filsys @var{fs}, ino_t @var{dir}, const char *@var{name}, ino_t @var{ino}, int flags) 582@end deftypefun 583 584@deftypefun errcode_t ext2fs_unlink (ext2_filsys @var{fs}, ino_t @var{dir}, const char *@var{name}, ino_t @var{ino}, int @var{flags}) 585@end deftypefun 586 587@c ---------------------------------------------------------------------- 588 589@node Looking up filenames, Translating inode numbers to filenames, Creating and removing directory entries, Directory functions 590@comment node-name, next, previous, up 591@subsection Looking up filenames 592 593@deftypefun errcode_t ext2fs_lookup (ext2_filsys @var{fs}, ino_t @var{dir}, const char *@var{name}, int @var{namelen}, char *@var{buf}, ino_t *@var{inode}) 594@end deftypefun 595 596@deftypefun errcode_t ext2fs_namei (ext2_filsys @var{fs}, ino_t @var{root}, ino_t @var{cwd}, const char *@var{name}, ino_t *@var{inode}) 597@end deftypefun 598 599@deftypefun errcode_t ext2fs_namei_follow (ext2_filsys @var{fs}, ino_t @var{root}, ino_t @var{cwd}, const char *@var{name}, ino_t *@var{inode}) 600@end deftypefun 601 602@deftypefun errcode_t ext2fs_follow_link (ext2_filsys @var{fs}, ino_t @var{root}, ino_t @var{cwd}, ino_t @var{inode}, ino_t *@var{res}_inode) 603@end deftypefun 604 605@c ---------------------------------------------------------------------- 606 607@node Translating inode numbers to filenames, , Looking up filenames, Directory functions 608@comment node-name, next, previous, up 609@subsection Translating inode numbers to filenames 610 611@deftypefun errcode_t ext2fs_get_pathname (ext2_filsys @var{fs}, ino_t @var{dir}, ino_t @var{ino}, char **@var{name}) 612@end deftypefun 613 614 615@c ---------------------------------------------------------------------- 616 617@node Bitmap Functions, EXT2 data abstractions, Directory functions, EXT2FS Library Functions 618@comment node-name, next, previous, up 619@section Bitmap Functions 620 621@menu 622* Reading and Writing Bitmaps:: 623* Allocating Bitmaps:: 624* Free bitmaps:: 625* Bitmap Operations:: 626* Comparing bitmaps:: 627* Modifying Bitmaps:: 628* Resizing Bitmaps:: 629* Clearing Bitmaps:: 630@end menu 631 632@c ---------------------------------------------------------------------- 633 634@node Reading and Writing Bitmaps, Allocating Bitmaps, Bitmap Functions, Bitmap Functions 635@comment node-name, next, previous, up 636@subsection Reading and Writing Bitmaps 637 638@deftypefun errcode_t ext2fs_write_inode_bitmap (ext2_filsys @var{fs}) 639@end deftypefun 640 641@deftypefun errcode_t ext2fs_write_block_bitmap (ext2_filsys @var{fs}) 642@end deftypefun 643 644@deftypefun errcode_t ext2fs_read_inode_bitmap (ext2_filsys @var{fs}) 645@end deftypefun 646 647@deftypefun errcode_t ext2fs_read_block_bitmap (ext2_filsys @var{fs}) 648@end deftypefun 649 650@deftypefun errcode_t ext2fs_read_bitmaps (ext2_filsys @var{fs}) 651@end deftypefun 652 653@deftypefun errcode_t ext2fs_write_bitmaps (ext2_filsys @var{fs}) 654@end deftypefun 655 656@c ---------------------------------------------------------------------- 657 658@node Allocating Bitmaps, Free bitmaps, Reading and Writing Bitmaps, Bitmap Functions 659@comment node-name, next, previous, up 660@subsection Allocating Bitmaps 661 662@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}) 663@end deftypefun 664 665@deftypefun errcode_t ext2fs_allocate_block_bitmap (ext2_filsys @var{fs}, const char *@var{descr}, ext2fs_block_bitmap *@var{ret}) 666@end deftypefun 667 668@deftypefun errcode_t ext2fs_allocate_inode_bitmap (ext2_filsys @var{fs}, const char *@var{descr}, ext2fs_inode_bitmap *@var{ret}) 669@end deftypefun 670 671@c ---------------------------------------------------------------------- 672 673@node Free bitmaps, Bitmap Operations, Allocating Bitmaps, Bitmap Functions 674@comment node-name, next, previous, up 675@subsection Freeing bitmaps 676 677 678@deftypefun void ext2fs_free_generic_bitmap (ext2fs_inode_bitmap @var{bitmap}) 679@end deftypefun 680 681@deftypefun void ext2fs_free_block_bitmap (ext2fs_block_bitmap @var{bitmap}) 682@end deftypefun 683 684@deftypefun void ext2fs_free_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}) 685@end deftypefun 686 687 688@c ---------------------------------------------------------------------- 689 690@node Bitmap Operations, Comparing bitmaps, Free bitmaps, Bitmap Functions 691@comment node-name, next, previous, up 692@subsection Bitmap Operations 693 694@deftypefun void ext2fs_mark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 695 696@deftypefunx void ext2fs_unmark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 697 698@deftypefunx int ext2fs_test_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 699 700These functions set, clear, and test bits in a block bitmap @var{bitmap}. 701@end deftypefun 702 703 704@deftypefun void ext2fs_mark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 705 706@deftypefunx void ext2fs_unmark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 707 708@deftypefunx int ext2fs_test_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 709 710These functions set, clear, and test bits in an inode bitmap @var{bitmap}. 711@end deftypefun 712 713@deftypefun void ext2fs_fast_mark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 714 715@deftypefunx void ext2fs_fast_unmark_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 716 717@deftypefunx int ext2fs_fast_test_block_bitmap (ext2fs_block_bitmap @var{bitmap}, blk_t @var{block}) 718 719@deftypefunx void ext2fs_fast_mark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 720 721@deftypefunx void ext2fs_fast_unmark_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 722 723@deftypefunx int ext2fs_fast_test_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{inode}) 724 725These ``fast'' functions are like their normal counterparts; however, 726they are implemented as inline functions and do not perform bounds 727checks on the inode number or block number; they are assumed to be 728correct. They should only be used in speed-critical applications, where 729the inode or block number has already been validated by other means. 730@end deftypefun 731 732@deftypefun blk_t ext2fs_get_block_bitmap_start (ext2fs_block_bitmap @var{bitmap}) 733@deftypefunx ino_t ext2fs_get_inode_bitmap_start (ext2fs_inode_bitmap @var{bitmap}) 734Return the first inode or block which is stored in the bitmap. 735@end deftypefun 736 737@deftypefun blk_t ext2fs_get_block_bitmap_end (ext2fs_block_bitmap @var{bitmap}) 738@deftypefunx ino_t ext2fs_get_inode_bitmap_end (ext2fs_inode_bitmap @var{bitmap}) 739 740Return the first inode or block which is stored in the bitmap. 741@end deftypefun 742 743 744@c ---------------------------------------------------------------------- 745 746@node Comparing bitmaps, Modifying Bitmaps, Bitmap Operations, Bitmap Functions 747@comment node-name, next, previous, up 748@subsection Comparing bitmaps 749 750@deftypefun errcode_t ext2fs_compare_block_bitmap (ext2fs_block_bitmap @var{bm1}, ext2fs_block_bitmap @var{bm2}) 751@end deftypefun 752 753@deftypefun errcode_t ext2fs_compare_inode_bitmap (ext2fs_inode_bitmap @var{bm1}, ext2fs_inode_bitmap @var{bm2}) 754@end deftypefun 755 756 757@c ---------------------------------------------------------------------- 758 759@node Modifying Bitmaps, Resizing Bitmaps, Comparing bitmaps, Bitmap Functions 760@comment node-name, next, previous, up 761@subsection Modifying Bitmaps 762 763@deftypefun errcode_t ext2fs_fudge_inode_bitmap_end (ext2fs_inode_bitmap @var{bitmap}, ino_t @var{end}, ino_t *@var{oend}) 764@end deftypefun 765 766@deftypefun errcode_t ext2fs_fudge_block_bitmap_end (ext2fs_block_bitmap @var{bitmap}, blk_t @var{end}, blk_t *@var{oend}) 767@end deftypefun 768 769@c ---------------------------------------------------------------------- 770 771@node Resizing Bitmaps, Clearing Bitmaps, Modifying Bitmaps, Bitmap Functions 772@comment node-name, next, previous, up 773@subsection Resizing Bitmaps 774 775@deftypefun errcode_t ext2fs_resize_generic_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_generic_bitmap @var{bmap}) 776@end deftypefun 777 778@deftypefun errcode_t ext2fs_resize_inode_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_inode_bitmap @var{bmap}) 779@end deftypefun 780 781@deftypefun errcode_t ext2fs_resize_block_bitmap (__u32 @var{new_end}, __u32 @var{new_real_end}, ext2fs_block_bitmap @var{bmap}) 782@end deftypefun 783 784 785@c ---------------------------------------------------------------------- 786 787@node Clearing Bitmaps, , Resizing Bitmaps, Bitmap Functions 788@comment node-name, next, previous, up 789@subsection Clearing Bitmaps 790 791@deftypefun void ext2fs_clear_inode_bitmap (ext2fs_inode_bitmap @var{bitmap}) 792@end deftypefun 793 794@deftypefun void ext2fs_clear_block_bitmap (ext2fs_block_bitmap @var{bitmap}) 795@end deftypefun 796 797 798@c ---------------------------------------------------------------------- 799 800@node EXT2 data abstractions, Byte-swapping functions, Bitmap Functions, EXT2FS Library Functions 801@comment node-name, next, previous, up 802@section EXT2 data abstractions 803 804The ext2 library has a number of abstractions which are useful for ext2 805utility programs. 806 807@menu 808* Badblocks list management:: 809* Directory-block list management:: 810* Inode count functions:: 811@end menu 812 813@c ---------------------------------------------------------------------- 814 815@node Badblocks list management, Directory-block list management, EXT2 data abstractions, EXT2 data abstractions 816@comment node-name, next, previous, up 817@subsection Badblocks list management 818 819 820@deftypefun errcode_t ext2fs_badblocks_list_create (ext2_badblocks_list *@var{ret}, int @var{size}) 821@end deftypefun 822 823@deftypefun void ext2fs_badblocks_list_free (ext2_badblocks_list @var{bb}) 824@end deftypefun 825 826@deftypefun errcode_t ext2fs_badblocks_list_add (ext2_badblocks_list @var{bb}, blk_t @var{blk}) 827@end deftypefun 828 829@deftypefun int ext2fs_badblocks_list_test (ext2_badblocks_list @var{bb}, blk_t @var{blk}) 830@end deftypefun 831 832@deftypefun errcode_t ext2fs_badblocks_list_iterate_begin (ext2_badblocks_list @var{bb}, ext2_badblocks_iterate *@var{ret}) 833@end deftypefun 834 835@deftypefun int ext2fs_badblocks_list_iterate (ext2_badblocks_iterate iter, blk_t *@var{blk}) 836@end deftypefun 837 838@deftypefun void ext2fs_badblocks_list_iterate_end (ext2_badblocks_iterate @var{iter}) 839@end deftypefun 840 841@deftypefun errcode_t ext2fs_update_bb_inode (ext2_filsys @var{fs}, ext2_badblocks_list @var{bb_list}) 842@end deftypefun 843 844@deftypefun errcode_t ext2fs_read_bb_inode (ext2_filsys @var{fs}, ext2_badblocks_list *@var{bb_list}) 845@end deftypefun 846 847@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})) 848@end deftypefun 849 850 851@c ---------------------------------------------------------------------- 852 853@node Directory-block list management, Inode count functions, Badblocks list management, EXT2 data abstractions 854@comment node-name, next, previous, up 855@subsection Directory-block list management 856 857The dblist abstraction stores a list of blocks belonging to 858directories. This list can be useful when a program needs to interate 859over all directory entries in a filesystem; @code{e2fsck} does this in 860pass 2 of its operations, and @code{debugfs} needs to do this when it is 861trying to turn an inode number into a pathname. 862 863@deftypefun errcode_t ext2fs_init_dblist (ext2_filsys @var{fs}, ext2_dblist *@var{ret_dblist}) 864 865Creates a dblist data structure and return it in @var{ret_dblist}. 866@end deftypefun 867 868@deftypefun void ext2fs_free_dblist (ext2_dblist @var{dblist}) 869 870Free a dblist data structure. 871@end deftypefun 872 873@deftypefun errcode_t ext2fs_add_dir_block (ext2_dblist @var{dblist}, ino_t @var{ino}, blk_t @var{blk}, int @var{blockcnt}) 874 875Add an entry to the dblist data structure. This call records the fact 876that block number @var{blockcnt} of directory inode @var{ino} is stored 877in block @var{blk}. 878@end deftypefun 879 880@deftypefun errcode_t ext2fs_set_dir_block (ext2_dblist @var{dblist}, ino_t @var{ino}, blk_t @var{blk}, int @var{blockcnt}) 881 882Change an entry in the dblist data structure; this changes the location 883of block number @var{blockcnt} of directory indoe @var{ino} to be block 884@var{blk}. 885@end deftypefun 886 887@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}) 888 889This iterator calls @var{func} for every entry in the dblist data structure. 890@end deftypefun 891 892@deftypefun errcode_t ext2fs_dblist_dir_iterate (ext2_dblist @var{dblist}, int flags, char *@var{block_buf}, int (*func)(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}) 893 894This iterator takes reads in the directory block indicated in each 895dblist entry, and calls @var{func} for each directory entry in each 896directory block. If @var{dblist} contains all the directory blocks in a 897filesystem, this function provides a convenient way to iterate over all 898directory entries for that filesystem. 899@end deftypefun 900 901@c ---------------------------------------------------------------------- 902 903@node Inode count functions, , Directory-block list management, EXT2 data abstractions 904@comment node-name, next, previous, up 905@subsection Inode count functions 906 907The icount abstraction is a specialized data type used by @code{e2fsck} 908to store how many times a particular inode is referenced by the 909filesystem. This is used twice; once to store the actual number of times 910that the inode is reference; and once to store the claimed number of times 911the inode is referenced according to the inode structure. 912 913This abstraction is designed to be extremely efficient for storing this 914sort of information, by taking advantage of the following properties of 915inode counts, namely (1) inode counts are very often zero (because 916the inode is currrently not in use), and (2) many files have a inode 917count of 1 (because they are a file which has no additional hard links). 918 919@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}) 920 921Creates an icount stucture for a filesystem @var{fs}, with initial space 922for @var{size} inodes whose count is greater than 1. The @var{flags} 923parameter is either 0 or @code{EXT2_ICOUNT_OPT_INCREMENT}, which 924indicates that icount structure should be able to increment inode counts 925quickly. The icount structure is returned in @var{ret}. The returned 926icount structure initially has a count of zero for all inodes. 927 928The @var{hint} parameter allows the caller to optionally pass in another 929icount structure which is used to initialize the array of inodes whose 930count is greater than 1. It is used purely as a speed optimization so 931that the icount structure can determine in advance which inodes are 932likely to contain a count grater than 1. 933@end deftypefun 934 935@deftypefun void ext2fs_free_icount(ext2_icount_t @var{icount}) 936 937Frees an icount structure. 938@end deftypefun 939 940@deftypefun errcode_t ext2fs_icount_fetch(ext2_icount_t @var{icount}, ino_t @var{ino}, __u16 *@var{ret}) 941 942Returns in @var{ret} fetches the count for a particular inode @var{ino}. 943@end deftypefun 944 945@deftypefun errcode_t ext2fs_icount_increment(ext2_icount_t @var{icount}, ino_t @var{ino}, __u16 *@var{ret}) 946 947Increments the ref count for inode @var{ino}. 948@end deftypefun 949 950@deftypefun errcode_t ext2fs_icount_decrement(ext2_icount_t @var{icount}, ino_t @var{ino}, __u16 *@var{ret}) 951 952Decrements the ref count for inode @var{ino}. 953@end deftypefun 954 955@deftypefun errcode_t ext2fs_icount_store(ext2_icount_t @var{icount}, ino_t @var{ino}, __u16 @var{count}) 956 957Sets the reference count for inode @var{ino} to be @var{count}. 958@end deftypefun 959 960@deftypefun ino_t ext2fs_get_icount_size(ext2_icount_t @var{icount}) 961 962Returns the current number of inodes in @var{icount} which has a count 963greater than 1. 964@end deftypefun 965 966@deftypefun errcode_t ext2fs_icount_validate(ext2_icount_t @var{icount}, FILE *@var{f}) 967 968Validates the internal rep invariant of @var{icount}; if there are any 969problems, print out debugging information to @var{f}. This function is 970intended for debugging and testing use only. 971@end deftypefun 972 973 974@c ---------------------------------------------------------------------- 975 976@node Byte-swapping functions, Other functions, EXT2 data abstractions, EXT2FS Library Functions 977@comment node-name, next, previous, up 978@section Byte-swapping functions 979 980@deftypefun void ext2fs_swap_super (struct ext2_super_block * @var{super}) 981@end deftypefun 982 983@deftypefun void ext2fs_swap_group_desc (struct ext2_group_desc *@var{gdp}) 984@end deftypefun 985 986@deftypefun void ext2fs_swap_inode (ext2_filsys @var{fs}, struct ext2_inode *@var{to}, struct ext2_inode *@var{from}, int @var{hostorder}) 987@end deftypefun 988 989@deftypefun int ext2fs_native_flag (void) 990@end deftypefun 991 992 993@c ---------------------------------------------------------------------- 994 995@node Other functions, , Byte-swapping functions, EXT2FS Library Functions 996@comment node-name, next, previous, up 997@section Other functions 998 999/* alloc.c */ 1000@deftypefun errcode_t ext2fs_new_inode (ext2_filsys @var{fs}, ino_t @var{dir}, int @var{mode}, ext2fs_inode_bitmap @var{map}, ino_t *@var{ret}) 1001@end deftypefun 1002 1003@deftypefun errcode_t ext2fs_new_block (ext2_filsys @var{fs}, blk_t @var{goal}, ext2fs_block_bitmap @var{map}, blk_t *@var{ret}) 1004@end deftypefun 1005 1006@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}) 1007@end deftypefun 1008 1009/* check_desc.c */ 1010@deftypefun errcode_t ext2fs_check_desc (ext2_filsys @var{fs}) 1011@end deftypefun 1012 1013@deftypefun errcode_t ext2_get_num_dirs (ext2_filsys @var{fs}, ino_t *@var{ret_num_dirs}) 1014@end deftypefun 1015 1016 1017/* getsize.c */ 1018@deftypefun errcode_t ext2fs_get_device_size (const char *@var{file}, int @var{blocksize}, blk_t *@var{retblocks}) 1019@end deftypefun 1020 1021 1022/* ismounted.c */ 1023@deftypefun errcode_t ext2fs_check_if_mounted (const char *@var{file}, int *@var{mount_flags}) 1024@end deftypefun 1025 1026/* version.c */ 1027 1028@deftypefun int ext2fs_get_library_version(const char **@var{ver_string}, const char **@var{date_string}) 1029 1030This function returns the current version of the ext2 library. The 1031return value contains an integer version code, which consists of the 1032major version number of the library multiplied by 100, plus the minor 1033version number of the library. Hence, if the library version is 1.08, 1034the returned value will be 108. 1035 1036If @var{ver_string} and/or @var{date_string} are non-NULL, they will be 1037set to point at a constant string containing the library version and/or 1038release date, respectively. 1039@end deftypefun 1040 1041@deftypefun int ext2fs_parse_version_string(const char *@var{ver_string}) 1042 1043This function takes a version string which may included in an 1044application and returns a version code using the same algorithm used by 1045@code{ext2fs_get_library_version}. It can be used by programs included 1046in the @code{e2fsprogs} distribution to assure that they are using an 1047up-to-date ext2 shared library. 1048@end deftypefun 1049 1050/* inline functions */ 1051@deftypefun int ext2fs_group_of_blk (ext2_filsys @var{fs}, blk_t @var{blk}) 1052@end deftypefun 1053 1054@deftypefun int ext2fs_group_of_ino (ext2_filsys @var{fs}, ino_t @var{ino}) 1055@end deftypefun 1056 1057 1058@c ---------------------------------------------------------------------- 1059 1060@node Concept Index, Function Index, EXT2FS Library Functions, Top 1061@comment node-name, next, previous, up 1062@unnumbered Concept Index 1063@printindex cp 1064 1065@c ---------------------------------------------------------------------- 1066 1067@node Function Index, , Concept Index, Top 1068@comment node-name, next, previous, up 1069@unnumbered Function and Type Index 1070@printindex fn 1071 1072 1073@contents 1074@bye 1075