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