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