doc/libext2fs.texinfo

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