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